Files
skyg-linux-tracker/plan/phase-5-consolidator/contracts.md
T
ari dde6a12ce4 F: try every resolved peer address instead of the first
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.
2026-10-20 15:04:09 -04:00

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 Log of 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 (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):

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 -> 405 method_not_allowed (existing shape).
  • Request headers added toward the peer: Authorization: Bearer <peer token> (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 <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, never 401 for 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 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<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 (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.<name> = { 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-<name> (the module adds LoadCredential=peer-<name>:/var/lib/peer-tokens/<name> 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/<p> 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/<p>/systemd/units[/<unit>.service] returns the peer's data with response header x-slinuxm-peer: <p>; 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": "<p>"} 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/<p>, with the service's MainPID unchanged. Rotation and revocation likewise leave MainPID alone.