16 KiB
16 KiB
WS-A: Config, secrets, diagnostics CLI (and A0 contract stubs)
Part of Phase 5: Consolidator. Contracts: contracts.md.
| Field | Value |
|---|---|
| Status | A1 to A4 done on ws/A, awaiting merge |
| 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
- 2026-10-19 (A0): stubs are on branch
ws/A0; C, D, E and B can compile againstsrc/peers/now. Rebase rather than re-creating the files.src/peers/{types,error,transport,testing}.rschange only through contracts.md after this point;registry.rs,proxy.rsandhealth.rsare 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>) andconfig.example.toml[peers]block for B and F.- The
peersubcommand for the docs (F4). - 2026-10-19 (review round 1):
[[peers.peer]]deserializes withenableddefaulting to true andallow_plain_http/ca_fileoptional, so the VM entry shape loads.PeerRegistry::reloadreturnsPeerConfigError(alias ofconfig::ConfigError).class_strno longer copies a peer'sBadRequesttext intolast_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}.rsstubs,AppState.peers,Config.peers,src/api/mod.rsmerge 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.rsis plainpublikesources::fake, because integration tests compile the library withoutcfg(test);health::check_onceis a minimal TCP +GET /api/v1/pingprobe (401/403 ->api.up = true, auth = rejected, D4) and WS-B replaces its classification/version parsing;ProxyOptslives inregistry.rsas the contract says;proxy::getalready addsx-slinuxm-hop: 1and any traceparent (never an Authorization header) but no allowlist (WS-C). - Contract discrepancy: section 3 declares
reload(&self, new: PeersConfig) -> Result<(), PeerConfigError>but noPeerConfigErrortype exists in the contract or the tree. Implemented asResult<(), crate::config::ConfigError>(the existing error for invalid configuration). Please fix the name in contracts.md if that is not the intent. Cargo.toml: addedurl(needed for the contract'surl::Urlfield, already inCargo.lockvia reqwest) andbytes(contract'sBytesbody type, already in the lock).cargo tree -i opensslstill empty.- Logged in WS-C, WS-D and WS-E: stubs are available, compile against them.
- Decisions taken here (contract allows the implementer to choose): timestamps are
- 2026-10-19 A0 review round 1: addressed
loop/A0/review-1.md.- Blocking:
PeerConfigfield defaults.enableddefaults to true,allow_plain_httpto false, andca_filemay be omitted (the VM entry lists it as optional; without a default, beta's entry fails the same wayenableddid).Config::loadof that shape isvm_peer_entries_load_when_enabled_and_ca_file_are_omittedintests/peers_config.rs; a toml parse of the same omission sits next to the type. proxy.rsmodule 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 shareproxy::get.reloadreturnspeers::PeerConfigError, a public alias ofconfig::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_strreturns the fixed tokenbad_requestforBadRequest. The peer's message stays only inpeer_error_to_app(D9).check_oncestoresclass_str()inlast_error, covered bybad_request_last_error_is_a_class_string.statusandcontainsparse the name and useBTreeMap::get; an unparseable name is an unknown peer.getparses and comparesPeerNameagainstconfig.peer. That field stays aVec(serde order, contract section 1), so it is not a second map; a key compare is the lookup.getwould do.FakeTransportdelay is asserted with a paused clock (per_peer_isolation_and_delay). That needs tokio'stest-utilfeature, added as a dev-dependency only (fulldoes not include it, andcargo builddoes not turn it on)./api/v1/pingwithout a bearer token is 401 onserver::build_router, and 200 with one (ping_without_a_token_is_unauthorized). The handler's exact version assertion stays insrc/api/ping.rs.tests/integration.rswas not edited: it is outside the owned files, and finding 7 allows this test to carry the 401 case.check_oncestill leaves APIlatency_msunset. A comment says the probe that replaces the stub is what measures it forpeer check.- For WS-C: when
peers::routes()is filled, assertGET /api/v1/peersis 404 whenstate.peersisNone. The merge inapi/mod.rscannot be observed whileroutes()is empty, so no test was added here. - Not changed, on purpose:
TODO.mdA0 box stays unticked. This round says the merger ticks it, andTODO.mdis not an owned file. AGENTS.md's definition-of-done item 4 is the merger's step.- The direct
bytesdependency stays. The body type in the transport contract isbytes::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.
- Blocking:
- 2026-10-19 A1 (done):
Config.peersisPeersConfigwith#[serde(default)]; the scalarSKYG_PEERS__*overrides need no bespoke code because the existing figmentEnv::prefixed("SKYG_").split("__")provider already nests them, and peer entries stay file-only (verified bypeers_env_overrides_scalars_and_keeps_file_entries).to_toml_redactedprintstoken_filepaths and no token value;config.example.tomlhas the[peers]block. Integration testprint_config_shows_peer_paths_and_not_token_contentsruns the real binary with a private token file and asserts neither stream contains the value. - 2026-10-19 A2 (done):
peers::config::validatecovers name regex and uniqueness (viaPeerName::parseplus a set), the 64-peer cap, URL scheme/userinfo/query/fragment/host, literal-IPdeny_cidrs, plain-http-to-non-loopback withallow_plain_httpand a warning that omits the address, absolutetoken_file/ca_file, and timeouts below their interval.enabledwith 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: addedipnetfordeny_cidrsparsing, as the workstream file allows;cargo tree -i opensslstill empty. - 2026-10-19 A3 (done):
src/peers/secrets.rsreads the file on every call and returns aSecret, 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 redactedDebug/Display, no log output, size boundaries and the permission rule; the integration testconfig_load_uses_the_token_loader_and_rereads_a_rotated_fileexercisesConfig::loadfor both permission cases and re-reads a replaced file. - 2026-10-19 A4 (done):
src/peers/cli.rsaddsPeerCmd::{List,Check}andCommand::Peerinsrc/main.rs.peer listrenders 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 runshealth::check_oncewith the configured timeouts through an injectedPeerTransportand prints the server/API class and latency plus the auth state. A rejected credential renders asapi 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 (currentlybail!("peer check: transport not available ...")) with the real client, including its limits;check_reportand its tests stay unchanged. Until then the binary lists peers butpeer checkfails with that message; the one-shot probe itself is covered withFakeTransportinsrc/peers/cli.rsandtests/peers_config.rs, including timeout/TLS classes and a revoked token.
- Wiring for WS-B:
- 2026-10-19 Handoff (WS-A): A1 to A4 are committed on
ws/Ain task order (A: A1 ...,A: A2 ...,A: A3 ...,A: A4 ...) on top of A0.cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo testandcargo 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, plusipnetinCargo.toml/Cargo.lock. Nothing outside the owned list changed andTODO.mdwas left for the merger.- Still open for others:
peer checkagainst a real peer (needs B1/B2 andreal_transport);PeerRegistry::reloadmust 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 isnix build && nix flake check. - Contract issue carried over from A0 (unchanged): section 3's
PeerConfigErroris implemented as an alias ofconfig::ConfigError; no contracts.md edit was made from this workstream.
- Still open for others:
- 2026-10-20 Gate round 1 (
loop/A/gate-2.log):- Duplication: the
tracingcapture layer both peer test modules used now lives once insrc/peers/testing.rsascapture::logged(test-only,#[cfg(test)]), soconfig.rsandsecrets.rstests share it instead of each carryingCapture/FieldVisit.tests/peers_config.rsuses onePeerFixture(private token file plus the single-betaconfig, with ascalarsargument for the timeout lines) instead of writing the same TOML three times. Cargo.toml:ipnetis the one dependency this workstream adds, and the plan allows it for A2deny_cidrs(see the A2 entry above). No other dependency changed;cargo tree -i opensslis still empty. The gate's ownership step flagsCargo.toml, which the plan authorises; the file is listed in the shared-file seam for exactly this case.
- Duplication: the