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

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 for dyn use.

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:

  1. SupplementaryGroups=docker in the unit file, documented as a trade-off. This is the plan's default.
  2. Point sources.docker_socket at 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: