doc updates
This commit is contained in:
1 parent
7e1bd4a9a4
commit
a511ff532e
26 files changed
+573
-770
No files matched your search
@@ -1,61 +0,0 @@
|
||||
# Board
|
||||
|
||||
_Last updated: 2026-10-19_
|
||||
|
||||
Move a card by cutting its row into another column. Keep the card's own **Status** field in sync. Rules are in [`README.md`](README.md).
|
||||
|
||||
## Blocked
|
||||
|
||||
| Card | Owner | Reason |
|
||||
|---|---|---|
|
||||
| — | | |
|
||||
|
||||
## Ready
|
||||
|
||||
| Card | Owner | Notes |
|
||||
|---|---|---|
|
||||
| — | | |
|
||||
|
||||
## In progress
|
||||
|
||||
| Card | Owner | Branch |
|
||||
|---|---|---|
|
||||
| — | | |
|
||||
|
||||
## Review
|
||||
|
||||
| Card | Owner | PR |
|
||||
|---|---|---|
|
||||
| [P3 Integration](workstreams/P3-integration.md) | — | merged to `main`; I6 (manual Verification #1–#6 on a real host) outstanding |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | — | merged to `main`; gate (`nix build`, `nix flake check`, fresh host) outstanding |
|
||||
|
||||
## Done
|
||||
|
||||
| Card | Completed |
|
||||
|---|---|
|
||||
| [P0 Foundation](workstreams/P0-foundation.md) | merged to `main` |
|
||||
| [WS-A systemd](workstreams/WS-A-systemd.md) | merged to `main` |
|
||||
| [WS-B journal](workstreams/WS-B-journal.md) | merged to `main` |
|
||||
| [WS-C docker](workstreams/WS-C-docker.md) | merged to `main` |
|
||||
| [WS-D auth + DB](workstreams/WS-D-auth.md) | merged to `main` |
|
||||
| [WS-E REST](workstreams/WS-E-rest.md) | merged to `main` |
|
||||
| [WS-F MCP](workstreams/WS-F-mcp.md) | merged to `main` |
|
||||
| [WS-G OTel](workstreams/WS-G-otel.md) | merged to `main` |
|
||||
| [WS-I TLS](workstreams/WS-I-tls.md) | merged to `main` |
|
||||
|
||||
## Backlog
|
||||
|
||||
| Card | Waiting on |
|
||||
|---|---|
|
||||
| — | |
|
||||
|
||||
## Milestones
|
||||
|
||||
| Milestone | Gate | Status |
|
||||
|---|---|---|
|
||||
| M0 Skeleton | `slinuxm serve --print-config` works. Clippy and tests are clean. No openssl. | ✅ |
|
||||
| M1 Sources live | All four Phase 1 examples run against a real host | 🟨 systemd, journal and docker verified live; merged |
|
||||
| M2 Surfaces | Verification #3, #4 and #5 pass | 🟨 #3 and #4 verified live on 2026-10-15; #5 (OTel smoke test) not run, no otelcol-contrib binary |
|
||||
| M3 Release | Verification #1–#6 pass. Unit file and README shipped. | ⬜ |
|
||||
| M4 NixOS | `nix flake check` passes including the VM test. `:1984` serves and a token is minted with the system-installed CLI. | ⬜ |
|
||||
| M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | ✅ merged to `main` |
|
||||
+20
-49
@@ -1,54 +1,25 @@
|
||||
# Workboard
|
||||
# Planning the next phase
|
||||
|
||||
Markdown workboard for building skyg-linux-tracker (CLI: `slinuxm`). The design lives in [`../plan.md`](../plan.md). This folder tracks the work.
|
||||
`plan/` is only for planning the next big piece of work, before it starts. It is empty of plans while the current board is clean.
|
||||
|
||||
| File | Purpose |
|
||||
Where other things live:
|
||||
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| [`BOARD.md`](BOARD.md) | Kanban view. One row per workstream card, moved between columns. |
|
||||
| [`../TODO.md`](../TODO.md) | Master checklist. The only place task checkboxes are ticked. |
|
||||
| [`workstreams/`](workstreams/) | One card per workstream: goal, owned files, dependencies, design notes, done criteria, log. |
|
||||
| [`review.md`](review.md) | Design review of `plan.md`. Corrections and gaps, each mapped to a task. |
|
||||
| [`decisions.md`](decisions.md) | Decision log. Open questions and proposed defaults. |
|
||||
| Work tracking and checkboxes | [`../TODO.md`](../TODO.md) (tick boxes only there) |
|
||||
| Current design and decisions | [`../ARCHITECTURE.md`](../ARCHITECTURE.md) |
|
||||
| Long-form docs | [`../docs/`](../docs/README.md) |
|
||||
| Records of finished workstreams | [`../docs/workstreams/`](../docs/workstreams/) |
|
||||
|
||||
## Cards
|
||||
## Proposing a phase plan
|
||||
|
||||
| Card | Phase | Depends on | Owned files |
|
||||
|---|---|---|---|
|
||||
| [P0 Foundation](workstreams/P0-foundation.md) | 0 | — | `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`, all stubs |
|
||||
| [WS-A systemd](workstreams/WS-A-systemd.md) | 1 | P0 | `src/sources/systemd.rs`, `examples/systemd_dump.rs` |
|
||||
| [WS-B journal](workstreams/WS-B-journal.md) | 1 | P0 | `src/sources/journal.rs`, `examples/journal_tail.rs` |
|
||||
| [WS-C docker](workstreams/WS-C-docker.md) | 1 | P0 | `src/sources/docker.rs`, `examples/docker_ps.rs` |
|
||||
| [WS-D auth + DB](workstreams/WS-D-auth.md) | 1 | P0 | `src/db.rs`, `src/auth/`, `migrations/` |
|
||||
| [WS-E REST](workstreams/WS-E-rest.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/api/` |
|
||||
| [WS-F MCP](workstreams/WS-F-mcp.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/mcp/` |
|
||||
| [WS-G OTel](workstreams/WS-G-otel.md) | 2 | P0 (fakes); A, B, C to finish | `src/telemetry/`, `dev/otelcol.yaml` |
|
||||
| [P3 Integration](workstreams/P3-integration.md) | 3 | E, F, G | `src/main.rs` (wiring), `systemd/`, `README.md`, `tests/` |
|
||||
| [WS-I TLS](workstreams/WS-I-tls.md) | 4 | P3 | `src/tls.rs`, `server.tls` config keys, `tests/tls.rs` |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | 4 | P3, WS-I | `flake.nix`, `nix/` |
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```
|
||||
P0 Foundation (config, DTOs, traits+fakes, AppState, stubs)
|
||||
├── WS-A systemd ──┐
|
||||
├── WS-B journal ──┤
|
||||
├── WS-C docker ───┼──► WS-E REST ──┐
|
||||
└── WS-D auth ─────┤ WS-F MCP ───┼──► P3 Integration
|
||||
└──► WS-G OTel ──┘
|
||||
|
||||
P3 Integration ──► WS-I TLS ──► WS-H NixOS (package + module + CLI + VM test)
|
||||
```
|
||||
|
||||
With source traits and fakes (DEC-2), Phase 2 cards can **start** as soon as P0 is done. They **finish** only once their real sources are merged and verified against a live host.
|
||||
|
||||
**Solo order:** P0 → A → B → C → D → E → F → G → P3.
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Status flow:** `Backlog` → `Ready` → `In progress` → `Review` → `Done`, plus `Blocked` with a reason. A card becomes `Ready` when everything in its "Depends on" is `Done`, or when it can run against fakes.
|
||||
2. **One owner per card.** Put the name (or agent/branch) in the card's Owner field and on the board.
|
||||
3. **File ownership is strict.** A card edits only its owned files. If it needs a change in someone else's file, typically a DTO in `src/sources/mod.rs`, raise it in the card log and make the change as a small separate commit agreed with that file's owner.
|
||||
4. **Tick tasks in `TODO.md`.** Cards describe tasks but do not carry checkboxes, so there is one source of truth.
|
||||
5. **A card moves to `Done`** when every task is ticked, its "Done when" criteria are demonstrated, and `cargo clippy -- -D warnings` + `cargo test` pass.
|
||||
6. **Decisions go in `decisions.md`.** Record the outcome there and link it from the card log.
|
||||
7. **Branch naming:** `ws-a/systemd-source`, `p0/foundation`, and so on.
|
||||
1. Copy [`TEMPLATE.md`](TEMPLATE.md) to `plan/<short-name>.md` (for example `plan/phase-5-alerting.md`).
|
||||
2. Fill in:
|
||||
- **Goal**: what changes for users or operators, in a few sentences.
|
||||
- **Scope**: what is in, and explicitly what is out.
|
||||
- **Workstreams**: independent tracks with owned files, dependencies and done criteria, so they can run in parallel without merge conflicts.
|
||||
- **Open decisions**: questions that need a human call, each with options and a recommendation.
|
||||
- **Exit criteria**: how you will know the phase is done (commands to run, behaviour to demonstrate).
|
||||
3. Review and settle the open decisions in the plan file.
|
||||
4. When the plan is accepted, move the work into [`../TODO.md`](../TODO.md): add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
|
||||
5. When the phase finishes, move the plan file (and any per-workstream notes) to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Phase N: <name>
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Draft / Accepted / In progress / Done |
|
||||
| Owner | |
|
||||
| Date | |
|
||||
| Depends on | |
|
||||
|
||||
## Goal
|
||||
|
||||
What changes for users or operators once this phase is done, in a few sentences.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
-
|
||||
|
||||
Out of scope:
|
||||
|
||||
-
|
||||
|
||||
## Workstreams
|
||||
|
||||
One block per independent track. Name the files each owns so tracks do not collide.
|
||||
|
||||
### WS-X: <name>
|
||||
|
||||
- Goal:
|
||||
- Owned files:
|
||||
- Depends on:
|
||||
- Tasks (IDs to be ticked in `TODO.md`):
|
||||
- **X1**
|
||||
- Done when:
|
||||
|
||||
## Open decisions
|
||||
|
||||
| ID | Question | Options | Recommendation | Decision |
|
||||
|---|---|---|---|---|
|
||||
| | | | | |
|
||||
|
||||
## Risks
|
||||
|
||||
-
|
||||
|
||||
## Exit criteria
|
||||
|
||||
Concrete, checkable. Commands to run and behaviour to demonstrate, for example `cargo clippy --all-targets -- -D warnings`, `cargo test`, and a live check on a real host.
|
||||
|
||||
-
|
||||
@@ -1,149 +0,0 @@
|
||||
# Decision log
|
||||
|
||||
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 | 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 | — |
|
||||
|
||||
---
|
||||
|
||||
## DEC-1 — Binary / CLI name
|
||||
|
||||
**Status:** Decided 2026-10-15
|
||||
|
||||
The plan used three names. The repo is `linux-system-monitor`, the service is `skyg-linux-tracker`, and the CLI examples said `skyg token create`.
|
||||
|
||||
**Decision:** The binary and CLI are **`slinuxm`**. Examples are `slinuxm serve` and `slinuxm token create <name>`. The `[[bin]]` name in `Cargo.toml` is `slinuxm`. Issued tokens use the prefix `slinuxm_`.
|
||||
|
||||
**Assumed unchanged:** the product name `skyg-linux-tracker`, the unit file `skyg-linux-tracker.service`, the state dir `/var/lib/skyg-linux-tracker`, the config path `/etc/skyg-linux-tracker.toml`, and the `SKYG_` env prefix. Revisit here if those should become `slinuxm` too.
|
||||
|
||||
---
|
||||
|
||||
## DEC-2 — Source traits + fakes in Phase 0
|
||||
|
||||
**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<dyn …>`.
|
||||
|
||||
- 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:** 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:** 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:** Accepted 2026-10-15. Runtime `sqlx::query` / `query_as`, no macros, no `.sqlx/` cache.
|
||||
|
||||
---
|
||||
|
||||
## DEC-4 — MCP auth failure = HTTP 401
|
||||
|
||||
**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:** 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:** 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:** Accepted 2026-10-15. Resources are list/read only, resolved live. No subscriptions in v1.
|
||||
|
||||
---
|
||||
|
||||
## DEC-6 — Docker socket access model
|
||||
|
||||
**Status:** Decided 2026-10-15
|
||||
|
||||
Membership in the `docker` group is root-equivalent. Our code only reads, but a compromised process could do anything.
|
||||
|
||||
Options:
|
||||
1. `SupplementaryGroups=docker` in the unit file, documented as a trade-off. This is the plan's default.
|
||||
2. Point `sources.docker_socket` at a read-only socket proxy that only allows container list, inspect and logs.
|
||||
|
||||
**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:** 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:** 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:** 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:** 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:** 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://<bind>:*` + `server.allowed_origins`. The config keys `server.allowed_hosts` and `server.allowed_origins` already exist.
|
||||
|
||||
---
|
||||
|
||||
## DEC-9 — Port 1984 by default, loopback by default
|
||||
|
||||
**Status:** Decided 2026-10-16
|
||||
|
||||
The binary and the NixOS module both default to `port = 1984` and `bind = "127.0.0.1"` (the binary default was 9109 until 2026-10-16, when the user made 1984 the default everywhere). Exposing the service to the LAN is an install-time choice made in the host's own config, never a default: the operator sets `bind`, `openFirewall` (or an interface-scoped rule) and `allowedHosts` for that deployment. Config validation already refuses auth-off on a non-loopback bind, and a non-loopback bind without TLS logs a warning (see DEC-12).
|
||||
|
||||
**Decision:** Accepted by the user. The default is loopback. Installs change the relevant settings.
|
||||
|
||||
---
|
||||
|
||||
## DEC-10 — No CLI wrapper
|
||||
|
||||
**Status:** Decided 2026-10-16
|
||||
|
||||
The module installs the plain `slinuxm` binary on `PATH`. Tokens are minted with `sudo -u skyg-linux-tracker slinuxm token create <name>`, documented in the README and in the module's post-install notes. No wrapper script.
|
||||
|
||||
Running the token commands as root is a trap: if the service has not started yet, root creates the state dir and DB owned by root, and root-owned WAL files can lock the service out. So the token subcommands refuse to run as root when the state dir or DB belongs to another user, and print the exact `sudo -u …` command to use. This is a small change in `slinuxm`, tracked as H5.
|
||||
|
||||
**Decision:** Accepted by the user. No wrapper. The app guards against the root mistake.
|
||||
|
||||
---
|
||||
|
||||
## DEC-11 — No declarative or bootstrap tokens in v1
|
||||
|
||||
**Status:** Decided 2026-10-16
|
||||
|
||||
Tokens are minted with `slinuxm token create <name>`, printed once, and never stored in plaintext. There is no `bootstrapTokens` option and no import of pre-hashed tokens in v1.
|
||||
|
||||
**Decision:** Accepted by the user: print the token once, never store it.
|
||||
|
||||
---
|
||||
|
||||
## DEC-12 — TLS terminated in-process with rustls
|
||||
|
||||
**Status:** Decided 2026-10-16
|
||||
|
||||
Bearer tokens over plain HTTP are readable on the wire, and LAN exposure is the intended deployment. The service gets native TLS: `server.tls.enabled`, `cert_file`, `key_file`, with certificate reload on SIGHUP so ACME or sops-managed rotation needs no restart. A reverse proxy still works and nothing depends on it. rustls is already in the dependency tree and openssl stays out. When TLS is enabled the MCP Origin allowlist uses `https://`. TLS is optional and off by default; with it off nothing changes. A non-loopback bind without TLS logs a startup warning but is not refused.
|
||||
|
||||
**Decision:** Accepted by the user: option A, in-process rustls. TLS stays optional and off by default.
|
||||
@@ -1,59 +0,0 @@
|
||||
# Design review — `plan.md`
|
||||
|
||||
Reviewed 2026-10-15 against `plan.md` (skyg-linux-tracker design doc).
|
||||
|
||||
**Verdict: sound, proceed.** The core architecture holds up. `sources/` is the only layer that talks to the host, and REST, MCP and OTel are thin projections over it. That makes the "same data on every surface" requirement true by construction and makes the parallel workstreams real. The crate choices are reasonable.
|
||||
|
||||
The items below are corrections or gaps. Each is folded into a task in [`../TODO.md`](../TODO.md) (task IDs in brackets). Items needing a human call are tracked in [`decisions.md`](decisions.md).
|
||||
|
||||
## Correctness issues (plan is wrong as written)
|
||||
|
||||
| # | Issue | Fix | Task |
|
||||
|---|---|---|---|
|
||||
| R1 | systemd's D-Bus `Manager` has **no `ListTimers` method**. `systemctl list-timers` lists `*.timer` units, then reads the `org.freedesktop.systemd1.Timer` interface on each. | Use `ListUnitsByPatterns(["*.timer"])` (or filter `ListUnits`), then `TimerProxy` properties `NextElapseUSecRealtime`, `LastTriggerUSec`, `Unit`. Treat `0` / `u64::MAX` as "not scheduled". | A3 |
|
||||
| R2 | `ExecMainStatus` and `NRestarts` live on the **`Service`** interface, not `Unit`. They do not exist for timers, sockets, mounts. | Read `Unit` props for every unit and `Service` props only for `.service` units. Make those DTO fields `Option`. | A4, P0-6 |
|
||||
| R3 | `.layer(auth_middleware)` on the whole router also protects **`/healthz`**, contradicting "unauthenticated liveness". | Build a protected router (`/api/v1`, `/mcp`) with the auth layer, then `.merge()` a public router holding `/healthz`. | I1, D6 |
|
||||
| R4 | Route table uses `:name`. **axum 0.8 uses `/{name}`** and panics at startup on the old `:name` syntax. | Use `{name}` in code. The table in `plan.md` is fine as notation. | E1 |
|
||||
| R5 | Tool count mismatch. The tool list has **8** tools (3 systemd, 2 journal, 3 docker) but WS-F says "9 tools". | Board uses 8. Add a 9th only deliberately. | F1 |
|
||||
| R6 | `config.example.toml` has no `otel.headers` (the tech table relies on it) and no **metrics** allowlists (the OTel section relies on them). Only log allowlists exist. | Add `otel.headers` and `[otel.metrics] units/containers`. | P0-4, P0-5 |
|
||||
| R7 | Repo layout comment says devenv needs `openssl`, which contradicts "rustls everywhere". | Drop openssl. Gate on `cargo tree -i openssl` returning nothing. | P0-1, P0-2 |
|
||||
| R8 | "Compile-time-checked queries" with `sqlx` needs `DATABASE_URL` at build time or a committed `.sqlx/` offline cache. Neither is in the plan. | For one table, use runtime `sqlx::query` / `query_as`. See decision DEC-3. | D3 |
|
||||
|
||||
## Gaps (missing from the plan, will bite during implementation)
|
||||
|
||||
| # | Gap | Fix | Task |
|
||||
|---|---|---|---|
|
||||
| G1 | **Blocking journal calls.** Only `follow()` mentions `spawn_blocking`. Snapshot `query()` is also blocking sd-journal FFI and would stall a tokio worker. | Run all sd-journal work in `spawn_blocking`. Never hold a `Journal` across an `.await`. | B1, B2 |
|
||||
| G2 | **Follow-stream leaks.** A blocking `wait()` loop does not notice an SSE client disconnecting, so threads pile up. | `wait()` with a short timeout and exit when `tx.is_closed()` or the shutdown token fires. Add a test. | B3, B6 |
|
||||
| G3 | **Graceful shutdown with open SSE.** axum's graceful shutdown waits for open connections. Long-lived SSE streams block it forever. | One `CancellationToken` in `AppState`. Every stream and background task selects on it. | P0-9, E4, G6, I1 |
|
||||
| G4 | **Docker containers come and go.** OTel log fan-out spawns per-container follow tasks at startup only. New containers are missed and dead ones leave dangling tasks. | Reconcile from the Docker events stream (`start`/`die`/`destroy`) or a periodic re-list. | G5 |
|
||||
| G5 | **File-ownership conflicts.** Phase 0 owns `main.rs` and `sources/mod.rs`, but WS-D must add the `token` CLI dispatch to `main.rs`, and each source track must add `pub mod x;` to `sources/mod.rs`. | Phase 0 creates every module as a stub with final function signatures. Workstreams then only fill in their own files. | P0-10 |
|
||||
| G6 | **No shared `AppState` defined.** Every surface needs the same handles: sources, DB pool, config, shutdown token. | Define it in Phase 0 (`src/state.rs`). | P0-9 |
|
||||
| G7 | **Input bounds.** `lines`, `tail`, and MCP `tail_journal { seconds }` are unbounded. A large value means a huge response or a hung MCP call. | Config-driven caps (`limits.max_lines`, `limits.max_follow_secs`). Validate unit and container names. | P0-4, A5, B2, F2 |
|
||||
| G8 | **MCP Origin validation.** The MCP Streamable HTTP spec requires servers to validate `Origin` to block DNS-rebinding attacks. The plan does not mention it. | Check what the pinned `rmcp` provides. Otherwise add a small Origin/Host check layer on `/mcp`. | P0-3, F8 |
|
||||
| G9 | **Docker absent at startup.** The plan wants a clean error on docker endpoints but doesn't say how the source is constructed. | Construct lazily. A missing or denied socket maps to `AppError::Unavailable` (503) per request and never fails startup. | C1, E9 |
|
||||
| G10 | **Metric cardinality default.** "Empty = all" for metrics means every loaded unit (often 300+), including inactive mounts and devices. | Default the metrics scope to `*.service` and `*.timer`. Allowlists narrow it further. See DEC-7. | G4 |
|
||||
| G11 | **Stale gauge series.** A unit or container that disappears keeps its last exported value with synchronous OTel gauges. | Use observable gauges fed from the latest poll snapshot, so vanished series stop being reported. | G3 |
|
||||
|
||||
## Recommendations (improvements, not errors)
|
||||
|
||||
- **Define the source traits in Phase 0 and ship fakes.** The layout already says "one trait per domain". With `SystemdSource` / `JournalSource` / `DockerSource` traits and in-memory fakes, WS-E/F/G can start right after Phase 0 against fakes instead of waiting for Phase 1. Handler and MCP tool tests also run without a live host. (DEC-2, P0-7)
|
||||
- **Move the "auth disabled + non-loopback bind" check into config validation.** It is pure config logic and `config.rs` is a Phase 0 file. WS-D keeps it in its done-criteria as a verification. (P0-4)
|
||||
- **MCP auth failures should be HTTP 401, not a JSON-RPC error.** The MCP authorization spec handles auth at the HTTP transport layer. Clients expect `401` with `WWW-Authenticate: Bearer`. Use the same middleware response for REST and MCP. (DEC-4, D5)
|
||||
- **MCP resources: no subscriptions in v1.** Subscribable resources need change detection, which means polling. That contradicts "live reads only". Expose them as list/read resources resolved live. (DEC-5, F7)
|
||||
- **Use OTel semantic-convention attribute names where they exist.** Examples are `container.name`, `container.id`, `container.image.name`, and `host.name` as a resource attribute. Keep `systemd.unit` for systemd, which has no convention. (G4)
|
||||
- **`unit_status` should prefer `GetUnit`.** `LoadUnit` can load a unit file into the manager, a small side effect for a "read-only" tool. Fall back to `LoadUnit` only to report on unloaded units. (A4)
|
||||
- **Token DB lookup by sha256 is already the check.** Constant-time comparison adds nothing once you do an indexed lookup on a high-entropy token's hash. Keep the lookup, skip the extra compare. (D5)
|
||||
- **Use SQLite WAL mode plus `busy_timeout`.** The `token` CLI and the running server write and read the same DB at the same time. (D1)
|
||||
- **Use systemd `StateDirectory=` in the unit file.** It creates `/var/lib/skyg-linux-tracker` with the right owner and mode, so the app does not need root to create it. The app keeps its "create if missing" fallback for dev runs. (I3)
|
||||
- **Docker group is root-equivalent.** Read-only in our code, but socket access grants full control of the daemon. Document it. Optionally support a read-only socket proxy (for example `docker-socket-proxy` with only `CONTAINERS=1`), which works as-is since `sources.docker_socket` is configurable. (DEC-6, I3, I4)
|
||||
- **Add a time-boxed API spike to Phase 0.** Several plan details depend on exact crate APIs: rmcp's `StreamableHttpServerConfig` fields, zbus_systemd proxy names, whether the `systemd` crate can open a journal namespace, and bollard's feature flags. Confirm them while pinning versions, before parallel work fixes the contracts. (P0-3)
|
||||
|
||||
## Things that are fine as-is
|
||||
|
||||
- One axum server for REST and MCP, with `rmcp`'s `StreamableHttpService` mounted via `nest_service`.
|
||||
- Bounded `tail_journal` for MCP instead of infinite streams.
|
||||
- Tokens stored as sha256 hashes, plaintext shown once.
|
||||
- Config precedence: CLI > env > file > defaults.
|
||||
- libsystemd as the one dynamic dependency. Every target host runs systemd anyway.
|
||||
- The Phase 0 → 1 → 2 → 3 structure and the dependency graph.
|
||||
@@ -1,120 +0,0 @@
|
||||
# P0 — Foundation
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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`.
|
||||
- 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<S, std::io::Error>, session_manager: Arc<M>, config: StreamableHttpServerConfig)`. Service type is `StreamableHttpService<S, LocalSessionManager>` (`rmcp::transport::streamable_http_server::{StreamableHttpService, StreamableHttpServerConfig, session::local::LocalSessionManager}`). It is a `tower_service::Service<Request<B>>` 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<Duration>) -> JournalWaitResult { Nop, Append, Invalidate }` supports a timeout. Other API: `seek_tail`, `previous_skip`, `next_entry`/`previous_entry` returning `JournalRecord = BTreeMap<String, String>`, `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<String,String>)`; `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<JoinHandle<()>>` 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()`.
|
||||
@@ -1,62 +0,0 @@
|
||||
# P3 — Integration & hardening
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Review |
|
||||
| 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.
|
||||
- 2026-10-15: Implemented on `p3/integration`. I1-I5 done; I6 partial. Router assembly lives in `src/server.rs` (`build_router`, `serve_listener`) so tests and `main` share it. Shutdown: signal -> cancel token -> graceful serve ends -> await exporter handles -> `guard.shutdown().await` -> close pool. `token` subcommand does not init telemetry. Unit uses a static `User=skyg` (not DynamicUser) so `sudo -u skyg slinuxm token ...` hits the same DB. I2: 8 tests in `tests/integration.rs` (raw HTTP client, no new deps). Release binary 19 MB; `ldd`: libsystemd, libgcc_s, libm, libc only.
|
||||
- I6 live results (release binary, loopback, real token via CLI, real systemd/journal/docker on this host): #1 build/tests pass; #2 serve + token create pass; #3 REST incl. `curl -N` journal SSE pass (docker log follow SSE not exercised live); #4 MCP initialize, tools/list, prompts/list, resources/list, 5 tool calls, no-token 401, bad Origin 403 pass via curl (MCP Inspector not run; not all 8 tools called); #5 OTel NOT RUN (otelcol-contrib not on PATH, devenv shell not started via `devenv up`); #6 pass via tests (401, auth-off+0.0.0.0 refuses, SIGTERM with open SSE exits 0 in <1s); missing-docker-socket 503 covered by WS-E fake test, not live. Unit file not installed on a clean host (only `systemd-analyze verify`, which cannot fully run here).
|
||||
- 2026-10-15: Review follow-ups applied. Shutdown drain and exporter awaits are bounded (10s each) and the unit uses TimeoutStopSec=30; new test: SIGTERM with an open MCP session and an in-flight 60s `tail_journal` exits 0. Unit: SystemCallFilter, ProtectProc=invisible, ProcSubset=pid, RestrictSUIDSGID, UMask=0077; docker.service is `After=` only. Hardening was run via `systemd-run --user` with the same sandbox properties (REST systemd/journal/docker and SIGTERM all worked); not run as a system unit with User=skyg/StateDirectory. Host allowlist guard on `/api/v1` when auth is disabled (test). `server.port = 0` rejected (test). Integration tests extended (13 tests): unmatched paths (401 with auth on, route existence not disclosed), POST 401/405, GET/DELETE /mcp without token, revoked token, Basic scheme, good Origin, missing docker socket (503 vs 200). SIGTERM tests use env_clear; the pick-port-then-drop race remains (port 0 is now rejected by config).
|
||||
@@ -1,43 +0,0 @@
|
||||
# WS-A — systemd source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Implemented on branch `ws-a/systemd-source`. Gates pass; example verified on live bus (timers match `systemctl list-timers`, NotFound/BadRequest verified). Beyond spec: LoadUnit result with load_state `not-found` also maps to NotFound; `unit_file_state`/`active_exit_time` populated.
|
||||
@@ -1,49 +0,0 @@
|
||||
# WS-B — journal source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Implemented B1-B6 on branch ws-b/journal-source. Query and follow verified on the live host. Unit filter matches `_SYSTEMD_UNIT` only; `UNIT` is used only as a fallback when mapping entries. Follow applies backpressure (no drops). `since` is applied during the backward backlog scan.
|
||||
- 2026-10-15: Review fixes: unit filter is now (_SYSTEMD_UNIT=u OR UNIT=u), with PRIORITY matches repeated per disjunct. Verified against `journalctl -u hyprland-headless.service` style PID1 lines (same 5 entries, same timestamps). Offline unit tests cover match plan, ordering, `since`, and send exit on drop/cancel. Live follow tests are #[ignore]: `cargo test -- --ignored live_`.
|
||||
@@ -1,45 +0,0 @@
|
||||
# WS-C — docker source
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Implemented C1-C6 on branch `ws-c/docker-source`. Verified against the real docker socket (ps, logs, follow). C7 skipped: no Podman socket on this host. `ps` uses `buffered(8)` (ordered) instead of `buffer_unordered`. Names are validated to `[A-Za-z0-9_.-]`. Non-readable log drivers are rejected up front from inspect (BadRequest naming the driver).
|
||||
@@ -1,54 +0,0 @@
|
||||
# WS-D — auth + DB
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Implemented on branch `ws-d/auth-db`. Token fns take `&SqlitePool` (`create`, `list`, `revoke`, `verify`); `db::migrate` is public for in-memory test pools. `last_used_at` is throttled to once a minute. Lookup is by sha256 hex hash with `slinuxm_` prefix pre-check.
|
||||
@@ -1,51 +0,0 @@
|
||||
# WS-E — REST API
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Implemented on branch `ws-e/rest-api`. E1-E9 done. Query errors, missing routes and source errors all use the `AppError` JSON shape. `lines`/`tail` are rejected at 0 and clamped to `limits.max_*`; `priority` parsed via `Priority::from_str`; `state` validated by the source (400). SSE ends on disconnect, `state.shutdown`, or `limits.max_follow_secs`. Journal SSE event name is `journal`; docker is `stdout`/`stderr`; data is the JSON DTO. `api::healthz` is public for P3 to mount at `/healthz`. `follow` and `all` accept 0/1/true/false.
|
||||
@@ -1,62 +0,0 @@
|
||||
# WS-F — MCP server
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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:1984/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.
|
||||
- 2026-10-15: Implemented on branch `ws-f/mcp-server`. Prompts and resources are hand-written `ServerHandler` methods (helpers in `prompts.rs`/`resources.rs` are testable without a request context). `tail_journal` follows with a 10-entry backlog, stops at `max_follow_secs` or `max_lines`. Origin validation is enforced (`enforce_origin_validation`) with loopback and bind origins on `server.port` plus configured extras. Tests use real time (1s cap) because tokio `test-util` is not enabled in Cargo.toml.
|
||||
- 2026-10-15: Review fixes. Tool handlers return source errors as `CallToolResult::error` (is_error) with an actionable message; prompts/resources keep protocol errors. Log tools return `{entries, truncated, note}` capped at 256 KiB. `tail_journal` notes reader-closed, shutdown and entry-cap stops; `seconds` defaults to 10 (schema 0-3600, server clamps to `max_follow_secs`). Log content is documented as untrusted data; `diagnose_unit` validates `name`. Notes: rmcp accepts requests with no `Origin` header, so bearer auth is the real gate; Origin/Host checks defend against browser DNS-rebinding. With `server.bind = 0.0.0.0`, LAN clients need their Host names in `server.allowed_hosts` (a startup warning is logged otherwise).
|
||||
@@ -1,58 +0,0 @@
|
||||
# WS-G — OpenTelemetry export
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| 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.
|
||||
- 2026-10-15: Review fixes F1-F8. Restart polling uses buffer_unordered(8) with a 15s budget; failed sections keep the previous snapshot; series carry identity attributes only; timer metric renamed `systemd.timer.next_elapse_timestamp_seconds`; units added; observations computed once per poll. New containers start from StartedAt, docker lines deduped on reconnect, own unit/identifier excluded from the journal follow (by name; cursor not used). `TelemetryGuard::shutdown().await` added; Drop is best-effort.
|
||||
- P3 notes: (1) call `guard.shutdown().await` after awaiting the exporter handles. (2) devenv: add `processes.otelcol.exec = "otelcol-contrib --config dev/otelcol.yaml"` to devenv.nix (not done here, P0 owner). (3) Cargo.toml needs `reqwest-blocking-client` on opentelemetry-otlp for http/protobuf; the exporter-build test is strict and fails without it. (4) RUST_LOG/EnvFilter deferred.
|
||||
- 2026-10-15: Implemented G1-G7 on `ws-g/otel`. Notes: no glob crate, so a small `*`/`?` matcher lives in `telemetry/mod.rs`. `DockerSource` has no events stream, so the log reconciler polls `ps(false)` every 5s (30s while Docker is unavailable) instead of subscribing to `events`. No `EnvFilter` (feature not enabled in Cargo.toml): level is fixed at INFO. `systemd.timer.next_elapse_seconds` exports absolute unix seconds. `systemd.unit.restarts` costs one `unit_status` per in-scope loaded service per interval. HTTP endpoints get `/v1/<signal>` appended unless already present. Live otelcol smoke test not run (no collector binary on PATH).
|
||||
@@ -1,63 +0,0 @@
|
||||
# WS-H — NixOS module + package
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Review |
|
||||
| Owner | — |
|
||||
| Phase | 4 (single track, after release candidate) |
|
||||
| Depends on | P3 (final unit hardening, `--print-config`, README); WS-I (TLS options) |
|
||||
| Blocks | — |
|
||||
| Owned files | `flake.nix`, `nix/package.nix`, `nix/module.nix`, `nix/tests/`, `README.md` (NixOS section only) |
|
||||
|
||||
## Goal
|
||||
|
||||
Install `skyg-linux-tracker` on NixOS as a systemd service that exposes the REST API and `/mcp` on **port 1984**, and install the `slinuxm` CLI system-wide so the operator can mint the first token.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **H1** `nix/package.nix`: `rustPlatform.buildRustPackage` from the committed `Cargo.lock`. `nativeBuildInputs = [ pkg-config cmake ]` (cmake for `aws-lc-sys`), `buildInputs = [ systemd ]`. Binary is `slinuxm`. Live-journal tests are `#[ignore]`, so the sandbox build runs `cargo test`.
|
||||
- **H2** `flake.nix` exporting `packages.<system>.default` and `nixosModules.default`, plus `checks` wired to H8.
|
||||
- **H3** `nix/module.nix` options under `services.skyg-linux-tracker`:
|
||||
- `enable`, `package`
|
||||
- `port` (default **1984**, same as the binary default)
|
||||
- `bind` (default `"127.0.0.1"`; LAN exposure is set per install)
|
||||
- `tls.enable`, `tls.certFile`, `tls.keyFile` (passed via systemd `LoadCredential`, DEC-12)
|
||||
- `openFirewall` (default `false`)
|
||||
- `allowedHosts` (extra Host/Origin entries for `/mcp`; the module adds `networking.hostName` automatically)
|
||||
- `docker.enable` (default `false`; adds the `docker` group and sets the socket path, DEC-6)
|
||||
- `settings` (freeform TOML via `pkgs.formats.toml`, merged over module defaults)
|
||||
- `environmentFile` (for secrets such as `SKYG_OTEL__HEADERS__*`, kept out of the store)
|
||||
- **H4** Service definition:
|
||||
- dedicated user and group
|
||||
- `StateDirectory=skyg-linux-tracker`, mode 0700 (matches `db_path`)
|
||||
- `SupplementaryGroups=systemd-journal` (plus `docker` when enabled)
|
||||
- the P3 hardening set (`NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome`, `PrivateTmp`, `RestrictAddressFamilies`, …), reusing `systemd/skyg-linux-tracker.service` rather than diverging
|
||||
- config written to `/etc/skyg-linux-tracker.toml`, the default path the app already reads, so the CLI and the service always agree
|
||||
- **H5** CLI install (required): `environment.systemPackages = [ cfg.package ]`, plain binary, no wrapper (DEC-10). Mint tokens with `sudo -u skyg-linux-tracker slinuxm token create <name>`; the module's NixOS notes and the README show this exact command. The root guard in `slinuxm` (token commands refuse to run as root against another user's DB and print the command above) is implemented here as a small change in the CLI code.
|
||||
- **H6** Firewall: `openFirewall` opens the port globally. Also support an interface-scoped option (`networking.firewall.interfaces.<if>.allowedTCPPorts`), which is the recommended LAN setup. Assert at eval time that `bind` non-loopback is accompanied by auth enabled.
|
||||
- **H7** README NixOS section: flake input, minimal config, token workflow (`sudo -u skyg-linux-tracker slinuxm token create <name>`), the exposure model (loopback + Tailscale or TLS proxy recommended, since bearer tokens over plain HTTP are readable on a LAN), `allowedHosts` for `bind = 0.0.0.0`.
|
||||
- **H8** NixOS VM test (`nix/tests/`):
|
||||
1. service starts and `curl :1984/healthz` returns 200 unauthenticated (a second case with TLS enabled and a test cert)
|
||||
2. `/api/v1/systemd/units` returns 401 without a token
|
||||
3. `sudo -u skyg-linux-tracker slinuxm token create t` prints a token, and the same request with it returns 200
|
||||
4. `/mcp` initialize and tools/list work with the token
|
||||
5. `slinuxm token revoke t` (same `sudo -u` form) makes the same request return 401 without a restart
|
||||
6. bad Origin on `/mcp` returns 403
|
||||
|
||||
## Done when
|
||||
|
||||
- `nix build .#default` produces `bin/slinuxm`, and `ldd` shows only libc and libsystemd (plus deps). No openssl.
|
||||
- `nix flake check` passes, including the VM test (H8).
|
||||
- On a NixOS host, enabling the module with `port = 1984` exposes `:1984` as described, and `slinuxm token create` works from a normal login shell.
|
||||
|
||||
## Notes
|
||||
|
||||
- Port 1984 is also the binary default, so the module just passes it through.
|
||||
- Tokens are printed once and never stored (DEC-11). Declarative/hash-imported tokens and activation-time `bootstrapTokens` are out of scope for v1 are not offered.
|
||||
- The module must not put secrets in the generated TOML. Anything sensitive goes through `environmentFile`.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created from design discussion.
|
||||
@@ -1,44 +0,0 @@
|
||||
# WS-I — Native TLS
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done |
|
||||
| Owner | — |
|
||||
| Phase | 4 (single track, after P3, before WS-H) |
|
||||
| Depends on | P3 |
|
||||
| Blocks | WS-H (the NixOS module exposes the TLS options) |
|
||||
| Owned files | `src/tls.rs`, `src/server.rs` (serve path only), `src/config.rs` (`server.tls` keys), `config.example.toml` (tls keys), `Cargo.toml` (tls deps, by agreed exception), `tests/tls.rs`, `README.md` (TLS section) |
|
||||
|
||||
## Goal
|
||||
|
||||
Serve REST and `/mcp` over HTTPS with certificates the operator provides, so bearer tokens are not readable on the LAN. No openssl.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **T1** Config: `server.tls.enabled` (default false), `server.tls.cert_file`, `server.tls.key_file`. Validation: enabled requires both paths, and both files must be readable at startup with a clear error. Document each key and its env var in `config.example.toml`.
|
||||
- **T2** Serve over rustls. Pick the integration that keeps openssl out (`axum-server` with `tls-rustls`, or `tokio-rustls` with hyper-util). Pin the crypto provider so only one is linked. Cargo.toml change is a small separate commit.
|
||||
- **T3** Reload certificate and key on SIGHUP without dropping connections. A bad new cert keeps the old one and logs an error.
|
||||
- **T4** MCP allowlists: when TLS is on, `allowed_origins` default to `https://…`. `allowed_hosts` is unchanged.
|
||||
- **T5** Startup warning when `bind` is non-loopback and TLS is off. Do not refuse.
|
||||
- **T6** Tests: generate a self-signed cert in the test (dev-dependency such as `rcgen`). Cover HTTPS `/healthz`, 401 and 200 with a token over TLS, plain HTTP to the TLS port failing, SIGHUP reload serving the new cert, bad cert files failing startup, and graceful shutdown still within its bound.
|
||||
- **T7** README TLS section, with a self-signed example and a note on ACME or sops certificate paths.
|
||||
- **T8** Live check: `curl --cacert` against the running server, and one `/mcp` initialize over HTTPS.
|
||||
|
||||
## Done when
|
||||
|
||||
- `server.tls.enabled = true` serves HTTPS, and `cargo tree -i openssl` is still empty.
|
||||
- Replacing the cert files and sending SIGHUP changes the served certificate without a restart.
|
||||
- Clippy, fmt and tests are clean, and the T8 live check passes.
|
||||
|
||||
## Notes
|
||||
|
||||
- **TLS is optional (user requirement, 2026-10-16).** `server.tls.enabled` defaults to `false`. With it off the server behaves exactly as before: plain HTTP, no cert or key files read, MCP origins stay `http://`. It is configurable by file, env (`SKYG_SERVER__TLS__*`) and shown by `--print-config`. Existing tests pass unchanged with the default config.
|
||||
- DEC-12 holds the rationale. The NixOS module (WS-H) passes certificate paths through systemd `LoadCredential` so the service user never needs read access to the original key file.
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-16: Card created from design discussion.
|
||||
- 2026-10-16: Implemented on `ws-i/tls`, T1-T8 done. **TLS is optional, default off** (user requirement): with `server.tls.enabled = false` the plain path is unchanged, the cert/key paths are ignored and never read, no rustls code runs, no provider is built, MCP origins stay `http://`; env (`SKYG_SERVER__TLS__*`) and `--print-config` cover the block. Design: `src/tls.rs` uses `tokio-rustls` + `hyper-util` (auto builder, HTTP/1.1 ALPN) with an accept loop and a `ReloadableCert` (`ResolvesServerCert` behind an RwLock) so SIGHUP swaps the cert for new handshakes without touching live connections; a bad pair logs an error and keeps the old one. The `ring` provider is passed explicitly to `ServerConfig::builder_with_provider`; no process-wide default is installed (aws-lc-rs was already in the tree via reqwest/OTLP; this adds no new provider or openssl). Cargo.toml: rustls, tokio-rustls, hyper-util (separate commit), rcgen dev-dependency. Shutdown: accept stops, each connection gets `graceful_shutdown`, bounded by the existing 10s drain (test: SIGTERM with an idle keep-alive and an open SSE stream over TLS exits 0). T5 warning is logged only when TLS is off and bind is non-loopback. Tests: 3 new unit tests (config validation, env, origins) and 8 in `tests/tls.rs`. Live check (debug binary, openssl-generated certs, curl): healthz, 401/200 REST, MCP initialize over HTTPS, plain HTTP rejected, SIGHUP changed the served fingerprint, a junk cert + SIGHUP kept the rotated one, SIGTERM exit 0.
|
||||
- 2026-10-16: Review fixes. TLS listener bounded by a semaphore (`tls::Limits::max_conns`, default 1024; at the cap accepting pauses) and a 30s hyper `header_read_timeout` (covers post-handshake silence and idle keep-alive), accept-error warnings rate-limited to one per 10s, HTTP/1.1 only. Note: the auto builder's `serve_connection_with_upgrades` sniffs the protocol before hyper starts, which defeats the header timeout, so the TLS path uses `serve_connection` (no upgrades; none are used). A SIGHUP handler is now installed at the top of `serve` on both paths, so SIGHUP never kills the process; with TLS off it only logs. Cert and key are read separately on reload: rotation tooling must send SIGHUP after BOTH files are in place (a mismatch keeps the old pair; fix the files and send HUP again). Intermediates must be in the `cert_file` chain. Pre-existing and out of scope: the plain-HTTP path has no connection cap or header timeout either (axum::serve defaults), the same exhaustion exposure it had before WS-I. New tests: silent-connection header timeout, connection cap, SIGHUP with TLS off, key/cert mismatch on SIGHUP.
|
||||
Reference in new issue
Block a user