Files
skyg-linux-tracker/plan/review.md
T
2026-10-15 17:07:03 -04:00

8.5 KiB

Design review — plan.md

Reviewed 2026-10-15 against plan.md (skyg-linux-tracker design doc).

Verdict: sound, proceed. The core architecture holds up. sources/ is the only layer that talks to the host, and REST, MCP and OTel are thin projections over it. That makes the "same data on every surface" requirement true by construction and makes the parallel workstreams real. The crate choices are reasonable.

The items below are corrections or gaps. Each is folded into a task in ../TODO.md (task IDs in brackets). Items needing a human call are tracked in decisions.md.

Correctness issues (plan is wrong as written)

# Issue Fix Task
R1 systemd's D-Bus Manager has no ListTimers method. systemctl list-timers lists *.timer units, then reads the org.freedesktop.systemd1.Timer interface on each. Use ListUnitsByPatterns(["*.timer"]) (or filter ListUnits), then TimerProxy properties NextElapseUSecRealtime, LastTriggerUSec, Unit. Treat 0 / u64::MAX as "not scheduled". A3
R2 ExecMainStatus and NRestarts live on the Service interface, not Unit. They do not exist for timers, sockets, mounts. Read Unit props for every unit and Service props only for .service units. Make those DTO fields Option. A4, P0-6
R3 .layer(auth_middleware) on the whole router also protects /healthz, contradicting "unauthenticated liveness". Build a protected router (/api/v1, /mcp) with the auth layer, then .merge() a public router holding /healthz. I1, D6
R4 Route table uses :name. axum 0.8 uses /{name} and panics at startup on the old :name syntax. Use {name} in code. The table in plan.md is fine as notation. E1
R5 Tool count mismatch. The tool list has 8 tools (3 systemd, 2 journal, 3 docker) but WS-F says "9 tools". Board uses 8. Add a 9th only deliberately. F1
R6 config.example.toml has no otel.headers (the tech table relies on it) and no metrics allowlists (the OTel section relies on them). Only log allowlists exist. Add otel.headers and [otel.metrics] units/containers. P0-4, P0-5
R7 Repo layout comment says devenv needs openssl, which contradicts "rustls everywhere". Drop openssl. Gate on cargo tree -i openssl returning nothing. P0-1, P0-2
R8 "Compile-time-checked queries" with sqlx needs DATABASE_URL at build time or a committed .sqlx/ offline cache. Neither is in the plan. For one table, use runtime sqlx::query / query_as. See decision DEC-3. D3

Gaps (missing from the plan, will bite during implementation)

# Gap Fix Task
G1 Blocking journal calls. Only follow() mentions spawn_blocking. Snapshot query() is also blocking sd-journal FFI and would stall a tokio worker. Run all sd-journal work in spawn_blocking. Never hold a Journal across an .await. B1, B2
G2 Follow-stream leaks. A blocking wait() loop does not notice an SSE client disconnecting, so threads pile up. wait() with a short timeout and exit when tx.is_closed() or the shutdown token fires. Add a test. B3, B6
G3 Graceful shutdown with open SSE. axum's graceful shutdown waits for open connections. Long-lived SSE streams block it forever. One CancellationToken in AppState. Every stream and background task selects on it. P0-9, E4, G6, I1
G4 Docker containers come and go. OTel log fan-out spawns per-container follow tasks at startup only. New containers are missed and dead ones leave dangling tasks. Reconcile from the Docker events stream (start/die/destroy) or a periodic re-list. G5
G5 File-ownership conflicts. Phase 0 owns main.rs and sources/mod.rs, but WS-D must add the token CLI dispatch to main.rs, and each source track must add pub mod x; to sources/mod.rs. Phase 0 creates every module as a stub with final function signatures. Workstreams then only fill in their own files. P0-10
G6 No shared AppState defined. Every surface needs the same handles: sources, DB pool, config, shutdown token. Define it in Phase 0 (src/state.rs). P0-9
G7 Input bounds. lines, tail, and MCP tail_journal { seconds } are unbounded. A large value means a huge response or a hung MCP call. Config-driven caps (limits.max_lines, limits.max_follow_secs). Validate unit and container names. P0-4, A5, B2, F2
G8 MCP Origin validation. The MCP Streamable HTTP spec requires servers to validate Origin to block DNS-rebinding attacks. The plan does not mention it. Check what the pinned rmcp provides. Otherwise add a small Origin/Host check layer on /mcp. P0-3, F8
G9 Docker absent at startup. The plan wants a clean error on docker endpoints but doesn't say how the source is constructed. Construct lazily. A missing or denied socket maps to AppError::Unavailable (503) per request and never fails startup. C1, E9
G10 Metric cardinality default. "Empty = all" for metrics means every loaded unit (often 300+), including inactive mounts and devices. Default the metrics scope to *.service and *.timer. Allowlists narrow it further. See DEC-7. G4
G11 Stale gauge series. A unit or container that disappears keeps its last exported value with synchronous OTel gauges. Use observable gauges fed from the latest poll snapshot, so vanished series stop being reported. G3

