105 lines
7.7 KiB
Markdown
105 lines
7.7 KiB
Markdown
# TODO — skyg-linux-tracker
|
||
|
||
Master checklist. **Tick boxes here only.** Card status lives on [`plan/BOARD.md`](plan/BOARD.md). Scope, owned files and design notes for each workstream live in [`plan/workstreams/`](plan/workstreams/).
|
||
|
||
Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md) · Open questions: [`plan/decisions.md`](plan/decisions.md)
|
||
|
||
## Before starting
|
||
|
||
- [x] Resolve **DEC-1**: binary and CLI are `slinuxm`
|
||
- [x] Accept or override the proposed decisions DEC-2 to DEC-7 (all accepted)
|
||
|
||
## Phase 0 — Foundation · [card](plan/workstreams/P0-foundation.md)
|
||
|
||
- [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)
|
||
|
||
### WS-A systemd · [card](plan/workstreams/WS-A-systemd.md)
|
||
- [ ] **A1** Shared system-bus `zbus::Connection` + `ManagerProxy`
|
||
- [ ] **A2** `list_units(state)` mapped to `UnitSummary`
|
||
- [ ] **A3** `list_timers()` via `*.timer` units + `TimerProxy` props (no `ListTimers` method exists)
|
||
- [ ] **A4** `unit_status(name)`: `GetUnit` first, `LoadUnit` as fallback. `Unit` props always, `Service` props for `.service` only.
|
||
- [ ] **A5** Unit-name validation. `NoSuchUnit` maps to `NotFound`.
|
||
- [ ] **A6** `examples/systemd_dump.rs` prints JSON from the live bus
|
||
- [ ] **A7** Unit tests for timestamp conversion and property mapping
|
||
|
||
### WS-B journal · [card](plan/workstreams/WS-B-journal.md)
|
||
- [ ] **B1** All sd-journal access inside `spawn_blocking`. Optional namespace, depending on the spike.
|
||
- [ ] **B2** `query(filter)`: unit, priority ≤ N, `lines` capped by `limits.max_lines`, returned in chronological order
|
||
- [ ] **B3** `follow(filter)` returns an mpsc receiver. `wait()` with a timeout. Exits on receiver drop or shutdown.
|
||
- [ ] **B4** Entry mapping with lossy UTF-8 for binary `MESSAGE`
|
||
- [ ] **B5** `examples/journal_tail.rs`
|
||
- [ ] **B6** Test: the follow thread exits after its receiver is dropped
|
||
|
||
### WS-C docker · [card](plan/workstreams/WS-C-docker.md)
|
||
- [ ] **C1** Lazy `bollard::Docker` on the configured socket. Missing or denied socket maps to `Unavailable`.
|
||
- [ ] **C2** `ps()`: list + concurrent bounded inspect (health, uptime, restarts, image)
|
||
- [ ] **C3** `container_status(name)`
|
||
- [ ] **C4** `logs(name, follow, tail, since)` stream that stops on drop or shutdown
|
||
- [ ] **C5** `tail` capped by config
|
||
- [ ] **C6** `examples/docker_ps.rs` + log follow
|
||
- [ ] **C7** *(nice-to-have)* Smoke test against the Podman socket
|
||
|
||
### WS-D auth + DB · [card](plan/workstreams/WS-D-auth.md)
|
||
- [ ] **D1** `db.rs`: open-or-create, dir `0700`, WAL, `busy_timeout`, embedded migrations
|
||
- [ ] **D2** Migration for `tokens(id, name UNIQUE, token_hash UNIQUE, created_at, revoked_at, last_used_at)`
|
||
- [ ] **D3** `tokens.rs`: create (32 random bytes, `slinuxm_` prefix, printed once), list, revoke. Uses runtime queries.
|
||
- [ ] **D4** `slinuxm token create|list|revoke` CLI wired via the Phase 0 stub
|
||
- [ ] **D5** Bearer middleware: sha256 + indexed lookup of non-revoked tokens. 401 + `WWW-Authenticate` JSON on failure.
|
||
- [ ] **D6** Middleware exposed as a layer for the protected router only. `/healthz` stays public.
|
||
- [ ] **D7** Tests: create, accept, revoke, reject. Unknown token is rejected. Startup refuses auth-off + non-loopback.
|
||
|
||
## Phase 2 — Surfaces (parallel)
|
||
|
||
### WS-E REST API · [card](plan/workstreams/WS-E-rest.md)
|
||
- [ ] **E1** `api::router(state)` using axum 0.8 `{name}` path syntax
|
||
- [ ] **E2** `GET /systemd/units?state=`, `/systemd/units/{name}`, `/systemd/timers`
|
||
- [ ] **E3** `GET /journal?unit=&priority=&lines=` with validation
|
||
- [ ] **E4** `GET /journal/follow` SSE with keep-alive. Ends on disconnect or shutdown.
|
||
- [ ] **E5** `GET /docker/ps`, `/docker/containers/{name}`, `/docker/containers/{name}/logs` (JSON, or SSE with `follow=1`)
|
||
- [ ] **E6** `GET /healthz` on the public router
|
||
- [ ] **E7** Consistent JSON error body from `AppError`
|
||
- [ ] **E8** Handler tests against fake sources (`tower::ServiceExt::oneshot`)
|
||
- [ ] **E9** Docker unavailable returns 503 on docker routes only
|
||
|
||
### WS-F MCP · [card](plan/workstreams/WS-F-mcp.md)
|
||
- [ ] **F1** `TrackerService` with `#[tool_router]` and 8 tools
|
||
- [ ] **F2** `tail_journal` capped by `limits.max_follow_secs` and an entry cap
|
||
- [ ] **F3** `get_container_logs` tail cap
|
||
- [ ] **F4** `ServerHandler::get_info`: instructions + capabilities (tools, prompts, resources)
|
||
- [ ] **F5** Tool descriptions that explain systemd states, health statuses and priorities
|
||
- [ ] **F6** Prompts `diagnose_unit { name }` and `container_health_report {}`
|
||
- [ ] **F7** Resources `systemd://units/failed` and `docker://containers`, read live, no subscriptions
|
||
- [ ] **F8** `mcp::service(state)` returns `StreamableHttpService` with Origin validation (DEC-8)
|
||
- [ ] **F9** Tests: tool list snapshot + each tool against fakes
|
||
|
||
### WS-G OTel · [card](plan/workstreams/WS-G-otel.md)
|
||
- [ ] **G1** `telemetry::init(cfg)`: OTLP grpc/http with headers. Resource has `service.name`, `service.version`, `host.name`. Returns a guard.
|
||
- [ ] **G2** `tracing` subscriber: fmt to stderr + `tracing-opentelemetry` layer when enabled
|
||
- [ ] **G3** Metrics poll loop feeds a snapshot. Observable gauges read it, so vanished series drop out.
|
||
- [ ] **G4** Metric set from `plan.md` with semconv attribute names, allowlists and the DEC-7 default scope
|
||
- [ ] **G5** Log export: journal follow + per-container docker follow, reconciled via the Docker events stream, with backoff
|
||
- [ ] **G6** Shutdown cancels tasks and flushes all providers
|
||
- [ ] **G7** `dev/otelcol.yaml` with a debug exporter, plus a devenv process to run it
|
||
|
||
## Phase 3 — Integration & hardening · [card](plan/workstreams/P3-integration.md)
|
||
|
||
- [ ] **I1** `main.rs` wiring: protected router (`/api/v1` + `/mcp` + auth) merged with the public `/healthz`, `TraceLayer`, SIGTERM/SIGINT leading to cancel, drain and OTel flush
|
||
- [ ] **I2** Automated negative tests (Verification #6)
|
||
- [ ] **I3** `systemd/skyg-linux-tracker.service` running `slinuxm serve`: `StateDirectory=`, `ProtectSystem=strict`, `NoNewPrivileges`, `SupplementaryGroups=systemd-journal`, docker group commented (DEC-6)
|
||
- [ ] **I4** README: install, config reference, token workflow, MCP client setup, hardened docker option
|
||
- [ ] **I5** Release build: `ldd` shows only libc + libsystemd and its deps. Record binary size.
|
||
- [ ] **I6** Full manual Verification #1–#6 from `plan.md` passes on a real host
|