8.0 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.
DEC-9 — Port 1984 in the NixOS module, loopback by default
Status: Decided 2026-10-16
The module defaults port = 1984 and bind = "127.0.0.1". The binary's own default is unchanged. Exposing the service to the LAN is an install-time choice made in the host's own config, never a default: the operator sets bind, openFirewall (or an interface-scoped rule) and allowedHosts for that deployment. Config validation already refuses auth-off on a non-loopback bind, and a non-loopback bind without TLS logs a warning (see DEC-12).
Decision: Accepted by the user. The default is loopback. Installs change the relevant settings.
DEC-10 — No CLI wrapper
Status: Decided 2026-10-16
The module installs the plain slinuxm binary on PATH. Tokens are minted with sudo -u skyg-linux-tracker slinuxm token create <name>, documented in the README and in the module's post-install notes. No wrapper script.
Running the token commands as root is a trap: if the service has not started yet, root creates the state dir and DB owned by root, and root-owned WAL files can lock the service out. So the token subcommands refuse to run as root when the state dir or DB belongs to another user, and print the exact sudo -u … command to use. This is a small change in slinuxm, tracked as H5.
Decision: Accepted by the user. No wrapper. The app guards against the root mistake.
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.
DEC-12 — TLS terminated in-process with rustls
Status: Proposed
Bearer tokens over plain HTTP are readable on the wire, and LAN exposure is the intended deployment. The service gets native TLS: server.tls.enabled, cert_file, key_file, with certificate reload on SIGHUP so ACME or sops-managed rotation needs no restart. A reverse proxy still works and nothing depends on it. rustls is already in the dependency tree and openssl stays out. When TLS is enabled the MCP Origin allowlist uses https://. TLS is optional and off by default; with it off nothing changes. A non-loopback bind without TLS logs a startup warning but is not refused.
Decision: