Land the shared peer contracts: types, error mapping, transport trait, fake transport and fixtures, registry/proxy/health skeletons, the AppState.peers and Config.peers seams, the ping and peers route stubs, and unit plus integration tests. No loops, no network, feature off by default.
47 lines
4.0 KiB
Markdown
47 lines
4.0 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.
|
|
- 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`.
|