diff --git a/TODO.md b/TODO.md index 9f559e6..aa672f9 100644 --- a/TODO.md +++ b/TODO.md @@ -7,22 +7,22 @@ Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md) ## Before starting - [x] Resolve **DEC-1**: binary and CLI are `slinuxm` -- [ ] Accept or override the proposed decisions DEC-2 to DEC-7 +- [x] Accept or override the proposed decisions DEC-2 to DEC-7 (all accepted) ## Phase 0 — Foundation · [card](plan/workstreams/P0-foundation.md) -- [ ] **P0-1** devenv: `pkg-config`, `systemd` (libsystemd.pc), `build`/`run`/`token` scripts. No openssl. `pkg-config --libs libsystemd` works in the shell. -- [ ] **P0-2** `Cargo.toml` with `[[bin]] name = "slinuxm"` and every dependency pinned for all phases. rustls-only features. Release profile set to lto + strip. -- [ ] **P0-3** Time-boxed API spike to confirm rmcp, zbus_systemd, systemd-journal and bollard APIs. Findings go in the card. Update DEC-8. -- [ ] **P0-4** `config.rs`: figment layering (defaults < TOML < `SKYG_*` env with `__` nesting < CLI). Add `otel.headers`, `otel.metrics.*` allowlists and `limits.*`. Validate the auth-disabled + non-loopback combination. -- [ ] **P0-5** `config.example.toml` covering every key, with comments -- [ ] **P0-6** Shared DTOs in `src/sources/mod.rs` with serde + schemars derives and RFC3339 timestamps. Service-only fields are `Option`. -- [ ] **P0-7** Source traits plus in-memory fakes (`src/sources/fake.rs`) -- [ ] **P0-8** `error.rs`: `AppError` mapped to HTTP status + JSON body and to MCP `ErrorData` -- [ ] **P0-9** `src/state.rs`: `AppState` (sources, optional DB pool, config, `CancellationToken`) -- [ ] **P0-10** Stub every module with its final signatures. `main.rs` dispatches `serve` / `token` / `--print-config` to them. -- [ ] **P0-11** Unit tests for config precedence and validation -- [ ] **Gate:** `slinuxm serve --print-config` prints effective config. Build, clippy, fmt and test are clean. `cargo tree -i openssl` is empty. +- [x] **P0-1** devenv: `pkg-config`, `systemd` (libsystemd.pc), `build`/`run`/`token` scripts. No openssl. `pkg-config --libs libsystemd` works in the shell. +- [x] **P0-2** `Cargo.toml` with `[[bin]] name = "slinuxm"` and every dependency pinned for all phases. rustls-only features. Release profile set to lto + strip. +- [x] **P0-3** Time-boxed API spike to confirm rmcp, zbus_systemd, systemd-journal and bollard APIs. Findings go in the card. Update DEC-8. +- [x] **P0-4** `config.rs`: figment layering (defaults < TOML < `SKYG_*` env with `__` nesting < CLI). Add `otel.headers`, `otel.metrics.*` allowlists and `limits.*`. Validate the auth-disabled + non-loopback combination. +- [x] **P0-5** `config.example.toml` covering every key, with comments +- [x] **P0-6** Shared DTOs in `src/sources/mod.rs` with serde + schemars derives and RFC3339 timestamps. Service-only fields are `Option`. +- [x] **P0-7** Source traits plus in-memory fakes (`src/sources/fake.rs`) +- [x] **P0-8** `error.rs`: `AppError` mapped to HTTP status + JSON body and to MCP `ErrorData` +- [x] **P0-9** `src/state.rs`: `AppState` (sources, optional DB pool, config, `CancellationToken`) +- [x] **P0-10** Stub every module with its final signatures. `main.rs` dispatches `serve` / `token` / `--print-config` to them. +- [x] **P0-11** Unit tests for config precedence and validation +- [x] **Gate:** `slinuxm serve --print-config` prints effective config. Build, clippy, fmt and test are clean. `cargo tree -i openssl` is empty. ## Phase 1 — Sources + auth (parallel) diff --git a/config.example.toml b/config.example.toml new file mode 100644 index 0000000..f39a88d --- /dev/null +++ b/config.example.toml @@ -0,0 +1,48 @@ +# skyg-linux-tracker example configuration. +# +# Precedence, lowest to highest: built-in defaults < this file < SKYG_* env vars < CLI flags. +# Default path: /etc/skyg-linux-tracker.toml (override with --config or SKYG_CONFIG). +# Every value below is the default. Env var names use the SKYG_ prefix and a +# double underscore for nesting, e.g. SKYG_SERVER__PORT. +# List values in env vars use array syntax: SKYG_OTEL__METRICS__UNITS='["nginx.service"]'. + +[server] +bind = "127.0.0.1" # listen address; non-loopback requires auth.enabled = true; SKYG_SERVER__BIND +port = 9109 # listen port; SKYG_SERVER__PORT +allowed_hosts = [] # extra Host header values accepted on /mcp, added to loopback names and bind; SKYG_SERVER__ALLOWED_HOSTS +allowed_origins = [] # extra Origin values accepted on /mcp, must include scheme, e.g. "https://app.example.com"; SKYG_SERVER__ALLOWED_ORIGINS + +[auth] +enabled = true # false is rejected at startup unless server.bind is loopback; SKYG_AUTH__ENABLED +db_path = "/var/lib/skyg-linux-tracker/db.sqlite" # SQLite database holding hashed API tokens; SKYG_AUTH__DB_PATH + +[otel] +enabled = false # master switch for OTLP export; SKYG_OTEL__ENABLED +endpoint = "http://localhost:4317" # OTLP gRPC; use http://host:4318 with protocol "http/protobuf"; SKYG_OTEL__ENDPOINT +protocol = "grpc" # "grpc" or "http/protobuf"; SKYG_OTEL__PROTOCOL +service_name = "skyg-linux-tracker" # OTel resource attribute service.name; SKYG_OTEL__SERVICE_NAME +export_unit_metrics = true # poll systemd units and containers and export gauges; SKYG_OTEL__EXPORT_UNIT_METRICS +export_logs = false # fan journal and docker logs out as OTel logs; SKYG_OTEL__EXPORT_LOGS +metrics_interval_secs = 30 # metrics poll interval; SKYG_OTEL__METRICS_INTERVAL_SECS + +# Extra OTLP headers (gRPC metadata for the grpc protocol). +# Env form: SKYG_OTEL__HEADERS__AUTHORIZATION. Values are redacted by --print-config. +[otel.headers] +# authorization = "Bearer " + +[otel.logs] +journal_units = [] # journal units to export as logs, empty = all; SKYG_OTEL__LOGS__JOURNAL_UNITS +docker_containers = [] # containers to export logs for, empty = all; SKYG_OTEL__LOGS__DOCKER_CONTAINERS + +[otel.metrics] +units = [] # glob allowlist of units; empty = *.service and *.timer only; SKYG_OTEL__METRICS__UNITS +containers = [] # glob allowlist of containers; empty = all; SKYG_OTEL__METRICS__CONTAINERS + +[sources] +docker_socket = "/var/run/docker.sock" # point at a read-only socket proxy for a hardened setup; SKYG_SOURCES__DOCKER_SOCKET +journal_namespace = "" # journal namespace, empty = default journal; SKYG_SOURCES__JOURNAL_NAMESPACE + +[limits] +max_lines = 1000 # max journal lines per request; SKYG_LIMITS__MAX_LINES +max_tail = 1000 # max container log lines per request; SKYG_LIMITS__MAX_TAIL +max_follow_secs = 60 # max duration of a bounded follow (MCP tail_journal); SKYG_LIMITS__MAX_FOLLOW_SECS diff --git a/plan/BOARD.md b/plan/BOARD.md index 2bd6b81..7ef17b0 100644 --- a/plan/BOARD.md +++ b/plan/BOARD.md @@ -14,7 +14,7 @@ Move a card by cutting its row into another column. Keep the card's own **Status | Card | Owner | Notes | |---|---|---| -| [P0 Foundation](workstreams/P0-foundation.md) | — | Confirm proposed decisions DEC-2 to DEC-7 first | +| — | | | ## In progress @@ -26,7 +26,7 @@ Move a card by cutting its row into another column. Keep the card's own **Status | Card | Owner | PR | |---|---|---| -| — | | | +| [P0 Foundation](workstreams/P0-foundation.md) | — | branch `p0/foundation` | ## Done @@ -51,7 +51,7 @@ Move a card by cutting its row into another column. Keep the card's own **Status | Milestone | Gate | Status | |---|---|---| -| M0 Skeleton | `slinuxm serve --print-config` works. Clippy and tests are clean. No openssl. | ⬜ | +| M0 Skeleton | `slinuxm serve --print-config` works. Clippy and tests are clean. No openssl. | 🟨 in review | | M1 Sources live | All four Phase 1 examples run against a real host | ⬜ | | M2 Surfaces | Verification #3, #4 and #5 pass | ⬜ | | M3 Release | Verification #1–#6 pass. Unit file and README shipped. | ⬜ | diff --git a/plan/decisions.md b/plan/decisions.md index 342eed7..77672c8 100644 --- a/plan/decisions.md +++ b/plan/decisions.md @@ -1,17 +1,17 @@ # 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. +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 | 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-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 | — | --- @@ -29,50 +29,50 @@ The plan used three names. The repo is `linux-system-monitor`, the service is `s ## DEC-2 — Source traits + fakes in Phase 0 -**Status:** Proposed (board assumes yes) +**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`. - 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:** +**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:** Proposed +**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:** +**Decision:** Accepted 2026-10-15. Runtime `sqlx::query` / `query_as`, no macros, no `.sqlx/` cache. --- ## DEC-4 — MCP auth failure = HTTP 401 -**Status:** Proposed +**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:** +**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:** Proposed +**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:** +**Decision:** Accepted 2026-10-15. Resources are list/read only, resolved live. No subscriptions in v1. --- ## DEC-6 — Docker socket access model -**Status:** Proposed +**Status:** Decided 2026-10-15 Membership in the `docker` group is root-equivalent. Our code only reads, but a compromised process could do anything. @@ -82,26 +82,26 @@ Options: **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:** +**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:** Proposed +**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:** +**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:** Open until spike P0-3 +**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:** +**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://:*` + `server.allowed_origins`. The config keys `server.allowed_hosts` and `server.allowed_origins` already exist. diff --git a/plan/workstreams/P0-foundation.md b/plan/workstreams/P0-foundation.md index 7d40465..ae0b82c 100644 --- a/plan/workstreams/P0-foundation.md +++ b/plan/workstreams/P0-foundation.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Ready | +| Status | Review | | Owner | — | | Phase | 0 (blocking, single track) | | Depends on | — | @@ -80,3 +80,41 @@ Tick these in [`TODO.md`](../../TODO.md). ## Log - 2026-10-15: Card created from `plan.md` review. DEC-1 decided: CLI is `slinuxm`. +- 2026-10-15: Implemented on branch `p0/foundation`. DEC-2 to DEC-7 accepted with the proposed defaults. DEC-8 resolved by the spike (below). Card moved to Review. + +### Pinned versions (Cargo.lock is committed) + +| Crate | Version | Notes | +|---|---|---| +| tokio / tokio-util / futures | 1.53.3 / 0.7.20 / 0.3.34 | | +| axum / tower / tower-http | 0.8.9 / 0.5.3 / 0.7.1 | `{name}` path syntax | +| rmcp | 3.5.1 | features `server`, `macros`, `schemars`, `transport-streamable-http-server` | +| zbus / zbus_systemd | 5.19.0 / 0.26200.0 | `zbus_systemd` features `systemd1` + `zbus-async-tokio` | +| systemd (journal) | 0.10.1 | features `journal`, `systemd_v245` (namespaces); default `bus` off | +| bollard | 0.21.1 | default features | +| opentelemetry / _sdk / -otlp | 0.33.1 | `tracing-opentelemetry` 0.34.0 | +| sqlx | 0.9.0 | `runtime-tokio`, `sqlite`, `migrate`, `macros` | +| serde / schemars / jiff | 1.0.229 / 1.2.3 (`jiff02`) / 0.2.38 | | +| figment / clap / toml | 0.10.19 / 4.6.7 / 1.1.8 | | +| sha2 / rand / base64 | 0.11.1 / 0.10.3 / 0.23.1 | newer major APIs than older docs | + +### Spike findings (P0-3) + +- **rmcp 3.5.1.** `StreamableHttpService::new(service_factory: impl Fn() -> Result, session_manager: Arc, config: StreamableHttpServerConfig)`. Service type is `StreamableHttpService` (`rmcp::transport::streamable_http_server::{StreamableHttpService, StreamableHttpServerConfig, session::local::LocalSessionManager}`). It is a `tower_service::Service>` with `Error = Infallible`, so `Router::nest_service("/mcp", svc)` works. Config is `#[non_exhaustive]`: build with `StreamableHttpServerConfig::default()` + `with_*`. Fields: `sse_keep_alive`, `sse_retry`, `legacy_session_mode` (default true), `json_response`, `cancellation_token`, `allowed_hosts` (default loopback names), `allowed_origins` (default empty = off), `session_store`, `max_request_body_bytes`, `stateless_protocol_metadata_required`. Note the plan's `with_json_response(false)` still exists. `ServerHandler::get_info` returns `rmcp::model::ServerConfig` (`ServerInfo` is deprecated). Errors: `rmcp::ErrorData` with `resource_not_found`, `invalid_params`, `invalid_request`, `internal_error` constructors. **Host and Origin validation are built in (DEC-8).** +- **zbus_systemd 0.26200.0.** Proxies from `zbus_systemd::systemd1`: `ManagerProxy` (default service and path set), `UnitProxy`, `ServiceProxy`, `TimerProxy` (the last three have `assume_defaults = false`, so build with `.builder(&conn).path(unit_path)`). `ListUnits` returns `Vec<(name, description, load_state, active_state, sub_state, followed, unit_path: OwnedObjectPath, job_id: u32, job_type, job_path)>`; `list_units_filtered(states)` and `list_units_by_patterns(states, patterns)` exist. `get_unit` and `load_unit` return `OwnedObjectPath`. Unit props: `description`, `load_state`, `active_state`, `sub_state`, `active_enter_timestamp: u64` (usec). Service: `exec_main_status: i32`, `n_restarts: u32`, `result: String`. Timer: `unit: String`, `next_elapse_u_sec_realtime: u64`, `last_trigger_u_sec: u64`. There is no `ListTimers`. Timestamps are microseconds since epoch; 0 and `u64::MAX` mean unset. Needs the `zbus-async-tokio` feature to run on tokio. +- **systemd 0.10.1 journal.** `journal::OpenOptions::default().system(true).open()` and `.open_namespace(ns)` (feature `systemd_v245`) return `Journal`. `Journal` is **not `Send` nor `Sync`**: open it inside the `spawn_blocking` thread and keep it there. `wait(Option) -> JournalWaitResult { Nop, Append, Invalidate }` supports a timeout. Other API: `seek_tail`, `previous_skip`, `next_entry`/`previous_entry` returning `JournalRecord = BTreeMap`, `match_add(key, val)`, `match_or`, `match_and`, `timestamp_usec`, `cursor`. `next_entry` yields string values, so binary `MESSAGE` fields may need `get_data` for raw bytes. +- **bollard 0.21.1.** Default features (`http`, `pipe`) give the unix socket with no TLS, and no rustls or openssl enters the tree. `Docker::connect_with_unix(path, timeout, &API_DEFAULT_VERSION)` checks that the socket exists at connect time, hence lazy construction (G9). +- **opentelemetry-otlp 0.33.1.** Builders via `SpanExporter::builder()`, `MetricExporter::builder()`, `LogExporter::builder()`, then `.with_tonic()` or `.with_http()`. `WithExportConfig::{with_endpoint, with_protocol}`; `WithHttpConfig::with_headers(HashMap)`; `WithTonicConfig::with_metadata(MetadataMap)`. The `http-proto` feature alone has **no HTTP client**; an explicit client feature is needed. We enabled `reqwest-rustls` (plus `tls-ring`, `tls-webpki-roots` for gRPC TLS). This pulls `aws-lc-sys` (C build) via reqwest but no openssl. If aws-lc is a problem, `hyper-client` gives plain-http only. +- **Cargo tree.** `cargo tree -i openssl` and `-i openssl-sys` print "did not match any packages". + +### Contract notes and deviations + +- Added `src/lib.rs`. The crate is lib + bin so unused stub items are not dead-code errors under `clippy -D warnings`. Surfaces import from `skyg_linux_tracker::...`. +- Added `telemetry::spawn_exporters(AppState) -> Vec>` beyond the listed `telemetry::init`, because metrics polling and log fan-out need the sources. +- Added `AppState::live(config, db, shutdown)` and `sources::fake::fake_state(config)` constructors. +- Source constructors are infallible and lazy: `DbusSystemd::new(&Config, CancellationToken)`, `SdJournal::new(..)`, `BollardDocker::new(..)`. Follow tasks get the shutdown token at construction, so trait `follow` methods take no token. +- `docker_logs` is split into `logs` (snapshot) and `follow_logs` (stream) on `DockerSource`. +- Added `server.allowed_hosts` / `server.allowed_origins` config keys for DEC-8. +- `Config` has no `Option` fields, so it serializes to TOML. Empty string or list means unset. +- `serve` currently validates config then exits with an error "server wiring is not implemented yet (P3 I1)". `--print-config` works with any subcommand and redacts `otel.headers` values. +- `config.example.toml` was drafted by goose (openrouter, gpt-4o-mini), then corrected by hand (invalid TOML on one line, comment layout). A test asserts it equals `Config::default()`. diff --git a/src/config.rs b/src/config.rs index 9bfa739..6e1c7c2 100644 --- a/src/config.rs +++ b/src/config.rs @@ -385,6 +385,12 @@ mod tests { }); } + #[test] + fn example_file_matches_defaults() { + let c: Config = toml::from_str(include_str!("../config.example.toml")).unwrap(); + assert_eq!(c, Config::default()); + } + #[test] fn toml_roundtrip_and_redaction() { let mut c = Config::default();