5.6 KiB
Decision log
Decisions that shape the work. All of DEC-1 to DEC-8 are decided. Override one here if you disagree.
| ID | Decision | Status | Blocks |
|---|---|---|---|
| DEC-1 | Binary / CLI name: slinuxm |
Decided | — |
| DEC-2 | Source traits + fakes in Phase 0 | Decided | P0-7 |
| DEC-3 | sqlx runtime queries instead of macros | Decided | D3 |
| DEC-4 | MCP auth failure = HTTP 401 | Decided | D5 |
| DEC-5 | MCP resources not subscribable in v1 | Decided | F7 |
| DEC-6 | Docker socket access model | Decided | I3 |
| DEC-7 | Default metrics scope | Decided | G4 |
| DEC-8 | Origin validation for /mcp |
Decided | — |
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: Decided 2026-10-15
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: Accepted 2026-10-15. Traits and fakes ship in Phase 0 (src/sources/mod.rs, src/sources/fake.rs). Uses async-trait for dyn dispatch.
DEC-3 — sqlx runtime queries instead of macros
Status: Decided 2026-10-15
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: Accepted 2026-10-15. Runtime sqlx::query / query_as, no macros, no .sqlx/ cache.
DEC-4 — MCP auth failure = HTTP 401
Status: Decided 2026-10-15
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: Accepted 2026-10-15. Auth failures on /api/v1 and /mcp are HTTP 401 with WWW-Authenticate: Bearer and the JSON error body. AppError::Unauthorized renders this.
DEC-5 — MCP resources not subscribable in v1
Status: Decided 2026-10-15
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: Accepted 2026-10-15. Resources are list/read only, resolved live. No subscriptions in v1.
DEC-6 — Docker socket access model
Status: Decided 2026-10-15
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: Accepted 2026-10-15. Option 1 in the unit file (docker group commented out). Option 2, a read-only socket proxy via sources.docker_socket, is documented in the README as the hardened setup.
DEC-7 — Default metrics scope
Status: Decided 2026-10-15
"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: Accepted 2026-10-15. Empty otel.metrics.units exports *.service and *.timer. A non-empty list is an explicit glob allowlist. Containers default to all.
DEC-8 — Origin validation for /mcp
Status: Decided 2026-10-15
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: Resolved by spike P0-3, 2026-10-15. rmcp 3.5.1 validates both headers itself: StreamableHttpServerConfig::with_allowed_hosts (default: loopback names only) and with_allowed_origins (default empty = Origin validation off; requests without Origin always pass). No custom tower layer is needed. F8 must set both. Hosts: loopback names + server.bind + server.allowed_hosts. Origins: http://localhost:*, http://127.0.0.1:*, http://[::1]:*, http://<bind>:* + server.allowed_origins. The config keys server.allowed_hosts and server.allowed_origins already exist.