Phase 10: central realm Registry, Host publishing lifecycle, deployment

crates/coa-registry-proto (protocol 1: types, limits, signed-request canonicalisation, test vectors),
services/coa-registry (axum + PostgreSQL, migrations, rate limits, Dockerfile, deploy files),
services/coa-registry-e2e (Host lifecycle against the real service, live VPS gate),
coa-core realm_registry (identity keys, client, publishing loop on its own thread),
Settings -> Public listing card, docs REGISTRY_PROTOCOL.md and REGISTRY_DEPLOYMENT.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
ДмитрийandClaude Sonnet 5.5 committed 2026-10-07 20:23:13 +05:00
1 parent ec40f146aa
commit 1267bcc41e
56 files changed
+10198 -13

No files matched your search

+1
View File
@@ -27,6 +27,7 @@ tracing-subscriber = { version = "0.3", default-features = false, features = ["f
tempfile = "3"
rusqlite = { version = "0.40.2", features = ["bundled"] }
if-addrs = "0.15"
coa-registry-proto = { path = "../coa-registry-proto" }
[dev-dependencies]
rand_core = { version = "0.6", features = ["getrandom"] }
+1
View File
@@ -36,6 +36,7 @@ pub mod allsettings;
pub mod modules;
pub mod realmlist;
pub mod realms;
pub mod realm_registry;
pub mod registry;
pub mod release;
pub mod report;
@@ -0,0 +1,179 @@
//! What a local realm advertises, and how the Host learns it.
use std::collections::{HashMap, HashSet};
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use coa_registry_proto::AdvertisedCapabilities;
use crate::portable::capabilities::RealmCapabilities;
use crate::portable::extension::ExtensionRegistry;
use crate::portable::realm::profile::probe_capabilities;
use crate::portable::service::access::{load_descriptors, RealmAccess};
use crate::{Error, Result};
/// The public form of a realm's capabilities: the profile as it is (same fields, same hash), bounded.
pub fn advertise(caps: &RealmCapabilities) -> Result<AdvertisedCapabilities> {
let value = serde_json::to_value(caps)?;
let advert: AdvertisedCapabilities = serde_json::from_value(value).map_err(|e| Error::Invalid(format!("the capabilities cannot be advertised: {e}")))?;
advert.validate().map_err(|e| Error::Invalid(e.to_string()))?;
Ok(advert)
}
#[derive(Clone, Debug, PartialEq)]
pub struct LocalAdvert {
/// The worldserver answers (database and console): only a running realm sends heartbeats.
pub running: bool,
/// What the realm advertises; the last known one while it is stopped, `None` before it was ever seen running.
pub capabilities: Option<AdvertisedCapabilities>,
pub player_count: Option<u32>,
pub player_capacity: Option<u32>,
pub manager_version: String,
}
/// Where the publishing loop gets a realm's current advertisement. Implementations must be quick or cache; they are called from the loop's thread.
pub trait AdvertSource: Send + Sync + 'static {
fn current(&self, local_id: &str) -> Option<LocalAdvert>;
}
struct Cached {
at: Instant,
advert: LocalAdvert,
caps_at: Option<Instant>,
}
struct Inner {
descriptors: PathBuf,
installs: Box<dyn Fn() -> Vec<(String, PathBuf)> + Send + Sync>,
registry: Arc<ExtensionRegistry>,
cache: Mutex<HashMap<String, Cached>>,
inflight: Mutex<HashSet<String>>,
fresh: Duration,
caps_every: Duration,
}
/// Probes the realms this Manager knows (installed servers and prepared descriptors) with the same code the portable engine uses.
///
/// Probing talks to the realm's database and console and can take many seconds, so it never runs on the caller's thread: `current` answers from
/// the last probe at once (`None` before the first one has finished) and starts a refresh in the background when that probe is older than a few seconds.
pub struct LocalRealmsSource {
inner: Arc<Inner>,
}
impl LocalRealmsSource {
pub fn new(descriptors: impl Into<PathBuf>, installs: impl Fn() -> Vec<(String, PathBuf)> + Send + Sync + 'static) -> Self {
Self {
inner: Arc::new(Inner {
descriptors: descriptors.into(),
installs: Box::new(installs),
registry: Arc::new(ExtensionRegistry::new()),
cache: Mutex::new(HashMap::new()),
inflight: Mutex::new(HashSet::new()),
fresh: Duration::from_secs(10),
caps_every: Duration::from_secs(60),
}),
}
}
}
impl Inner {
fn access(&self, local_id: &str) -> Option<RealmAccess> {
if let Some((id, root)) = (self.installs)().into_iter().find(|(id, _)| format!("srv-{id}") == local_id || id == local_id) {
return Some(RealmAccess::from_install(&id, &root));
}
let (descriptors, _) = load_descriptors(&self.descriptors);
descriptors.into_iter().find(|d| d.id == local_id).and_then(|d| RealmAccess::from_descriptor(d).ok())
}
fn probe(&self, local_id: &str) {
let previous = self.cache.lock().ok().and_then(|c| c.get(local_id).map(|c| (c.advert.clone(), c.caps_at)));
let Some(access) = self.access(local_id) else { return };
let mut advert = LocalAdvert { running: false, capabilities: previous.as_ref().and_then(|(a, _)| a.capabilities.clone()), player_count: None, player_capacity: None, manager_version: crate::MANAGER_VERSION.to_string() };
let mut caps_at = previous.as_ref().and_then(|(_, t)| *t);
if access.db_reachable() {
if let (Ok(db), Ok(mut ra)) = (access.db(), access.ra()) {
advert.running = true;
advert.player_count = ra.run("server info").ok().and_then(|text| connected_players(&text));
if caps_at.is_none_or(|t| t.elapsed() >= self.caps_every) || advert.capabilities.is_none() {
let data = access.data_dir.is_dir().then_some(access.data_dir.as_path());
if let Ok(caps) = probe_capabilities(&db, data, Some(&mut ra), &self.registry) {
if let Ok(a) = advertise(&caps) {
advert.capabilities = Some(a);
caps_at = Some(Instant::now());
}
}
}
}
}
if let Ok(mut cache) = self.cache.lock() {
cache.insert(local_id.to_string(), Cached { at: Instant::now(), advert, caps_at });
}
}
}
/// `Connected players: 3. Characters in world: 3.`
pub fn connected_players(server_info: &str) -> Option<u32> {
let rest = server_info.split("Connected players:").nth(1)?;
rest.trim_start().split(|c: char| !c.is_ascii_digit()).next()?.parse().ok()
}
impl AdvertSource for LocalRealmsSource {
fn current(&self, local_id: &str) -> Option<LocalAdvert> {
let (answer, stale) = match self.inner.cache.lock().ok()?.get(local_id) {
Some(c) => (Some(c.advert.clone()), c.at.elapsed() >= self.inner.fresh),
None => (None, true),
};
if stale && self.inner.inflight.lock().ok()?.insert(local_id.to_string()) {
let inner = self.inner.clone();
let id = local_id.to_string();
let spawned = std::thread::Builder::new().name("realm-probe".into()).spawn(move || {
inner.probe(&id);
if let Ok(mut f) = inner.inflight.lock() {
f.remove(&id);
}
});
if spawned.is_err() {
self.inner.inflight.lock().ok()?.remove(local_id);
}
}
answer
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_player_count_is_read_from_the_server_info_report() {
assert_eq!(connected_players("Connected players: 3. Characters in world: 3."), Some(3));
assert_eq!(connected_players("x\nConnected players: 0.\n"), Some(0));
assert_eq!(connected_players("nothing"), None);
assert_eq!(connected_players("Connected players: many"), None);
}
#[test]
fn a_real_profile_is_advertised_without_changing_its_hash() {
use crate::portable::capabilities::*;
use crate::portable::model::Ruleset;
use std::collections::{BTreeMap, BTreeSet};
let content = ContentProfile {
ruleset: Ruleset::Coa,
character_formats: ContentProfile::manager_formats(),
online_import_job_formats: vec![2],
session_protocol: 2,
collection_protocol: 1,
features: [Feature::RuntimeSessions, Feature::Wardrobe, Feature::Collections, Feature::LevelProjection].into_iter().collect::<BTreeSet<_>>(),
collection_kinds: ["coa:appearance".to_string(), "coa:vanity".to_string()].into_iter().collect(),
extensions: vec![ExtensionSupport { namespace: "coa".into(), module_version: "1".into(), formats: FormatRange::single(1) }],
client_catalog: BTreeMap::from([("Appearances.dbc".to_string(), CatalogEntry { sha256: "c".repeat(64), records: 7 })]),
};
let progression = Progression { max_player_level: 60, projection_protocol: 1, projection_policy_version: 1, progression_signature: "d".repeat(64), scaling_enabled: true };
let core = Some(CoreIdentity { commit: "0f3737574afd".into(), branch: "feat/x".into(), date: "2026-10-01".into() });
let caps = RealmCapabilities::build(core, content, Some(progression)).unwrap();
let advert = advertise(&caps).unwrap();
assert_eq!(advert.content_profile_hash, caps.content_profile_hash, "the Registry sees the hash the Manager computed");
assert_eq!(serde_json::to_value(&advert).unwrap(), serde_json::to_value(&caps).unwrap(), "the same JSON, field for field");
}
}
@@ -0,0 +1,116 @@
//! The Host's HTTP client of Registry protocol 1. Blocking, with hard timeouts; every mutating request is signed with the realm's own key.
use std::time::Duration;
use coa_registry_proto::sign::sign_request;
use coa_registry_proto::*;
use ed25519_dalek::SigningKey;
use serde::de::DeserializeOwned;
use serde::Serialize;
use std::result::Result;
/// Why a request did not succeed, in the terms the retry policy needs.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ClientError {
/// The network, a timeout, a 5xx or a rate limit: the same request may work later.
Transient(String),
/// The Registry understood the request and refused it with this code.
Rejected { code: ErrorCode, status: u16, message: String },
/// The answer is not Registry protocol 1.
Protocol(String),
}
impl ClientError {
/// Repeating cannot help: the Host stops instead of retrying.
pub fn is_permanent(&self) -> bool {
match self {
ClientError::Transient(_) => false,
ClientError::Rejected { code, .. } => code.is_permanent(),
ClientError::Protocol(_) => true,
}
}
pub fn code(&self) -> Option<ErrorCode> {
match self {
ClientError::Rejected { code, .. } => Some(*code),
_ => None,
}
}
}
impl std::fmt::Display for ClientError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
ClientError::Transient(m) => write!(f, "the Registry could not be reached: {m}"),
ClientError::Rejected { code, status, message } => write!(f, "the Registry refused the request ({status} {code:?}): {message}"),
ClientError::Protocol(m) => write!(f, "the Registry answered something that is not protocol {REGISTRY_PROTOCOL_VERSION}: {m}"),
}
}
}
impl std::error::Error for ClientError {}
pub struct RegistryClient {
base: String,
http: reqwest::blocking::Client,
}
impl RegistryClient {
pub fn new(base: &str) -> crate::Result<Self> {
let base = super::settings::validate_url(base)?;
let http = reqwest::blocking::Client::builder()
.timeout(Duration::from_secs(10))
.connect_timeout(Duration::from_secs(5))
.redirect(reqwest::redirect::Policy::none())
.user_agent(concat!("coa-manager/", env!("CARGO_PKG_VERSION")))
.build()
.map_err(|e| crate::Error::Invalid(e.to_string()))?;
Ok(Self { base, http })
}
pub fn base(&self) -> &str {
&self.base
}
fn send<R: DeserializeOwned>(&self, method: &str, path: &str, body: Vec<u8>, key: &SigningKey, realm: &RealmId, ts: i64) -> Result<R, ClientError> {
let headers = sign_request(key, method, path, realm, ts, &body);
let url = format!("{}{}", self.base, path);
let mut req = if method == "GET" { self.http.get(url) } else { self.http.post(url).header("content-type", "application/json").body(body) };
for (name, value) in headers.pairs() {
req = req.header(name, value);
}
let resp = req.send().map_err(|e| ClientError::Transient(e.without_url().to_string()))?;
let status = resp.status();
let bytes = resp.bytes().map_err(|e| ClientError::Transient(e.without_url().to_string()))?;
if status.is_success() {
return serde_json::from_slice(&bytes).map_err(|_| ClientError::Protocol("the answer cannot be read".into()));
}
match serde_json::from_slice::<ErrorBody>(&bytes) {
Ok(e) if status.as_u16() == 429 || status.as_u16() == 503 => Err(ClientError::Transient(format!("{:?}: {}", e.error.code, e.error.message))),
Ok(e) => Err(ClientError::Rejected { code: e.error.code, status: status.as_u16(), message: e.error.message }),
Err(_) if status.is_server_error() || status.as_u16() == 408 || status.as_u16() == 429 => Err(ClientError::Transient(format!("HTTP {status}"))),
Err(_) => Err(ClientError::Protocol(format!("HTTP {status} without a Registry error body"))),
}
}
fn post<B: Serialize, R: DeserializeOwned>(&self, path: &str, body: &B, key: &SigningKey, realm: &RealmId, ts: i64) -> Result<R, ClientError> {
let bytes = serde_json::to_vec(body).map_err(|e| ClientError::Protocol(e.to_string()))?;
self.send("POST", path, bytes, key, realm, ts)
}
pub fn register(&self, key: &SigningKey, req: &RegisterRequest, ts: i64) -> Result<RegisterResponse, ClientError> {
self.post(PATH_REGISTER, req, key, &req.realm_id, ts)
}
pub fn heartbeat(&self, key: &SigningKey, realm: &RealmId, req: &HeartbeatRequest, ts: i64) -> Result<HeartbeatResponse, ClientError> {
self.post(&path_heartbeat(realm), req, key, realm, ts)
}
pub fn unpublish(&self, key: &SigningKey, realm: &RealmId, ts: i64) -> Result<UnpublishResponse, ClientError> {
self.post(&path_unpublish(realm), &UnpublishRequest { protocol_version: REGISTRY_PROTOCOL_VERSION }, key, realm, ts)
}
/// The Registry's own record of this realm (the authenticated read).
pub fn self_info(&self, key: &SigningKey, realm: &RealmId, ts: i64) -> Result<SelfResponse, ClientError> {
self.send("GET", &path_self(realm), Vec::new(), key, realm, ts)
}
}
+550
View File
@@ -0,0 +1,550 @@
//! The publishing lifecycle of a Host Manager, independent of Player Mode and of the portable engine.
//!
//! ```text
//! publish enabled -> ensure the realm's identity (UUIDv7 + Ed25519 key) -> register -> heartbeat every ~30 s
//! the realm's capabilities changed -> the next heartbeat carries them
//! Manager restart -> the same RealmId and key -> register again as itself -> heartbeat
//! publish disabled -> unpublish (retried in the background until it is delivered or refused)
//! ```
//!
//! Nothing here touches the realm's database writes, the worldserver or any portable store: the loop only *reads* what a realm advertises, and a
//! Registry that is down, slow or hostile changes nothing but this module's own status. Transient failures are retried with a capped exponential
//! backoff and jitter; a refusal that repeating cannot fix (bad signature, wrong key, unsupported protocol, invalid metadata) stops the realm's
//! publication until the owner acts.
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::{Duration, Instant};
use coa_registry_proto::sign::encode_public_key;
use coa_registry_proto::*;
use ed25519_dalek::SigningKey;
use serde::Serialize;
use super::advert::{AdvertSource, LocalAdvert};
use super::client::{ClientError, RegistryClient};
use super::keys::KeyStore;
use super::settings::{self, PublishConfig, RegistrySettings};
use crate::{Error, Result};
pub type Clock = Arc<dyn Fn() -> i64 + Send + Sync>;
pub fn system_clock() -> Clock {
Arc::new(|| std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs() as i64).unwrap_or(0))
}
#[derive(Clone, Debug)]
pub struct Timing {
pub heartbeat: Duration,
pub backoff_base: Duration,
pub backoff_cap: Duration,
/// How long to wait before looking again at a realm that is not running or not known yet (no network involved).
pub idle_poll: Duration,
/// Clock-skew refusals are retried this often at most; a clock that stays wrong is the owner's to fix.
pub max_clock_failures: u32,
pub max_unpublish_attempts: u32,
}
impl Default for Timing {
fn default() -> Self {
Self { heartbeat: Duration::from_secs(HEARTBEAT_INTERVAL_SECS), backoff_base: Duration::from_secs(5), backoff_cap: Duration::from_secs(300), idle_poll: Duration::from_secs(5), max_clock_failures: 20, max_unpublish_attempts: 12 }
}
}
/// `base * 2^(attempt-1)` capped, then spread by +-25% with `unit` in `[0, 1)`.
pub fn backoff(attempt: u32, base: Duration, cap: Duration, unit: f64) -> Duration {
let exp = attempt.saturating_sub(1).min(20);
let raw = base.as_secs_f64() * f64::from(1u32 << exp);
let capped = raw.min(cap.as_secs_f64());
Duration::from_secs_f64(capped * (0.75 + 0.5 * unit.clamp(0.0, 0.999_999)))
}
fn unit() -> f64 {
let b = uuid::Uuid::new_v4();
let n = u64::from_le_bytes(b.as_bytes()[..8].try_into().expect("8 bytes"));
(n >> 11) as f64 / (1u64 << 53) as f64
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PublishState {
/// Waiting for the first attempt.
Starting,
/// The realm is not known, not running or has no capabilities yet: nothing is sent.
WaitingForRealm,
RealmStopped,
Online,
/// The Registry could not be reached (or asked to slow down); trying again.
Retrying,
/// The Registry refused the request and repeating cannot change that.
Rejected,
Unpublishing,
Disabled,
}
#[derive(Clone, Debug, Serialize)]
pub struct RealmPublishStatus {
pub local_id: String,
pub realm_id: Option<String>,
pub enabled: bool,
pub state: PublishState,
pub display_name: String,
pub description: String,
pub language: String,
pub metadata_revision: Option<u64>,
pub last_ok_unix: Option<i64>,
pub last_error: Option<String>,
pub retry_in_secs: Option<u64>,
}
#[derive(Clone, Debug, Default, Serialize)]
pub struct RegistryStatus {
pub url: Option<String>,
pub realms: Vec<RealmPublishStatus>,
}
enum Phase {
Register,
Beat,
}
struct Publisher {
cfg: PublishConfig,
realm: Option<RealmId>,
key: Option<SigningKey>,
phase: Phase,
state: PublishState,
/// `None`: nothing to do until the owner acts (a permanent refusal).
due: Option<Instant>,
failures: u32,
clock_failures: u32,
unpublish_attempts: u32,
acked_hash: Option<String>,
sent_meta: Option<(String, String, String)>,
revision: Option<u64>,
last_ok: Option<i64>,
last_error: Option<String>,
last_ts: i64,
}
impl Publisher {
fn new(cfg: PublishConfig, now: Instant) -> Self {
let enabled = cfg.enabled;
Self {
cfg,
realm: None,
key: None,
phase: Phase::Register,
state: if enabled { PublishState::Starting } else { PublishState::Disabled },
due: enabled.then_some(now),
failures: 0,
clock_failures: 0,
unpublish_attempts: 0,
acked_hash: None,
sent_meta: None,
revision: None,
last_ok: None,
last_error: None,
last_ts: 0,
}
}
fn reset_progress(&mut self, now: Instant) {
self.phase = Phase::Register;
self.failures = 0;
self.clock_failures = 0;
self.acked_hash = None;
self.sent_meta = None;
self.last_error = None;
self.state = PublishState::Starting;
self.due = Some(now);
}
}
pub struct RegistryHost {
dir: PathBuf,
settings: RegistrySettings,
keys: Arc<dyn KeyStore>,
source: Arc<dyn AdvertSource>,
clock: Clock,
timing: Timing,
client: Option<RegistryClient>,
publishers: BTreeMap<String, Publisher>,
}
impl RegistryHost {
pub fn open(dir: &Path, keys: Arc<dyn KeyStore>, source: Arc<dyn AdvertSource>, clock: Clock, timing: Timing, now: Instant) -> Result<Self> {
let settings = settings::load(dir)?;
let client = settings.url.as_deref().map(RegistryClient::new).transpose()?;
let mut host = Self { dir: dir.to_path_buf(), settings, keys, source, clock, timing, client, publishers: BTreeMap::new() };
for (local, cfg) in host.settings.realms.clone() {
let mut p = Publisher::new(cfg.clone(), now);
if cfg.enabled {
host.attach_identity(&mut p);
}
host.publishers.insert(local, p);
}
Ok(host)
}
pub fn url(&self) -> Option<&str> {
self.settings.url.as_deref()
}
/// The identity of an enabled realm: its id and key must both exist; a missing key is not replaced behind the owner's back.
fn attach_identity(&self, p: &mut Publisher) {
let Some(id) = p.cfg.realm_id else {
p.state = PublishState::Rejected;
p.due = None;
p.last_error = Some("the realm has no identity yet".into());
return;
};
p.realm = Some(id);
match self.keys.load(&id) {
Ok(Some(key)) => p.key = Some(key),
Ok(None) => {
p.state = PublishState::Rejected;
p.due = None;
p.last_error = Some("the realm's key is missing on this machine; stop publishing and publish again to create a new identity".into());
}
Err(e) => {
p.state = PublishState::Rejected;
p.due = None;
p.last_error = Some(format!("the realm's key cannot be read: {e}"));
}
}
}
fn save(&self) -> Result<()> {
settings::save(&self.dir, &self.settings)
}
pub fn set_url(&mut self, url: Option<&str>, now: Instant) -> Result<()> {
let url = match url.map(str::trim).filter(|u| !u.is_empty()) {
Some(u) => Some(settings::validate_url(u)?),
None => None,
};
if url == self.settings.url {
return Ok(());
}
self.client = url.as_deref().map(RegistryClient::new).transpose()?;
self.settings.url = url;
self.save()?;
for p in self.publishers.values_mut().filter(|p| p.cfg.enabled && p.key.is_some()) {
p.reset_progress(now);
}
Ok(())
}
/// Start (or restart) publishing a local realm. The first time creates its identity; later times keep it.
pub fn publish(&mut self, local_id: &str, display_name: &str, description: &str, language: &str, now: Instant) -> Result<()> {
if self.client.is_none() {
return Err(Error::Invalid("set the Registry address first".into()));
}
let mut cfg = self.settings.realms.get(local_id).cloned().unwrap_or_default();
cfg.display_name = display_name.trim().to_string();
cfg.description = description.trim().to_string();
cfg.language = language.trim().to_string();
cfg.enabled = true;
cfg.validate()?;
// an identity whose key is gone from this machine cannot sign for itself any more: publishing again makes a new identity, never a guess at the old key
if let Some(id) = cfg.realm_id {
if matches!(self.keys.load(&id), Ok(None)) {
cfg.realm_id = None;
}
}
let created = if cfg.realm_id.is_none() {
let id = RealmId::new();
self.keys.create(&id)?;
cfg.realm_id = Some(id);
true
} else {
false
};
self.settings.realms.insert(local_id.to_string(), cfg.clone());
if let Err(e) = self.save() {
if created {
if let Some(id) = cfg.realm_id {
let _ = self.keys.remove(&id);
}
}
self.settings.realms.remove(local_id);
return Err(e);
}
let mut p = Publisher::new(cfg, now);
self.attach_identity(&mut p);
if let Some(old) = self.publishers.get(local_id) {
p.last_ok = old.last_ok;
p.last_ts = old.last_ts;
}
self.publishers.insert(local_id.to_string(), p);
Ok(())
}
/// Stop publishing: the realm is unpublished at the Registry (retried in the background); its identity is kept for a later republication.
pub fn unpublish(&mut self, local_id: &str, now: Instant) -> Result<()> {
let Some(cfg) = self.settings.realms.get_mut(local_id) else { return Ok(()) };
cfg.enabled = false;
let cfg = cfg.clone();
self.save()?;
let Some(p) = self.publishers.get_mut(local_id) else { return Ok(()) };
let was_registered = p.realm.is_some() && p.key.is_some() && (p.revision.is_some() || matches!(p.phase, Phase::Beat));
p.cfg = cfg;
p.unpublish_attempts = 0;
p.failures = 0;
if was_registered && self.client.is_some() {
p.state = PublishState::Unpublishing;
p.due = Some(now);
} else {
p.state = PublishState::Disabled;
p.due = None;
}
Ok(())
}
/// Try again now (after a refusal the owner has dealt with).
pub fn retry(&mut self, local_id: &str, now: Instant) {
if let Some(p) = self.publishers.get_mut(local_id) {
if p.cfg.enabled && p.key.is_some() {
p.reset_progress(now);
}
}
}
pub fn status(&self, now: Instant) -> RegistryStatus {
let realms = self
.publishers
.iter()
.map(|(local, p)| RealmPublishStatus {
local_id: local.clone(),
realm_id: p.cfg.realm_id.map(|r| r.to_string()),
enabled: p.cfg.enabled,
state: p.state,
display_name: p.cfg.display_name.clone(),
description: p.cfg.description.clone(),
language: p.cfg.language.clone(),
metadata_revision: p.revision,
last_ok_unix: p.last_ok,
last_error: p.last_error.clone(),
retry_in_secs: p.due.map(|d| d.saturating_duration_since(now).as_secs()),
})
.collect();
RegistryStatus { url: self.settings.url.clone(), realms }
}
/// The public key a published realm is known by (never the private one).
pub fn public_key(&self, local_id: &str) -> Option<String> {
self.publishers.get(local_id).and_then(|p| p.key.as_ref()).map(|k| encode_public_key(&k.verifying_key()))
}
/// What the Registry itself says about a published realm (the authenticated read; useful for support and for tests).
pub fn registry_record(&mut self, local_id: &str) -> std::result::Result<SelfResponse, ClientError> {
let Some(mut p) = self.publishers.remove(local_id) else { return Err(ClientError::Protocol("the realm is not known here".into())) };
let out = match (self.client.as_ref(), p.realm, p.key.clone()) {
(Some(client), Some(realm), Some(key)) => {
let ts = self.next_ts(&mut p);
client.self_info(&key, &realm, ts)
}
_ => Err(ClientError::Protocol("the realm has no identity or the Registry address is not set".into())),
};
self.publishers.insert(local_id.to_string(), p);
out
}
pub fn realm_id(&self, local_id: &str) -> Option<RealmId> {
self.publishers.get(local_id).and_then(|p| p.realm)
}
fn next_ts(&self, p: &mut Publisher) -> i64 {
let ts = (self.clock)().max(p.last_ts + 1);
p.last_ts = ts;
ts
}
/// One pass over the realms that are due. Network calls block (with their own timeouts); nothing else does.
pub fn tick(&mut self, now: Instant) {
let due: Vec<String> = self.publishers.iter().filter(|(_, p)| p.due.is_some_and(|d| d <= now)).map(|(k, _)| k.clone()).collect();
for local in due {
let Some(mut p) = self.publishers.remove(&local) else { continue };
self.step(&local, &mut p, now);
self.publishers.insert(local, p);
}
}
fn step(&self, local: &str, p: &mut Publisher, now: Instant) {
let (Some(client), Some(realm), Some(key)) = (self.client.as_ref(), p.realm, p.key.clone()) else {
p.due = None;
return;
};
if p.state == PublishState::Unpublishing {
return self.step_unpublish(client, &realm, &key, p, now);
}
let Some(advert) = self.source.current(local) else {
p.state = PublishState::WaitingForRealm;
p.due = Some(now + self.timing.idle_poll);
return;
};
let result = match p.phase {
Phase::Register => self.register(client, &realm, &key, p, &advert, now),
Phase::Beat => self.beat(client, &realm, &key, p, &advert, now),
};
if let Err(e) = result {
self.on_error(p, e, now);
}
}
fn register(&self, client: &RegistryClient, realm: &RealmId, key: &SigningKey, p: &mut Publisher, advert: &LocalAdvert, now: Instant) -> std::result::Result<(), ClientError> {
let Some(caps) = advert.capabilities.clone().filter(|_| advert.running) else {
p.state = if advert.running { PublishState::WaitingForRealm } else { PublishState::RealmStopped };
p.due = Some(now + self.timing.idle_poll);
return Ok(());
};
let req = RegisterRequest {
protocol_version: REGISTRY_PROTOCOL_VERSION,
realm_id: *realm,
public_key: encode_public_key(&key.verifying_key()),
display_name: p.cfg.display_name.clone(),
description: p.cfg.description.clone(),
language: p.cfg.language.clone(),
ruleset: caps.content.ruleset,
manager_version: advert.manager_version.clone(),
capabilities_hash: caps.advert_hash(),
capabilities: caps,
player_count: advert.player_count,
player_capacity: advert.player_capacity,
};
let ts = self.next_ts(p);
let resp = client.register(key, &req, ts)?;
p.phase = Phase::Beat;
p.acked_hash = Some(resp.capabilities_hash);
p.sent_meta = Some((req.display_name, req.description, req.language));
self.ok(p, resp.metadata_revision, now);
Ok(())
}
fn beat(&self, client: &RegistryClient, realm: &RealmId, key: &SigningKey, p: &mut Publisher, advert: &LocalAdvert, now: Instant) -> std::result::Result<(), ClientError> {
let Some(caps) = advert.capabilities.clone().filter(|_| advert.running) else {
p.state = PublishState::RealmStopped;
p.due = Some(now + self.timing.idle_poll);
return Ok(());
};
let hash = caps.advert_hash();
let meta = (p.cfg.display_name.clone(), p.cfg.description.clone(), p.cfg.language.clone());
let meta_changed = p.sent_meta.as_ref() != Some(&meta);
let req = HeartbeatRequest {
protocol_version: REGISTRY_PROTOCOL_VERSION,
capabilities: (p.acked_hash.as_deref() != Some(hash.as_str())).then_some(caps),
capabilities_hash: hash,
manager_version: Some(advert.manager_version.clone()),
player_count: advert.player_count,
player_capacity: advert.player_capacity,
display_name: meta_changed.then(|| meta.0.clone()),
description: meta_changed.then(|| meta.1.clone()),
language: meta_changed.then(|| meta.2.clone()),
};
let ts = self.next_ts(p);
let resp = client.heartbeat(key, realm, &req, ts)?;
if meta_changed {
p.sent_meta = Some(meta);
}
if resp.resend_capabilities {
p.acked_hash = None;
self.ok(p, resp.metadata_revision, now);
p.due = Some(now + Duration::from_secs(1));
} else {
p.acked_hash = Some(resp.capabilities_hash);
self.ok(p, resp.metadata_revision, now);
}
Ok(())
}
fn ok(&self, p: &mut Publisher, revision: u64, now: Instant) {
p.state = PublishState::Online;
p.failures = 0;
p.clock_failures = 0;
p.last_error = None;
p.revision = Some(revision);
p.last_ok = Some((self.clock)());
p.due = Some(now + self.timing.heartbeat.mul_f64(0.9 + 0.2 * unit()));
}
fn on_error(&self, p: &mut Publisher, e: ClientError, now: Instant) {
p.last_error = Some(e.to_string());
match &e {
ClientError::Rejected { code: ErrorCode::UnknownRealm | ErrorCode::NotPublished, .. } => {
p.phase = Phase::Register;
p.acked_hash = None;
p.failures += 1;
p.state = PublishState::Retrying;
p.due = Some(now + if p.failures <= 1 { Duration::from_secs(1) } else { backoff(p.failures, self.timing.backoff_base, self.timing.backoff_cap, unit()) });
}
ClientError::Rejected { code: ErrorCode::BadTimestamp | ErrorCode::TimestampNotMonotonic, .. } => {
p.clock_failures += 1;
p.failures += 1;
if p.clock_failures > self.timing.max_clock_failures {
p.state = PublishState::Rejected;
p.due = None;
} else {
p.state = PublishState::Retrying;
p.due = Some(now + backoff(p.failures, self.timing.backoff_base, self.timing.backoff_cap, unit()));
}
}
e if e.is_permanent() => {
p.state = PublishState::Rejected;
p.due = None;
}
_ => {
p.failures += 1;
p.state = PublishState::Retrying;
p.due = Some(now + backoff(p.failures, self.timing.backoff_base, self.timing.backoff_cap, unit()));
}
}
}
fn step_unpublish(&self, client: &RegistryClient, realm: &RealmId, key: &SigningKey, p: &mut Publisher, now: Instant) {
let ts = self.next_ts(p);
match client.unpublish(key, realm, ts) {
Ok(resp) => {
p.revision = Some(resp.metadata_revision);
p.last_error = None;
p.state = PublishState::Disabled;
p.due = None;
}
Err(ClientError::Rejected { code: ErrorCode::UnknownRealm, .. }) => {
p.state = PublishState::Disabled;
p.due = None;
}
Err(e) => {
p.last_error = Some(e.to_string());
p.unpublish_attempts += 1;
if e.is_permanent() || p.unpublish_attempts >= self.timing.max_unpublish_attempts {
p.state = PublishState::Disabled;
p.due = None;
} else {
p.due = Some(now + backoff(p.unpublish_attempts, self.timing.backoff_base, self.timing.backoff_cap, unit()));
}
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_backoff_grows_is_capped_and_is_spread() {
let (base, cap) = (Duration::from_secs(5), Duration::from_secs(300));
let mid = |n| backoff(n, base, cap, 0.5).as_secs_f64();
assert!((mid(1) - 5.0).abs() < 0.01 && (mid(2) - 10.0).abs() < 0.01 && (mid(3) - 20.0).abs() < 0.01);
assert!((mid(10) - 300.0).abs() < 0.01 && (mid(500) - 300.0).abs() < 0.01, "capped");
assert!(backoff(4, base, cap, 0.0) < backoff(4, base, cap, 0.999), "jitter spreads");
assert!(backoff(30, base, cap, 0.999) <= Duration::from_secs_f64(300.0 * 1.25));
assert!(backoff(1, base, cap, 0.0).as_secs_f64() >= 3.7);
for _ in 0..1000 {
let u = unit();
assert!((0.0..1.0).contains(&u));
}
}
}
+160
View File
@@ -0,0 +1,160 @@
//! A realm's Ed25519 identity key: one per realm, generated on first publication, never leaving this machine.
//!
//! Storage is behind [`KeyStore`]. The implementation here keeps one file per realm in the Manager's own data folder, readable by the current user
//! only (mode 0600 on Unix; on Windows the inherited permissions are removed and the current user is granted access with `icacls`). That is
//! weaker than an OS-protected secret store (DPAPI / Credential Manager), which this project does not use yet: anybody who can read the user's
//! files can read the key. The key is never written to the realm descriptor, a log, the diagnostics or the Registry.
use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};
use base64::engine::general_purpose::URL_SAFE_NO_PAD as B64;
use base64::Engine;
use coa_registry_proto::RealmId;
use ed25519_dalek::SigningKey;
use crate::{Error, Result};
pub trait KeyStore: Send + Sync {
/// The key of this realm, if one was created.
fn load(&self, realm: &RealmId) -> Result<Option<SigningKey>>;
/// A new random key for a realm that has none. Refuses to replace an existing one.
fn create(&self, realm: &RealmId) -> Result<SigningKey>;
fn remove(&self, realm: &RealmId) -> Result<()>;
}
pub struct FileKeyStore {
dir: PathBuf,
}
impl FileKeyStore {
pub fn new(dir: impl Into<PathBuf>) -> Self {
Self { dir: dir.into() }
}
fn file(&self, realm: &RealmId) -> PathBuf {
self.dir.join(format!("{realm}.key"))
}
}
fn random_seed() -> [u8; 32] {
let mut seed = [0u8; 32];
seed[..16].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
seed[16..].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
seed
}
#[cfg(unix)]
fn restrict(file: &Path) -> Result<()> {
use std::os::unix::fs::PermissionsExt;
fs::set_permissions(file, fs::Permissions::from_mode(0o600))?;
Ok(())
}
#[cfg(windows)]
fn restrict(file: &Path) -> Result<()> {
let user = std::env::var("USERNAME").map_err(|_| Error::Invalid("the current user is unknown".into()))?;
let domain = std::env::var("USERDOMAIN").unwrap_or_default();
let who = if domain.is_empty() { user } else { format!("{domain}\\{user}") };
let out = std::process::Command::new("icacls").arg(file).arg("/inheritance:r").arg("/grant:r").arg(format!("{who}:(F)")).output()?;
if !out.status.success() {
return Err(Error::Invalid("the key file's permissions could not be restricted".into()));
}
Ok(())
}
#[cfg(not(any(unix, windows)))]
fn restrict(_file: &Path) -> Result<()> {
Ok(())
}
impl KeyStore for FileKeyStore {
fn load(&self, realm: &RealmId) -> Result<Option<SigningKey>> {
let text = match fs::read_to_string(self.file(realm)) {
Ok(t) => t,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(e.into()),
};
let bytes = B64.decode(text.trim()).map_err(|_| Error::Invalid("a realm key file is not valid".into()))?;
let seed: [u8; 32] = bytes.try_into().map_err(|_| Error::Invalid("a realm key file is not valid".into()))?;
Ok(Some(SigningKey::from_bytes(&seed)))
}
fn create(&self, realm: &RealmId) -> Result<SigningKey> {
fs::create_dir_all(&self.dir)?;
let path = self.file(realm);
if path.exists() {
return Err(Error::Invalid("this realm already has a key".into()));
}
let seed = random_seed();
let tmp = self.dir.join(format!(".{realm}.{}.tmp", uuid::Uuid::new_v4().simple()));
let write = || -> Result<()> {
let mut f = fs::OpenOptions::new().write(true).create_new(true).open(&tmp)?;
restrict(&tmp)?;
f.write_all(B64.encode(seed).as_bytes())?;
f.sync_all()?;
drop(f);
fs::rename(&tmp, &path)?;
Ok(())
};
if let Err(e) = write() {
let _ = fs::remove_file(&tmp);
return Err(e);
}
Ok(SigningKey::from_bytes(&seed))
}
fn remove(&self, realm: &RealmId) -> Result<()> {
match fs::remove_file(self.file(realm)) {
Ok(()) => Ok(()),
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(e) => Err(e.into()),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_key_is_created_once_and_read_back() {
let dir = tempfile::tempdir().unwrap();
let store = FileKeyStore::new(dir.path().join("keys"));
let realm = RealmId::new();
assert!(store.load(&realm).unwrap().is_none());
let key = store.create(&realm).unwrap();
assert_eq!(store.load(&realm).unwrap().unwrap().to_bytes(), key.to_bytes());
assert!(store.create(&realm).is_err(), "a key is never replaced");
let other = RealmId::new();
assert_ne!(store.create(&other).unwrap().to_bytes(), key.to_bytes(), "one key per realm");
store.remove(&realm).unwrap();
assert!(store.load(&realm).unwrap().is_none());
store.remove(&realm).unwrap();
let leftovers: Vec<_> = fs::read_dir(dir.path().join("keys")).unwrap().flatten().filter(|e| e.file_name().to_string_lossy().ends_with(".tmp")).collect();
assert!(leftovers.is_empty());
}
#[test]
fn a_damaged_key_file_is_an_error_not_a_new_identity() {
let dir = tempfile::tempdir().unwrap();
let store = FileKeyStore::new(dir.path());
let realm = RealmId::new();
fs::write(dir.path().join(format!("{realm}.key")), "garbage").unwrap();
assert!(store.load(&realm).is_err());
assert!(store.create(&realm).is_err(), "the broken file is not silently replaced");
}
#[cfg(windows)]
#[test]
fn the_key_file_is_not_inherited_from_the_folder() {
let dir = tempfile::tempdir().unwrap();
let store = FileKeyStore::new(dir.path());
let realm = RealmId::new();
store.create(&realm).unwrap();
let out = std::process::Command::new("icacls").arg(dir.path().join(format!("{realm}.key"))).output().unwrap();
let text = String::from_utf8_lossy(&out.stdout).to_string();
assert!(!text.contains("BUILTIN\\Users") && !text.contains("Everyone") && !text.contains("Authenticated Users"), "{text}");
}
}
+19
View File
@@ -0,0 +1,19 @@
//! Publishing a realm to the central Registry (Phase 10): the Host side of registration and presence.
//!
//! The Registry is discovery infrastructure only. What this module sends is the realm's public identity (a UUIDv7 and an Ed25519 public key), a
//! display name, a description, a language, the Manager version, the realm's advertised capabilities and optionally its player count. It never
//! sends or reads a database or console credential, a game account, a character, a canonical revision or a session payload, and it never changes
//! portable state. See `docs/REGISTRY_PROTOCOL.md`.
pub mod advert;
pub mod client;
pub mod host;
pub mod keys;
pub mod runtime;
pub mod settings;
pub use advert::{advertise, AdvertSource, LocalAdvert, LocalRealmsSource};
pub use client::{ClientError, RegistryClient};
pub use host::{PublishState, RealmPublishStatus, RegistryHost, RegistryStatus, Timing};
pub use keys::{FileKeyStore, KeyStore};
pub use runtime::RegistryRuntime;
@@ -0,0 +1,107 @@
//! The publishing loop on its own thread: it starts with the application, keeps going while the interface is elsewhere, and stops with the Manager.
//! Commands are answered between passes; a pass blocks only on the Registry's own timeouts.
use std::path::Path;
use std::sync::mpsc::{self, RecvTimeoutError, Sender};
use std::sync::{Arc, Mutex};
use std::thread::JoinHandle;
use std::time::{Duration, Instant};
use super::advert::AdvertSource;
use super::host::{system_clock, Clock, RegistryHost, RegistryStatus, Timing};
use super::keys::KeyStore;
use crate::{Error, Result};
enum Cmd {
SetUrl(Option<String>, Sender<Result<()>>),
Publish { local_id: String, name: String, description: String, language: String, reply: Sender<Result<()>> },
Unpublish(String, Sender<Result<()>>),
Retry(String),
Shutdown,
}
pub struct RegistryRuntime {
tx: Sender<Cmd>,
status: Arc<Mutex<RegistryStatus>>,
join: Mutex<Option<JoinHandle<()>>>,
}
impl RegistryRuntime {
pub fn start(dir: &Path, keys: Arc<dyn KeyStore>, source: Arc<dyn AdvertSource>) -> Result<Self> {
Self::start_with(dir, keys, source, system_clock(), Timing::default())
}
pub fn start_with(dir: &Path, keys: Arc<dyn KeyStore>, source: Arc<dyn AdvertSource>, clock: Clock, timing: Timing) -> Result<Self> {
let mut host = RegistryHost::open(dir, keys, source, clock, timing, Instant::now())?;
let status = Arc::new(Mutex::new(host.status(Instant::now())));
let (tx, rx) = mpsc::channel::<Cmd>();
let shared = status.clone();
let join = std::thread::Builder::new()
.name("realm-registry".into())
.spawn(move || loop {
match rx.recv_timeout(Duration::from_millis(500)) {
Ok(Cmd::Shutdown) | Err(RecvTimeoutError::Disconnected) => return,
Ok(Cmd::SetUrl(url, reply)) => {
let _ = reply.send(host.set_url(url.as_deref(), Instant::now()));
}
Ok(Cmd::Publish { local_id, name, description, language, reply }) => {
let _ = reply.send(host.publish(&local_id, &name, &description, &language, Instant::now()));
}
Ok(Cmd::Unpublish(local_id, reply)) => {
let _ = reply.send(host.unpublish(&local_id, Instant::now()));
}
Ok(Cmd::Retry(local_id)) => host.retry(&local_id, Instant::now()),
Err(RecvTimeoutError::Timeout) => {}
}
let now = Instant::now();
host.tick(now);
if let Ok(mut s) = shared.lock() {
*s = host.status(now);
}
})
.map_err(Error::Io)?;
Ok(Self { tx, status, join: Mutex::new(Some(join)) })
}
pub fn status(&self) -> RegistryStatus {
self.status.lock().map(|s| s.clone()).unwrap_or_default()
}
fn ask(&self, make: impl FnOnce(Sender<Result<()>>) -> Cmd) -> Result<()> {
let (reply, answer) = mpsc::channel();
self.tx.send(make(reply)).map_err(|_| Error::Invalid("the registry loop has stopped".into()))?;
answer.recv_timeout(Duration::from_secs(30)).map_err(|_| Error::Invalid("the registry loop did not answer".into()))?
}
pub fn set_url(&self, url: Option<String>) -> Result<()> {
self.ask(|reply| Cmd::SetUrl(url, reply))
}
pub fn publish(&self, local_id: &str, name: &str, description: &str, language: &str) -> Result<()> {
self.ask(|reply| Cmd::Publish { local_id: local_id.into(), name: name.into(), description: description.into(), language: language.into(), reply })
}
pub fn unpublish(&self, local_id: &str) -> Result<()> {
self.ask(|reply| Cmd::Unpublish(local_id.into(), reply))
}
pub fn retry(&self, local_id: &str) {
let _ = self.tx.send(Cmd::Retry(local_id.into()));
}
/// Stop the loop. A published realm is left published: it simply stops being heard of and goes offline after the TTL.
pub fn shutdown(&self) {
let _ = self.tx.send(Cmd::Shutdown);
if let Ok(mut guard) = self.join.lock() {
if let Some(j) = guard.take() {
let _ = j.join();
}
}
}
}
impl Drop for RegistryRuntime {
fn drop(&mut self) {
self.shutdown();
}
}
@@ -0,0 +1,111 @@
//! What the Host remembers about publishing: the Registry's address and, per local realm, whether it is published and under which public identity.
//! No key and no credential is stored here (keys live behind [`KeyStore`](super::keys::KeyStore)).
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use coa_registry_proto::{validate_description, validate_display_name, validate_language, RealmId};
use serde::{Deserialize, Serialize};
use crate::{fsx, Error, Result};
pub const SETTINGS_SCHEMA: u32 = 1;
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PublishConfig {
pub realm_id: Option<RealmId>,
pub enabled: bool,
pub display_name: String,
pub description: String,
pub language: String,
}
impl PublishConfig {
pub fn validate(&self) -> Result<()> {
validate_display_name(&self.display_name).map_err(|e| Error::Invalid(e.to_string()))?;
validate_description(&self.description).map_err(|e| Error::Invalid(e.to_string()))?;
validate_language(&self.language).map_err(|e| Error::Invalid(e.to_string()))?;
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RegistrySettings {
pub schema: u32,
/// The Registry's base address, e.g. `http://host` or `https://registry.example` (no path).
pub url: Option<String>,
/// Keyed by the local realm id (`srv-<install id>` or a prepared realm's id).
pub realms: BTreeMap<String, PublishConfig>,
}
impl Default for RegistrySettings {
fn default() -> Self {
Self { schema: SETTINGS_SCHEMA, url: None, realms: BTreeMap::new() }
}
}
/// A Registry address: http or https, a host, an optional port, nothing else.
pub fn validate_url(url: &str) -> Result<String> {
let trimmed = url.trim().trim_end_matches('/');
let rest = trimmed.strip_prefix("http://").or_else(|| trimmed.strip_prefix("https://")).ok_or_else(|| Error::Invalid("the Registry address must start with http:// or https://".into()))?;
if rest.is_empty() || rest.contains(['/', '?', '#', '@', ' ']) {
return Err(Error::Invalid("the Registry address is a host and an optional port, nothing else".into()));
}
let host = rest.rsplit_once(':').map(|(h, p)| if p.bytes().all(|b| b.is_ascii_digit()) && !p.is_empty() { h } else { rest }).unwrap_or(rest);
if !crate::client::host_ok(host) || host.contains(':') {
return Err(Error::Invalid("the Registry host is not a host name or an IPv4 address".into()));
}
Ok(trimmed.to_string())
}
pub fn file(dir: &Path) -> PathBuf {
dir.join("registry.json")
}
pub fn load(dir: &Path) -> Result<RegistrySettings> {
match std::fs::read(file(dir)) {
Ok(bytes) => {
let s: RegistrySettings = serde_json::from_slice(&bytes)?;
if s.schema != SETTINGS_SCHEMA {
return Err(Error::Invalid(format!("registry settings schema {} is not supported", s.schema)));
}
Ok(s)
}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(RegistrySettings::default()),
Err(e) => Err(e.into()),
}
}
pub fn save(dir: &Path, settings: &RegistrySettings) -> Result<()> {
fsx::atomic_write(&file(dir), &serde_json::to_vec_pretty(settings)?)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn addresses_are_a_host_and_a_port_only() {
assert_eq!(validate_url("http://127.0.0.1:8080/").unwrap(), "http://127.0.0.1:8080");
assert_eq!(validate_url(" https://registry.example ").unwrap(), "https://registry.example");
for bad in ["", "ftp://x", "registry.example", "http://", "http://x/registry", "http://user:pw@x", "http://x?y=1", "http://x y", "http://[::1]:80", "http://x:abc"] {
assert!(validate_url(bad).is_err(), "{bad}");
}
}
#[test]
fn settings_round_trip_and_refuse_what_they_do_not_know() {
let dir = tempfile::tempdir().unwrap();
assert_eq!(load(dir.path()).unwrap(), RegistrySettings::default());
let mut s = RegistrySettings { url: Some("http://x".into()), ..Default::default() };
s.realms.insert("srv-1".into(), PublishConfig { realm_id: Some(RealmId::new()), enabled: true, display_name: "A".into(), description: String::new(), language: "en".into() });
save(dir.path(), &s).unwrap();
assert_eq!(load(dir.path()).unwrap(), s);
let text = std::fs::read_to_string(file(dir.path())).unwrap();
assert!(!text.contains("key") && !text.contains("password"), "{text}");
std::fs::write(file(dir.path()), r#"{"schema":1,"url":null,"realms":{},"private_key":"x"}"#).unwrap();
assert!(load(dir.path()).is_err());
}
}
+19
View File
@@ -0,0 +1,19 @@
[package]
name = "coa-registry-proto"
description = "Wire protocol of the CoA realm Registry (version 1): types, limits, validation and signed-request canonicalisation. No I/O."
version = "0.1.0"
edition = "2021"
license = "AGPL-3.0-only"
publish = false
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sha2 = "0.10"
hex = "0.4"
base64 = "0.22"
uuid = { version = "1", features = ["serde", "v7"] }
ed25519-dalek = "2"
thiserror = "2"
[dev-dependencies]
+312
View File
@@ -0,0 +1,312 @@
//! The form of `RealmCapabilities` (Manager profile version 2) that a realm advertises to the Registry.
//!
//! The types mirror `coa_core::portable::capabilities` field for field (same names, same order: the content hash is taken over the JSON,
//! so the order is part of the contract), with the limits of a public, hostile-input boundary added. `coa-core` has a test that a real
//! profile parses into this type and keeps its hash, so the two cannot drift apart unnoticed. What the Registry stores is host-advertised
//! discovery metadata: a future JOIN negotiates the capabilities again with the live Host.
use std::collections::{BTreeMap, BTreeSet};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use crate::{invalid, Result};
pub const PROFILE_VERSION: u32 = 2;
pub const MAX_EXTENSIONS: usize = 64;
pub const MAX_COLLECTION_KINDS: usize = 16;
pub const MAX_JOB_FORMATS: usize = 16;
pub const MAX_CATALOG_ENTRIES: usize = 8;
const MAX_TOKEN: usize = 64;
const MAX_IDENTITY: usize = 128;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Ruleset {
Coa,
Wildcard,
}
impl Ruleset {
pub fn as_str(self) -> &'static str {
match self {
Ruleset::Coa => "coa",
Ruleset::Wildcard => "wildcard",
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Feature {
RuntimeSessions,
Wardrobe,
Collections,
LevelProjection,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FormatRange {
pub min: u32,
pub max: u32,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CharacterFormats {
pub readable: FormatRange,
pub writable: FormatRange,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CatalogEntry {
pub sha256: String,
pub records: u32,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExtensionSupport {
pub namespace: String,
pub module_version: String,
pub formats: FormatRange,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CoreIdentity {
pub commit: String,
pub branch: String,
pub date: String,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ContentProfile {
pub ruleset: Ruleset,
pub character_formats: CharacterFormats,
pub online_import_job_formats: Vec<u32>,
pub session_protocol: u32,
pub collection_protocol: u32,
pub features: BTreeSet<Feature>,
pub collection_kinds: BTreeSet<String>,
pub extensions: Vec<ExtensionSupport>,
pub client_catalog: BTreeMap<String, CatalogEntry>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Progression {
pub max_player_level: u32,
pub projection_protocol: u32,
pub projection_policy_version: u32,
pub progression_signature: String,
pub scaling_enabled: bool,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AdvertisedCapabilities {
pub profile_version: u32,
pub core: Option<CoreIdentity>,
pub content: ContentProfile,
pub content_profile_hash: String,
#[serde(default)]
pub progression: Option<Progression>,
}
fn hex64(s: &str) -> bool {
s.len() == 64 && s.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}
fn token(s: &str, what: &str) -> Result<()> {
if s.is_empty() || s.len() > MAX_TOKEN || !s.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-' | b'_' | b':' | b'+')) {
return invalid(format!("capabilities: {what} is not a short token"));
}
Ok(())
}
fn identity_text(s: &str, what: &str) -> Result<()> {
if s.len() > MAX_IDENTITY || s.chars().any(char::is_control) {
return invalid(format!("capabilities: {what} is too long or has control characters"));
}
Ok(())
}
fn range(r: &FormatRange, what: &str) -> Result<()> {
if r.min < 1 || r.min > r.max || r.max > 1000 {
return invalid(format!("capabilities: {what} is not a sane version range"));
}
Ok(())
}
impl ContentProfile {
/// SHA-256 of the canonical JSON, as the Manager computes it (`coa-content-profile-v1\0` + the JSON with the extensions sorted).
pub fn hash(&self) -> String {
let mut canonical = self.clone();
canonical.extensions.sort_by(|a, b| a.namespace.cmp(&b.namespace));
let json = serde_json::to_vec(&canonical).expect("a profile serialises");
let mut h = Sha256::new();
h.update(b"coa-content-profile-v1\0");
h.update(json);
hex::encode(h.finalize())
}
}
impl AdvertisedCapabilities {
/// Bounds on everything, and the declared hash must be the hash of the content.
pub fn validate(&self) -> Result<()> {
if self.profile_version != PROFILE_VERSION {
return invalid(format!("capabilities: profile version {} is not supported (expected {PROFILE_VERSION})", self.profile_version));
}
let c = &self.content;
range(&c.character_formats.readable, "the readable character formats")?;
range(&c.character_formats.writable, "the writable character formats")?;
if c.online_import_job_formats.len() > MAX_JOB_FORMATS || c.online_import_job_formats.iter().any(|v| *v == 0 || *v > 1000) {
return invalid("capabilities: the import job formats are out of range");
}
if c.session_protocol > 1000 || c.collection_protocol > 1000 {
return invalid("capabilities: a protocol version is out of range");
}
if c.collection_kinds.len() > MAX_COLLECTION_KINDS {
return invalid("capabilities: too many collection kinds");
}
for k in &c.collection_kinds {
token(k, "a collection kind")?;
}
if c.extensions.len() > MAX_EXTENSIONS {
return invalid("capabilities: too many extensions");
}
let mut seen = BTreeSet::new();
for e in &c.extensions {
token(&e.namespace, "an extension namespace")?;
token(&e.module_version, "an extension version")?;
range(&e.formats, "an extension's formats")?;
if !seen.insert(&e.namespace) {
return invalid("capabilities: an extension is listed twice");
}
}
if c.client_catalog.len() > MAX_CATALOG_ENTRIES {
return invalid("capabilities: too many client tables");
}
for (name, entry) in &c.client_catalog {
if name.is_empty() || name.len() > MAX_TOKEN || !name.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-')) {
return invalid("capabilities: a client table name is not a plain file name");
}
if !hex64(&entry.sha256) || entry.records > 100_000_000 {
return invalid("capabilities: a client table entry is malformed");
}
}
if let Some(core) = &self.core {
identity_text(&core.commit, "the core commit")?;
identity_text(&core.branch, "the core branch")?;
identity_text(&core.date, "the core date")?;
}
if let Some(p) = &self.progression {
if p.max_player_level == 0 || p.max_player_level > 255 || p.projection_protocol == 0 || p.projection_protocol > 1000 || p.projection_policy_version == 0 || p.projection_policy_version > 1000 {
return invalid("capabilities: the progression numbers are out of range");
}
if !hex64(&p.progression_signature) {
return invalid("capabilities: the progression signature is not a SHA-256");
}
}
if !hex64(&self.content_profile_hash) {
return invalid("capabilities: the content hash is not a SHA-256");
}
if self.content.hash() != self.content_profile_hash {
return invalid("capabilities: the content hash is not the hash of the content");
}
Ok(())
}
/// The hash that identifies this advertisement (the content hash plus the progression signature: both change what a Host can take).
pub fn advert_hash(&self) -> String {
let mut h = Sha256::new();
h.update(b"coa-registry-advert-v1\0");
h.update(self.content_profile_hash.as_bytes());
match &self.progression {
Some(p) => {
h.update(b"\x01");
h.update(p.max_player_level.to_be_bytes());
h.update(p.projection_protocol.to_be_bytes());
h.update(p.projection_policy_version.to_be_bytes());
h.update(p.progression_signature.as_bytes());
h.update([p.scaling_enabled as u8]);
}
None => h.update(b"\x00"),
}
hex::encode(h.finalize())
}
}
#[cfg(test)]
pub(crate) mod tests {
use super::*;
pub(crate) fn sample() -> AdvertisedCapabilities {
let content = ContentProfile {
ruleset: Ruleset::Coa,
character_formats: CharacterFormats { readable: FormatRange { min: 1, max: 2 }, writable: FormatRange { min: 2, max: 2 } },
online_import_job_formats: vec![2],
session_protocol: 2,
collection_protocol: 1,
features: [Feature::RuntimeSessions, Feature::Wardrobe, Feature::LevelProjection].into_iter().collect(),
collection_kinds: ["coa:appearance".to_string()].into_iter().collect(),
extensions: vec![ExtensionSupport { namespace: "coa".into(), module_version: "1".into(), formats: FormatRange { min: 1, max: 1 } }],
client_catalog: [("Appearances.dbc".to_string(), CatalogEntry { sha256: "a".repeat(64), records: 5 })].into_iter().collect(),
};
let content_profile_hash = content.hash();
AdvertisedCapabilities {
profile_version: 2,
core: Some(CoreIdentity { commit: "abc123".into(), branch: "main".into(), date: "2026-10-01".into() }),
content,
content_profile_hash,
progression: Some(Progression { max_player_level: 60, projection_protocol: 1, projection_policy_version: 1, progression_signature: "b".repeat(64), scaling_enabled: false }),
}
}
#[test]
fn a_sound_advertisement_validates_and_a_lying_hash_does_not() {
sample().validate().unwrap();
let mut c = sample();
c.content_profile_hash = "0".repeat(64);
assert!(c.validate().is_err());
let mut c = sample();
c.content.session_protocol = 3;
assert!(c.validate().is_err(), "the content changed under the same hash");
}
#[test]
fn hostile_content_is_bounded() {
let mut c = sample();
c.content.extensions = (0..65).map(|i| ExtensionSupport { namespace: format!("ns{i}"), module_version: "1".into(), formats: FormatRange { min: 1, max: 1 } }).collect();
c.content_profile_hash = c.content.hash();
assert!(c.validate().is_err());
let mut c = sample();
c.content.client_catalog.insert("../../x".into(), CatalogEntry { sha256: "a".repeat(64), records: 1 });
c.content_profile_hash = c.content.hash();
assert!(c.validate().is_err());
let mut c = sample();
c.core.as_mut().unwrap().branch = "x".repeat(10_000);
assert!(c.validate().is_err());
let mut c = sample();
c.content.collection_kinds.insert("<script>".into());
c.content_profile_hash = c.content.hash();
assert!(c.validate().is_err());
assert!(serde_json::from_str::<AdvertisedCapabilities>(r#"{"profile_version":2,"extra":1}"#).is_err(), "unknown fields");
}
#[test]
fn the_advert_hash_moves_with_the_progression() {
let a = sample();
let mut b = sample();
b.progression.as_mut().unwrap().max_player_level = 70;
assert_ne!(a.advert_hash(), b.advert_hash());
assert_eq!(a.advert_hash(), sample().advert_hash());
let mut c = sample();
c.progression = None;
assert_ne!(a.advert_hash(), c.advert_hash());
}
}
+66
View File
@@ -0,0 +1,66 @@
//! The wire protocol of the CoA realm Registry, version 1 (Phase 10).
//!
//! The Registry is discovery and presence infrastructure only. Everything in this crate is public, host-advertised metadata:
//! it never carries a credential, a character, a snapshot or a session payload. The protocol version is the Registry's own and
//! is unrelated to the portable character, session or capability-profile versions.
//!
//! * [`sign`]: the canonical signed-request input and Ed25519 helpers (see `docs/REGISTRY_PROTOCOL.md`).
//! * [`wire`]: request and response bodies with their limits and validation.
//! * [`caps`]: the strict, bounded form of `RealmCapabilities` a realm advertises.
pub mod caps;
pub mod sign;
pub mod wire;
pub use caps::AdvertisedCapabilities;
pub use sign::{RealmId, SignedHeaders};
pub use wire::*;
/// The only protocol version this crate speaks.
pub const REGISTRY_PROTOCOL_VERSION: u32 = 1;
/// The largest request body any endpoint accepts.
pub const MAX_REQUEST_BYTES: usize = 64 * 1024;
/// A realm's display name, in characters.
pub const MAX_DISPLAY_NAME_CHARS: usize = 80;
/// A realm's description, in UTF-8 bytes.
pub const MAX_DESCRIPTION_BYTES: usize = 1024;
/// The longest language tag.
pub const MAX_LANGUAGE_BYTES: usize = 16;
/// The longest Manager version string.
pub const MAX_VERSION_BYTES: usize = 32;
/// Players or capacity above this are refused as nonsense.
pub const MAX_PLAYER_NUMBER: u32 = 100_000;
/// How often a Host sends a heartbeat.
pub const HEARTBEAT_INTERVAL_SECS: u64 = 30;
/// A realm that has not been heard of for this long is offline (it is never deleted for it).
pub const ONLINE_TTL_SECS: u64 = 120;
/// How far a request's timestamp may be from the Registry's clock.
pub const MAX_CLOCK_SKEW_SECS: i64 = 300;
pub const PATH_PREFIX: &str = "/registry/v1";
pub const PATH_REGISTER: &str = "/registry/v1/realms/register";
pub const PATH_HEALTHZ: &str = "/registry/v1/healthz";
pub fn path_heartbeat(realm: &RealmId) -> String {
format!("{PATH_PREFIX}/realms/{realm}/heartbeat")
}
pub fn path_unpublish(realm: &RealmId) -> String {
format!("{PATH_PREFIX}/realms/{realm}/unpublish")
}
pub fn path_self(realm: &RealmId) -> String {
format!("{PATH_PREFIX}/realms/{realm}")
}
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum ProtoError {
#[error("{0}")]
Invalid(String),
}
pub type Result<T> = std::result::Result<T, ProtoError>;
pub(crate) fn invalid<T>(what: impl Into<String>) -> Result<T> {
Err(ProtoError::Invalid(what.into()))
}
+251
View File
@@ -0,0 +1,251 @@
//! Signed requests. One canonical input, one algorithm (Ed25519); see `docs/REGISTRY_PROTOCOL.md` for the format and test vectors.
//!
//! ```text
//! coa-registry-sig-v1
//! <protocol version> decimal
//! <HTTP method> upper case
//! <request path> exactly as sent, no query
//! <realm id> lower-case hyphenated UUID
//! <unix timestamp> decimal seconds
//! <hex SHA-256 of the body> lower case; the empty body for a GET
//! ```
//!
//! The lines are joined with `\n` (no trailing newline) and the UTF-8 bytes are signed. The signature travels base64url (no padding).
use base64::engine::general_purpose::URL_SAFE_NO_PAD as B64;
use base64::Engine;
use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
use sha2::{Digest, Sha256};
use uuid::Uuid;
use crate::{invalid, Result, REGISTRY_PROTOCOL_VERSION};
pub const SIGNATURE_DOMAIN: &str = "coa-registry-sig-v1";
pub const HEADER_VERSION: &str = "x-coa-registry-version";
pub const HEADER_REALM: &str = "x-coa-realm";
pub const HEADER_TIMESTAMP: &str = "x-coa-timestamp";
pub const HEADER_SIGNATURE: &str = "x-coa-signature";
/// A realm's persistent identity: a UUIDv7, in its one canonical spelling.
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct RealmId(Uuid);
impl RealmId {
pub fn new() -> Self {
Self(Uuid::now_v7())
}
/// Only the canonical form (lower case, hyphenated) of a version-7 UUID is accepted, so one id has one spelling in the signed input.
pub fn parse(text: &str) -> Result<Self> {
let Ok(uuid) = Uuid::parse_str(text) else { return invalid("the realm id is not a UUID") };
if uuid.get_version_num() != 7 || uuid.get_variant() != uuid::Variant::RFC4122 {
return invalid("the realm id is not a version-7 UUID");
}
if uuid.hyphenated().to_string() != text {
return invalid("the realm id is not in canonical form");
}
Ok(Self(uuid))
}
pub fn as_uuid(&self) -> Uuid {
self.0
}
pub fn from_uuid(uuid: Uuid) -> Result<Self> {
Self::parse(&uuid.hyphenated().to_string())
}
}
impl Default for RealmId {
fn default() -> Self {
Self::new()
}
}
impl std::fmt::Display for RealmId {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.0.hyphenated())
}
}
impl std::fmt::Debug for RealmId {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "RealmId({self})")
}
}
impl serde::Serialize for RealmId {
fn serialize<S: serde::Serializer>(&self, s: S) -> std::result::Result<S::Ok, S::Error> {
s.collect_str(self)
}
}
impl<'de> serde::Deserialize<'de> for RealmId {
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
let text = String::deserialize(d)?;
Self::parse(&text).map_err(serde::de::Error::custom)
}
}
/// The exact bytes that are signed.
pub fn signature_input(method: &str, path: &str, realm: &RealmId, timestamp: i64, body: &[u8]) -> Vec<u8> {
format!("{SIGNATURE_DOMAIN}\n{REGISTRY_PROTOCOL_VERSION}\n{}\n{path}\n{realm}\n{timestamp}\n{}", method.to_ascii_uppercase(), hex::encode(Sha256::digest(body))).into_bytes()
}
/// The four headers of a signed request.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SignedHeaders {
pub version: u32,
pub realm: RealmId,
pub timestamp: i64,
pub signature: [u8; 64],
}
impl SignedHeaders {
pub fn pairs(&self) -> [(&'static str, String); 4] {
[
(HEADER_VERSION, self.version.to_string()),
(HEADER_REALM, self.realm.to_string()),
(HEADER_TIMESTAMP, self.timestamp.to_string()),
(HEADER_SIGNATURE, B64.encode(self.signature)),
]
}
/// Read the headers from whatever the transport offers. A missing or malformed header is an error; the protocol version is checked by the caller.
pub fn parse<'a>(get: impl Fn(&str) -> Option<&'a str>) -> Result<Self> {
let need = |name: &str| get(name).ok_or_else(|| crate::ProtoError::Invalid(format!("the {name} header is missing")));
let version: u32 = need(HEADER_VERSION)?.parse().map_err(|_| crate::ProtoError::Invalid("the protocol version header is not a number".into()))?;
let realm = RealmId::parse(need(HEADER_REALM)?)?;
let timestamp: i64 = need(HEADER_TIMESTAMP)?.parse().map_err(|_| crate::ProtoError::Invalid("the timestamp header is not a number".into()))?;
let sig = need(HEADER_SIGNATURE)?;
if sig.len() != 86 {
return invalid("the signature header has the wrong length");
}
let bytes = B64.decode(sig).map_err(|_| crate::ProtoError::Invalid("the signature header is not base64url".into()))?;
let signature: [u8; 64] = bytes.try_into().map_err(|_| crate::ProtoError::Invalid("the signature is not 64 bytes".into()))?;
Ok(Self { version, realm, timestamp, signature })
}
}
/// Sign a request. The caller chooses the timestamp (it must grow with every request of one realm).
pub fn sign_request(key: &SigningKey, method: &str, path: &str, realm: &RealmId, timestamp: i64, body: &[u8]) -> SignedHeaders {
let signature = key.sign(&signature_input(method, path, realm, timestamp, body)).to_bytes();
SignedHeaders { version: REGISTRY_PROTOCOL_VERSION, realm: *realm, timestamp, signature }
}
/// Verify a request against a public key. Strict: a signature that merely validates under a weak key or a non-canonical encoding is refused.
pub fn verify_request(public: &VerifyingKey, headers: &SignedHeaders, method: &str, path: &str, body: &[u8]) -> bool {
let input = signature_input(method, path, &headers.realm, headers.timestamp, body);
public.verify_strict(&input, &Signature::from_bytes(&headers.signature)).is_ok()
}
pub fn encode_public_key(key: &VerifyingKey) -> String {
B64.encode(key.as_bytes())
}
pub fn decode_public_key(text: &str) -> Result<VerifyingKey> {
if text.len() != 43 {
return invalid("the public key has the wrong length");
}
let bytes = B64.decode(text).map_err(|_| crate::ProtoError::Invalid("the public key is not base64url".into()))?;
let array: [u8; 32] = bytes.try_into().map_err(|_| crate::ProtoError::Invalid("the public key is not 32 bytes".into()))?;
let key = VerifyingKey::from_bytes(&array).map_err(|_| crate::ProtoError::Invalid("the public key is not a valid Ed25519 key".into()))?;
if key.is_weak() {
return invalid("the public key is a weak key");
}
Ok(key)
}
#[cfg(test)]
mod tests {
use super::*;
const REALM: &str = "018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d";
fn key() -> SigningKey {
SigningKey::from_bytes(&[7u8; 32])
}
#[test]
fn realm_ids_have_one_spelling() {
assert!(RealmId::parse(REALM).is_ok());
assert!(RealmId::parse(&REALM.to_uppercase()).is_err(), "upper case is another spelling");
assert!(RealmId::parse(&REALM.replace('-', "")).is_err(), "so is the simple form");
assert!(RealmId::parse("018f2d9e-5c3a-4b21-8c4d-0e5f6a7b8c9d").is_err(), "version 4 is not an identity");
assert!(RealmId::parse("018f2d9e-5c3a-7b21-0c4d-0e5f6a7b8c9d").is_err(), "nor is a foreign variant");
assert!(RealmId::parse("../../etc").is_err());
assert!(RealmId::parse("").is_err());
assert_eq!(RealmId::new().to_string().len(), 36);
}
/// The deterministic vector documented in `docs/REGISTRY_PROTOCOL.md`: Ed25519 signatures are deterministic, so this never changes.
#[test]
fn the_documented_test_vector() {
let realm = RealmId::parse(REALM).unwrap();
let key = key();
assert_eq!(encode_public_key(&key.verifying_key()), VECTOR_PUBLIC_KEY);
let body = br#"{"protocol_version":1}"#;
let input = signature_input("post", "/registry/v1/realms/018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d/heartbeat", &realm, 1_790_000_000, body);
assert_eq!(String::from_utf8(input).unwrap(), VECTOR_INPUT);
let headers = sign_request(&key, "POST", "/registry/v1/realms/018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d/heartbeat", &realm, 1_790_000_000, body);
assert_eq!(B64.encode(headers.signature), VECTOR_SIGNATURE);
assert!(verify_request(&key.verifying_key(), &headers, "POST", "/registry/v1/realms/018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d/heartbeat", body));
}
/// The second documented vector: a GET has the empty body, whose SHA-256 is `e3b0c442...`.
#[test]
fn the_documented_vector_of_a_read() {
let realm = RealmId::parse(REALM).unwrap();
let headers = sign_request(&key(), "GET", "/registry/v1/realms/018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d", &realm, 1_790_000_030, b"");
assert_eq!(B64.encode(headers.signature), "38nHMS6yvl8yrTbLmG1w5LiLVkvTaiRdQPrgT2GSvtR8jW_W0z50IRxD_kInBYP5Yl1Qwwm-r6BVDdTR5ts-BQ");
}
const VECTOR_PUBLIC_KEY: &str = "6kpsY-KcUgq-9VB7Ey7F-ZVHdq6-vnuSQh7qaRRG0iw";
const VECTOR_INPUT: &str = "coa-registry-sig-v1
1
POST
/registry/v1/realms/018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d/heartbeat
018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d
1790000000
00aa4c2c857995eb8e19cb0fade07e4b49aac774e37a99c37a0c9f549204d9de";
const VECTOR_SIGNATURE: &str = "1ys2C7RVjhEtTl0bVrdowpuPELwOnhuiYZKp88dAWdcA3cezP9QuI903OJi2N2mFA9kifblD_fvdT2B_8F5_Dw";
#[test]
fn every_part_of_the_input_is_covered() {
let realm = RealmId::parse(REALM).unwrap();
let other = RealmId::parse("018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9e").unwrap();
let key = key();
let path = "/registry/v1/realms/x";
let h = sign_request(&key, "POST", path, &realm, 100, b"body");
let public = key.verifying_key();
assert!(verify_request(&public, &h, "POST", path, b"body"));
assert!(!verify_request(&public, &h, "POST", path, b"bodY"), "the body");
assert!(!verify_request(&public, &h, "POST", "/registry/v1/realms/y", b"body"), "the path");
assert!(!verify_request(&public, &h, "GET", path, b"body"), "the method");
assert!(!verify_request(&public, &SignedHeaders { realm: other, ..h.clone() }, "POST", path, b"body"), "the realm");
assert!(!verify_request(&public, &SignedHeaders { timestamp: 101, ..h.clone() }, "POST", path, b"body"), "the timestamp");
assert!(!verify_request(&SigningKey::from_bytes(&[8u8; 32]).verifying_key(), &h, "POST", path, b"body"), "the key");
}
#[test]
fn headers_round_trip_and_hostile_ones_are_refused() {
let realm = RealmId::parse(REALM).unwrap();
let h = sign_request(&key(), "POST", "/p", &realm, 5, b"");
let pairs = h.pairs();
let get = |name: &str| pairs.iter().find(|(n, _)| *n == name).map(|(_, v)| v.as_str());
assert_eq!(SignedHeaders::parse(get).unwrap(), h);
assert!(SignedHeaders::parse(|n| if n == HEADER_SIGNATURE { None } else { get(n) }).is_err());
assert!(SignedHeaders::parse(|n| if n == HEADER_SIGNATURE { Some("AAAA") } else { get(n) }).is_err());
assert!(SignedHeaders::parse(|n| if n == HEADER_TIMESTAMP { Some("12x") } else { get(n) }).is_err());
assert!(SignedHeaders::parse(|n| if n == HEADER_REALM { Some("nope") } else { get(n) }).is_err());
}
#[test]
fn public_keys_are_checked() {
assert!(decode_public_key(&encode_public_key(&key().verifying_key())).is_ok());
assert!(decode_public_key("short").is_err());
assert!(decode_public_key(&B64.encode([0u8; 32])).is_err(), "the identity point is a weak key");
assert!(decode_public_key(&"A".repeat(43)).is_err());
}
}
+363
View File
@@ -0,0 +1,363 @@
//! Request and response bodies of Registry protocol 1. Every request type refuses unknown fields and validates its own bounds.
use serde::{Deserialize, Serialize};
use crate::caps::{AdvertisedCapabilities, Ruleset};
use crate::sign::RealmId;
use crate::{invalid, Result, MAX_DESCRIPTION_BYTES, MAX_DISPLAY_NAME_CHARS, MAX_LANGUAGE_BYTES, MAX_PLAYER_NUMBER, MAX_VERSION_BYTES, REGISTRY_PROTOCOL_VERSION};
fn bidi_or_control(c: char, allow_newline: bool) -> bool {
(c.is_control() && !(allow_newline && c == '\n')) || matches!(c, '\u{200E}' | '\u{200F}' | '\u{202A}'..='\u{202E}' | '\u{2066}'..='\u{2069}' | '\u{FEFF}' | '\u{2028}' | '\u{2029}')
}
/// Plain text only: the Registry stores text and never HTML, and a consumer must render it as text.
pub fn validate_display_name(s: &str) -> Result<()> {
let n = s.chars().count();
if n == 0 || n > MAX_DISPLAY_NAME_CHARS {
return invalid(format!("the display name must be 1 to {MAX_DISPLAY_NAME_CHARS} characters"));
}
if s != s.trim() || s.chars().any(|c| bidi_or_control(c, false)) {
return invalid("the display name has control characters, direction overrides or surrounding spaces");
}
Ok(())
}
pub fn validate_description(s: &str) -> Result<()> {
if s.len() > MAX_DESCRIPTION_BYTES {
return invalid(format!("the description is limited to {MAX_DESCRIPTION_BYTES} bytes"));
}
if s.chars().any(|c| bidi_or_control(c, true)) {
return invalid("the description has control characters or direction overrides");
}
Ok(())
}
/// A short language tag such as `en`, `ru`, `pt-BR`.
pub fn validate_language(s: &str) -> Result<()> {
let ok = !s.is_empty() && s.len() <= MAX_LANGUAGE_BYTES && s.split('-').enumerate().all(|(i, part)| !part.is_empty() && part.len() <= 8 && part.bytes().all(|b| b.is_ascii_alphanumeric()) && (i > 0 || part.bytes().all(|b| b.is_ascii_lowercase()) && part.len() >= 2));
if !ok {
return invalid("the language is not a short language tag");
}
Ok(())
}
pub fn validate_version(s: &str) -> Result<()> {
if s.is_empty() || s.len() > MAX_VERSION_BYTES || !s.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-' | b'+' | b'_')) {
return invalid("the Manager version is not a short version string");
}
Ok(())
}
pub fn validate_players(count: Option<u32>, capacity: Option<u32>) -> Result<()> {
if count.is_some_and(|n| n > MAX_PLAYER_NUMBER) || capacity.is_some_and(|n| n > MAX_PLAYER_NUMBER) {
return invalid("a player number is out of range");
}
if let (Some(c), Some(cap)) = (count, capacity) {
if c > cap {
return invalid("more players than capacity");
}
}
Ok(())
}
fn check_version(v: u32) -> Result<()> {
if v != REGISTRY_PROTOCOL_VERSION {
return invalid(format!("protocol version {v} is not supported"));
}
Ok(())
}
fn hex64(s: &str) -> bool {
s.len() == 64 && s.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RegisterRequest {
pub protocol_version: u32,
pub realm_id: RealmId,
/// Base64url (no padding) of the 32-byte Ed25519 public key.
pub public_key: String,
pub display_name: String,
pub description: String,
pub language: String,
pub ruleset: Ruleset,
pub manager_version: String,
pub capabilities: AdvertisedCapabilities,
/// [`AdvertisedCapabilities::advert_hash`]
pub capabilities_hash: String,
#[serde(default)]
pub player_count: Option<u32>,
#[serde(default)]
pub player_capacity: Option<u32>,
}
impl RegisterRequest {
pub fn validate(&self) -> Result<()> {
check_version(self.protocol_version)?;
crate::sign::decode_public_key(&self.public_key)?;
validate_display_name(&self.display_name)?;
validate_description(&self.description)?;
validate_language(&self.language)?;
validate_version(&self.manager_version)?;
validate_players(self.player_count, self.player_capacity)?;
self.capabilities.validate()?;
if self.capabilities.content.ruleset != self.ruleset {
return invalid("the ruleset is not the ruleset of the capabilities");
}
if !hex64(&self.capabilities_hash) || self.capabilities_hash != self.capabilities.advert_hash() {
return invalid("the capabilities hash is not the hash of the capabilities");
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HeartbeatRequest {
pub protocol_version: u32,
/// The hash of the capabilities the Host advertises now.
pub capabilities_hash: String,
/// Present when the Host's hash differs from the one the Registry last acknowledged.
#[serde(default)]
pub capabilities: Option<AdvertisedCapabilities>,
#[serde(default)]
pub manager_version: Option<String>,
#[serde(default)]
pub player_count: Option<u32>,
#[serde(default)]
pub player_capacity: Option<u32>,
#[serde(default)]
pub display_name: Option<String>,
#[serde(default)]
pub description: Option<String>,
#[serde(default)]
pub language: Option<String>,
}
impl HeartbeatRequest {
pub fn validate(&self) -> Result<()> {
check_version(self.protocol_version)?;
if !hex64(&self.capabilities_hash) {
return invalid("the capabilities hash is not a SHA-256");
}
if let Some(c) = &self.capabilities {
c.validate()?;
if c.advert_hash() != self.capabilities_hash {
return invalid("the capabilities hash is not the hash of the capabilities");
}
}
if let Some(v) = &self.manager_version {
validate_version(v)?;
}
if let Some(n) = &self.display_name {
validate_display_name(n)?;
}
if let Some(d) = &self.description {
validate_description(d)?;
}
if let Some(l) = &self.language {
validate_language(l)?;
}
validate_players(self.player_count, self.player_capacity)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UnpublishRequest {
pub protocol_version: u32,
}
impl UnpublishRequest {
pub fn validate(&self) -> Result<()> {
check_version(self.protocol_version)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct RegisterResponse {
pub protocol_version: u32,
pub realm_id: RealmId,
pub created: bool,
pub metadata_revision: u64,
pub published: bool,
pub capabilities_hash: String,
pub server_time: i64,
pub heartbeat_interval_secs: u64,
pub online_ttl_secs: u64,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct HeartbeatResponse {
pub protocol_version: u32,
pub metadata_revision: u64,
pub published: bool,
/// The hash the Registry holds now.
pub capabilities_hash: String,
/// The heartbeat carried another hash without the capabilities: send them with the next one.
pub resend_capabilities: bool,
pub server_time: i64,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct UnpublishResponse {
pub protocol_version: u32,
pub published: bool,
pub metadata_revision: u64,
pub server_time: i64,
}
/// What the Registry holds about one realm (the authenticated self endpoint; there is no public list yet).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct SelfResponse {
pub protocol_version: u32,
pub realm_id: RealmId,
pub public_key: String,
pub display_name: String,
pub description: String,
pub language: String,
pub ruleset: Ruleset,
pub manager_version: String,
pub capabilities: AdvertisedCapabilities,
pub capabilities_hash: String,
pub metadata_revision: u64,
pub published: bool,
/// Published and heard of within the online TTL.
pub online: bool,
pub created_at: i64,
pub updated_at: i64,
pub last_seen_at: i64,
pub player_count: Option<u32>,
pub player_capacity: Option<u32>,
pub server_time: i64,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ErrorCode {
MalformedRequest,
UnsupportedProtocolVersion,
RequestTooLarge,
InvalidMetadata,
InvalidRealmId,
InvalidSignature,
BadTimestamp,
TimestampNotMonotonic,
RealmKeyMismatch,
UnknownRealm,
NotPublished,
RateLimited,
Unavailable,
Internal,
}
impl ErrorCode {
/// Errors that repeating the same request cannot fix (the Host stops instead of retrying).
pub fn is_permanent(self) -> bool {
matches!(self, ErrorCode::MalformedRequest | ErrorCode::UnsupportedProtocolVersion | ErrorCode::RequestTooLarge | ErrorCode::InvalidMetadata | ErrorCode::InvalidRealmId | ErrorCode::InvalidSignature | ErrorCode::RealmKeyMismatch)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ErrorBody {
pub error: ErrorDetail,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ErrorDetail {
pub code: ErrorCode,
pub message: String,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Health {
pub status: String,
pub protocol_version: u32,
}
#[cfg(test)]
mod tests {
use super::*;
use crate::caps::tests::sample;
pub(crate) fn register() -> RegisterRequest {
let key = ed25519_dalek::SigningKey::from_bytes(&[7u8; 32]);
let capabilities = sample();
RegisterRequest {
protocol_version: 1,
realm_id: RealmId::parse("018f2d9e-5c3a-7b21-8c4d-0e5f6a7b8c9d").unwrap(),
public_key: crate::sign::encode_public_key(&key.verifying_key()),
display_name: "Friends' realm".into(),
description: "A small realm.\nPlain text.".into(),
language: "en".into(),
ruleset: Ruleset::Coa,
manager_version: "0.6.6".into(),
capabilities_hash: capabilities.advert_hash(),
capabilities,
player_count: Some(2),
player_capacity: Some(100),
}
}
#[test]
fn a_sound_registration_validates() {
register().validate().unwrap();
}
#[test]
fn text_is_plain_and_bounded() {
for bad in ["", " lead", "trail ", "tab\there", "ctl\u{0007}", "rtl\u{202E}name", &"x".repeat(81)] {
assert!(validate_display_name(bad).is_err(), "{bad:?}");
}
assert!(validate_display_name(&"я".repeat(80)).is_ok(), "80 characters, not bytes");
assert!(validate_description(&"x".repeat(1025)).is_err());
assert!(validate_description(&"я".repeat(600)).is_err(), "bytes, not characters");
assert!(validate_description("a\nb").is_ok());
assert!(validate_description("a\r\nb").is_err());
assert!(validate_description("\u{2066}x").is_err());
assert!(validate_language("pt-BR").is_ok() && validate_language("en").is_ok());
for bad in ["", "E", "EN", "en_US", "en-", "-en", "<b>", "x".repeat(17).as_str()] {
assert!(validate_language(bad).is_err(), "{bad:?}");
}
assert!(validate_version("0.6.6").is_ok() && validate_version("0.6.6-rc.1+b2").is_ok());
assert!(validate_version("1 2").is_err() && validate_version("").is_err());
assert!(validate_players(Some(5), Some(4)).is_err() && validate_players(Some(100_001), None).is_err() && validate_players(None, None).is_ok());
}
#[test]
fn the_request_refuses_what_it_does_not_know_and_what_does_not_add_up() {
let mut r = register();
r.protocol_version = 2;
assert!(r.validate().is_err());
let mut r = register();
r.ruleset = Ruleset::Wildcard;
assert!(r.validate().is_err(), "ruleset and capabilities disagree");
let mut r = register();
r.capabilities_hash = "0".repeat(64);
assert!(r.validate().is_err());
let mut value = serde_json::to_value(register()).unwrap();
value.as_object_mut().unwrap().insert("character".into(), serde_json::json!({"name": "x"}));
assert!(serde_json::from_value::<RegisterRequest>(value).is_err(), "no field for a character, and none is accepted");
let mut value = serde_json::to_value(register()).unwrap();
value["realm_id"] = serde_json::json!("018F2D9E-5C3A-7B21-8C4D-0E5F6A7B8C9D");
assert!(serde_json::from_value::<RegisterRequest>(value).is_err());
}
#[test]
fn a_heartbeat_with_capabilities_must_hash_to_its_claim() {
let caps = sample();
let mut h = HeartbeatRequest { protocol_version: 1, capabilities_hash: caps.advert_hash(), capabilities: Some(caps.clone()), manager_version: None, player_count: None, player_capacity: None, display_name: None, description: None, language: None };
h.validate().unwrap();
h.capabilities_hash = "1".repeat(64);
assert!(h.validate().is_err());
h.capabilities = None;
h.validate().unwrap();
}
#[test]
fn permanent_and_transient_errors_are_told_apart() {
assert!(ErrorCode::InvalidSignature.is_permanent() && ErrorCode::RealmKeyMismatch.is_permanent() && ErrorCode::UnsupportedProtocolVersion.is_permanent());
assert!(!ErrorCode::RateLimited.is_permanent() && !ErrorCode::Unavailable.is_permanent() && !ErrorCode::BadTimestamp.is_permanent() && !ErrorCode::UnknownRealm.is_permanent());
}
}