mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-22 11:25:56 +00:00
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:
1 parent
ec40f146aa
commit
1267bcc41e
56 files changed
+10198
-13
No files matched your search
@@ -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"] }
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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}");
|
||||
}
|
||||
}
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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]
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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()))
|
||||
}
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user