Files
skyg-linux-tracker/TODO.md
T

23 KiB
Raw Blame History

TODO — skyg-linux-tracker

The single place for work tracking. Tick boxes here only. Design lives in ARCHITECTURE.md. Archived workstream design notes and logs are in docs/workstreams/. Plans for the next big thing go in plan/.

Last updated: 2026-10-20

Status

The build is functionally complete and merged to main. REST, MCP, OTel, TLS and the NixOS module are implemented. Verification #1–#4 and #6 passed live on minipc1 (2026-10-19). The WS-H nix gate passed on 2026-10-19. Phase 5 (consolidator, optional peers) and the generated OpenAPI doc are merged, and the binary serves it as a Redoc page at /docs (DEC-16); the Phase 5 record is archived in docs/workstreams/P5-consolidator/. Everything open is in the Backlog.

Milestone Gate Status
M0 Skeleton slinuxm serve --print-config works. Clippy and tests are clean. No openssl. Done
M1 Sources live All four Phase 1 examples run against a real host Done (systemd, journal, docker verified live)
M2 Surfaces Verification #3, #4 and #5 pass Partial: #3 and #4 pass live (minipc1, 2026-10-19, all 8 MCP tools); #5 OTel deferred to I6-5 (collector on minipc1 is down)
M3 Release Verification #1–#6 pass. Unit file and README shipped. Partial: #1–#4 and #6 pass, unit installed on minipc1; needs #5 (I6-5)
M4 NixOS nix flake check passes including the VM test. :1984 serves and a token is minted with the system-installed CLI. ✅ 2026-10-19: nix build and nix flake check (incl. VM test, plain + TLS) pass; see WS-H log
M5 TLS HTTPS serves REST and /mcp, SIGHUP reloads certs, no openssl. Done
M6 Consolidator Phase 5 exit criteria; peer-less instance unchanged (8 MCP tools); nix flake check incl. the peers VM test Met, except two live checks still open: P5-1 minipc1 cross-check needs a user-minted token, P5-2 OTel peer-gauge check via devenv up not yet recorded (both in the Backlog)

In progress / Review

Item Owner State
— Nothing in flight
  • WS-H Gate: nix build and nix flake check pass. ldd shows no openssl. A fresh NixOS host serves :1984 and a token can be minted from a login shell.

Backlog

Parked, not scheduled. Each has a reason. Nothing here blocks the current work. Tick here when picked up and finished.

