Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-c-rest.md
T
ari 4bfb097be6 A0: contract stubs types, transport, fake and registry seams
Land the shared peer contracts: types, error mapping, transport trait,
fake transport and fixtures, registry/proxy/health skeletons, the
AppState.peers and Config.peers seams, the ping and peers route stubs,
and unit plus integration tests. No loops, no network, feature off by
default.
2026-10-19 20:02:17 -04:00

4.0 KiB

WS-C: REST surface

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

Field Value
Status Not started
Owner
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.