# Phase 5 contracts Part of [Phase 5: Consolidator](README.md). 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](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 `Log` of every affected workstream file ([ws-a](ws-a-config.md), [ws-b](ws-b-registry.md), [ws-c](ws-c-rest.md), [ws-d](ws-d-mcp.md), [ws-e](ws-e-telemetry.md), [ws-f](ws-f-nixos-docs.md), [ws-t](ws-t-tests.md)). - 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](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`) ```rust /// 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; 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, 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, pub peer: Vec, } // Added to Config as `pub peers: PeersConfig` (A1, `#[serde(default)]`). ``` ### PeerStatus model (serialized as-is by REST, `GET /api/v1/peers[/{peer}]`) ```rust #[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, // last change; None until first check; resets on restart pub last_checked: Option, pub last_error: Option, // class string, no secrets, no URL pub latency_ms: Option, } #[derive(Debug, Clone, PartialEq, Serialize)] pub struct ApiStatus { pub up: bool, // true also when the peer answered 401 (D4) pub since: Option, pub last_checked: Option, pub last_error: Option, pub latency_ms: Option, pub auth: AuthState, // "ok" | "rejected" | "unknown" pub peer_version: Option, } #[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`) ```rust /// 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, // "text/event-stream" for follow } pub struct PeerResponse { pub status: u16, pub content_type: Option, pub body: PeerBody, // Bytes (capped) for JSON, or a byte stream for SSE } pub enum PeerBody { Bytes(Bytes), Stream(BoxStream<'static, Result>) } #[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; /// 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; } ``` `PeerError` (`src/peers/error.rs`): ```rust #[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)` for SSE. - `.delay(Duration)` to simulate slowness (uses `tokio::time`, pauseable). - Default for an unscripted peer: tcp ok (1 ms); `GET /api/v1/ping` returns `200 {"status":"ok","version":"0.0.0-fake"}`; any other path `404`. - Records every call (`fake.calls()` -> `Vec<(PeerName, PeerRequest)>`) so tests assert that `Authorization` is never forwarded, `x-slinuxm-hop: 1` is added and `traceparent` is injected. - Scripted `Rejected` on `/api/v1/ping` reproduces the "token revoked" state for D4/D9/T4-style tests. Helpers (also in `testing.rs`): ```rust pub fn fake_peers_config(names: &[&str]) -> PeersConfig; // enabled, short intervals, plain-http allowed pub fn registry_with(fake: Arc, cfg: PeersConfig) -> Arc; // no loops spawned pub fn static_registry(statuses: Vec) -> Arc; // fixed snapshot, for REST/MCP/OTel tests pub fn fake_state_with_peers(config: Config, reg: Arc) -> 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>`) `None` = feature off: no routes, no tools, no tasks, no metrics. ```rust impl PeerRegistry { /// Sorted by name. Includes disabled peers (enabled = false). pub fn snapshot(&self) -> Vec; pub fn status(&self, name: &str) -> Result; // NotFound if unknown pub fn contains(&self, name: &str) -> bool; pub fn config(&self) -> Arc; // 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; // 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, 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) ```rust /// 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 : not found on peer` | | `BadRequest(m)` | `BadRequest` | `peer : ` | | `Rejected` | `Unavailable` (never `Unauthorized`) | `peer : peer rejected credentials` | | `Timeout`, `Unreachable`, `Dns`, `Tls`, `Http(5xx)`, `Oversize`, `Saturated`, `TokenFile` | `Unavailable` | `peer : ` (class: timeout, unreachable, dns, tls_error, http_, oversize, saturated, token_file) | | `Malformed` | `Internal` | `peer : malformed response` | | unknown `{peer}` (registry) | `NotFound` | `peer : 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](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 ```json { "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 -> `405` `method_not_allowed` (existing shape). - Request headers added toward the peer: `Authorization: Bearer ` (never the caller's), `x-slinuxm-hop: 1`, `traceparent` when present. Request headers rejected from the caller: any `x-slinuxm-hop` -> `400 bad_request` (`peer : chained requests are not allowed`). - Response: peer's status and body unchanged for 2xx; header `x-slinuxm-peer: ` 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`, never `401` for the caller. ## 6. Config surface (TOML) ```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":""}` (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` ("name of a configured peer; omit for this host"). Absent = local, identical behaviour. Present = same arguments forwarded to the peer through `PeerRegistry::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 }` -> one `PeerStatus` JSON; unknown name -> tool error (`not_found` data code). - Tool count 10. Errors: `AppError` -> existing `tool_error`/`ErrorData` mapping, so peer failures are tool errors with the section 4 messages. - Resource `peers://status` -> same JSON as `list_peers`. `container_health_report` and `diagnose_unit` prompts gain an optional `peer` argument. - 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`, 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`, which `ProxyOpts.traceparent` carries; WS-C/WS-D pass it through and need not know more). ## 9. NixOS options contract ```nix services.skyg-linux-tracker.peers = { enable = false; # bool settings = { }; # freeform: intervals/caps, keys as in [peers] (snake_case) peers. = { 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-"`, `LoadCredential=peer-:`, `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` (peers `beta` over plain HTTP, `gamma` over HTTPS with `ca_file`), `beta` (peer `alpha`), `gamma` (TLS-only, no peers). Port 1984; `alpha` and `beta` bind `::` (dual stack) and `gamma` binds `0.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; }` and `peers.peers. = { url; tokenFile; caFile ? null; allowPlainHttp }`. The module renders `[peers]` plus one `[[peers.peer]]` per enabled peer with keys `name`, `url`, `token_file`, `allow_plain_http`, optional `ca_file`. - `token_file = /run/credentials/skyg-linux-tracker.service/peer-` (the module adds `LoadCredential=peer-:/var/lib/peer-tokens/` and `RefreshOnReload=credentials`); the file holds the placeholder `pending` until the test installs a real token, so the placeholder must pass A3 loading (non-empty, under `$CREDENTIALS_DIRECTORY` so the permission check is skipped) and be reported as `auth = "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. `alpha` and `beta` bind `::` (dual stack) and the TLS peer `gamma` binds `0.0.0.0`, so the test covers both a dual-stack and an IPv4-only peer; the peer URLs keep the hostnames. - Token rotation = `mv` a new file into place and `systemctl reload skyg-linux-tracker.service` (SIGHUP with `RefreshOnReload=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 = 4` and the test's `elapsed < 15` bound the proxy call when a peer VM is down. - Assertions the contract must satisfy: `GET /api/v1/peers/

` JSON has `server.up`, `api.up`, `api.auth` in {`ok`,`rejected`}; `GET /api/v1/peers` body contains each peer name; proxied `GET /api/v1/peers/

/systemd/units[/.service]` returns the peer's data with response header `x-slinuxm-peer:

`; `POST`/`DELETE` on 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; MCP `list_peers` output contains the peer names; MCP `list_systemd_units` with `{"peer": "

"}` returns the peer's units. - The peer's `/api/v1/ping` must return 401 for a bad token (placeholder case) and 200 for a good one; the test relies on `api.up = true` with `auth = "rejected"` for the 401 case (D4). - Removal: the test replaces the rendered `/etc/skyg-linux-tracker.toml` symlink with an edited copy (one `[[peers.peer]]` block dropped), sends SIGHUP, and expects the peer to disappear from `GET /api/v1/peers` and to 404 on `GET /api/v1/peers/

`, with the service's `MainPID` unchanged. Rotation and revocation likewise leave `MainPID` alone.