329 lines
20 KiB
Markdown
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; `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.
|