F: F4 peers docs, agenix example and tool-count note

README peers section, docs/consolidator.md (threat model, tokens, firewall,
worked agenix example, reload/restart), the MCP tool count in both tables,
and config.example.toml commentary.
This commit is contained in:
ari committed 2026-10-20 15:04:09 -04:00
1 parent 66ee41a672
commit 4d83c2eff5
7 files changed
+301 -20

No files matched your search

@@ -81,3 +81,10 @@ Shippable, documented, verified.
- Cases: plain peer (status `server.up`/`api.up`/`auth ok`, `peer_version`, list shape, 401 without a caller token, 404 for an unknown peer, 405 on POST, both checks flipping when the peer dies, proxy 503 naming the peer while the caller's token keeps working); TLS peer with an `rcgen` CA and a leaf for `127.0.0.1` via `ca_file` (`api.up` needs a verified handshake and our token); a peer signed by a different CA (`server.up` true, `api.up` false, `last_error = tls_error`, proxy 503 `tls_error`); a `302` (503 `http_302`, and the `Location` target sees **zero** connections); an oversize body (503 `oversize` with `max_response_bytes = 64`); a silent peer (503 `timeout`, bounded); the 64-peer cap (`Config::validate`, the path `serve` uses: 64 accepted, 65 refused); and shutdown ending a proxied follow.
- **Blocking finding, reported to WS-C's Log (2026-10-20)**: the proxy hands the transport the stripped route (`/systemd/units`) while peers serve `/api/v1/systemd/units`, so every proxied call to a healthy peer answers `peer <name>: not found on peer`. Health checks are fine (`/api/v1/ping`). Two tests (`a_plain_peer_serves_its_own_data_through_the_proxy`, `shutdown_ends_a_proxied_follow`) are `#[ignore]`d with that reason and state the contract; removing the attribute is the acceptance check once C (or B) prefixes the path. The same defect will fail the proxy subtest of `checks.vm-peers`.
- Verified: `cargo test --test peers` → 7 passed, 2 ignored.
- 2026-10-20: **F4 done** (commit `F: F4 peers docs, agenix example and tool-count note`).
- `README.md`: new `## Peers (consolidator)` section between TLS and NixOS — TOML example, why `token_file` is a path (DEC-13) and why each consolidator needs its own token, the two checks with a server/api/auth table, REST/`peer list`/`peer check` examples, the pass-through rules, MCP 8-to-10 and OTel metric names, a NixOS snippet, and pointers to `docs/consolidator.md` and the test runner. The MCP section now says "eight tools (ten with a consolidator)"; the peers section names the underlying `nix build .#checks.x86_64-linux.vm-peers -L` next to `dev-test integration peers` / `dev-test vm peers`.
- `docs/consolidator.md`: every section except `## Testing`, which is byte-identical (checked). Title and intro; `## Model` (checks, thresholds, `last_error` classes, the `server`/`api`/`auth` reading table); `## Configuration` (all keys, `SKYG_PEERS__*`, validation rules, `deny_cidrs` against the resolved address); `## REST and MCP` (status shape, allowlist, hop header, error mapping table, the 405-has-no-peer-header exception); `## OpenTelemetry`; `## Credentials and threat model` (DEC-13, per-consolidator tokens, what it does not protect, the D14 note that a consolidator token reaches every peer's data); `## NixOS with agenix` (options, mint-on-the-peer, `secrets.nix`, `age.secrets`, the module block, `tokenFile`/`caFile` consequences, reload-vs-restart including the review-n5 note that adding or removing a peer or changing its `tokenFile` restarts on `switch`); `## Firewall and networking` plus `### Address families`; `## Limits and non-goals` (no aggregation, no chaining, GET-only, no history, declarative only).
- `AGENTS.md`: the tool-count line is now "8 without peers and 10 with `peers.enabled` (`list_peers`, `get_peer`, an optional `peer` argument on the other eight); the snapshot test guards both tables". Command lists untouched.
- `config.example.toml`: commentary only — one token per consolidator, the module's `tokenFile` option and a pointer to `docs/consolidator.md`. Keys and defaults unchanged and checked against `docs/consolidator.md` and `PeersConfig::default`.
- Corrected F1's `caFile` description in `nix/module.nix`: nothing opens the CA at startup, so "fails at startup" was wrong; a root-only file makes every check and proxied request to that peer fail as `tls_error`.
- Not an Owned file, so left for the fold: `docs/README.md`'s Reference table does not list `docs/consolidator.md` yet.