Files
skyg-linux-tracker/plan/phase-5-consolidator/contracts.md
T
ari ca000d973f F: F2 promote the peers VM test and the module eval test into checks
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.
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, 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; } 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, 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 as unreachable (the transport connects to the first resolved address); see the ws-f Log.
  • 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.