Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-c-rest.md
T
2026-10-19 16:43:35 -04:00

46 lines
3.5 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 | 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](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.