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

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 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 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 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 sections 1 to 4 and 6 (it defines what A0 builds); 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

  • 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.