ID Item Reason parked
C7 (optional) Smoke test against the Podman socket (WS-C) Nice-to-have; no Podman host in use
I6-5 Verification #5: OTel smoke test end to end (P3) Waiting on the minipc1 collector fix (X-1); slinuxm itself exports fine
B-1 Live check of docker log-follow SSE (/docker/containers/{name}/logs?follow=1) Not exercised in the live runs so far
B-2 Live check of REST, bearer auth and TLS against minipc1 The MCP-tool run did not cover them
X-1 (external) Investigate failed opentelemetry-collector.service and var-lib-loki.mount on minipc1 Outside this repo; blocks I6-5
F-1 Cap concurrent follow streams Security review 2026-10-16; not scheduled
F-2 Bound line and message length Security review 2026-10-16; not scheduled
F-3 Unit hardening extras Security review 2026-10-16; needs a clean-host test first
P5-1 minipc1 cross-check of the consolidator against a real peer Needs a read-only token minted by the user on minipc1; agents never mint tokens on real hosts
P5-2 Record the OTel peer-gauge check (devenv up, Verification step 5 with peers) Not yet run and recorded; no automated test asserts the exported peer metrics end to end
D8 Fleet aggregation (merged views across peers) Out of scope for v1 (DEC-14: no aggregation, no chaining); needs a design for partial failure and ordering
P5-3 Scoped tokens (per-peer or read-class scopes) Any valid inbound token may read peer data (DEC-14); scopes need a token schema change and a policy decision
P5-4 Peer health history State is in memory only by design; history needs storage or an external TSDB, and the OTel gauges already cover it
P5-5 Runtime peer management (add/remove without editing config) Peers are declarative so no write path or DB table exists (DEC-14); would need a write path against the read-only rule
DOC-1 Show the MCP tools (x-mcp-tools) in the Redoc page Redoc renders REST operations only; needs the tool list generated into a tag description (or a section) in openapi.rs, which changes the spec
DOC-2 Config switch to turn the /docs viewer off Static, public and data-free (DEC-16), so not needed yet; adds a config key, README and config.example.toml entries
  • C7 (nice-to-have) Smoke test against the Podman socket
  • I6-5 Verification #5 OTel smoke test against a working collector (see the verification checklist)
  • B-1 Docker log-follow SSE live check
  • B-2 REST, auth and TLS live check against minipc1
  • X-1 (external) Fix or investigate opentelemetry-collector.service / var-lib-loki.mount on minipc1
  • P5-1 minipc1 cross-check: run a consolidator against minipc1 with a read-only token the user mints there (list_peers, get_peer, one pass-through)
  • P5-2 OTel peer gauges: run devenv up, enable [otel] with peers, confirm peer.up, peer.api.auth_ok, peer.check.duration_seconds, peer.last_change_timestamp_seconds reach the collector, and record the result
  • D8 Fleet aggregation across peers
  • P5-3 Scoped tokens
  • P5-4 Peer health history
  • P5-5 Runtime peer management
  • DOC-1 MCP tools in the Redoc page
  • DOC-2 Config switch for the /docs viewer
  • F-1 Cap concurrent follow streams. Each journal follow, tail_journal call or docker follow pins a spawn_blocking thread for up to limits.max_follow_secs. Add a global semaphore shared by REST and MCP (suggested 16) returning 429/503 when full. A client that stops reading may hold the thread past the deadline (untested); add a write timeout or a hard tokio::time::timeout around the producer.
  • F-2 Bound line and message length. Docker LineSplitter and journal MESSAGE are buffered without limit before the 256 KiB result cap applies. Truncate per line (suggested 64 KiB, with a visible marker) and cap total bytes collected.
  • F-3 Unit hardening: ProtectKernelLogs, ProtectHostname, RemoveIPC, LimitNOFILE, TasksMax, MemoryMax, narrower RestrictAddressFamilies, PrivateUsers (check journal group access). Test under the hardened unit on a clean host before enabling. Document how the service user gets read access to the TLS key.

Completed workstreams

Design notes, owned files and logs for each are archived under docs/workstreams/. Task IDs below are stable references.

