Files
skyg-linux-tracker/plan/decisions.md
T

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

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:

  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: 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.


DEC-9 — Port 1984 in the NixOS module, reachable from a remote server on the LAN

Status: Revised 2026-10-16, awaiting answers

The module defaults port = 1984. The binary's own default is unchanged, so non-Nix installs are unaffected.

Intended use: another server on the LAN calls this host. So the host config sets bind to a LAN address (or 0.0.0.0), the firewall opens 1984 for that traffic, and auth must be enabled (config validation already refuses auth-off on a non-loopback bind). For /mcp, server.allowed_hosts must include the hostname or IP the remote client uses, or rmcp answers 403.

Open: (a) restrict the firewall to the remote server's IP or subnet, which is recommended, versus the whole LAN; (b) plain HTTP versus TLS in front, since bearer tokens are readable on the wire over plain HTTP; (c) the LAN address or hostname clients use.

Decision:


DEC-10 — CLI wrapper for token commands

Status: Proposed

The DB is in a 0700 state dir owned by the service user, so a login user cannot run slinuxm token … directly. The module installs slinuxm on PATH as a wrapper that re-execs token subcommands via sudo -u <service user> and passes everything else through. Alternative: ship the bare binary and document sudo -u.

Decision:


DEC-11 — No declarative or bootstrap tokens in v1

Status: Decided 2026-10-16

Tokens are minted with slinuxm token create <name>, printed once, and never stored in plaintext. There is no bootstrapTokens option and no import of pre-hashed tokens in v1.

Decision: Accepted by the user: print the token once, never store it.