initial setup
This commit is contained in:
1 parent
58ebcaa97f
commit
389c4f998a
19 files changed
+1206
-40
No files matched your search
@@ -0,0 +1,82 @@
|
||||
# P0 — Foundation
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Ready |
|
||||
| Owner | — |
|
||||
| Phase | 0 (blocking, single track) |
|
||||
| Depends on | — |
|
||||
| Blocks | Every other card |
|
||||
| Owned files | `Cargo.toml`, `devenv.nix`, `config.example.toml`, `src/main.rs`, `src/config.rs`, `src/error.rs`, `src/state.rs`, `src/sources/mod.rs`, `src/sources/fake.rs`, initial stubs of every other module |
|
||||
|
||||
## Goal
|
||||
|
||||
Fix every contract that parallel work depends on: dependencies, config shape, DTOs, source traits, error type, `AppState`, and module signatures. After P0, no other card should need to touch `Cargo.toml`, `main.rs` or `sources/mod.rs`, except by agreed exception.
|
||||
|
||||
Keep it small. Stubs contain `todo!()` and no logic.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **P0-1 devenv.** Keep `languages.rust.enable` and the existing `CLAUDE_CONFIG_DIR` `enterShell`. Add `pkgs.pkg-config` and `pkgs.systemd` (its `.dev` output provides `libsystemd.pc`). Add `scripts.build`, `scripts.run` and `scripts.token`, which wraps `cargo run -- token`. Do not add openssl. Optionally add `pkgs.opentelemetry-collector-contrib` for G7.
|
||||
- **P0-2 Cargo.toml.** Package `skyg-linux-tracker` with `[[bin]] name = "slinuxm"` (DEC-1). Pin every crate needed by all phases:
|
||||
- Runtime: `tokio` (full), `tokio-util` (`CancellationToken`), `futures`.
|
||||
- HTTP: `axum` 0.8, `tower`, `tower-http` (`trace`).
|
||||
- Data: `serde`, `serde_json`, `schemars`, `thiserror`, `jiff` or `chrono`.
|
||||
- Config/CLI: `figment` (`toml`, `env`), `clap` (`derive`, `env`).
|
||||
- MCP: `rmcp` (`server`, `macros`, `schemars`, `transport-streamable-http-server`).
|
||||
- systemd/journal: `zbus`, `zbus_systemd` (`systemd1`), `systemd` (`journal`, default features off where possible).
|
||||
- Docker: `bollard`, no TLS features needed for a unix socket.
|
||||
- OTel: `opentelemetry`, `opentelemetry_sdk`, `opentelemetry-otlp` (`grpc-tonic`, `http-proto`, rustls), `tracing`, `tracing-subscriber`, `tracing-opentelemetry`.
|
||||
- Auth: `sqlx` (`runtime-tokio`, `sqlite`), `sha2`, `rand`, `base64`.
|
||||
- Optional: `async-trait`.
|
||||
- Release profile: `lto = true`, `strip = true`, `codegen-units = 1`.
|
||||
- **P0-3 API spike, max half a day.** Confirm against the pinned versions:
|
||||
- The rmcp `StreamableHttpService::new` signature, `StreamableHttpServerConfig` fields, and whether it validates Origin or Host (DEC-8).
|
||||
- zbus_systemd `ManagerProxy`, `UnitProxy`, `ServiceProxy`, `TimerProxy` names and property types.
|
||||
- The `systemd` crate journal open API, `wait` with timeout, namespace support, and whether `Journal` is `Send`.
|
||||
- bollard feature flags that avoid pulling openssl or rustls when only the unix socket is used.
|
||||
- The opentelemetry-otlp builder API for headers and protocol selection.
|
||||
- Record findings in the log below.
|
||||
- **P0-4 config.rs.** Use figment `Serialized::defaults` < `Toml::file` < `Env::prefixed("SKYG_").split("__")` < CLI overrides. Key additions over `plan.md`:
|
||||
- `otel.headers` (map)
|
||||
- `otel.metrics.units` / `otel.metrics.containers` (glob allowlists)
|
||||
- `limits.max_lines` (default 1000), `limits.max_tail` (default 1000), `limits.max_follow_secs` (default 60)
|
||||
- Validation: reject `auth.enabled = false` when `bind` is not loopback.
|
||||
- **P0-5 config.example.toml.** Document every key with a comment and its env-var name.
|
||||
- **P0-6 DTOs** in `src/sources/mod.rs`:
|
||||
- `UnitSummary`, `UnitStatus` (service fields `Option`), `TimerInfo`
|
||||
- `JournalQuery`, `JournalEntry`, `Priority` (0–7, parse from name or number)
|
||||
- `ContainerSummary`, `ContainerStatus`, `LogLine { stream: Stdout|Stderr, ts, message }`
|
||||
- All derive `Serialize`, `JsonSchema` and `Debug`. Timestamps serialize as RFC3339.
|
||||
- **P0-7 Traits + fakes.** `SystemdSource`, `JournalSource`, `DockerSource`. Follow methods return `mpsc::Receiver` or a boxed `Stream`. `fake.rs` provides fixture-backed implementations for tests (DEC-2).
|
||||
- **P0-8 error.rs.** `AppError { NotFound, BadRequest, Unauthorized, Unavailable, Internal }`. Implement `IntoResponse` (status + `{"error": {"code", "message"}}`) and `From<AppError> for rmcp::ErrorData`.
|
||||
- **P0-9 state.rs.** `AppState { config: Arc<Config>, systemd: Arc<dyn SystemdSource>, journal: Arc<dyn JournalSource>, docker: Arc<dyn DockerSource>, db: Option<SqlitePool>, shutdown: CancellationToken }`. Must be `Clone`.
|
||||
- **P0-10 Stubs with final signatures:**
|
||||
- `api::router(AppState) -> Router`
|
||||
- `mcp::service(AppState) -> StreamableHttpService<…>`
|
||||
- `telemetry::init(&Config) -> Result<TelemetryGuard>`
|
||||
- `auth::layer(AppState)`
|
||||
- `auth::tokens::run(TokenCmd, &Config) -> Result<()>`
|
||||
- `db::open(&Config) -> Result<SqlitePool>`
|
||||
- Source constructors in `sources/{systemd,journal,docker}.rs`.
|
||||
- `main.rs` dispatches `slinuxm serve` (default), `slinuxm token …`, and `--print-config`.
|
||||
- **P0-11 Tests.** Defaults only, file overrides defaults, env overrides file, CLI overrides env. The auth-off + `0.0.0.0` combination is an error.
|
||||
|
||||
## Done when
|
||||
|
||||
- `cargo run -- serve --print-config` prints the merged config, and precedence works by hand.
|
||||
- `cargo build` produces `target/debug/slinuxm`.
|
||||
- `cargo clippy -- -D warnings`, `cargo fmt --check` and `cargo test` are clean.
|
||||
- `cargo tree -i openssl` and `cargo tree -i openssl-sys` print nothing.
|
||||
- Spike findings are recorded below and DEC-8 is updated.
|
||||
|
||||
## Risks
|
||||
|
||||
- Changing DTOs after Phase 1 starts causes merge pain in four places. Spend the time here.
|
||||
- rmcp moves fast. Pin the exact version and note it in the log.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created from `plan.md` review. DEC-1 decided: CLI is `slinuxm`.
|
||||
@@ -0,0 +1,59 @@
|
||||
# P3 — Integration & hardening
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 3 (single track) |
|
||||
| Depends on | WS-E, WS-F, WS-G (and transitively A–D) |
|
||||
| Blocks | Release |
|
||||
| Owned files | `src/main.rs` (serve wiring), `systemd/skyg-linux-tracker.service`, `README.md`, `tests/` |
|
||||
|
||||
## Goal
|
||||
|
||||
Wire every surface into one axum server, prove the negative paths, and ship the unit file and docs. This is the only place the surfaces meet.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **I1** `slinuxm serve` wiring in `main.rs`:
|
||||
1. Load config, then `telemetry::init`, then `db::open` when auth is enabled, then construct sources and `AppState`.
|
||||
2. Build the protected router: `.nest("/api/v1", api::router(state))` and `.nest_service("/mcp", mcp::service(state))`, then `.layer(auth::layer(state))`.
|
||||
3. Build the public router with `/healthz`.
|
||||
4. `public.merge(protected).layer(TraceLayer::new_for_http())` (review R3).
|
||||
5. Spawn the metrics and log export tasks when enabled.
|
||||
6. On SIGINT or SIGTERM: cancel `state.shutdown` so SSE streams and background tasks end, run `axum::serve(...).with_graceful_shutdown`, then drop the telemetry guard to flush OTel (review G3).
|
||||
- **I2** Integration tests in `tests/` covering Verification #6:
|
||||
- A missing or invalid token gets 401 on `/api/v1/*` and `/mcp`. `/healthz` returns 200 without a token.
|
||||
- `auth.enabled = false` with `bind = 0.0.0.0` makes startup exit non-zero with a clear message.
|
||||
- A missing Docker socket gives 503 on docker routes while systemd routes still return 200.
|
||||
- SIGTERM with an open SSE client exits within a few seconds.
|
||||
- **I3** `systemd/skyg-linux-tracker.service`:
|
||||
- `ExecStart=/usr/local/bin/slinuxm serve --config /etc/skyg-linux-tracker.toml`
|
||||
- A dedicated `User=` (for example `skyg`), or `DynamicUser=yes` if the token CLI story still works. Decide and note it.
|
||||
- `StateDirectory=skyg-linux-tracker`, `StateDirectoryMode=0700`
|
||||
- `ProtectSystem=strict`, `ProtectHome=yes`, `PrivateTmp=yes`, `NoNewPrivileges=yes`, `ProtectKernelTunables=yes`, `ProtectControlGroups=yes`, `RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6`, `LockPersonality=yes`, `MemoryDenyWriteExecute=yes`
|
||||
- `SupplementaryGroups=systemd-journal`. Add `docker` commented out with a root-equivalence warning (DEC-6).
|
||||
- **I4** `README.md`:
|
||||
- What it is and how to build it (`devenv shell`, `cargo build --release`).
|
||||
- Install: binary, config, unit file.
|
||||
- Config reference, or a pointer to `config.example.toml` and the env-var naming.
|
||||
- Token workflow: `sudo -u skyg slinuxm token create <name>`.
|
||||
- REST endpoint list, and MCP client setup with a bearer header example.
|
||||
- OTel setup and the hardened Docker socket-proxy option.
|
||||
- **I5** Release build checks:
|
||||
- `cargo build --release`.
|
||||
- `ldd target/release/slinuxm` lists only libc, libsystemd and libsystemd's own deps.
|
||||
- Record the binary size in the log.
|
||||
- **I6** Run Verification #1–#6 from `plan.md` by hand on a real systemd + Docker host and record the results in the log.
|
||||
|
||||
## Done when
|
||||
|
||||
- I2 tests pass in `cargo test`.
|
||||
- I6 results are logged with all six checks passing.
|
||||
- The unit file starts the service on a clean host with only the binary, config and unit installed.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,42 @@
|
||||
# WS-A — systemd source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 1 (parallel) |
|
||||
| Depends on | P0 |
|
||||
| Blocks | WS-E, WS-F, WS-G (to finish) |
|
||||
| Owned files | `src/sources/systemd.rs`, `examples/systemd_dump.rs` |
|
||||
|
||||
## Goal
|
||||
|
||||
Implement `SystemdSource` over D-Bus with `zbus_systemd`. Every call hits the bus live, with no caching.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **A1** Create one `zbus::Connection::system()` at construction and share `ManagerProxy`.
|
||||
- **A2** `list_units(state: Option<…>)`. Use `ListUnitsFiltered(states)` when a state is given, otherwise `ListUnits`. Map the tuple to `UnitSummary` (name, description, load/active/sub state).
|
||||
- **A3** `list_timers()`. The Manager has no `ListTimers` method (review R1). Call `ListUnitsByPatterns([], ["*.timer"])`, then for each timer read `TimerProxy`: `NextElapseUSecRealtime`, `LastTriggerUSec`, `Unit` (the triggered unit). Convert µs since epoch to RFC3339. `0` or `u64::MAX` means `None`.
|
||||
- **A4** `unit_status(name)`. Try `GetUnit(name)` first, falling back to `LoadUnit` only on `NoSuchUnit`. The fallback lets inactive unloaded units still report without side effects on loaded ones.
|
||||
- `Unit` props: `ActiveState`, `SubState`, `LoadState`, `Description`, `ActiveEnterTimestamp`, `FragmentPath`.
|
||||
- `Service` props, only when the name ends in `.service`: `ExecMainStatus`, `NRestarts`, `MainPID`.
|
||||
- **A5** Validate names against systemd's charset (`[A-Za-z0-9:_.@\-\\]`, max 255) and return `BadRequest`. Map D-Bus `NoSuchUnit` to `NotFound`. Map bus connection failure to `Unavailable`.
|
||||
- **A6** `examples/systemd_dump.rs` prints JSON for units, failed units, timers and one unit's status.
|
||||
- **A7** Unit tests for µs-to-RFC3339 conversion, sentinel handling and tuple mapping.
|
||||
|
||||
## Done when
|
||||
|
||||
- `cargo run --example systemd_dump` prints sane JSON on a real host. Timers show next elapse times that match `systemctl list-timers`.
|
||||
- `unit_status("nonexistent.service")` returns `NotFound` and `unit_status("../etc")` returns `BadRequest`.
|
||||
|
||||
## Notes
|
||||
|
||||
- Property reads cost one D-Bus round-trip each. Fetch with `GetAll` where zbus_systemd exposes it, or `join!` the reads.
|
||||
- Unprivileged reads on the system bus are allowed. No polkit involvement is needed for these calls.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,47 @@
|
||||
# WS-B — journal source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 1 (parallel) |
|
||||
| Depends on | P0 (incl. spike findings on the `systemd` crate) |
|
||||
| Blocks | WS-E, WS-F, WS-G (to finish) |
|
||||
| Owned files | `src/sources/journal.rs`, `examples/journal_tail.rs` |
|
||||
|
||||
## Goal
|
||||
|
||||
Implement `JournalSource` over sd-journal via the `systemd` crate. It provides a bounded snapshot query and a cancellable live follow.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **B1** Run every sd-journal call inside `tokio::task::spawn_blocking` (review G1). Open the journal inside the blocking closure and never hold it across `.await`. Use `sources.journal_namespace` if the spike found namespace support. Otherwise log a warning when it is set and use the default journal.
|
||||
- **B2** `query(JournalQuery)`:
|
||||
- Unit filter via `match_add("_SYSTEMD_UNIT", unit)`.
|
||||
- Priority filter `≤ N` by adding one `PRIORITY=k` match for each k in 0..=N. Matches on the same field are OR'ed by sd-journal.
|
||||
- `seek_tail`, then step backward `lines` entries. `lines` is clamped to `limits.max_lines`.
|
||||
- Reverse the result so it returns oldest-first.
|
||||
- **B3** `follow(JournalQuery, CancellationToken) -> mpsc::Receiver<JournalEntry>`:
|
||||
- Seek to tail and run a blocking loop of `wait(Some(500ms))`, then drain new entries with `next`.
|
||||
- Each iteration checks `tx.is_closed()` and `token.is_cancelled()` and exits if either is true (review G2).
|
||||
- Use `blocking_send` with a bounded channel, around 1024 entries. Decide on drop-or-block for slow consumers and document it.
|
||||
- **B4** Map `__REALTIME_TIMESTAMP`, `PRIORITY`, `_SYSTEMD_UNIT`, `SYSLOG_IDENTIFIER`, `_PID`, `_HOSTNAME` and `MESSAGE` to `JournalEntry`. `MESSAGE` may be binary, so convert it with lossy UTF-8.
|
||||
- **B5** `examples/journal_tail.rs --unit X [--priority err] [--lines N] [--follow]`.
|
||||
- **B6** Test that dropping the receiver makes the blocking thread exit within about one second. Use a counter or `JoinHandle` to prove it.
|
||||
|
||||
## Done when
|
||||
|
||||
- The example snapshot output matches `journalctl -u X -p err -n N -o json` for the same filters.
|
||||
- Follow prints new entries live. `logger -t test hello` shows up in under a second.
|
||||
- B6 passes.
|
||||
|
||||
## Notes
|
||||
|
||||
- Reading the full system journal needs the `systemd-journal` group (or root). Without it you only see your own user's entries. Say so in the example's error output.
|
||||
- If the `systemd` crate turns out unmaintained or broken during the spike, record the alternative in the P0 log before starting.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,44 @@
|
||||
# WS-C — docker source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 1 (parallel) |
|
||||
| Depends on | P0 |
|
||||
| Blocks | WS-E, WS-F, WS-G (to finish) |
|
||||
| Owned files | `src/sources/docker.rs`, `examples/docker_ps.rs` |
|
||||
|
||||
## Goal
|
||||
|
||||
Implement `DockerSource` over the Docker or Podman API with `bollard` on a unix socket. A missing Docker never breaks the rest of the service.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **C1** Construct with `Docker::connect_with_unix(socket, timeout, API_DEFAULT_VERSION)`. Construction must not fail when the socket is absent (review G9). Map connection-refused, not-found and permission-denied to `AppError::Unavailable` with a clear message on each call.
|
||||
- **C2** `ps()`:
|
||||
- `list_containers(all = true)`.
|
||||
- Then `inspect_container` for each one concurrently, bounded with `buffer_unordered(8)`.
|
||||
- Map `State.Health.Status`, `State.StartedAt` (to uptime seconds), `RestartCount`, image, and status.
|
||||
- **C3** `container_status(name)` uses inspect only. A 404 maps to `NotFound`.
|
||||
- **C4** `logs(name, follow, tail, since, token)` returns a boxed `Stream<Item = Result<LogLine>>`. Use `stdout`, `stderr` and `timestamps = true`, parse the timestamp prefix, and keep the stream type (stdout or stderr). The stream ends when dropped or when the token fires.
|
||||
- **C5** Clamp `tail` to `limits.max_tail`.
|
||||
- **C6** `examples/docker_ps.rs` prints `ps` as JSON. `--logs NAME [--follow]` streams logs.
|
||||
- **C7** *(nice-to-have)* Run the example against `/run/podman/podman.sock` and note any field differences.
|
||||
|
||||
## Done when
|
||||
|
||||
- The example matches `docker ps -a` and shows health and uptime for containers with healthchecks.
|
||||
- Following logs streams live, and Ctrl-C exits cleanly.
|
||||
- With `docker_socket` pointed at a missing path, every call returns `Unavailable` and nothing panics.
|
||||
|
||||
## Notes
|
||||
|
||||
- Container names from the API have a leading `/`. Strip it in DTOs and accept names with or without it.
|
||||
- `docker logs` only works for the `json-file`, `local` and `journald` log drivers. Others return an API error, which should map to `BadRequest` with the driver named.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,53 @@
|
||||
# WS-D — auth + DB
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 1 (parallel) |
|
||||
| Depends on | P0 |
|
||||
| Blocks | WS-E, WS-F (to finish), P3 |
|
||||
| Owned files | `src/db.rs`, `src/auth/mod.rs`, `src/auth/tokens.rs`, `migrations/` |
|
||||
|
||||
## Goal
|
||||
|
||||
Provide token storage in SQLite, the `slinuxm token` CLI, and one bearer-auth middleware that protects both `/api/v1` and `/mcp`.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **D1** `db::open`:
|
||||
- Create the parent dir with mode `0700` if it is missing. In production, systemd `StateDirectory=` already creates it.
|
||||
- Use `SqliteConnectOptions` with `create_if_missing`, `journal_mode(Wal)` and `busy_timeout(5s)`.
|
||||
- Run `sqlx::migrate!()` from embedded `migrations/`.
|
||||
- **D2** First migration: `tokens(id INTEGER PK, name TEXT NOT NULL UNIQUE, token_hash TEXT NOT NULL UNIQUE, created_at TEXT NOT NULL, revoked_at TEXT, last_used_at TEXT)`.
|
||||
- **D3** `tokens.rs` with runtime `sqlx::query` / `query_as` (DEC-3):
|
||||
- `create(name)` generates 32 bytes from the OS RNG and formats the token as `slinuxm_<base64url>`. Store `hex(sha256(token))` and print the plaintext once with a warning.
|
||||
- `list()` shows name, created, revoked and last-used, never hashes.
|
||||
- `revoke(name)` sets `revoked_at`. Revoking twice is a no-op with a message.
|
||||
- **D4** Implement `auth::tokens::run(TokenCmd, &Config)` behind `slinuxm token create|list|revoke`. The `main.rs` dispatch already exists from P0, so do not edit `main.rs`.
|
||||
- **D5** Middleware:
|
||||
- Extract `Authorization: Bearer <t>`, hash it, and look up `WHERE token_hash = ? AND revoked_at IS NULL`.
|
||||
- On success, optionally update `last_used_at`. Throttle that update to at most once a minute per token, or skip it.
|
||||
- On failure, return `401` with `WWW-Authenticate: Bearer` and the standard JSON error body. Use the same response for `/mcp` (DEC-4).
|
||||
- When `auth.enabled = false`, the layer is a pass-through.
|
||||
- **D6** Expose the middleware so P3 applies it to the protected router only. `/healthz` must stay reachable without a token (review R3).
|
||||
- **D7** Tests:
|
||||
- Use an in-memory or tempdir DB.
|
||||
- Create a token and confirm it is accepted. Revoke it and confirm it is rejected. Garbage and missing headers are rejected.
|
||||
- Re-assert the P0 startup refusal for auth-off + non-loopback bind.
|
||||
|
||||
## Done when
|
||||
|
||||
- `slinuxm token create ci` prints a token. `slinuxm token list` shows it. A request with it passes the middleware.
|
||||
- After `slinuxm token revoke ci`, the same request returns 401 without a server restart.
|
||||
- D7 passes.
|
||||
|
||||
## Notes
|
||||
|
||||
- The CLI writes the same DB the server reads, so WAL mode is required. In production, run the CLI as the service user, for example `sudo -u skyg slinuxm token create …`. Document this in the README (I4).
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,50 @@
|
||||
# WS-E — REST API
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 2 (parallel) |
|
||||
| Depends on | P0 to start (fakes). A, B, C, D to finish. |
|
||||
| Blocks | P3 |
|
||||
| Owned files | `src/api/mod.rs`, `src/api/systemd.rs`, `src/api/journal.rs`, `src/api/docker.rs` |
|
||||
|
||||
## Goal
|
||||
|
||||
Build thin, read-only GET handlers over `AppState` sources, with SSE for follow endpoints. `api::router(state)` returns a router that P3 nests under `/api/v1`.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **E1** `api::router(AppState) -> Router`. Use axum 0.8 path syntax `/{name}`, because `:name` panics (review R4). GET only.
|
||||
- **E2** Systemd routes:
|
||||
- `/systemd/units?state=failed|active|…`
|
||||
- `/systemd/units/{name}`
|
||||
- `/systemd/timers`
|
||||
- **E3** `/journal?unit=&priority=err|3&lines=`. Parse priority by name or number. Clamp `lines` and return 400 on bad input.
|
||||
- **E4** `/journal/follow?unit=&priority=` returns `Sse` built from the source receiver:
|
||||
- `KeepAlive::default()`.
|
||||
- The stream ends on client disconnect, which drops the receiver and stops the blocking thread, or on `state.shutdown` (review G3).
|
||||
- **E5** Docker routes:
|
||||
- `/docker/ps`
|
||||
- `/docker/containers/{name}`
|
||||
- `/docker/containers/{name}/logs?tail=&since=&follow=`: JSON array when `follow=0`, SSE when `follow=1`. Each SSE event's `event:` is `stdout` or `stderr`.
|
||||
- **E6** Provide a public `healthz` handler for P3 to mount outside auth. It returns `{"status":"ok","version":…}`.
|
||||
- **E7** All errors go through `AppError`, giving one JSON shape everywhere.
|
||||
- **E8** Tests with `fake.rs` sources via `tower::ServiceExt::oneshot`. Cover each route's happy path, 400, 404, and one SSE stream that yields events and then ends.
|
||||
- **E9** When the fake docker returns `Unavailable`, docker routes return 503 and systemd and journal routes still return 200.
|
||||
|
||||
## Done when
|
||||
|
||||
- E8 and E9 pass.
|
||||
- With real sources wired by P3, Verification #3 curl checks pass, including `curl -N` on both SSE endpoints.
|
||||
|
||||
## Notes
|
||||
|
||||
- Handlers stay thin: parse, call the source, serialize. No business logic.
|
||||
- `tower-http` `TraceLayer` is applied in P3, not here.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,60 @@
|
||||
# WS-F — MCP server
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 2 (parallel) |
|
||||
| Depends on | P0 to start (fakes, spike findings). A, B, C, D to finish. |
|
||||
| Blocks | P3 |
|
||||
| Owned files | `src/mcp/mod.rs`, `src/mcp/prompts.rs`, `src/mcp/resources.rs` |
|
||||
|
||||
## Goal
|
||||
|
||||
Build an `rmcp` Streamable HTTP server exposing the same data as REST, plus agent-facing context: instructions, rich descriptions, prompts and resources. `mcp::service(state)` returns the Tower service that P3 mounts at `/mcp`.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **F1** `TrackerService` holding `AppState`, with `#[tool_router]`. There are 8 tools (review R5):
|
||||
- `list_systemd_units { state? }`
|
||||
- `get_systemd_unit { name }`
|
||||
- `list_systemd_timers {}`
|
||||
- `get_journal_logs { unit?, priority?, lines }`
|
||||
- `tail_journal { unit, seconds }`
|
||||
- `list_containers {}`
|
||||
- `get_container { name }`
|
||||
- `get_container_logs { name, tail }`
|
||||
- Parameter structs derive `Deserialize` and `JsonSchema`.
|
||||
- **F2** `tail_journal` clamps `seconds` to `limits.max_follow_secs` and stops early at an entry cap, for example `limits.max_lines`. It returns whatever it collected and never streams indefinitely.
|
||||
- **F3** `get_container_logs` clamps `tail` to `limits.max_tail`.
|
||||
- **F4** `ServerHandler::get_info` sets server name/version, capabilities for tools, prompts and resources, and **instructions**. The instructions describe the workflow: start with failed units or unhealthy containers, then pull logs for the specific unit or container, and use timers to explain scheduled jobs.
|
||||
- **F5** `#[tool(description = …)]` strings explain:
|
||||
- active/sub states (`failed`, `activating`, `auto-restart`)
|
||||
- journal priority numbers and names
|
||||
- Docker health states (`starting`, `healthy`, `unhealthy`, `none`)
|
||||
- **F6** Prompts in `prompts.rs`:
|
||||
- `diagnose_unit { name }`: status, then recent err+ logs, then restart count, then a suggested next look.
|
||||
- `container_health_report {}`: list, then unhealthy and restarting containers, then their logs.
|
||||
- **F7** Resources in `resources.rs`: `systemd://units/failed` and `docker://containers`. Implement list and read, resolved live on each read, with no subscriptions (DEC-5).
|
||||
- **F8** `mcp::service(state)` builds `StreamableHttpService::new(|| Ok(TrackerService::new(state.clone())), LocalSessionManager::default().into(), config)`. Apply Origin validation per DEC-8.
|
||||
- **F9** Tests against fake sources:
|
||||
- A snapshot of the tool list (names + schemas), so description changes are reviewed deliberately.
|
||||
- Each tool's happy path.
|
||||
- `AppError` maps to MCP errors.
|
||||
- `tail_journal` respects its time cap.
|
||||
|
||||
## Done when
|
||||
|
||||
- F9 passes.
|
||||
- With P3 wiring, Verification #4 passes. MCP Inspector at `http://localhost:9109/mcp` with a bearer header lists 8 tools, 2 prompts and 2 resources, and every tool returns data. Without the header the client receives 401.
|
||||
|
||||
## Notes
|
||||
|
||||
- Tool handlers must not duplicate logic from `api/`. Both call `sources/` directly.
|
||||
- Keep tool output JSON-shaped (serialized DTOs) so agents can parse it, with a short text summary line where it helps.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
@@ -0,0 +1,55 @@
|
||||
# WS-G — OpenTelemetry export
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Backlog |
|
||||
| Owner | — |
|
||||
| Phase | 2 (parallel) |
|
||||
| Depends on | P0 to start (fakes, spike findings). A, B, C to finish. |
|
||||
| Blocks | P3 |
|
||||
| Owned files | `src/telemetry/mod.rs`, `src/telemetry/metrics_export.rs`, `src/telemetry/logs_export.rs`, `dev/otelcol.yaml` |
|
||||
|
||||
## Goal
|
||||
|
||||
Export traces, metrics and logs over a single OTLP exporter config. This is the only push path in the system. Metrics come from a poll loop, and logs fan out from the journal and Docker follow streams.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **G1** `telemetry::init(&Config) -> TelemetryGuard`:
|
||||
- Build tracer, meter and logger providers from one exporter config: `otel.endpoint`, `otel.protocol` (`grpc` or `http`) and `otel.headers`.
|
||||
- Resource attributes: `service.name`, `service.version`, `host.name`.
|
||||
- When `otel.enabled = false`, return a no-op guard.
|
||||
- **G2** Tracing subscriber: `fmt` to stderr (journald captures it under the unit) plus `tracing-opentelemetry` when enabled. Do **not** route the app's own logs into the OTel logs pipeline. That pipeline is for host logs.
|
||||
- **G3** Metrics (review G11):
|
||||
- A background task runs every `metrics_interval_secs`, calls `list_units`, `list_timers` and `ps`, and stores the result in an `ArcSwap` or `RwLock` snapshot.
|
||||
- Observable gauges read the latest snapshot in their callbacks, so units or containers that disappear stop being reported.
|
||||
- **G4** Metric set from `plan.md`:
|
||||
- `systemd.unit.active`, `systemd.unit.failed`, `systemd.unit.restarts`, `systemd.timer.next_elapse_seconds`
|
||||
- `docker.container.running`, `docker.container.healthy`, `docker.container.uptime_seconds`, `docker.container.restarts`
|
||||
- Attribute names: `systemd.unit`, `systemd.sub_state`, `systemd.load_state`; `container.name`, `container.id`, `container.image.name` (semconv).
|
||||
- Scope: apply `otel.metrics.units` / `otel.metrics.containers` globs. With an empty unit list, use the `*.service` + `*.timer` default (DEC-7).
|
||||
- **G5** Logs (`otel.export_logs = true`, review G4):
|
||||
- Journal: one `follow()` per configured unit, or one unfiltered follow when `otel.logs.journal_units` is empty. Map priority 0–7 to OTel severity (emerg/alert/crit to FATAL, err to ERROR, warning to WARN, notice/info to INFO, debug to DEBUG).
|
||||
- Docker: a reconciler subscribes to Docker `events` (`start`, `die`, `destroy`). It starts and stops per-container `logs(follow)` tasks for allowlisted containers and does an initial list at startup. stderr maps to WARN and stdout to INFO.
|
||||
- Every task restarts with exponential backoff on error. If Docker is unavailable, log once and retry slowly.
|
||||
- Attributes: `systemd.unit` or `container.name`, plus `host.name` from the resource.
|
||||
- **G6** On shutdown: cancel all tasks via `state.shutdown`, then `force_flush` and `shutdown` each provider, with a bounded timeout.
|
||||
- **G7** `dev/otelcol.yaml` with an OTLP receiver (grpc 4317, http 4318) and a `debug` exporter at `verbosity: detailed`. Add a devenv `processes.otelcol` entry, coordinating the `devenv.nix` edit with the P0 owner.
|
||||
|
||||
## Done when
|
||||
|
||||
- Verification #5 passes. With `[otel] enabled = true`, the collector shows the gauges every interval and log records with correct severity and attributes.
|
||||
- `logger -p user.err test` appears as an ERROR record.
|
||||
- Starting a new container shows its logs without restarting the service.
|
||||
- SIGTERM flushes pending records before exit.
|
||||
|
||||
## Notes
|
||||
|
||||
- opentelemetry-rust marks metrics and logs Stable and traces Beta. Pin versions together, because the `opentelemetry*` crates must match each other.
|
||||
- Cardinality: one series per unit or container per attribute set. With the DEC-7 default, expect a few hundred series on a typical host.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
Reference in new issue
Block a user