Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-c-rest.md
T

7.4 KiB

WS-C: REST surface

Part of Phase 5: Consolidator. Contracts: contracts.md sections 3 to 5.

Field Value
Status Done (C1 to C4; end-to-end re-check with WS-B pending)
Owner WS-C agent (2026-10-19)
Depends on B (original plan). In practice: A0 for compiling, B only for the final end-to-end check; develop against FakeTransport + registry_with / static_registry
Blocks WS-D D1 (shares PeerRegistry::get / proxy.rs; D can stub it from A0 until C2 lands), F
Can start when A0 is merged (earlier in a branch against contracts.md)
Owned files src/api/peers.rs, src/peers/proxy.rs (the single proxy implementation: allowlist, header rules, error mapping calls), src/error.rs (only if D9 adds a variant), docs/api.md, src/api/behaviour_tests.rs (peer cases appended)
Do not touch src/api/mod.rs (A0 wired pub mod peers, the conditional merge and the 404/405 fallbacks; stay out), src/api/ping.rs (B), src/peers/{registry,health,client}.rs (B), src/peers/{types,error,transport,testing}.rs (contracts.md only), src/mcp/** (D), src/telemetry/** (E), src/state.rs (A0), nix/**, README.md (F)

Shared-file seam: src/api/mod.rs is edited only by A0. WS-C fills peers::routes() (returns the Router merged when state.peers is Some). The contract for what a route returns is contracts.md section 5.

Goal

Status and pass-through over REST under the existing auth.

Tasks

  • C1 GET /api/v1/peers and /{peer}: status JSON (shape in contracts section 5), sorted by name; unknown peer is NotFound.
  • C2 pass-through GET /api/v1/peers/{peer}/{*path}: allowlist of the peer's documented routes (systemd/..., journal, journal/follow, docker/...; ping and peers/... excluded), reject .., encoded slashes and non-allowlisted query keys; forward only the allowlisted query; never forward the caller's Authorization or cookies, use the peer token; add x-slinuxm-hop: 1 and reject requests that already carry it (no chaining); stream bodies through the size cap; SSE passes through bounded by limits.max_follow_secs and shutdown. Implemented in src/peers/proxy.rs as the body of PeerRegistry::get, which WS-D also calls; the route in peers.rs is a thin adapter. (Axum 0.8: routes use /{peer} and /{*path}.)
  • C3 response header x-slinuxm-peer: <name>; body unchanged so clients can reuse local parsers.
  • C4 (note, no new task from the original) error mapping goes through peer_error_to_app (contracts section 4). Whether to add an extra peer field to the REST error body is optional; if done it is a contracts.md change plus src/error.rs.

Inputs

  • Contracts sections 3 (registry API), 4 (error table), 5 (REST shapes).
  • Fakes: FakeTransport (records calls to assert hop header, no Authorization, filtered query), registry_with, static_registry, fake_state_with_peers.

Done when

Behaviour tests with the fake transport for every error mapping row in D9; 405 on non-GET; traversal and header-smuggling cases rejected; SSE ends on shutdown.

Handoff

  • PeerRegistry::get fully implemented (allowlist, hop, mapping) for WS-D; post in D's Log when C2 merges.
  • docs/api.md section for the peers endpoints for F4.
  • Verified shapes that WS-T asserts (x-slinuxm-peer, 405, 4xx on hop header, 503 naming the peer).

Log

  • 2026-10-19: Split from the single phase plan 2026-10-19. The proxy logic is placed in src/peers/proxy.rs (not api/peers.rs) so REST and MCP share one implementation, as the original plan required.
  • 2026-10-19 (A0): contract stubs landed (src/peers/{types,error,transport,testing,registry,proxy,health}.rs, src/api/peers.rs stub, AppState.peers, Config.peers, tests/peers_config.rs). PeerRegistry::get forwards through PeerTransport and proxy.rs already adds x-slinuxm-hop and traceparent; path/query allowlists, the hop-header rejection and the x-slinuxm-peer response header are still yours. api::peers::routes() is empty and merged only when state.peers.is_some(), so fill it without touching api/mod.rs.
  • 2026-10-19 (C1): GET /api/v1/peers and /peers/{peer} landed in src/api/peers.rs (sorted snapshot, one object for the single-peer route, peer <name>: unknown peer 404), with behaviour tests for shape, sorting, unknown/invalid names, the empty registry, route absence when peers are disabled and local routes staying available. docs/api.md gained the route table row and the status section.
  • 2026-10-19 (C2): the allowlist proxy is the body of PeerRegistry::get in src/peers/proxy.rs; src/api/peers.rs is a thin adapter that parses the raw (still percent-encoded) path, the raw query and the trace/accept headers, then renders PeerResponse. Allowed routes: systemd/units, systemd/units/{name}, systemd/timers, journal, journal/follow, docker/ps, docker/containers/{name}, docker/containers/{name}/logs; an /api/v1 prefix from the caller is stripped. .., encoded slashes/backslashes, NUL/CRLF, a second encoding layer, empty segments and over-long paths/queries are rejected before any transport call. Query keys are per route, single-valued and character-checked; anything else is peer <name>: unsupported query parameter. The caller's Authorization/Cookie are never copied (the request is rebuilt, the transport attaches the peer token), x-slinuxm-hop: 1 is added and any inbound hop header is 400 peer <name>: chained requests are not allowed. Buffered bodies over peers.max_response_bytes are 503 oversize; streams are cut at the cap, at limits.max_follow_secs or on the shared CancellationToken. SSE is selected by Accept or journal/follow / docker follow=1. A peer Content-Type that is not a valid header value becomes 500 malformed response instead of smuggling a second header.
  • 2026-10-19 (C3): x-slinuxm-peer: <name> is attached to every outcome of the pass-through route, including the consolidator's own 400/404/500/503 for that peer (a 405 is produced by the router fallback in api/mod.rs, which WS-C does not own, and carries no peer header; WS-T does not require one there).
  • 2026-10-19 (C4): mapping stays in peer_error_to_app (WS-A file, unchanged); REST adds no peer field to the error body, so the note in this file is closed as "not done, optional". A behaviour test drives every D9 row through the fake transport and asserts status, code, message, the peer name in the body, the peer header, and that no row is 401, leaks a token-file path or a URL.
  • 2026-10-19 Handoff: C1 to C4 are committed as four task commits on ws/C (9356596, a1ea58a, cf6b81c, c967ad9). cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test (154 lib tests) and cargo tree -i openssl (empty) pass. WS-D can call PeerRegistry::get now: it takes /api/v1-prefixed or bare paths, returns PeerResponse with the peer's status/content type/body, or an already-mapped AppError; SSE callers set ProxyOpts.accept_sse and must bound the returned stream with their own shutdown/deadline. WS-F/WS-T: the x-slinuxm-peer header, 405, hop-header 400, 503-with-peer-name and query filtering behaviours the VM test asserts are covered by src/api/behaviour_tests.rs. Re-check against the real registry once B lands (real transport must map peer statuses to PeerError before C sees them; the fake returns statuses verbatim). No Nix VM test was run by this workstream.