7.4 KiB
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/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. - 2026-10-19 (C1):
GET /api/v1/peersand/peers/{peer}landed insrc/api/peers.rs(sorted snapshot, one object for the single-peer route,peer <name>: unknown peer404), 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.mdgained the route table row and the status section. - 2026-10-19 (C2): the allowlist proxy is the body of
PeerRegistry::getinsrc/peers/proxy.rs;src/api/peers.rsis a thin adapter that parses the raw (still percent-encoded) path, the raw query and the trace/accept headers, then rendersPeerResponse. Allowed routes:systemd/units,systemd/units/{name},systemd/timers,journal,journal/follow,docker/ps,docker/containers/{name},docker/containers/{name}/logs; an/api/v1prefix 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 ispeer <name>: unsupported query parameter. The caller'sAuthorization/Cookieare never copied (the request is rebuilt, the transport attaches the peer token),x-slinuxm-hop: 1is added and any inbound hop header is400 peer <name>: chained requests are not allowed. Buffered bodies overpeers.max_response_bytesare503 oversize; streams are cut at the cap, atlimits.max_follow_secsor on the sharedCancellationToken. SSE is selected byAcceptorjournal/follow/ dockerfollow=1. A peerContent-Typethat is not a valid header value becomes500 malformed responseinstead 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 own400/404/500/503for that peer (a405is produced by the router fallback inapi/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 nopeerfield 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 is401, 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) andcargo tree -i openssl(empty) pass. WS-D can callPeerRegistry::getnow: it takes/api/v1-prefixed or bare paths, returnsPeerResponsewith the peer's status/content type/body, or an already-mappedAppError; SSE callers setProxyOpts.accept_sseand must bound the returned stream with their own shutdown/deadline. WS-F/WS-T: thex-slinuxm-peerheader, 405, hop-header 400, 503-with-peer-name and query filtering behaviours the VM test asserts are covered bysrc/api/behaviour_tests.rs. Re-check against the real registry once B lands (real transport must map peer statuses toPeerErrorbefore C sees them; the fake returns statuses verbatim). No Nix VM test was run by this workstream.