108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# 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:**
|