6.3 KiB
6.3 KiB
WS-A: Config, secrets, diagnostics CLI (and A0 contract stubs)
Part of Phase 5: Consolidator. Contracts: contracts.md.
| Field | Value |
|---|---|
| Status | Not started |
| Owner | |
| Depends on | none |
| Blocks | WS-B, WS-C, WS-D, WS-E 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. 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), 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 addspub peers: Option<Arc<PeerRegistry>>(alwaysNoneinAppState::live) and fixes the other constructor,sources::fake::fake_state(src/sources/fake.rs), to setpeers: None. WS-B later assigns the real registry whereserve()builds the state (see ws-b seams). Nobody else editsstate.rs.src/lib.rs: A0 addspub mod peers;.src/api/mod.rs: A0 addspub mod peers; pub mod ping;with stub modules and the merge lines inrouter():.merge(ping::routes())(unconditional; the route is authenticated like the rest) and the peers routes merged only whenstate.peers.is_some(). WS-B fillsping.rs, WS-C fillspeers.rs; neither editsmod.rs.Cargo.toml: A0 and A add nothing unless unavoidable (anipnet-style CIDR crate for D11deny_cidrsis allowed in A2; note it in the Log). WS-B ownsreqwest/TLS dependency edits.src/main.rs: A edits the clapCommandenum and its dispatch; WS-B editsserve()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 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_appwith the D9 table),transport.rs(PeerTransport,PeerRequest,PeerResponse),testing.rs(FakeTransport,fake_peers_config,registry_with,static_registry,fake_state_with_peers), skeletons ofregistry.rs(PeerRegistrywithsnapshot/status/contains/config/getover a stored map and the transport, no loops),proxy.rs(getforwarding through the transport without allowlist; WS-C hardens it),health.rs(signature ofcheck_once, a stub). Wire the seams listed above. Addpeers: PeersConfigtoConfigwith#[serde(default)]andenabled = false, so the peer-less default is unchanged. Tests: the D9 table (pure mapping),FakeTransportdefault and scripted behaviour,static_registrysnapshot ordering. Done whencargo 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 section 6, "Config surface"), envSKYG_PEERS__*for the scalars, redaction check,--print-config(showstoken_filepaths, never contents). Also fills the[peers]block ofconfig.example.toml. - A2 validation: name regex
^[a-z0-9][a-z0-9_-]{0,31}$, unique names, URL rules (D11),token_fileabsolute and (whenpeers.enabled) readable at startup with a clear error naming the peer, max 64 peers. Also timeouts below their interval;peers.enabledwith 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 orDebug-print the value (wrapper type with redactedDebug). - A4 CLI
peer list(config only) andpeer 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 listis done within WS-A;peer checkcallspeers::health::check_oncewith the real transport, so it is wired when WS-B's B1/B2 land (until then it is tested withFakeTransportand returns "transport not available" in the binary). Record the wiring in the Log.
Inputs
- contracts.md sections 1 to 4 and 6 (it defines what A0 builds); decisions.md D1, D2, D11, D13 and DEC-13.
- No fakes needed except
FakeTransportfor 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
- 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>) andconfig.example.toml[peers]block for B and F.- The
peersubcommand 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.