13 KiB
13 KiB
WS-C: REST surface
Part of Phase 5: Consolidator. Contracts: contracts.md sections 3 to 5.
| Field | Value |
|---|---|
| Status | Merged |
| 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.
- 2026-10-19 (review round 2): fixes.
- Blocking: proxied journal query values now accept what the local route accepts on the unit side.
query_value_ok(key, value)takes the key: forunitit callssources::systemd::validate_unit_name, the helper the localsystemd/units/{name}route already uses, so there is still one unit rule and no second validator. Escaped units (mnt-data\x2dbackup.mount,dev-disk-by\x2did.device) therefore work throughjournalandjournal/followas text, as%5Cand as%5c; the value is forwarded decoded, which is what the transport re-encodes as one query pair. Other keys keep the generic\,/and..rejection, and every key keeps the length bound, the control-character rule and the second-encoding-layer rejection (%252f,%255c,%2e%2e). - Tests:
journal_unit_values_are_forwarded_like_the_local_route(raw,%5C,%5c, a second key,-.mount,user@100.service, and a decodedunitpair for the MCP path) andjournal_unit_values_still_reject_unsafe_textinproxy.rs; behaviour-levelproxy_forwards_journal_unit_values_the_local_route_acceptsasserts the forwarded query values and that an unknown key or traversal text is still400.proxy_forwards_unit_names_the_local_route_acceptsgained a raw-backslash systemd path next to the encoded ones, so both routes cover raw and encoded input. With theunitbranch reverted, all three journal tests fail on the old check (the behaviour one with the reported400), so they pin the fix. - Non-blocking 2: the status table is now
proxy::classify_status(u16) -> PeerError, one function with one test (status_classification_is_one_table).prepare_responsecalls it and keeps the 2xx-only guard as defence in depth. Handoff to WS-B: the real transport classifies a live response withcrate::peers::proxy::classify_statusinstead of copying the table, so the two cannot drift. - Handoff to WS-D:
PeerRequest.querycarries decoded pairs. Aunitargument reaches the proxy as the unit name itself (dev-disk-by\x2did.device, backslash included) and needs no encoding on D's side; the tool schema takes the plain name, so an already percent-encoded string such asdev-disk-by%5Cx2did.deviceis not a unit name and is400. - Non-blocking 3: a
..inside a single segment is not traversal, because segments cannot contain/and the forwarded path is re-encoded from them. Pinned by allowlist casessystemd/units/foo..bar.mountanddocker/containers/foo..bar, plus a rejection case for an encoded%2e%2einside one segment (systemd/units/foo%2e%2ebar.mount), whichencoding_forbiddencatches. docs/api.mdstates theunitquery rule and the%5C/literal-backslash forms.
- Blocking: proxied journal query values now accept what the local route accepts on the unit side.