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

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 added AppState.peers. B assigns it in serve() in src/main.rs (state is built there by AppState::live, then state.peers = peers::start(&state) before server::build_router). One edit region, serve(); WS-A edits the Command enum elsewhere in the file.
  • SIGHUP: serve() installs the handler and tls::spawn_sighup_reload consumes it. B adds the fan-out so the same signal also calls PeerRegistry::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.rs is already merged by A0. B only fills ping::routes().
  • Cargo.toml/Cargo.lock: B owns dependency edits (reqwest direct dep per D15, features, any CIDR crate not already added by A). Regenerate Cargo.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-peer Semaphore plus a global one, custom CA per peer, rustls with the ring provider passed explicitly; cargo tree -i openssl stays empty. Implements PeerTransport for real (ReqwestTransport) and records the D15 outcome in the Log.
  • B2 health loops: one task per peer with its own child CancellationToken and start jitter; TCP check = TcpStream::connect(host:port) under timeout; API check = authenticated GET /api/v1/ping; classification ok | unauthorized | http_error | timeout | unreachable | tls_error. Provides health::check_once (shared with slinuxm peer check, A4) and the /api/v1/ping handler in ping.rs returning {status, version}; fallback for peers without /ping is /healthz plus auth = 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 need fail_threshold consecutive failures, recovery is immediate; since is 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 PeerTransport trait 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: FakeTransport and registry_with for 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 PeerRegistry with the contract API (snapshot, status, get, reload, shutdown) assigned to AppState.peers when peers.enabled.
  • GET /api/v1/ping; ReqwestTransport; health::check_once for 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.