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

329 lines
20 KiB
Markdown

# 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<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}]`)
```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<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`)
```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<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`):
```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<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`):
```rust
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.
```rust
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)
```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 <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_<code>, 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](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 <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)
```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
```nix
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.