Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-a-config.md
T
2026-10-19 20:02:42 -04:00

11 KiB

WS-A: Config, secrets, diagnostics CLI (and A0 contract stubs)

Part of Phase 5: Consolidator. Contracts: contracts.md.

Field Value
Status In progress (A0 merged)
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

  • 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).
  • 2026-10-19 (review round 1): [[peers.peer]] deserializes with enabled defaulting to true and allow_plain_http / ca_file optional, so the VM entry shape loads. PeerRegistry::reload returns PeerConfigError (alias of config::ConfigError). class_str no longer copies a peer's BadRequest text into last_error.

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.
  • 2026-10-19 A0 review round 1: addressed loop/A0/review-1.md.
    • Blocking: PeerConfig field defaults. enabled defaults to true, allow_plain_http to false, and ca_file may be omitted (the VM entry lists it as optional; without a default, beta's entry fails the same way enabled did). Config::load of that shape is vm_peer_entries_load_when_enabled_and_ca_file_are_omitted in tests/peers_config.rs; a toml parse of the same omission sits next to the type.
    • proxy.rs module comment now says the allowlist, .. / encoded-slash rejection and the query allowlist belong in that module and are not implemented yet. REST and MCP still share proxy::get.
    • reload returns peers::PeerConfigError, a public alias of config::ConfigError. contracts.md already names that type, so it was not edited (not an owned file, and the name there is already the one the review asked the code to match). The earlier log line asking for a contracts.md rename is superseded by this alias.
    • PeerError::class_str returns the fixed token bad_request for BadRequest. The peer's message stays only in peer_error_to_app (D9). check_once stores class_str() in last_error, covered by bad_request_last_error_is_a_class_string.
    • status and contains parse the name and use BTreeMap::get; an unparseable name is an unknown peer. get parses and compares PeerName against config.peer. That field stays a Vec (serde order, contract section 1), so it is not a second map; a key compare is the lookup .get would do.
    • FakeTransport delay is asserted with a paused clock (per_peer_isolation_and_delay). That needs tokio's test-util feature, added as a dev-dependency only (full does not include it, and cargo build does not turn it on). /api/v1/ping without a bearer token is 401 on server::build_router, and 200 with one (ping_without_a_token_is_unauthorized). The handler's exact version assertion stays in src/api/ping.rs. tests/integration.rs was not edited: it is outside the owned files, and finding 7 allows this test to carry the 401 case.
    • check_once still leaves API latency_ms unset. A comment says the probe that replaces the stub is what measures it for peer check.
    • For WS-C: when peers::routes() is filled, assert GET /api/v1/peers is 404 when state.peers is None. The merge in api/mod.rs cannot be observed while routes() is empty, so no test was added here.
    • Not changed, on purpose:
      • TODO.md A0 box stays unticked. This round says the merger ticks it, and TODO.md is not an owned file. AGENTS.md's definition-of-done item 4 is the merger's step.
      • The direct bytes dependency stays. The body type in the transport contract is bytes::Bytes; axum only re-exports the same crate. Dropping the direct dep would not change the graph, and the 2026-10-19 log already records why it was added.