A peer whose name resolves to both families but which listens on only one of them was reported unreachable, which the documented 0.0.0.0 binding produces on a dual-stack LAN and in the NixOS test network. resolve_target now returns the whole address set (still refusing the name if any address is denied), the HTTP client pins it with resolve_to_addrs so the connector falls through to the next address, and tcp_check tries each address in order with a per-attempt share of the remaining deadline. ClientKey keys on the set. Regression cover: a client test that resolves localhost against a single-family listener, a tests/peers.rs case declaring the peer as http://localhost:<port>, and the VM test's TLS peer gamma now binds 0.0.0.0 (IPv4 only) while alpha and beta stay dual stack. Docs and the contracts section 10 address note describe the new behaviour.
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;alphaandbetabind::(dual stack) andgammabinds0.0.0.0(IPv4 only), so a single-family peer stays covered (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. The transport uses every resolved address (the probe tries them in order inside its timeout, the client pins the whole set, and one denied address refuses the name), so a peer is found on whichever family it listens on.
alphaandbetabind::(dual stack) and the TLS peergammabinds0.0.0.0, so the test covers both a dual-stack and an IPv4-only peer; the peer URLs keep the hostnames. - 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.