ID What Key outcome Tasks Completed
P0 Foundation: devenv, Cargo, config, DTOs, source traits + fakes, errors, AppState, stubs serve --print-config works; build, clippy, fmt, test clean; cargo tree -i openssl empty P0-1..P0-11, Gate merged to main
WS-A systemd source (zbus) Units, timers (via *.timer + Timer props), read-only GetUnit status A1..A7 merged to main
WS-B journal source (sd-journal) Snapshot + follow in spawn_blocking; follow thread exits on receiver drop B1..B6 merged to main
WS-C docker source (bollard) Lazy socket, bounded concurrent inspect, log streams; missing socket maps to Unavailable C1..C6 (C7 in Backlog) merged to main
WS-D auth + SQLite token DB sha256 tokens, slinuxm token create, list, revoke, bearer middleware, 401 + WWW-Authenticate D1..D7 merged to main
WS-E REST API All /api/v1 routes, SSE follow, /healthz, 503 on docker-only failures E1..E9 merged to main
WS-F MCP server 8 tools, 2 prompts, 2 resources, instructions, Origin/Host validation F1..F9 merged to main
WS-G OTel export Traces, observable-gauge metrics, journal/docker log fan-out with reconcile, flush on shutdown, dev/otelcol.yaml G1..G7 merged to main
P3 Integration and hardening One axum server, negative tests, hardened unit, README; I6 verified on minipc1 (#1–#4, #6) I1..I6 (I6-5 in Backlog) 2026-10-19
WS-I Native TLS (rustls) server.tls.*, SIGHUP reload, HTTPS tests, live curl --cacert check T1..T8 merged to main
WS-H NixOS package, module, VM test H1..H8 merged (PR #1, 34da657); gate passed 2026-10-19 H1..H8 merged; gate passed 2026-10-19
P5 Consolidator: optional peers (WS-T, A..F) Declarative peers with TCP and API health checks, /api/v1/peers status and GET pass-through, peer argument and list_peers/get_peer (10 MCP tools with peers, 8 without), four OTel gauges, NixOS module option, SSRF guard, peers VM test; peer-less instance unchanged T1..T7, A0..A4, B1..B5, C1..C4, D1..D3, E1..E2, F1..F4 (P5-1, P5-2 in Backlog) 2026-10-20
WS-G (OpenAPI) Generated OpenAPI 3.1 doc (stand-alone, after P5) utoipa paths plus schemars bridge, x-mcp-tools, GET /api/v1/openapi.json, slinuxm openapi [--peers], drift test, docs/openapi.json G1..G4 2026-10-20
WS-H (final fixes) Phase 5 final-review fixes One token loader, one set of peer helpers, IPv4-mapped deny check, IPv6 deny_cidrs, client span kind, flaky test fixes, docs corrections review items 2026-10-20

Done (archive)

All ticked. One line per workstream; the full task text is on each card.

  • P0 — devenv scripts and libsystemd (P0-1); Cargo.toml with slinuxm bin, rustls-only, LTO+strip (P0-2); API spike (P0-3); figment config with otel.headers, otel.metrics.*, limits.* and validation (P0-4); config.example.toml (P0-5); DTOs with serde/schemars (P0-6); source traits + fakes (P0-7); AppError mapping (P0-8); AppState (P0-9); stubs and main.rs dispatch (P0-10); config tests (P0-11); gate.
  • WS-A — bus connection (A1); list_units (A2); list_timers (A3); unit_status via GetUnit (A4); name validation, NoSuchUnit to NotFound (A5); examples/systemd_dump.rs (A6); mapping tests (A7).
  • WS-B — spawn_blocking access (B1); query (B2); follow (B3); lossy UTF-8 mapping (B4); examples/journal_tail.rs (B5); follow-exit test (B6).
  • WS-C — lazy bollard client (C1); ps (C2); container_status (C3); logs stream (C4); tail cap (C5); examples/docker_ps.rs (C6).
  • WS-D — db.rs open-or-create, WAL (D1); tokens migration (D2); token CRUD (D3); CLI (D4); bearer middleware (D5); protected-router layer, /healthz public (D6); tests (D7).
  • WS-E — router with {name} syntax (E1); systemd routes (E2); journal snapshot (E3); journal SSE (E4); docker routes (E5); /healthz (E6); JSON errors (E7); handler tests (E8); docker 503 (E9).
  • WS-F — TrackerService, 8 tools (F1); tail_journal cap (F2); get_container_logs cap (F3); get_info instructions (F4); tool descriptions (F5); prompts (F6); resources (F7); mcp::service with Origin validation (F8); tests (F9).
  • WS-G — telemetry::init (G1); tracing subscriber (G2); snapshot + observable gauges (G3); metric set and allowlists (G4); log export with reconcile (G5); shutdown flush (G6); dev/otelcol.yaml (G7).
  • P3 — serve wiring and shutdown (I1); negative tests (I2); systemd unit, verified with systemd-analyze security --offline (1.5 OK) and installed as a system unit on minipc1, 2026-10-19 (I3); README (I4); release build, ldd clean (I5); manual Verification #1–#4 and #6 on minipc1, 2026-10-19; #5 deferred as I6-5 (I6).
  • WS-I — server.tls.* config (T1); rustls with pinned provider (T2); SIGHUP reload (T3); https:// MCP origins (T4); non-loopback-without-TLS warning (T5); self-signed cert tests (T6); README TLS section (T7); live check (T8).
  • WS-H — nix/package.nix (H1); flake.nix (H2); module options (H3); service definition (H4); system-wide CLI with root guard (H5); firewall options and eval assertion (H6); README NixOS section (H7); VM test (H8). Gate passed 2026-10-19 (build, flake check, VM test).
  • P5 — runner dev/dev-test.nu and peers VM test (WS-T); config, validation, secrets loader, peer CLI (WS-A); registry, health loops, status model, SIGHUP reload, transport with SSRF guard (WS-B); status routes, pass-through, x-slinuxm-peer, error mapping (WS-C); peer argument, list_peers/get_peer, instructions (WS-D); gauges, client spans and propagation (WS-E); NixOS module, promoted VM test, tests/peers.rs, README and docs/consolidator.md (WS-F).
  • WS-G (OpenAPI) — REST spec (G1); MCP x-mcp-tools (G2); route and slinuxm openapi (G3); drift guard and docs/openapi.json (G4).
  • WS-H (final fixes) — see the record.

Early decisions (DEC-1..DEC-8) were accepted before work started; all decisions are recorded in ARCHITECTURE.md.