The test nodes declare peers through the first-class module options, so LoadCredential and RefreshOnReload come from the module. Every node binds :: because the test network resolves node names to IPv6 first. poll() raises with the last observed status JSON.
20 KiB
Phase 5 contracts
Part of Phase 5: Consolidator. Shared interface contracts that let WS-C, WS-D, WS-E and WS-F start against fakes before WS-B lands. Decisions behind them are in decisions.md.
Change rule
- This file is the only place a shared interface changes. Do not alter a signature, JSON shape, metric name or option name in code first.
- A contract change = edit this file in its own small commit/PR, then add a dated note to the
Logof every affected workstream file (ws-a, ws-b, ws-c, ws-d, ws-e, ws-f, ws-t). - The WS-T test (
nix/tests/peers.nix) is the executable form of the REST/config parts. If a change breaks it, the change is wrong or WS-T must be updated in the same PR. - Signatures below are the intended shape, not frozen syntax: names, field types and the JSON in sections 3 to 5 are the contract. Lifetimes, derives and module-private helpers are the implementer's call.
Landing order of the stubs
Task A0 (in ws-a-config.md) lands sections 1, 2 and 6 as compilable stubs in src/peers/ plus the AppState.peers field and route/tool seams. Until A0 is merged, C/D/E/F code against this file and rebase onto A0 afterwards.
1. Rust types (src/peers/types.rs, src/peers/error.rs)
/// Validated peer name, regex ^[a-z0-9][a-z0-9_-]{0,31}$ (A2). Cheap to clone.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct PeerName(String);
impl PeerName { pub fn parse(s: &str) -> Result<Self, ConfigError>; pub fn as_str(&self) -> &str; }
/// Token wrapper with redacted Debug/Display. Never Serialize (A3).
pub struct Secret(/* private */);
impl Secret { pub fn expose(&self) -> &str; } // only the transport calls this
/// One `[[peers.peer]]` entry after validation (src/peers/config.rs).
#[derive(Debug, Clone, PartialEq)]
pub struct PeerConfig {
pub name: PeerName,
pub url: url::Url, // http/https, no userinfo/query/fragment (D11)
pub token_file: PathBuf, // absolute; contents never held here
pub ca_file: Option<PathBuf>,
pub allow_plain_http: bool, // default false
pub enabled: bool, // default true
}
/// `[peers]` section (src/peers/config.rs); defaults in section 6.
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<String>,
pub peer: Vec<PeerConfig>,
}
// Added to Config as `pub peers: PeersConfig` (A1, `#[serde(default)]`).
PeerStatus model (serialized as-is by REST, GET /api/v1/peers[/{peer}])
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct PeerStatus {
pub name: PeerName,
pub enabled: bool,
pub url: String, // display form; no userinfo by construction
pub server: ServerStatus, // "server up": TCP connect
pub api: ApiStatus, // "API running": authenticated GET /api/v1/ping
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ServerStatus {
pub up: bool,
pub since: Option<Timestamp>, // last change; None until first check; resets on restart
pub last_checked: Option<Timestamp>,
pub last_error: Option<String>, // class string, no secrets, no URL
pub latency_ms: Option<u64>,
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ApiStatus {
pub up: bool, // true also when the peer answered 401 (D4)
pub since: Option<Timestamp>,
pub last_checked: Option<Timestamp>,
pub last_error: Option<String>,
pub latency_ms: Option<u64>,
pub auth: AuthState, // "ok" | "rejected" | "unknown"
pub peer_version: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AuthState { Ok, Rejected, Unknown }
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CheckClass { Ok, Unauthorized, HttpError, Timeout, Unreachable, TlsError } // B2
Timestamp is RFC 3339 UTC in JSON (same type the existing DTOs use for times; if none exists, time::OffsetDateTime/chrono as already in the tree, decided in A0 and noted in the A log). Initial state before the first check: up = false, auth = unknown, timestamps null.
2. Transport (src/peers/transport.rs)
/// One GET to a peer. `path` is already validated by the proxy layer (C2); query is pre-filtered.
pub struct PeerRequest {
pub path: String, // e.g. "/api/v1/systemd/units"
pub query: Vec<(String, String)>,
pub headers: Vec<(HeaderName, HeaderValue)>, // traceparent, x-slinuxm-hop; never Authorization
pub accept: Option<String>, // "text/event-stream" for follow
}
pub struct PeerResponse {
pub status: u16,
pub content_type: Option<String>,
pub body: PeerBody, // Bytes (capped) for JSON, or a byte stream for SSE
}
pub enum PeerBody { Bytes(Bytes), Stream(BoxStream<'static, Result<Bytes, PeerError>>) }
#[async_trait]
pub trait PeerTransport: Send + Sync {
/// TCP connect to host:port under `timeout`. Returns connect latency.
async fn tcp_check(&self, peer: &PeerConfig, timeout: Duration) -> Result<Duration, PeerError>;
/// Authenticated GET. Reads the token file on each call (rotation needs no restart).
/// Enforces redirect-off, size cap and per-peer/global concurrency (B1).
async fn get(&self, peer: &PeerConfig, req: PeerRequest, timeout: Duration)
-> Result<PeerResponse, PeerError>;
}
PeerError (src/peers/error.rs):
#[derive(Debug, Clone)]
pub enum PeerError {
Rejected, // peer 401/403: our credential was refused
NotFound, // peer 404
BadRequest(String), // peer 400/422
Http(u16), // other 5xx / unexpected status
Timeout, Unreachable, Dns, Tls, Oversize,
Malformed(String), // peer JSON could not be parsed
TokenFile(String), // missing/empty/oversize token file
Saturated, // concurrency limit hit
}
impl PeerError { pub fn class(&self) -> CheckClass; } // for health classification
Fake behaviour (src/peers/testing.rs, #[cfg(any(test, feature = "test-support"))] or plain pub if integration tests need it; A0 decides, noted in log)
FakeTransport is configured per peer name and mirrors the DEC-2 fake sources:
FakeTransport::new();.peer(name)returns a builder with:.tcp(Ok(latency) | Err(PeerError::..)).respond(path_prefix, status, content_type, body)scripted GET responses (first matching prefix wins);.respond_err(path_prefix, PeerError);.stream(path_prefix, Vec<Bytes>)for SSE..delay(Duration)to simulate slowness (usestokio::time, pauseable).
- Default for an unscripted peer: tcp ok (1 ms);
GET /api/v1/pingreturns200 {"status":"ok","version":"0.0.0-fake"}; any other path404. - Records every call (
fake.calls()->Vec<(PeerName, PeerRequest)>) so tests assert thatAuthorizationis never forwarded,x-slinuxm-hop: 1is added andtraceparentis injected. - Scripted
Rejectedon/api/v1/pingreproduces the "token revoked" state for D4/D9/T4-style tests.
Helpers (also in testing.rs):
pub fn fake_peers_config(names: &[&str]) -> PeersConfig; // enabled, short intervals, plain-http allowed
pub fn registry_with(fake: Arc<FakeTransport>, cfg: PeersConfig) -> Arc<PeerRegistry>; // no loops spawned
pub fn static_registry(statuses: Vec<PeerStatus>) -> Arc<PeerRegistry>; // fixed snapshot, for REST/MCP/OTel tests
pub fn fake_state_with_peers(config: Config, reg: Arc<PeerRegistry>) -> AppState; // wraps sources::fake::fake_state
registry_with + FakeTransport lets C and D test full proxy behaviour; static_registry lets C1/D2/E1 test status rendering and metrics without any transport.
3. PeerRegistry read API (src/peers/registry.rs, field AppState.peers: Option<Arc<PeerRegistry>>)
None = feature off: no routes, no tools, no tasks, no metrics.
impl PeerRegistry {
/// Sorted by name. Includes disabled peers (enabled = false).
pub fn snapshot(&self) -> Vec<PeerStatus>;
pub fn status(&self, name: &str) -> Result<PeerStatus, AppError>; // NotFound if unknown
pub fn contains(&self, name: &str) -> bool;
pub fn config(&self) -> Arc<PeersConfig>; // limits for C2/E (max_follow comes from Config.limits)
/// Used by REST C2 and MCP D1: single proxy implementation (src/peers/proxy.rs, owned by WS-C).
pub async fn get(&self, name: &str, path: &str, query: &[(String, String)], opts: ProxyOpts)
-> Result<PeerResponse, AppError>; // already error-mapped (below)
/// Lifecycle (WS-B): start loops, reload, shutdown. Not used by surfaces.
pub async fn reload(&self, new: PeersConfig) -> Result<(), PeerConfigError>;
pub async fn shutdown(&self);
}
pub struct ProxyOpts { pub traceparent: Option<String>, pub accept_sse: bool }
Rules for get (implemented by C2 in proxy.rs, the A0 stub forwards without allowlist): allowlist check, ../encoded-slash rejection, query allowlist, hop header, no caller credentials, peer error mapping. MCP D1 calls exactly this; no second implementation. For typed use: PeerResponse JSON bodies are returned to the MCP tool verbatim (the tool result is the peer's JSON text, wrapped in the usual cap/truncation).
Registry reads are lock-light (ArcSwap or RwLock clone of a Vec); surfaces must never await on a peer to render status.
4. Error mapping (src/peers/error.rs, implements D9)
/// Pure function; the only place peer failures become AppError.
pub fn peer_error_to_app(peer: &PeerName, e: &PeerError) -> AppError;
| PeerError | AppError | Message form |
|---|---|---|
NotFound |
NotFound |
peer <name>: not found on peer |
BadRequest(m) |
BadRequest |
peer <name>: <m> |
Rejected |
Unavailable (never Unauthorized) |
peer <name>: peer rejected credentials |
Timeout, Unreachable, Dns, Tls, Http(5xx), Oversize, Saturated, TokenFile |
Unavailable |
peer <name>: <class> (class: timeout, unreachable, dns, tls_error, http_, oversize, saturated, token_file) |
Malformed |
Internal |
peer <name>: malformed response |
unknown {peer} (registry) |
NotFound |
peer <name>: unknown peer |
Messages always contain the peer name (WS-T asserts "beta" in body on 503). No new AppError variant (D9). The message never contains URLs, tokens or token-file paths. An optional extra peer field in the REST error body is not part of this contract (see ws-c-rest.md, C4 note).
5. REST contract
All under the existing inbound auth; absent entirely when state.peers is None (route-level 404 as for any unknown route).
GET /api/v1/peers -> 200
{
"peers": [
{
"name": "beta",
"enabled": true,
"url": "http://beta:1984",
"server": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:09Z", "last_error": null, "latency_ms": 1 },
"api": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:05Z", "last_error": null, "latency_ms": 7,
"auth": "ok", "peer_version": "0.1.0" }
}
]
}
Sorted by name. auth is "ok" | "rejected" | "unknown". The WS-T test reads s["server"]["up"], s["api"]["up"], s["api"]["auth"] from the single-peer response and string-matches peer names in the list.
GET /api/v1/peers/{peer} -> 200 one object (the element above, not wrapped); unknown peer -> 404 {"error":{"code":"not_found",...}}.
GET /api/v1/peers/{peer}/{*path} (pass-through)
- Allowlisted path prefixes (peer-side routes):
systemd/...,journal,journal/follow,docker/.... Excluded:ping,peers/.... - Methods other than GET ->
405method_not_allowed(existing shape). - Request headers added toward the peer:
Authorization: Bearer <peer token>(never the caller's),x-slinuxm-hop: 1,traceparentwhen present. Request headers rejected from the caller: anyx-slinuxm-hop->400 bad_request(peer <name>: chained requests are not allowed). - Response: peer's status and body unchanged for 2xx; header
x-slinuxm-peer: <name>on every proxied response, including errors produced by the consolidator for that peer (503 etc.). Content-Type passes through (application/json,text/event-stream). - Errors per section 4; a rejected peer token is
503, never401for the caller.
6. Config surface (TOML)
[peers]
enabled = false # default; peer-less behaviour is byte-identical
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 = 8388608
max_concurrent_per_peer = 4
max_concurrent_total = 16
deny_cidrs = ["169.254.0.0/16", "0.0.0.0/8"]
[[peers.peer]]
name = "minipc1" # ^[a-z0-9][a-z0-9_-]{0,31}$, unique, max 64 peers
url = "https://minipc1:1984" # http/https only; no userinfo/query/fragment
token_file = "/run/credentials/skyg-linux-tracker.service/peer-minipc1" # absolute
ca_file = "/etc/ssl/private-ca.pem" # optional
allow_plain_http = false # required true for http:// to a non-loopback host
enabled = true
Env overrides for scalars: SKYG_PEERS__ENABLED, SKYG_PEERS__TCP_INTERVAL_SECS, ... (peer entries are file-only). Validation: each timeout below its interval; enabled with zero peers is a warning. --print-config shows token_file paths, never contents.
Peer-side endpoint added by WS-B: GET /api/v1/ping (authenticated) returns 200 {"status":"ok","version":"<crate version>"} (D4). GET /healthz stays public and unchanged.
7. MCP contract
With peers.enabled = false the tool list is exactly today's 8 tools and their schemas are unchanged.
With peers enabled:
- Every one of the 8 existing tools gains an optional parameter
peer: Option<String>("name of a configured peer; omit for this host"). Absent = local, identical behaviour. Present = same arguments forwarded to the peer throughPeerRegistry::get(path and query built from the same params as the local REST route). - New tool
list_peers(no params) -> JSON{"peers":[PeerStatus,...]}(same shape as REST list). - New tool
get_peer { name: String }-> onePeerStatusJSON; unknown name -> tool error (not_founddata code). - Tool count 10. Errors:
AppError-> existingtool_error/ErrorDatamapping, so peer failures are tool errors with the section 4 messages. - Resource
peers://status-> same JSON aslist_peers.container_health_reportanddiagnose_unitprompts gain an optionalpeerargument. - Instructions/descriptions mention peers only when enabled, and state that peer-sourced text is untrusted data.
Rust shape of the added parameter: each params struct gets #[serde(default)] pub peer: Option<String>, plus pub struct GetPeerParams { pub name: String }.
8. OTel contract (D10)
All are observable f64 gauges read from PeerRegistry::snapshot() (no polling), registered only when state.peers is Some and otel.metrics.enabled.
| Metric | Unit | Attributes | Value |
|---|---|---|---|
peer.up |
1 |
peer.name, peer.check = server or api |
0/1 |
peer.api.auth_ok |
1 |
peer.name |
0/1 (0 with server up + api up = "token rejected") |
peer.check.duration_seconds |
s |
peer.name, peer.check |
last check latency |
peer.last_change_timestamp_seconds |
s |
peer.name, peer.check |
Unix time of since |
No URL or version attributes. Removed peers vanish because the callback only reports what is in the snapshot. Outbound spans: name peer.request, attribute peer.name; traceparent injected into the PeerRequest.headers by the proxy layer (E2 provides the helper telemetry::inject_traceparent() -> Option<String>, which ProxyOpts.traceparent carries; WS-C/WS-D pass it through and need not know more).
9. NixOS options contract
services.skyg-linux-tracker.peers = {
enable = false; # bool
settings = { }; # freeform: intervals/caps, keys as in [peers] (snake_case)
peers.<name> = {
url = "https://minipc1:1984"; # str
tokenFile = config.age.secrets.peer-minipc1.path; # str, never a path literal; store paths rejected by assertion
caFile = null; # null or str
enable = true;
allowPlainHttp = false;
};
};
Rendering: one [[peers.peer]] per enabled peer with token_file = "/run/credentials/skyg-linux-tracker.service/peer-<name>", LoadCredential=peer-<name>:<tokenFile>, RefreshOnReload=credentials, ExecReload = SIGHUP, assertions as in F1.
10. Test config contract (nix/tests/peers.nix)
The VM test declares its peers with the module's first-class options (F2), so the TOML contract above must stay compatible with what they render:
- Hosts:
alpha(peersbetaover plain HTTP,gammaover HTTPS withca_file),beta(peeralpha),gamma(TLS-only, no peers). Port 1984, bind::(dual stack, see the address note below). - Config comes through the module:
peers.enable = true,peers.settings = { tcp_interval_secs = 2; tcp_timeout_secs = 1; api_interval_secs = 3; api_timeout_secs = 2; fail_threshold = 2; request_timeout_secs = 4; }andpeers.peers.<name> = { url; tokenFile; caFile ? null; allowPlainHttp }. The module renders[peers]plus one[[peers.peer]]per enabled peer with keysname,url,token_file,allow_plain_http, optionalca_file. token_file = /run/credentials/skyg-linux-tracker.service/peer-<name>(the module addsLoadCredential=peer-<name>:/var/lib/peer-tokens/<name>andRefreshOnReload=credentials); the file holds the placeholderpendinguntil the test installs a real token, so the placeholder must pass A3 loading (non-empty, under$CREDENTIALS_DIRECTORYso the permission check is skipped) and be reported asauth = "rejected", not as a config error.- Address note: a test node's name resolves to both its IPv4 and its IPv6 address, and resolution returns the IPv6 one first, so each node binds
::and the peer URLs keep the hostnames. A peer reachable only on IPv4 is reported asunreachable(the transport connects to the first resolved address); see the ws-f Log. - Token rotation =
mva new file into place andsystemctl reload skyg-linux-tracker.service(SIGHUP withRefreshOnReload=credentials); status must recover without a restart. SIGHUP must therefore re-read token files and keep the registry (B4). - Timeouts (1 s / 2 s) are below intervals (2 s / 3 s), as validation requires;
request_timeout_secs = 4and the test'selapsed < 15bound the proxy call when a peer VM is down. - Assertions the contract must satisfy:
GET /api/v1/peers/<p>JSON hasserver.up,api.up,api.authin {ok,rejected};GET /api/v1/peersbody contains each peer name; proxiedGET /api/v1/peers/<p>/systemd/units[/<unit>.service]returns the peer's data with response headerx-slinuxm-peer: <p>;POST/DELETEon a proxy path -> 405;x-slinuxm-hop: 1-> 4xx; unknown peer -> 404; peer rejected/down -> 503 with the peer name in the body and the caller's own token still valid; MCPlist_peersoutput contains the peer names; MCPlist_systemd_unitswith{"peer": "<p>"}returns the peer's units. - The peer's
/api/v1/pingmust return 401 for a bad token (placeholder case) and 200 for a good one; the test relies onapi.up = truewithauth = "rejected"for the 401 case (D4). - Removal: the test replaces the rendered
/etc/skyg-linux-tracker.tomlsymlink with an edited copy (one[[peers.peer]]block dropped), sends SIGHUP, and expects the peer to disappear fromGET /api/v1/peersand to 404 onGET /api/v1/peers/<p>, with the service'sMainPIDunchanged. Rotation and revocation likewise leaveMainPIDalone.