Files
2026-10-20 16:35:11 -04:00

22 KiB

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

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

Field Value
Status 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.
  • 2026-10-19 A1 (done): Config.peers is PeersConfig with #[serde(default)]; the scalar SKYG_PEERS__* overrides need no bespoke code because the existing figment Env::prefixed("SKYG_").split("__") provider already nests them, and peer entries stay file-only (verified by peers_env_overrides_scalars_and_keeps_file_entries). to_toml_redacted prints token_file paths and no token value; config.example.toml has the [peers] block. Integration test print_config_shows_peer_paths_and_not_token_contents runs the real binary with a private token file and asserts neither stream contains the value.
  • 2026-10-19 A2 (done): peers::config::validate covers name regex and uniqueness (via PeerName::parse plus a set), the 64-peer cap, URL scheme/userinfo/query/fragment/host, literal-IP deny_cidrs, plain-http-to-non-loopback with allow_plain_http and a warning that omits the address, absolute token_file/ca_file, and timeouts below their interval. enabled with no peers is a warning. Token readability is checked only for peers the process would call (peers.enabled && peer.enabled), so a disabled entry can name a credential that is not on disk yet; a non-empty placeholder file loads (VMs install the real token later). Cargo.toml: added ipnet for deny_cidrs parsing, as the workstream file allows; cargo tree -i openssl still empty.
  • 2026-10-19 A3 (done): src/peers/secrets.rs reads the file on every call and returns a Secret, so rotation needs no restart and no copy survives the call. It trims one trailing newline (and a preceding \r), refuses empty, non-UTF-8, over 4 KiB, non-files and unreadable paths, and refuses group/world-readable files unless the path canonicalizes under $CREDENTIALS_DIRECTORY; an empty or unset directory keeps the mode check (fail closed). Errors carry a short reason, never the path or bytes. Unit tests assert redacted Debug/Display, no log output, size boundaries and the permission rule; the integration test config_load_uses_the_token_loader_and_rereads_a_rotated_file exercises Config::load for both permission cases and re-reads a replaced file.
  • 2026-10-19 A4 (done): src/peers/cli.rs adds PeerCmd::{List,Check} and Command::Peer in src/main.rs. peer list renders name/enabled/URL/token path sorted by name, from configuration only, and needs no database or transport. peer check <name> resolves the configured peer, then runs health::check_once with the configured timeouts through an injected PeerTransport and prints the server/API class and latency plus the auth state. A rejected credential renders as api up, auth rejected. It never prints a token; errors name the peer or the missing transport only.
    • Wiring for WS-B: cli::real_transport() is the single seam. When B1/B2 land, replace its body (currently bail!("peer check: transport not available ...")) with the real client, including its limits; check_report and its tests stay unchanged. Until then the binary lists peers but peer check fails with that message; the one-shot probe itself is covered with FakeTransport in src/peers/cli.rs and tests/peers_config.rs, including timeout/TLS classes and a revoked token.
  • 2026-10-19 Handoff (WS-A): A1 to A4 are committed on ws/A in task order (A: A1 ..., A: A2 ..., A: A3 ..., A: A4 ...) on top of A0. cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test and cargo tree -i openssl (no match) are clean. Owned files touched: src/peers/{cli,config,secrets,mod}.rs, src/config.rs, src/main.rs, config.example.toml [peers], tests/peers_config.rs, plus ipnet in Cargo.toml/Cargo.lock. Nothing outside the owned list changed and TODO.md was left for the merger.
    • Still open for others: peer check against a real peer (needs B1/B2 and real_transport); PeerRegistry::reload must call the loader (B4) for reload-time re-reads; the registry/serve wiring and SIGHUP fan-out are WS-B. No Nix files changed here, so no VM test was run; when one is needed the command is nix build && nix flake check.
    • Contract issue carried over from A0 (unchanged): section 3's PeerConfigError is implemented as an alias of config::ConfigError; no contracts.md edit was made from this workstream.
  • 2026-10-20 Gate round 1 (loop/A/gate-2.log):
    • Duplication: the tracing capture layer both peer test modules used now lives once in src/peers/testing.rs as capture::logged (test-only, #[cfg(test)]), so config.rs and secrets.rs tests share it instead of each carrying Capture/FieldVisit. tests/peers_config.rs uses one PeerFixture (private token file plus the single-beta config, with a scalars argument for the timeout lines) instead of writing the same TOML three times.
    • Cargo.toml: ipnet is the one dependency this workstream adds, and the plan allows it for A2 deny_cidrs (see the A2 entry above). No other dependency changed; cargo tree -i openssl is still empty. The gate's ownership step flags Cargo.toml, which the plan authorises; the file is listed in the shared-file seam for exactly this case.
  • 2026-10-19 Review round 2 (loop/A/review-n.md): every Blocking and Important item addressed; minors fixed except where noted. Rebased onto main (B merged): the only textual conflict was the import list in src/main.rs (both sides kept), and Cargo.toml gained ipnet twice (B's pin 2.11.0 in the dependency block was kept, this workstream's line removed, same lock entry).
    • Blocking 1 (token files read by every subcommand) — fixed by splitting the check. peers::config::validate is structural only (names and uniqueness, the 64 cap, URL rules, deny CIDRs, absolute token_file/ca_file, timeouts below intervals, the enabled-with-no-peers warning) and never opens a file. peers::config::validate_tokens opens the files of the peers this process would contact, validate_peer_token does it for one peer, and Config::validate_token_readiness exposes the former. Config::load calls only the structural part, so token create|list, peer list, --print-config and an unknown-name peer check work where the credential is absent. serve() runs validate_token_readiness before telemetry, the database or the listener; peer check runs validate_peer_token on the probed peer only. Binary tests: commands_that_do_not_contact_a_peer_work_without_the_token_file (print-config, peer list, token create and list with a nonexistent token_file), serve_refuses_to_start_and_names_the_peer_with_the_unreadable_token, peer_check_reports_the_missing_token_before_the_missing_transport. Unit tests token_file_must_be_absolute_but_is_not_opened_by_structural_checks and token_readiness_is_checked_only_for_peers_that_are_contacted. This also fixes the reload path for free: B's SIGHUP reload goes through Config::load, so a rotated or not-yet-installed credential cannot block a reload.
    • Important 2 (byte-identical print-config not tested) — fixed with a committed snapshot. tests/peers_config.rs holds PRE_PEERS_DEFAULT (the full pre-peers --print-config text) and PEERS_DEFAULT (the peer-less [peers] table). The default output must equal the two concatenated; a config with a peer must leave everything before [peers] byte-identical. Any change to another section now fails and has to be explained.
    • Important 3 (tests that could not fail) — fixed. The bad-name assertion now matches must match ^[a-z0-9][a-z0-9_-]{0,31}$ instead of accepting any message containing the input. list_report is fed a token_file that does not exist, which proves the report renders from config alone (writing a secret and asserting its absence proved nothing, and the duplicated gamma assertion is gone). New loader tests: a_directory_is_not_a_token_file and a_symlink_cannot_borrow_the_credentials_directory_exemption (a link under $CREDENTIALS_DIRECTORY to a 0644 file outside it is rejected, because the target's mode decides).
    • Important 4 (A4 overstated API latency) — resolved rather than deferred. B is merged in this rebase, so cli::real_transport now builds ReqwestTransport from [peers] (limits and deny list included) instead of bailing. check_once is B's probe, which times the API request, so peer check now really prints classification and latency: peer_check_binary_probes_a_real_peer_and_prints_latency asserts server up (...), api up, auth ok and a ms value against a real loopback server, plus rejected-credential, unreachable-peer and unknown-name binary tests. The earlier log line ("prints the classification and latency") was true of the injection point but not of the binary until now; no B2 obligation is left. server up latency is a connect time, so it can read 0 ms; only the API latency is the probe's measured round trip.
    • Minor 5 (duplicated test helpers, flaky temp names) — fixed. peers::testing::TempDir is now the single scratch-directory fixture (new(prefix), path, write(name, bytes, mode), write_token(contents)), used by the config.rs and secrets.rs unit tests and by tests/peers_config.rs; the three copies and the ad-hoc temp paths are gone, and the name is pid + sequence + nanos with a retry on AlreadyExists.
    • Minor 6 (IPv4-mapped literals) — fixed here, not deferred. host_ip canonicalises with IpAddr::to_canonical, so http://[::ffff:169.254.169.254] is matched against the IPv4 deny list (test ipv4_mapped_ipv6_literals_match_the_v4_deny_list); the same canonicalisation makes [::ffff:127.0.0.1] count as loopback. Connect-time enforcement stays B5's.
    • Minor 7 (blocking loader) — recorded in WS-B's Log. load_token is unchanged: it is called once at startup and once per API check by B's transport, inside its request deadline. B's transport already reads the file per check; the note asks for spawn_blocking or a bounded tokio::fs read if that ever moves to a hot path.
    • Minor 8 (host in the plain-http error) — fixed. The error no longer names the host, matching the warning that deliberately omits the address.
    • src/main.rs beyond the Command::Peer region (one line, as the review asked): serve() now calls config.validate_token_readiness() before it installs the SIGHUP handler, opens the database or binds. serve() is otherwise WS-B's; the call is the whole of this workstream's change there, and it needs no cooperation from the registry.
    • One edit outside the owned list, on purpose: src/peers/registry.rs (B's file) had two fixtures with api_interval_secs = 2 and the default api_timeout_secs = 5, which the A2 timeout rule rejects; the reload and SIGHUP tests failed as soon as the branches met. One line, api_timeout_secs = 1, added to the reload test's inline TOML; the other test's reload now passes because Config::load no longer opens token files.
    • Scope note (for the merger): wiring real_transport in this workstream is the plan's "A4 is wired when B1/B2 land" condition, taken now because B is merged and cli.rs is A's file. The seam paragraph in B's Log is updated to point here.