8.2 KiB
8.2 KiB
WS-F: NixOS, docs, end-to-end tests
Part of Phase 5: Consolidator. Contracts: contracts.md sections 5 to 10.
| Field | Value |
|---|---|
| Status | In progress (F1 done; F2 to F4 pending) |
| 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 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 intochecks.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 withdocs/consolidator.mdand 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.settingsfor intervals/caps. The module renders[[peers.peer]]entries into the TOML with the paths only and adds oneLoadCredential=peer-<name>:<tokenFile>per peer, pointing eachtoken_fileat/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).tokenFileis 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 viaExecReload(SIGHUP) withreloadIfChanged, else restarts. Assertions: at least one peer whenpeers.enable; names valid and unique. Also addRefreshOnReload=credentialsasnix/tests/peers.nixdoes (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 proxiedunitsmatch a direct call, then rotate a token file and revoke the token on the peer:authflips 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.rsend-to-end (plain, TLS with anrcgenCA 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.nixentry,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 checkoutput, docs, example config, the Verification plan results in the README. - To the orchestrator: ARCHITECTURE.md decision rows (DEC-13 and the DEC-11 clarification), TODO.md checklists, and moving
plan/phase-5-consolidator/todocs/workstreams/.
Log
- 2026-10-19: Split from the single phase plan 2026-10-19.
tests/peers.rsownership moved here from WS-T;docs/consolidator.mdshares one## Testingsection with WS-T. - 2026-10-19: F1 done (commit
F: F1 NixOS peers options with LoadCredential token delivery).- Options under
services.skyg-linux-tracker.peers:enable(off by default),settings(freeform[peers]tuning, snake_case, no secrets) andpeers.<name> = { url; tokenFile; caFile ? null; enable ? true; allowPlainHttp ? false; }. - Rendering: one
[[peers.peer]]per peer withenable = true, withname,url,allow_plain_http,ca_file(only when set) andtoken_file = /run/credentials/skyg-linux-tracker.service/peer-<name>. Peers withenable = falseare left out of both the TOML andLoadCredential. A peer-less config gains no[peers]section, so existing deployments keep the same generated file. - Credentials:
LoadCredential=peer-<name>:<tokenFile>per enabled peer, merged with the TLScert/keyentries;RefreshOnReload=credentialsnow applies when TLS or peers are on;ExecReloadstays SIGHUP. - Reload vs restart: with peers enabled the config file moves from
restartTriggerstoreloadTriggers, so a peer edit is applied with SIGHUP (and the credential copy is refreshed). This is deliberate instead ofreloadIfChanged: that flag would also reload on unrelated unit changes such as a package upgrade, keeping the old binary running. Changes SIGHUP cannot apply (bind, port, auth database) need a manualsystemctl restart; the module description of the trigger notes it. With peers off the unit still restarts on config change, byte-identical to before. - Assertions: declaring
peers.<name>requirespeers.enable;peers.enablerequires at least one declared peer (or the legacy freeform list); names match^[a-z0-9][a-z0-9_-]{0,31}$(uniqueness is by attribute name);tokenFileis absolute and outside the store (an interpolated"${./secret}"would otherwise put the token in the store);caFileis absolute when set; first-class peers andsettings.peers.peercannot be mixed. The pre-F1 freeform style stays valid, sonix/tests/peers.nixevaluates unchanged (verified: alpha keeps its two peers, gamma none). - Tests:
nix/tests/module-peers.nix(new file, eval only, no builds) renders the config and the unit and checks 25 cases: peer-less default, TLS-only unchanged, TLS+peers credential list, rendering of enabled/disabled peers, token path never in the config, reload/restart triggers, freeform compatibility and every assertion. Not wired intoflake.nix(F2 owns that file); run it with:nix eval --impure --json --expr 'let f = builtins.getFlake (toString ./.); in import ./nix/tests/module-peers.nix { pkgs = f.inputs.nixpkgs.legacyPackages.x86_64-linux; module = f.nixosModules.default; }' - Not run (no nix builds in this worktree):
nix build .#checks.x86_64-linux.vm -L,nix build .#tests.x86_64-linux.peers -L,nix flake check. The orchestrator should run those;vmcovers the unchanged peer-less/TLS path,peerscovers the legacy freeform path F2 will migrate to the new options. - Handoff: F1 is complete; F2 can switch
nix/tests/peers.nixtopeers.enable/peers.peers.<name>.tokenFile(the TOML it produced is identical), move the test intochecks.vm-peersand add the three-machine variant. F4 still owes the README peers section,docs/consolidator.mdand the DEC-14 note (a consolidator token reaches every peer's data).systemd/skyg-linux-tracker.serviceis unchanged: the example is a manual install without peers.
- Options under