Recommendations (improvements, not errors)

  • Define the source traits in Phase 0 and ship fakes. The layout already says "one trait per domain". With SystemdSource / JournalSource / DockerSource traits and in-memory fakes, WS-E/F/G can start right after Phase 0 against fakes instead of waiting for Phase 1. Handler and MCP tool tests also run without a live host. (DEC-2, P0-7)
  • Move the "auth disabled + non-loopback bind" check into config validation. It is pure config logic and config.rs is a Phase 0 file. WS-D keeps it in its done-criteria as a verification. (P0-4)
  • MCP auth failures should be HTTP 401, not a JSON-RPC error. The MCP authorization spec handles auth at the HTTP transport layer. Clients expect 401 with WWW-Authenticate: Bearer. Use the same middleware response for REST and MCP. (DEC-4, D5)
  • MCP resources: no subscriptions in v1. Subscribable resources need change detection, which means polling. That contradicts "live reads only". Expose them as list/read resources resolved live. (DEC-5, F7)
  • Use OTel semantic-convention attribute names where they exist. Examples are container.name, container.id, container.image.name, and host.name as a resource attribute. Keep systemd.unit for systemd, which has no convention. (G4)
  • unit_status should prefer GetUnit. LoadUnit can load a unit file into the manager, a small side effect for a "read-only" tool. Fall back to LoadUnit only to report on unloaded units. (A4)
  • Token DB lookup by sha256 is already the check. Constant-time comparison adds nothing once you do an indexed lookup on a high-entropy token's hash. Keep the lookup, skip the extra compare. (D5)
  • Use SQLite WAL mode plus busy_timeout. The token CLI and the running server write and read the same DB at the same time. (D1)
  • Use systemd StateDirectory= in the unit file. It creates /var/lib/skyg-linux-tracker with the right owner and mode, so the app does not need root to create it. The app keeps its "create if missing" fallback for dev runs. (I3)
  • Docker group is root-equivalent. Read-only in our code, but socket access grants full control of the daemon. Document it. Optionally support a read-only socket proxy (for example docker-socket-proxy with only CONTAINERS=1), which works as-is since sources.docker_socket is configurable. (DEC-6, I3, I4)
  • Add a time-boxed API spike to Phase 0. Several plan details depend on exact crate APIs: rmcp's StreamableHttpServerConfig fields, zbus_systemd proxy names, whether the systemd crate can open a journal namespace, and bollard's feature flags. Confirm them while pinning versions, before parallel work fixes the contracts. (P0-3)

Things that are fine as-is

  • One axum server for REST and MCP, with rmcp's StreamableHttpService mounted via nest_service.
  • Bounded tail_journal for MCP instead of infinite streams.
  • Tokens stored as sha256 hashes, plaintext shown once.
  • Config precedence: CLI > env > file > defaults.
  • libsystemd as the one dynamic dependency. Every target host runs systemd anyway.
  • The Phase 0 → 1 → 2 → 3 structure and the dependency graph.