96 lines
22 KiB
Markdown
96 lines
22 KiB
Markdown
# WS-A: Config, secrets, diagnostics CLI (and A0 contract stubs)
|
|
|
|
Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](contracts.md).
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Merged |
|
|
| Owner | |
|
|
| Depends on | none |
|
|
| Blocks | [WS-B](ws-b-registry.md), [WS-C](ws-c-rest.md), [WS-D](ws-d-mcp.md), [WS-E](ws-e-telemetry.md) 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](ws-t-tests.md). **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](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](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](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](contracts.md) sections 1 to 4 and 6 (it defines what A0 builds); [decisions.md](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.
|