3.5 KiB
3.5 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/peersand/{peer}: status JSON (shape in contracts section 5), sorted by name; unknown peer isNotFound. - C2 pass-through
GET /api/v1/peers/{peer}/{*path}: allowlist of the peer's documented routes (systemd/...,journal,journal/follow,docker/...;pingandpeers/...excluded), reject.., encoded slashes and non-allowlisted query keys; forward only the allowlisted query; never forward the caller'sAuthorizationor cookies, use the peer token; addx-slinuxm-hop: 1and reject requests that already carry it (no chaining); stream bodies through the size cap; SSE passes through bounded bylimits.max_follow_secsand shutdown. Implemented insrc/peers/proxy.rsas the body ofPeerRegistry::get, which WS-D also calls; the route inpeers.rsis 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 extrapeerfield to the REST error body is optional; if done it is a contracts.md change plussrc/error.rs.
Inputs
- Contracts sections 3 (registry API), 4 (error table), 5 (REST shapes).
- Fakes:
FakeTransport(records calls to assert hop header, noAuthorization, 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::getfully implemented (allowlist, hop, mapping) for WS-D; post in D's Log when C2 merges.docs/api.mdsection 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(notapi/peers.rs) so REST and MCP share one implementation, as the original plan required.