50 lines
4.8 KiB
Markdown
50 lines
4.8 KiB
Markdown
# WS-F: NixOS, docs, end-to-end tests
|
|
|
|
Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](contracts.md) sections 5 to 10.
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Not started |
|
|
| Owner | |
|
|
| Depends on | C, D, E (original plan). F1 (module) and F4 (docs drafts) can begin once A1 settles the config keys, since they depend only on contracts sections 6 and 9; F2/F3 need the other streams |
|
|
| Blocks | phase exit |
|
|
| Can start when | F1 and doc drafts: after A0/A1 land. F2: after C, D, E and [WS-T](ws-t-tests.md) are green. F3: after B and C |
|
|
| Owned files | `nix/module.nix`, `nix/tests/vm.nix`, `systemd/skyg-linux-tracker.service`, `README.md` (peers section), `docs/consolidator.md` (new; except the `## Testing` section owned by WS-T), `tests/peers.rs`, `tests/common/mod.rs` (shared helpers, append-only with B), `config.example.toml` (merge with A1: comments and example peers, not the keys), `flake.nix` (only the move of `tests.<system>.peers` into `checks.vm-peers`, in F2), `AGENTS.md` (MCP tool count note) |
|
|
| Do not touch | `src/**` (all code streams; report bugs to the owning stream's Log), `nix/tests/peers.nix` except to adapt it to the first-class options in F2 (coordinate with WS-T, update contracts section 10), `dev/test.nu`, `devenv.nix` (T), `docs/api.md` (C), `src/config.rs` (A) |
|
|
|
|
Shared-file seams:
|
|
|
|
- `flake.nix`: WS-T owns it until F2; F2 then moves exactly one attribute into `checks`.
|
|
- `README.md` / `AGENTS.md`: WS-T owns the command lists; F4 owns the peers section and the MCP tool count note (tool count becomes "8, or 10 with peers enabled").
|
|
- `config.example.toml`: A1 owns the keys and defaults; F reviews that it is in sync with `docs/consolidator.md` and adds only commentary/examples.
|
|
- `tests/common/mod.rs`: append-only; B may have added helpers already.
|
|
|
|
## Goal
|
|
|
|
Shippable, documented, verified.
|
|
|
|
## Tasks
|
|
|
|
- **F1** module: `peers.enable`; `peers.peers.<name> = { url; tokenFile; caFile ? null; enable ? true; allowPlainHttp ? false; }`; `peers.settings` for intervals/caps. The module renders `[[peers.peer]]` entries into the TOML with the *paths* only and adds one `LoadCredential=peer-<name>:<tokenFile>` per peer, pointing each `token_file` at `/run/credentials/skyg-linux-tracker.service/peer-<name>` so the service user needs no read access to `/run/agenix/*` (same mechanism as TLS, DEC-12). `tokenFile` is typed as a string (`config.age.secrets.<x>.path`), never a path literal, so secrets cannot enter the Nix store; an eval assertion rejects a store path. Config change reloads via `ExecReload` (SIGHUP) with `reloadIfChanged`, else restarts. Assertions: at least one peer when `peers.enable`; names valid and unique. Also add `RefreshOnReload=credentials` as `nix/tests/peers.nix` does (contracts section 10) if the systemd version supports it.
|
|
- **F2** promote WS-T to `checks`, switched to the first-class module options (`peers.peers.<name>.tokenFile`); plus a three-machine variant (consolidator, peer1, peer2) for fan-in. Mint tokens on peers, write them to root-owned 0400 files on the consolidator (stand-ins for agenix paths) and declare the peers through the module, assert status via REST and MCP, stop peer2's service and assert server/api flip, assert proxied `units` match a direct call, then rotate a token file and revoke the token on the peer: `auth` flips to rejected, then back after rewriting the file, with no restart. Remove a peer from the config, SIGHUP, assert the series is gone.
|
|
- **F3** `tests/peers.rs` end-to-end (plain, TLS with an `rcgen` CA via `--ca-file`, wrong CA rejected, redirect not followed, oversize body, slow-loris peer, 64-peer cap, cancel on shutdown).
|
|
- **F4** README section, `docs/consolidator.md` (threat model, token handling, firewall note: peers must allow the consolidator), a worked agenix example (`secrets.nix` entry, `age.secrets.peer-minipc1.file`, `peers.peers.minipc1.tokenFile = config.age.secrets.peer-minipc1.path`), AGENTS.md MCP tool count note.
|
|
|
|
## Inputs
|
|
|
|
- Contracts section 9 (Nix options), 6 (TOML), 10 (test contract), 5 and 7 (what the tests assert). Fakes: none for F2 (real binary); F3 uses in-process servers, not the fake transport.
|
|
- Constraint: nix builds only when the nix gate is free (AGENTS.md).
|
|
|
|
## Done when
|
|
|
|
`nix flake check` passes including the new VM test; docs and example config in sync.
|
|
|
|
## Handoff
|
|
|
|
- Phase exit evidence: `nix flake check` output, docs, example config, the Verification plan results in the [README](README.md#verification-plan).
|
|
- To the orchestrator: ARCHITECTURE.md decision rows (DEC-13 and the DEC-11 clarification), TODO.md checklists, and moving `plan/phase-5-consolidator/` to `docs/workstreams/`.
|
|
|
|
## Log
|
|
|
|
- 2026-10-19: Split from the single phase plan 2026-10-19. `tests/peers.rs` ownership moved here from WS-T; `docs/consolidator.md` shares one `## Testing` section with WS-T.
|