Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-a-config.md
T
ari 4bfb097be6 A0: contract stubs types, transport, fake and registry seams
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.
2026-10-19 20:02:17 -04:00

60 lines
8.1 KiB
Markdown

# WS-A: Config, secrets, diagnostics CLI (and A0 contract stubs)
Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](contracts.md).
| Field | Value |
|---|---|
| Status | Not started |
| Owner | |
| Depends on | none |
| Blocks | [WS-B](ws-b-registry.md), [WS-C](ws-c-rest.md), [WS-D](ws-d-mcp.md), [WS-E](ws-e-telemetry.md) can start before A0 lands but cannot compile or merge until it does; A4 `peer check` needs B1/B2 |
| Can start when | day one, in parallel with [WS-T](ws-t-tests.md). **A0 first**: it is small and everything else rebases onto it |
| Owned files | `src/peers/mod.rs`, `src/peers/types.rs`, `src/peers/error.rs`, `src/peers/transport.rs`, `src/peers/testing.rs` (A0 creates; after A0 they change only through [contracts.md](contracts.md)), `src/peers/config.rs`, `src/peers/secrets.rs`, `src/peers/cli.rs`, `src/config.rs` (`[peers]`, validation), `src/main.rs` (`Command::Peer` and its dispatch only), `config.example.toml` (the `[peers]` block), `tests/peers_config.rs` |
| Created by A0, then owned by | `src/peers/registry.rs`, `src/peers/health.rs`, `src/peers/client.rs` (WS-B); `src/peers/proxy.rs`, `src/api/peers.rs` (WS-C); `src/api/ping.rs` (WS-B) |
| Do not touch | `src/peers/client.rs`, `health.rs`, `registry.rs` bodies after A0 (WS-B); `src/peers/proxy.rs`, `src/api/peers.rs`, `docs/api.md` (WS-C); `src/mcp/**` (WS-D); `src/telemetry/**` (WS-E); `nix/**`, `systemd/**`, `README.md`, `docs/consolidator.md` (WS-F); `dev/test.nu`, `devenv.nix`, `flake.nix` (WS-T); `Cargo.toml` except as noted below |
Shared-file seams (A0 wires them once, so later streams only fill their own files):
- `src/state.rs`: A0 adds `pub peers: Option<Arc<PeerRegistry>>` (always `None` in `AppState::live`) and fixes the other constructor, `sources::fake::fake_state` (`src/sources/fake.rs`), to set `peers: None`. WS-B later assigns the real registry where `serve()` builds the state (see ws-b seams). Nobody else edits `state.rs`.
- `src/lib.rs`: A0 adds `pub mod peers;`.
- `src/api/mod.rs`: A0 adds `pub mod peers; pub mod ping;` with stub modules and the merge lines in `router()`: `.merge(ping::routes())` (unconditional; the route is authenticated like the rest) and the peers routes merged only when `state.peers.is_some()`. WS-B fills `ping.rs`, WS-C fills `peers.rs`; neither edits `mod.rs`.
- `Cargo.toml`: A0 and A add nothing unless unavoidable (an `ipnet`-style CIDR crate for D11 `deny_cidrs` is allowed in A2; note it in the Log). WS-B owns `reqwest`/TLS dependency edits.
- `src/main.rs`: A edits the clap `Command` enum and its dispatch; WS-B edits `serve()` only.
## Goal
Peers are declared in config, validated, and loadable; the CLI can list and one-shot check them. No network loops yet.
## Tasks
- **A0** contract stubs (new, small, lands first; see [contracts.md](contracts.md) sections 1 to 4, 6). Add to `src/peers/`: `types.rs` (`PeerName`, `Secret`, `PeerConfig`, `PeersConfig`, `PeerStatus`/`ServerStatus`/`ApiStatus`/`AuthState`/`CheckClass`), `error.rs` (`PeerError`, `peer_error_to_app` with the D9 table), `transport.rs` (`PeerTransport`, `PeerRequest`, `PeerResponse`), `testing.rs` (`FakeTransport`, `fake_peers_config`, `registry_with`, `static_registry`, `fake_state_with_peers`), skeletons of `registry.rs` (`PeerRegistry` with `snapshot/status/contains/config/get` over a stored map and the transport, no loops), `proxy.rs` (`get` forwarding through the transport without allowlist; WS-C hardens it), `health.rs` (signature of `check_once`, a stub). Wire the seams listed above. Add `peers: PeersConfig` to `Config` with `#[serde(default)]` and `enabled = false`, so the peer-less default is unchanged. Tests: the D9 table (pure mapping), `FakeTransport` default and scripted behaviour, `static_registry` snapshot ordering. Done when `cargo build`, `cargo test`, clippy and fmt pass and every contract signature compiles; announce completion in the Log of A and of C, D, E. This task must not take more than a small PR; anything not needed to compile the contracts moves to A1 to A4 or B.
- **A1** `[peers]` config and `[[peers.peer]]` entries (keys in [contracts.md](contracts.md) section 6, "Config surface"), env `SKYG_PEERS__*` for the scalars, redaction check, `--print-config` (shows `token_file` paths, never contents). Also fills the `[peers]` block of `config.example.toml`.
- **A2** validation: name regex `^[a-z0-9][a-z0-9_-]{0,31}$`, unique names, URL rules (D11), `token_file` absolute and (when `peers.enabled`) readable at startup with a clear error naming the peer, max 64 peers. Also timeouts below their interval; `peers.enabled` with zero peers is a warning, not an error. A placeholder token file whose content is non-empty must load (see contracts section 10).
- **A3** secrets loader: read the token file at start and on reload; trim one trailing newline; reject empty, over 4 KiB, or world/group-readable files only when they are not under `$CREDENTIALS_DIRECTORY`; never log or `Debug`-print the value (wrapper type with redacted `Debug`).
- **A4** CLI `peer list` (config only) and `peer check <name>` (one-shot TCP plus API probe, prints classification and latency, never the token). Runs as any user that can read the config and token file. `peer list` is done within WS-A; `peer check` calls `peers::health::check_once` with the real transport, so it is wired when WS-B's B1/B2 land (until then it is tested with `FakeTransport` and returns "transport not available" in the binary). Record the wiring in the Log.
## Inputs
- [contracts.md](contracts.md) sections 1 to 4 and 6 (it defines what A0 builds); [decisions.md](decisions.md) D1, D2, D11, D13 and DEC-13.
- No fakes needed except `FakeTransport` for A4 tests.
## Done when
Unit tests for validation and loader; a peer-less default config is byte-identical in `--print-config` apart from the new `[peers]` block; the token never appears in stdout, logs, `--print-config` or `Debug` output.
## Handoff
- 2026-10-19 (A0): stubs are on branch `ws/A0`; C, D, E and B can compile against `src/peers/` now. Rebase rather than re-creating the files. `src/peers/{types,error,transport,testing}.rs` change only through contracts.md after this point; `registry.rs`, `proxy.rs` and `health.rs` are skeletons to be filled by WS-B (registry, health) and WS-C (proxy).
- A0 merged: C, D, E, B compile against the stubs; post in all their Logs.
- `PeersConfig`/`PeerConfig`, the secrets loader (`Secret`, `load_token(&PeerConfig) -> Result<Secret, PeerError>`) and `config.example.toml` `[peers]` block for B and F.
- The `peer` subcommand for the docs (F4).
## Log
- 2026-10-19: Split from the single phase plan 2026-10-19. A0 added to cover the shared stubs so C/D/E/F can start against fakes; ownership of the stub files passes to B/C after A0 merges.
- 2026-10-19 A0 (done): contract stubs landed. `src/peers/{types,error,transport,testing,registry,proxy,health}.rs`, `src/api/{ping,peers}.rs` stubs, `AppState.peers`, `Config.peers`, `src/api/mod.rs` merge seam, `tests/peers_config.rs`.
- Decisions taken here (contract allows the implementer to choose): timestamps are `jiff::Timestamp` (the type the existing DTOs use); `testing.rs` is plain `pub` like `sources::fake`, because integration tests compile the library without `cfg(test)`; `health::check_once` is a minimal TCP + `GET /api/v1/ping` probe (401/403 -> `api.up = true, auth = rejected`, D4) and WS-B replaces its classification/version parsing; `ProxyOpts` lives in `registry.rs` as the contract says; `proxy::get` already adds `x-slinuxm-hop: 1` and any traceparent (never an Authorization header) but no allowlist (WS-C).
- Contract discrepancy: section 3 declares `reload(&self, new: PeersConfig) -> Result<(), PeerConfigError>` but no `PeerConfigError` type exists in the contract or the tree. Implemented as `Result<(), crate::config::ConfigError>` (the existing error for invalid configuration). Please fix the name in contracts.md if that is not the intent.
- `Cargo.toml`: added `url` (needed for the contract's `url::Url` field, already in `Cargo.lock` via reqwest) and `bytes` (contract's `Bytes` body type, already in the lock). `cargo tree -i openssl` still empty.
- Logged in WS-C, WS-D and WS-E: stubs are available, compile against them.