# 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`](../TODO.md) (task IDs in brackets). Items needing a human call are tracked in [`decisions.md`](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.