5.3 KiB
5.3 KiB
WS-B: Client, health, registry
Part of Phase 5: Consolidator. Contracts: contracts.md sections 1 to 4 and 8.
| Field | Value |
|---|---|
| Status | Not started |
| Owner | |
| Depends on | A0 (stubs and seams) and A1 to A3 for real config/secrets; can start on B1 as soon as A0 lands |
| Blocks | integration of C, D, E (they are developed against the fake registry and finish for real once B lands); F |
| Can start when | A0 is merged (design and client code can begin earlier in a branch against contracts.md) |
| Owned files | src/peers/client.rs, src/peers/health.rs, src/peers/registry.rs (bodies; signatures per contracts), src/api/ping.rs (new authenticated GET /api/v1/ping, see D4), Cargo.toml/Cargo.lock, src/main.rs (serve() only), src/tls.rs (SIGHUP fan-out line only, if the handler stays there), tests/peers_registry.rs, tests/common/mod.rs (append new helpers only) |
| Do not touch | src/peers/types.rs, transport.rs, error.rs, testing.rs (change via contracts.md only); src/peers/config.rs, secrets.rs, cli.rs, src/config.rs (WS-A); src/peers/proxy.rs, src/api/peers.rs, src/api/mod.rs, src/error.rs (WS-C / A0); src/mcp/** (D); src/telemetry/** (E); nix/**, docs/**, README.md (F, T) |
Shared-file seams:
src/state.rs: do not edit; A0 addedAppState.peers. B assigns it inserve()insrc/main.rs(state is built there byAppState::live, thenstate.peers = peers::start(&state)beforeserver::build_router). One edit region,serve(); WS-A edits theCommandenum elsewhere in the file.- SIGHUP:
serve()installs the handler andtls::spawn_sighup_reloadconsumes it. B adds the fan-out so the same signal also callsPeerRegistry::reload(and the plain-TLS-off branch no longer just logs when peers are enabled). Keep the TLS reload behaviour unchanged. src/api/mod.rs: untouched;ping.rsis already merged by A0. B only fillsping::routes().Cargo.toml/Cargo.lock: B owns dependency edits (reqwest direct dep per D15, features, any CIDR crate not already added by A). RegenerateCargo.lock, never hand-merge.tests/common/mod.rs: append-only helpers; WS-F appends too.
Goal
A PeerRegistry built from config that keeps live status; a bounded HTTP client.
Tasks
- B1 client: connect/request timeouts, redirects disabled, GET only, response byte cap enforced while streaming (not just
Content-Length), per-peerSemaphoreplus a global one, custom CA per peer, rustls with the ring provider passed explicitly;cargo tree -i opensslstays empty. ImplementsPeerTransportfor real (ReqwestTransport) and records the D15 outcome in the Log. - B2 health loops: one task per peer with its own child
CancellationTokenand start jitter; TCP check =TcpStream::connect(host:port)under timeout; API check = authenticatedGET /api/v1/ping; classificationok | unauthorized | http_error | timeout | unreachable | tls_error. Provideshealth::check_once(shared withslinuxm peer check, A4) and the/api/v1/pinghandler inping.rsreturning{status, version}; fallback for peers without/pingis/healthzplusauth = unknown(D4). - B3 status model (in memory only):
{server: {up, since, last_checked, last_error}, api: {up, since, last_checked, last_error, latency_ms, auth: ok|rejected|unknown, peer_version}}; flips needfail_thresholdconsecutive failures, recovery is immediate;sinceis the last change time and resets on restart. - B4 reload: on startup build the registry; on SIGHUP (shared handler with TLS) re-read only the
[peers]block and token files, start loops for new peers, cancel removed ones, restart changed ones; a bad reload keeps the old registry (same rule as TLS T3). Token files are re-read on every API check, so rotating an agenix secret needs no restart. Shutdown awaits all loops (bounded). - B5
PeerTransporttrait and fake; SSRF guard (D11) applied at config load and again at connect time on the resolved address. The trait and fake already exist from A0 (contracts section 2); B5 is now the SSRF guard on the real transport plus any fake extensions the loops need (changed through contracts.md).
Inputs
- contracts.md sections 1 to 4 (types, transport, registry API, error mapping), 6 (config), 10 (the test's timings and rotation flow).
- Fake:
FakeTransportandregistry_withfor loop/classification unit tests with paused time; real in-process servers for the integration test.
Done when
Integration test starts a second in-process server (fake sources) as a peer and observes up, down (port closed), api-down-but-server-up (listener that accepts and hangs), unauthorized (wrong token) and recovery; one hung peer does not delay another peer's check beyond its own timeout; clippy, fmt, cargo tree -i openssl clean.
Handoff
- Real
PeerRegistrywith the contract API (snapshot,status,get,reload,shutdown) assigned toAppState.peerswhenpeers.enabled. GET /api/v1/ping;ReqwestTransport;health::check_oncefor A4.- Post in C, D, E, F Logs when the registry is wired, so they swap their fakes for real end-to-end checks.
Log
- 2026-10-19: Split from the single phase plan 2026-10-19. The trait and fake moved to A0 so C/D/E are not blocked on this stream; B keeps the implementations.