Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
7.7 KiB
7.7 KiB
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/tokenscripts. No openssl.pkg-config --libs libsystemdworks in the shell. - P0-2
Cargo.tomlwith[[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). Addotel.headers,otel.metrics.*allowlists andlimits.*. Validate the auth-disabled + non-loopback combination. - P0-5
config.example.tomlcovering every key, with comments - P0-6 Shared DTOs in
src/sources/mod.rswith serde + schemars derives and RFC3339 timestamps. Service-only fields areOption. - P0-7 Source traits plus in-memory fakes (
src/sources/fake.rs) - P0-8
error.rs:AppErrormapped to HTTP status + JSON body and to MCPErrorData - P0-9
src/state.rs:AppState(sources, optional DB pool, config,CancellationToken) - P0-10 Stub every module with its final signatures.
main.rsdispatchesserve/token/--print-configto them. - P0-11 Unit tests for config precedence and validation
- Gate:
slinuxm serve --print-configprints effective config. Build, clippy, fmt and test are clean.cargo tree -i opensslis empty.
Phase 1 — Sources + auth (parallel)
WS-A systemd · card
- A1 Shared system-bus
zbus::Connection+ManagerProxy - A2
list_units(state)mapped toUnitSummary - A3
list_timers()via*.timerunits +TimerProxyprops (noListTimersmethod exists) - A4
unit_status(name):GetUnitfirst,LoadUnitas fallback.Unitprops always,Serviceprops for.serviceonly. - A5 Unit-name validation.
NoSuchUnitmaps toNotFound. - A6
examples/systemd_dump.rsprints 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,linescapped bylimits.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::Dockeron the configured socket. Missing or denied socket maps toUnavailable. - 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
tailcapped 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, dir0700, 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|revokeCLI wired via the Phase 0 stub - D5 Bearer middleware: sha256 + indexed lookup of non-revoked tokens. 401 +
WWW-AuthenticateJSON on failure. - D6 Middleware exposed as a layer for the protected router only.
/healthzstays 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/followSSE with keep-alive. Ends on disconnect or shutdown. - E5
GET /docker/ps,/docker/containers/{name},/docker/containers/{name}/logs(JSON, or SSE withfollow=1) - E6
GET /healthzon 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
TrackerServicewith#[tool_router]and 8 tools - F2
tail_journalcapped bylimits.max_follow_secsand an entry cap - F3
get_container_logstail 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 }andcontainer_health_report {} - F7 Resources
systemd://units/failedanddocker://containers, read live, no subscriptions - F8
mcp::service(state)returnsStreamableHttpServicewith 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 hasservice.name,service.version,host.name. Returns a guard. - G2
tracingsubscriber: fmt to stderr +tracing-opentelemetrylayer when enabled - G3 Metrics poll loop feeds a snapshot. Observable gauges read it, so vanished series drop out.
- G4 Metric set from
plan.mdwith 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.yamlwith a debug exporter, plus a devenv process to run it
Phase 3 — Integration & hardening · card
- I1
main.rswiring: 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.servicerunningslinuxm 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:
lddshows only libc + libsystemd and its deps. Record binary size. - I6 Full manual Verification #1–#6 from
plan.mdpasses on a real host