108 lines
5.6 KiB
Markdown
108 lines
5.6 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.
|