52 lines
7.4 KiB
Markdown
52 lines
7.4 KiB
Markdown
# WS-C: REST surface
|
|
|
|
Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](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](ws-d-mcp.md) 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](contracts.md) section 5.
|
|
|
|
## Goal
|
|
|
|
Status and pass-through over REST under the existing auth.
|
|
|
|
## Tasks
|
|
|
|
- **C1** `GET /api/v1/peers` and `/{peer}`: status JSON (shape in contracts section 5), sorted by name; unknown peer is `NotFound`.
|
|
- **C2** pass-through `GET /api/v1/peers/{peer}/{*path}`: allowlist of the peer's documented routes (`systemd/...`, `journal`, `journal/follow`, `docker/...`; `ping` and `peers/...` excluded), reject `..`, encoded slashes and non-allowlisted query keys; forward only the allowlisted query; never forward the caller's `Authorization` or cookies, use the peer token; add `x-slinuxm-hop: 1` and reject requests that already carry it (no chaining); stream bodies through the size cap; SSE passes through bounded by `limits.max_follow_secs` and shutdown. Implemented in `src/peers/proxy.rs` as the body of `PeerRegistry::get`, which WS-D also calls; the route in `peers.rs` is 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 extra `peer` field to the REST error body is optional; if done it is a contracts.md change plus `src/error.rs`.
|
|
|
|
## Inputs
|
|
|
|
- Contracts sections 3 (registry API), 4 (error table), 5 (REST shapes).
|
|
- Fakes: `FakeTransport` (records calls to assert hop header, no `Authorization`, 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::get` fully implemented (allowlist, hop, mapping) for WS-D; post in D's Log when C2 merges.
|
|
- `docs/api.md` section 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` (not `api/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.rs` stub, `AppState.peers`, `Config.peers`, `tests/peers_config.rs`). `PeerRegistry::get` forwards through `PeerTransport` and `proxy.rs` already adds `x-slinuxm-hop` and traceparent; path/query allowlists, the hop-header rejection and the `x-slinuxm-peer` response header are still yours. `api::peers::routes()` is empty and merged only when `state.peers.is_some()`, so fill it without touching `api/mod.rs`.
|
|
- 2026-10-19 (C1): `GET /api/v1/peers` and `/peers/{peer}` landed in `src/api/peers.rs` (sorted snapshot, one object for the single-peer route, `peer <name>: unknown peer` 404), 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.md` gained the route table row and the status section.
|
|
- 2026-10-19 (C2): the allowlist proxy is the body of `PeerRegistry::get` in `src/peers/proxy.rs`; `src/api/peers.rs` is a thin adapter that parses the raw (still percent-encoded) path, the raw query and the trace/accept headers, then renders `PeerResponse`. Allowed routes: `systemd/units`, `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs`; an `/api/v1` prefix 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 is `peer <name>: unsupported query parameter`. The caller's `Authorization`/`Cookie` are never copied (the request is rebuilt, the transport attaches the peer token), `x-slinuxm-hop: 1` is added and any inbound hop header is `400 peer <name>: chained requests are not allowed`. Buffered bodies over `peers.max_response_bytes` are `503 oversize`; streams are cut at the cap, at `limits.max_follow_secs` or on the shared `CancellationToken`. SSE is selected by `Accept` or `journal/follow` / docker `follow=1`. A peer `Content-Type` that is not a valid header value becomes `500 malformed response` instead 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 own `400`/`404`/`500`/`503` for that peer (a `405` is produced by the router fallback in `api/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 no `peer` field 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 is `401`, 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) and `cargo tree -i openssl` (empty) pass. WS-D can call `PeerRegistry::get` now: it takes `/api/v1`-prefixed or bare paths, returns `PeerResponse` with the peer's status/content type/body, or an already-mapped `AppError`; SSE callers set `ProxyOpts.accept_sse` and must bound the returned stream with their own shutdown/deadline. WS-F/WS-T: the `x-slinuxm-peer` header, 405, hop-header 400, 503-with-peer-name and query filtering behaviours the VM test asserts are covered by `src/api/behaviour_tests.rs`. Re-check against the real registry once B lands (real transport must map peer statuses to `PeerError` before C sees them; the fake returns statuses verbatim). No Nix VM test was run by this workstream.
|