//! Types shared by peer configuration, the registry, proxying and fixtures. use std::fmt; use std::path::PathBuf; use jiff::Timestamp; use serde::{Deserialize, Deserializer, Serialize, Serializer}; use url::Url; use crate::config::ConfigError; /// Upper bound on configured peers; keeps health loops and snapshots bounded. pub const MAX_PEERS: usize = 64; /// Validated peer name, `^[a-z0-9][a-z0-9_-]{0,31}$`. /// /// Names end up in URLs, MCP arguments and metric attributes, so the /// character set is deliberately narrow. #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, schemars::JsonSchema)] #[schemars(transparent)] pub struct PeerName(String); impl PeerName { pub fn parse(s: &str) -> Result { let valid = !s.is_empty() && s.len() <= 32 && s.bytes().enumerate().all(|(i, b)| match b { b'a'..=b'z' | b'0'..=b'9' => true, b'_' | b'-' => i > 0, _ => false, }); if !valid { return Err(ConfigError::Invalid(format!( "peer name {s:?} must match ^[a-z0-9][a-z0-9_-]{{0,31}}$" ))); } Ok(Self(s.to_owned())) } pub fn as_str(&self) -> &str { &self.0 } } impl fmt::Display for PeerName { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str(&self.0) } } impl Serialize for PeerName { fn serialize(&self, s: S) -> Result { s.serialize_str(&self.0) } } impl<'de> Deserialize<'de> for PeerName { fn deserialize>(d: D) -> Result { let s = String::deserialize(d)?; Self::parse(&s).map_err(serde::de::Error::custom) } } /// A token value that must never reach logs, `Debug` output or serialized /// config. Only the transport may read it. #[derive(Clone, PartialEq, Eq)] pub struct Secret(String); impl Secret { pub fn new(value: impl Into) -> Self { Self(value.into()) } pub fn expose(&self) -> &str { &self.0 } } impl fmt::Debug for Secret { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("Secret(***)") } } impl fmt::Display for Secret { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("***") } } fn peer_enabled_default() -> bool { true } /// One validated `[[peers.peer]]` entry. The token itself is not held here; /// only the path of the externally managed file. /// /// `enabled` defaults to true, `allow_plain_http` to false, and `ca_file` /// may be omitted: entries often carry only `name`, `url` and `token_file`. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct PeerConfig { pub name: PeerName, pub url: Url, pub token_file: PathBuf, #[serde(default)] pub ca_file: Option, #[serde(default)] pub allow_plain_http: bool, #[serde(default = "peer_enabled_default")] pub enabled: bool, } impl PeerConfig { /// Display form for REST and MCP output. `Url` normalizes an empty path /// to `/`; drop it so `http://beta:1984` does not render as `.../`. pub fn display_url(&self) -> String { let s = self.url.as_str(); if self.url.path() == "/" { s.strip_suffix('/').unwrap_or(s).to_owned() } else { s.to_owned() } } } /// The `[peers]` config section. Defaults keep the feature off. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(default)] pub struct PeersConfig { pub enabled: bool, pub tcp_interval_secs: u64, pub tcp_timeout_secs: u64, pub api_interval_secs: u64, pub api_timeout_secs: u64, pub fail_threshold: u32, pub request_timeout_secs: u64, pub max_response_bytes: u64, pub max_concurrent_per_peer: usize, pub max_concurrent_total: usize, pub deny_cidrs: Vec, pub peer: Vec, } /// Refused by default: link-local and cloud metadata addresses in both /// families, plus the unspecified address. Private LAN ranges stay allowed, /// since that is where peers live. pub const DEFAULT_DENY_CIDRS: [&str; 5] = [ "169.254.0.0/16", "0.0.0.0/8", "fe80::/10", "::/128", "fd00:ec2::254/128", ]; impl Default for PeersConfig { fn default() -> Self { Self { enabled: false, tcp_interval_secs: 10, tcp_timeout_secs: 3, api_interval_secs: 30, api_timeout_secs: 5, fail_threshold: 2, request_timeout_secs: 10, max_response_bytes: 8 * 1024 * 1024, max_concurrent_per_peer: 4, max_concurrent_total: 16, deny_cidrs: DEFAULT_DENY_CIDRS.iter().map(|c| c.to_string()).collect(), peer: Vec::new(), } } } /// Registry snapshot entry, serialized as-is by REST and MCP. #[derive(Debug, Clone, PartialEq, Serialize, schemars::JsonSchema)] pub struct PeerStatus { /// Configured peer name. pub name: PeerName, /// `false` for a peer kept in configuration but not checked. pub enabled: bool, /// Display form of the configured URL; never carries credentials. pub url: String, /// "Server up": a TCP connect to the peer's host and port. pub server: ServerStatus, /// "API running": an authenticated `GET /api/v1/ping`. pub api: ApiStatus, } #[derive(Debug, Clone, PartialEq, Default, Serialize, schemars::JsonSchema)] pub struct ServerStatus { pub up: bool, /// Last change; `None` until the first check and reset on restart. pub since: Option, pub last_checked: Option, /// Failure class such as `timeout` or `unreachable`; never a URL or a secret. pub last_error: Option, pub latency_ms: Option, } #[derive(Debug, Clone, PartialEq, Default, Serialize, schemars::JsonSchema)] pub struct ApiStatus { pub up: bool, /// Last change; `None` until the first check and reset on restart. pub since: Option, pub last_checked: Option, /// Failure class such as `http_500` or `token_file`; never a URL or a secret. pub last_error: Option, pub latency_ms: Option, /// State of the consolidator's credential on the peer. pub auth: AuthState, /// Version the peer reported, when it has the ping route. pub peer_version: Option, } /// `Ok` and `Rejected` refer to our credential; `Unknown` is used before the /// first check and for peers without the authenticated ping endpoint. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, schemars::JsonSchema)] #[serde(rename_all = "snake_case")] pub enum AuthState { Ok, Rejected, #[default] Unknown, } /// Coarse outcome of a check; the precise cause is in [`crate::peers::error::PeerError`]. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] #[serde(rename_all = "snake_case")] pub enum CheckClass { Ok, Unauthorized, HttpError, Timeout, Unreachable, TlsError, } impl CheckClass { pub fn as_str(&self) -> &'static str { match self { Self::Ok => "ok", Self::Unauthorized => "unauthorized", Self::HttpError => "http_error", Self::Timeout => "timeout", Self::Unreachable => "unreachable", Self::TlsError => "tls_error", } } } #[cfg(test)] mod tests { use super::*; fn peer(name: &str, url: &str) -> PeerConfig { PeerConfig { name: PeerName::parse(name).unwrap(), url: Url::parse(url).unwrap(), token_file: PathBuf::from(format!("/run/peers/{name}.token")), ca_file: None, allow_plain_http: false, enabled: true, } } #[test] fn peer_name_accepts_and_rejects() { assert!(PeerName::parse("a").is_ok()); assert!(PeerName::parse("minipc1").is_ok()); assert!(PeerName::parse("a_b-c9").is_ok()); assert!(PeerName::parse(&"a".repeat(32)).is_ok()); for bad in ["", "-a", "_a", "Beta", "beta!", "a b", &"a".repeat(33)] { assert!(PeerName::parse(bad).is_err(), "{bad:?} should be rejected"); } } #[test] fn peer_name_serde_roundtrip_and_validation() { let n = PeerName::parse("beta").unwrap(); let json = serde_json::to_string(&n).unwrap(); assert_eq!(json, "\"beta\""); assert_eq!(serde_json::from_str::(&json).unwrap(), n); assert!(serde_json::from_str::("\"Beta\"").is_err()); assert_eq!(n.to_string(), "beta"); } #[test] fn secret_redacts_debug_and_display() { let s = Secret::new("slinuxm_super_secret"); assert_eq!(s.expose(), "slinuxm_super_secret"); assert!(!format!("{s:?}").contains("super")); assert!(!format!("{s}").contains("super")); assert_eq!(format!("{s:?}"), "Secret(***)"); } #[test] fn peer_defaults_are_off() { let c = PeersConfig::default(); assert!(!c.enabled); assert!(c.peer.is_empty()); assert_eq!(c.tcp_interval_secs, 10); assert_eq!(c.request_timeout_secs, 10); assert_eq!(c.max_response_bytes, 8 * 1024 * 1024); assert_eq!( c.deny_cidrs, vec![ "169.254.0.0/16", "0.0.0.0/8", "fe80::/10", "::/128", "fd00:ec2::254/128", ] ); } #[test] fn partial_toml_keeps_defaults() { let c: PeersConfig = toml::from_str("enabled = true\napi_interval_secs = 7\n").unwrap(); assert!(c.enabled); assert_eq!(c.api_interval_secs, 7); assert_eq!(c.tcp_interval_secs, 10); } #[test] fn peer_entry_omits_optional_keys() { let c: PeersConfig = toml::from_str( r#" [[peer]] name = "beta" url = "http://beta:1984" token_file = "/run/credentials/skyg-linux-tracker.service/peer-beta" allow_plain_http = true [[peer]] name = "delta" url = "https://delta:1984" token_file = "/run/credentials/skyg-linux-tracker.service/peer-delta" enabled = false "#, ) .unwrap(); assert!(c.peer[0].enabled); assert!(c.peer[0].allow_plain_http); assert!(c.peer[0].ca_file.is_none()); assert!(!c.peer[1].enabled); assert!(!c.peer[1].allow_plain_http); assert!(c.peer[1].ca_file.is_none()); } #[test] fn display_url_drops_normalized_root_path() { assert_eq!( peer("beta", "http://beta:1984").display_url(), "http://beta:1984" ); assert_eq!( peer("beta", "https://beta:1984/").display_url(), "https://beta:1984" ); assert_eq!( peer("beta", "https://beta:1984/base").display_url(), "https://beta:1984/base" ); } #[test] fn status_json_shape() { let st = PeerStatus { name: PeerName::parse("beta").unwrap(), enabled: true, url: "http://beta:1984".into(), server: ServerStatus::default(), api: ApiStatus::default(), }; let v = serde_json::to_value(&st).unwrap(); assert_eq!(v["name"], "beta"); assert_eq!(v["server"]["up"], serde_json::json!(false)); assert_eq!(v["server"]["since"], serde_json::Value::Null); assert_eq!(v["api"]["auth"], "unknown"); assert_eq!( serde_json::to_value(CheckClass::TlsError).unwrap(), "tls_error" ); assert_eq!(serde_json::to_value(AuthState::Ok).unwrap(), "ok"); } }