11 KiB
11 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, NUL/CRLF, a second encoding layer, empty segments and over-long paths/queries are rejected before any transport call; a backslash is only legal inside a unit name (see the review entry). 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 and returnsPeerResponseor an already-mappedAppError. SSE callers setProxyOpts.accept_sseand then hand the response toproxy::prepare_response(peer, resp, reg.config().max_response_bytes, deadline, shutdown)and streamPreparedResponse.body: that function (not the REST adapter) owns the 2xx-only status check, the content-type check, the buffered cap and the follow deadline/shutdown bound, so D must not add a second copy. See the review entry below. 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. - 2026-10-19 (review round 1): fixes.
- Blocking: the proxy allowlist no longer keeps a second, stricter copy of unit-name validation.
systemd/units/{name}decodes the segment and callssources::systemd::validate_unit_name, so escaped units (foo\x2dbar.mount,mnt-data%5Cx2dbackup.mount) and-.mount/-.slicework through the proxy as they do locally;%5c/\is now rejected only where the route is not a unit name (an exact route or a docker container). Each segment is decoded on its own, and the forwarded path is re-encoded from the decoded segment (\becomes%5C), because the transport builds the URL withUrl::set_pathand a literal backslash would be read as a separator there. - Size/stream bounds moved out of the REST adapter:
proxy::prepare_responseis the shared step for REST and MCP. It applies the buffered cap, the stream cap, the follow deadline and shutdown, and validates the content type. - A non-2xx
PeerResponseis classified instead of relayed (404 ->NotFound, 401/403 ->Rejected, anything else ->Http(code)), so a transport bug cannot pass a redirect or the peer's error body through. x-slinuxm-peeris attached only when the name parses and the registry knows it; an unknown name is the contract's 404 with no peer header, and the proxy is not called.- Proxied
text/event-streamresponses now carryCache-Control: no-cachelike the localSseroutes. - The unreachable fallbacks are gone: the routes are merged only with a registry, so the handler expects one, and the peer name is taken from
PeerRegistry::status(one parse and one lookup) instead of being parsed again after a successful proxy. - Tests: allowlist and forward-form cases for escaped and
--root units (unit and behaviour level), non-2xx mapping rows (404,401,403,500,302), unknown/malformed peer names with no header and no transport call,no-cacheon a proxied follow, and the double-encoding/control-character rejections (%252f,%255c,%00,%0a,%0d) in bothbad_pathsandbad_queries. Each was checked to fail with the fix reverted (the unit-name, non-2xx status, encoding-rejection and no-cache tests were run against the old code); the unknown-peer header assertion replaces one that asserted the old labelled behaviour. - Disagreeing with / not doing:
- Disabled peers are still proxied in this tree, but the gating belongs to
PeerRegistry::getinsrc/peers/registry.rs, which WS-C does not own and WS-B's review already covers (its finding 2). A test here would have to assert behaviour C cannot change, so no C-side test is added; when B refuses disabled peers, the REST route inherits it unchanged because C only resolves the name via the registry. - The
raw_peer_pathNonebranch is kept: it is anOptioncheck on the request URI, not an error-shape fallback, and it is cheap insurance if the route pattern changes. 405on a proxied path is still produced by the router fallback inapi/mod.rs(not owned by WS-C), so it carries nox-slinuxm-peer; the contract's "every proxied response" is satisfied for responses that reach a peer handler, and WS-T does not assert the header on 405.
- Disabled peers are still proxied in this tree, but the gating belongs to
- Blocking: the proxy allowlist no longer keeps a second, stricter copy of unit-name validation.