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.
4.0 KiB
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/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. - 2026-10-19 (A0): contract stubs landed (
src/peers/{types,error,transport,testing,registry,proxy,health}.rs,src/api/peers.rsstub,AppState.peers,Config.peers,tests/peers_config.rs).PeerRegistry::getforwards throughPeerTransportandproxy.rsalready addsx-slinuxm-hopand traceparent; path/query allowlists, the hop-header rejection and thex-slinuxm-peerresponse header are still yours.api::peers::routes()is empty and merged only whenstate.peers.is_some(), so fill it without touchingapi/mod.rs.