150 lines
7.9 KiB
Markdown
150 lines
7.9 KiB
Markdown
# 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, 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://`. A non-loopback bind without TLS logs a startup warning but is not refused.
|
|
|
|
**Decision:**
|