Files
skyg-linux-tracker/TODO.md
T

7.7 KiB
Raw Blame History

TODO — skyg-linux-tracker

Master checklist. Tick boxes here only. Card status lives on plan/BOARD.md. Scope, owned files and design notes for each workstream live in plan/workstreams/.

Design: plan.md · Review fixes: plan/review.md · Open questions: plan/decisions.md

Before starting

  • Resolve DEC-1: binary and CLI are slinuxm
  • Accept or override the proposed decisions DEC-2 to DEC-7 (all accepted)

Phase 0 — Foundation · card

  • 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.

Phase 1 — Sources + auth (parallel)

WS-A systemd · card

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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