4.3 KiB
Decision log
Decisions that shape the work. Open ones need a human call before the listed task starts. Proposed ones have a recommended default that the board already assumes. Override them here if you disagree.
| ID | Decision | Status | Blocks |
|---|---|---|---|
| DEC-1 | Binary / CLI name: slinuxm |
Decided | — |
| DEC-2 | Source traits + fakes in Phase 0 | Proposed | P0-7 |
| DEC-3 | sqlx runtime queries instead of macros | Proposed | D3 |
| DEC-4 | MCP auth failure = HTTP 401 | Proposed | D5 |
| DEC-5 | MCP resources not subscribable in v1 | Proposed | F7 |
| DEC-6 | Docker socket access model | Proposed | I3 |
| DEC-7 | Default metrics scope | Proposed | G4 |
| DEC-8 | Origin validation for /mcp |
Open until spike | F8 |
DEC-1 — Binary / CLI name
Status: Decided 2026-10-15
The plan used three names. The repo is linux-system-monitor, the service is skyg-linux-tracker, and the CLI examples said skyg token create.
Decision: The binary and CLI are slinuxm. Examples are slinuxm serve and slinuxm token create <name>. The [[bin]] name in Cargo.toml is slinuxm. Issued tokens use the prefix slinuxm_.
Assumed unchanged: the product name skyg-linux-tracker, the unit file skyg-linux-tracker.service, the state dir /var/lib/skyg-linux-tracker, the config path /etc/skyg-linux-tracker.toml, and the SKYG_ env prefix. Revisit here if those should become slinuxm too.
DEC-2 — Source traits + fakes in Phase 0
Status: Proposed (board assumes yes)
Define SystemdSource, JournalSource, DockerSource traits in src/sources/mod.rs, with in-memory fakes in src/sources/fake.rs. AppState holds Arc<dyn …>.
- Pro: WS-E/F/G can start right after Phase 0 against fakes. Handler and tool tests run in CI without systemd or Docker.
- Con: About 100 extra lines in Phase 0. Needs
async-trait, or native async fn in traits with boxed futures fordynuse.
Decision:
DEC-3 — sqlx runtime queries instead of macros
Status: Proposed
sqlx::query! macros need DATABASE_URL at build time or a committed .sqlx/ cache via cargo sqlx prepare. With one table and about five queries, runtime sqlx::query_as plus tests gives the same safety with no build-time DB.
Decision:
DEC-4 — MCP auth failure = HTTP 401
Status: Proposed
The plan says auth failures on MCP return a JSON-RPC error. The MCP authorization spec puts auth at the HTTP layer. Clients expect 401 Unauthorized with WWW-Authenticate: Bearer. One middleware gives the same response for /api/v1 and /mcp.
Decision:
DEC-5 — MCP resources not subscribable in v1
Status: Proposed
Subscriptions need the server to detect changes and push notifications, which means background polling. That conflicts with "live reads only". v1 exposes systemd://units/failed and docker://containers as list/read resources resolved live on each read.
Decision:
DEC-6 — Docker socket access model
Status: Proposed
Membership in the docker group is root-equivalent. Our code only reads, but a compromised process could do anything.
Options:
SupplementaryGroups=dockerin the unit file, documented as a trade-off. This is the plan's default.- Point
sources.docker_socketat a read-only socket proxy that only allows container list, inspect and logs.
Recommendation: Ship option 1 commented out in the unit file. Document option 2 in the README as the hardened setup. No code changes needed either way.
Decision:
DEC-7 — Default metrics scope
Status: Proposed
"Empty allowlist = all units" exports every loaded unit, often more than 300 including devices and mounts.
Recommendation: With empty otel.metrics.units, export *.service and *.timer units only. A non-empty list is an explicit allowlist that accepts glob patterns. Containers default to all, since counts are usually small.
Decision:
DEC-8 — Origin validation for /mcp
Status: Open until spike P0-3
The MCP spec requires Origin validation on Streamable HTTP servers. If the pinned rmcp version has a built-in allowed-hosts or Origin option, use it. Otherwise add a small tower layer on /mcp that rejects requests whose Origin is present and not in an allowlist. Default allowlist: loopback origins plus server.bind.
Decision: