54 lines
6.3 KiB
Markdown
54 lines
6.3 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 | Not started |
|
|
| 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
|
|
|
|
- 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.
|