Fold Phase 5 into docs
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
6be774e98b
commit
f5e5f752e3
17 files changed
+71
-43
No files matched your search
@@ -8,8 +8,8 @@ Canonical guidance for AI coding agents in this repo (no CLAUDE.md; this file is
|
||||
|
||||
## Repo map
|
||||
|
||||
- `src/`: `sources/` (the only code touching D-Bus, journald, Docker; traits + `fake.rs`), `api/` (REST), `mcp/`, `telemetry/`, `auth/`, `config.rs`, `server.rs`, `tls.rs`, `state.rs`, `error.rs`, `db.rs`
|
||||
- `tests/`, `examples/`, `migrations/`, `dev/otelcol.yaml`, `systemd/` (example unit), `flake.nix` + `nix/` (package, NixOS module, VM test), `config.example.toml`
|
||||
- `src/`: `sources/` (the only code touching D-Bus, journald, Docker; traits + `fake.rs`), `api/` (REST), `mcp/`, `telemetry/`, `peers/` (consolidator: registry, health, the one outbound HTTP client), `openapi.rs` (generated spec), `cli.rs`, `auth/`, `config.rs`, `server.rs`, `tls.rs`, `state.rs`, `error.rs`, `db.rs`
|
||||
- `tests/`, `docs/openapi.json` (generated; regenerate with `cargo run -- openapi --peers > docs/openapi.json`), `examples/`, `migrations/`, `dev/otelcol.yaml`, `systemd/` (example unit), `flake.nix` + `nix/` (package, NixOS module, VM test), `config.example.toml`
|
||||
- [`ARCHITECTURE.md`](ARCHITECTURE.md): design, decisions (DEC-n), gotchas, verification checklist. Read before structural changes.
|
||||
- [`TODO.md`](TODO.md): all work tracking. [`plan/`](plan/README.md): plans for the next big phase only. [`docs/`](docs/README.md): long-form docs, archived workstream records.
|
||||
- [`README.md`](README.md): user-facing install and usage.
|
||||
@@ -23,7 +23,7 @@ All checks go through one runner, `dev/dev-test.nu`. `devenv shell -- dev-test
|
||||
```sh
|
||||
devenv shell -- dev-test lint # cargo fmt --check, clippy -D warnings, cargo tree -i openssl (empty)
|
||||
devenv shell -- dev-test unit # cargo test --lib --bins
|
||||
devenv shell -- dev-test integration [filter] [--nocapture] # cargo test --test '*' (plain, tls, integration, binary_smoke, peers)
|
||||
devenv shell -- dev-test integration [filter] [--nocapture] # cargo test --test '*' (plain, tls, integration, binary_smoke, peers, peers_config, peers_registry, mcp_peers, openapi)
|
||||
devenv shell -- dev-test vm [vm|peers] # NixOS VM test (slow, needs /dev/kvm)
|
||||
devenv shell -- dev-test all # lint, unit, integration; stops at the first failure
|
||||
devenv shell -- dev-test ci # all plus the vm test
|
||||
|
||||
+38
-14
@@ -2,7 +2,7 @@
|
||||
|
||||
skyg-linux-tracker (binary and CLI: `slinuxm`) is a read-only Linux system monitor in Rust, shipped as a single binary. It exposes systemd state, journald logs and Docker container state/logs over three surfaces that share one core: a **REST API**, an **MCP server** (Streamable HTTP) and **OpenTelemetry export**. Everything is read live from the source on every request. Nothing is collected or buffered, except a small SQLite database holding hashed API tokens.
|
||||
|
||||
User-facing usage is in [`README.md`](README.md). Work tracking is in [`TODO.md`](TODO.md). Per-workstream design logs from the original build are archived in [`docs/workstreams/`](docs/workstreams/).
|
||||
User-facing usage is in [`README.md`](README.md). Work tracking is in [`TODO.md`](TODO.md). Per-workstream design logs from the original build and Phase 5 are archived in [`docs/workstreams/`](docs/workstreams/).
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -26,6 +26,8 @@ User-facing usage is in [`README.md`](README.md). Work tracking is in [`TODO.md`
|
||||
| Docker | `bollard` (unix socket only) | Async Docker/Podman API; `list_containers`, `inspect_container` (health), log streams |
|
||||
| OTel | `opentelemetry`, `opentelemetry_sdk`, `opentelemetry-otlp` 0.33, `tracing-opentelemetry` | One OTLP config (endpoint, protocol, headers) drives all three signals. Metrics and logs are Stable, traces Beta |
|
||||
| Auth DB | `sqlx` (sqlite, bundled) with **runtime** queries | Async, pure-Rust bundled SQLite, no build-time database (DEC-3) |
|
||||
| Peer client | `reqwest` 0.13 (`rustls-no-provider`, ring passed in) + `webpki-roots` | Outbound calls to peers; no openssl, nothing installed process-wide (DEC-14) |
|
||||
| OpenAPI | `utoipa` 6 + `schemars` | Generated REST and MCP description (DEC-15) |
|
||||
| Config | `figment` (TOML + env) + `clap` | Layered config with clear precedence |
|
||||
|
||||
Rust edition 2021; release profile uses LTO and `strip`. Cargo.lock is committed. The only dynamic dependencies are libc, libm, libgcc_s and libsystemd (check with `ldd`).
|
||||
@@ -41,10 +43,13 @@ migrations/0001_tokens.sql # embedded sqlx migration
|
||||
systemd/skyg-linux-tracker.service # hardened example unit
|
||||
dev/otelcol.yaml # local collector with debug exporter (`devenv up`)
|
||||
examples/ # systemd_dump, journal_tail, docker_ps: run one source against the live host
|
||||
tests/ # integration.rs, tls.rs, plain.rs, binary_smoke.rs, common/
|
||||
docs/openapi.json # generated OpenAPI 3.1 doc (with peers), guarded by a drift test
|
||||
tests/ # integration.rs, tls.rs, plain.rs, binary_smoke.rs, peers.rs, peers_config.rs, peers_registry.rs, mcp_peers.rs, openapi.rs, common/
|
||||
src/
|
||||
main.rs # clap CLI: serve | token create|list|revoke, --print-config
|
||||
main.rs # clap CLI: serve | token create|list|revoke | peer list|check | openapi [--peers], --print-config
|
||||
lib.rs
|
||||
cli.rs # `slinuxm openapi`
|
||||
openapi.rs # builds the OpenAPI document (route and CLI share it)
|
||||
config.rs # figment layering + validation
|
||||
error.rs # AppError -> HTTP status + JSON body, and -> MCP ErrorData
|
||||
state.rs # AppState: sources (Arc<dyn ...>), optional DB pool, config, CancellationToken
|
||||
@@ -56,16 +61,17 @@ src/
|
||||
mod.rs # traits + shared DTOs (UnitSummary, TimerInfo, JournalEntry, ContainerSummary, ...)
|
||||
systemd.rs, journal.rs, docker.rs # real implementations
|
||||
fake.rs # in-memory fakes used by handler and tool tests
|
||||
api/ # REST layer: systemd.rs, journal.rs, docker.rs, mod.rs
|
||||
peers/ # consolidator: config.rs, secrets.rs (token loader), registry.rs, health.rs, client.rs (reqwest transport), proxy.rs, transport.rs (trait), types.rs, error.rs, cli.rs, testing.rs (fakes)
|
||||
api/ # REST layer: systemd.rs, journal.rs, docker.rs, ping.rs, peers.rs, mod.rs
|
||||
mcp/ # TrackerService (mod.rs), prompts.rs, resources.rs
|
||||
telemetry/ # mod.rs (providers, guard), metrics_export.rs, logs_export.rs
|
||||
telemetry/ # mod.rs (providers, guard, peer request span), metrics_export.rs, logs_export.rs
|
||||
```
|
||||
|
||||
The key structural decision: **`sources/` is the only place that talks to D-Bus, journald or Docker.** `api/`, `mcp/` and `telemetry/` are thin projections over it, which makes "MCP and REST expose the same data" true by construction. Sources are traits held as `Arc<dyn ...>` in `AppState` (DEC-2), so every handler and tool test runs against fakes without systemd or Docker. `server.rs` is the only place the surfaces meet.
|
||||
The key structural decision: **`sources/` is the only place that talks to D-Bus, journald or Docker.** `api/`, `mcp/` and `telemetry/` are thin projections over it, which makes "MCP and REST expose the same data" true by construction. `peers/` is the one outbound HTTP client; the registry exists only when `[peers] enabled = true`, and REST and MCP share its proxy functions. Sources are traits held as `Arc<dyn ...>` in `AppState` (DEC-2), so every handler and tool test runs against fakes without systemd or Docker. `server.rs` is the only place the surfaces meet.
|
||||
|
||||
## Configuration
|
||||
|
||||
See [`config.example.toml`](config.example.toml); every value shown is the default. Sections: `[server]` (`bind` 127.0.0.1, `port` 1984, `allowed_hosts`, `allowed_origins`, `[server.tls]`), `[auth]` (`enabled`, `db_path`), `[otel]` (`enabled`, `endpoint`, `protocol`, `service_name`, `export_unit_metrics`, `export_logs`, `metrics_interval_secs`, `[otel.headers]`, `[otel.logs]`, `[otel.metrics]` allowlists), `[sources]` (`docker_socket`, `journal_namespace`) and `[limits]` (`max_lines`, `max_tail`, `max_follow_secs`).
|
||||
See [`config.example.toml`](config.example.toml); every value shown is the default. Sections: `[server]` (`bind` 127.0.0.1, `port` 1984, `allowed_hosts`, `allowed_origins`, `[server.tls]`), `[auth]` (`enabled`, `db_path`), `[otel]` (`enabled`, `endpoint`, `protocol`, `service_name`, `export_unit_metrics`, `export_logs`, `metrics_interval_secs`, `[otel.headers]`, `[otel.logs]`, `[otel.metrics]` allowlists), `[sources]` (`docker_socket`, `journal_namespace`) and `[limits]` (`max_lines`, `max_tail`, `max_follow_secs`) and `[peers]` (off by default; see Consolidator).
|
||||
|
||||
Precedence: defaults < config file (`--config`, default `/etc/skyg-linux-tracker.toml`) < `SKYG_*` env (nesting with `__`, e.g. `SKYG_SERVER__PORT`) < CLI flags. `slinuxm --print-config` prints the effective config with secrets redacted. Validation rejects `auth.enabled = false` with a non-loopback `bind`, `port = 0`, and incomplete TLS settings.
|
||||
|
||||
@@ -89,6 +95,10 @@ All under `/api/v1`, GET only, behind the auth middleware when enabled. Routes u
|
||||
| `GET /api/v1/docker/ps` | `ps()` |
|
||||
| `GET /api/v1/docker/containers/{name}` | `container_status()` |
|
||||
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` (JSON, or SSE events `stdout`/`stderr`) | `logs()` |
|
||||
| `GET /api/v1/ping` | authenticated liveness, used by a consolidator's API check |
|
||||
| `GET /api/v1/openapi.json` | generated OpenAPI 3.1 document; peer paths and tools only when peers are enabled |
|
||||
| `GET /api/v1/peers`, `GET /api/v1/peers/{peer}` | peer status (only with `peers.enabled`) |
|
||||
| `GET /api/v1/peers/{peer}/{*path}` | allowlisted GET pass-through to the peer; the response carries `x-slinuxm-peer` (only with `peers.enabled`) |
|
||||
| `GET /healthz` | public liveness, `{"status":"ok","version":...}` |
|
||||
|
||||
SSE streams (`axum::response::Sse` with keep-alive) read from the mpsc channels of `sources/` and end on client disconnect or shutdown.
|
||||
@@ -97,8 +107,9 @@ SSE streams (`axum::response::Sse` with keep-alive) read from the mpsc channels
|
||||
|
||||
`rmcp`'s `StreamableHttpService` is a Tower service nested at `/mcp` on the protected router (`mcp::service(state)`). One per-session `TrackerService` shares `AppState`. Auth failures are HTTP 401 with `WWW-Authenticate: Bearer` (DEC-4), the same middleware as REST.
|
||||
|
||||
Eight tools, each a thin wrapper over `sources/` with `schemars` parameter schemas: `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 }`.
|
||||
Eight tools (ten with `peers.enabled`, below), each a thin wrapper over `sources/` with `schemars` parameter schemas: `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 }`.
|
||||
|
||||
- With `peers.enabled` there are ten: `list_peers` and `get_peer { name }` are added, each of the eight takes an optional `peer` argument that reads from that peer through this instance, and the instructions gain a peers paragraph. The tool-list snapshot test guards both tables.
|
||||
- `tail_journal` is a bounded follow: it clamps `seconds` to `limits.max_follow_secs`, stops at an entry cap and returns what it collected. There are no infinite MCP streams.
|
||||
- Log tools return `{entries, truncated, note}` capped at 256 KiB. Source errors come back as `CallToolResult` errors with an actionable message. Log content is documented as untrusted data.
|
||||
- Agent context: `ServerHandler` **instructions** (start with failed units or unhealthy containers, then pull logs, use timers to explain jobs), rich tool descriptions (systemd states, health states, journal priorities), **prompts** `diagnose_unit { name }` and `container_health_report`, **resources** `systemd://units/failed` and `docker://containers` plus templates `systemd://unit/{name}` and `docker://container/{name}`. Resources are list/read, resolved live, not subscribable (DEC-5).
|
||||
@@ -141,10 +152,19 @@ One OTLP exporter config (grpc or http/protobuf, optional headers) drives three
|
||||
| `docker.container.restarts` | `{restart}` | `container.name` |
|
||||
|
||||
Scope: an empty `otel.metrics.units` exports `*.service` and `*.timer` only (DEC-7); a non-empty list is a glob allowlist. An empty `otel.metrics.containers` exports all containers.
|
||||
3. **Logs**: when `otel.export_logs = true`, `logs_export.rs` runs a journal follow plus per-container docker follow tasks, reconciled against the Docker events stream (start/die/destroy) with backoff, so containers that come and go are tracked. Journal priority maps to OTel severity (emerg/alert/crit to FATAL, err ERROR, warning WARN, notice/info INFO, debug DEBUG); docker stderr is WARN, stdout INFO. Attributes: `systemd.unit`, `log.syslog.identifier`, `process.pid`, `container.name`, `log.iostream`. `otel.logs.journal_units` / `docker_containers` narrow the scope (empty = all).
|
||||
3. **Peer gauges** (only with `peers.enabled`): `peer.up` (`peer.name`, `peer.check`), `peer.check.duration_seconds`, `peer.last_change_timestamp_seconds` and `peer.api.auth_ok` (`peer.name`). They read the in-memory registry snapshot at each collection, so peers added or removed by a SIGHUP reload appear without re-registering; disabled peers are left out. Outbound peer requests run in a `peer.request` span exported as a client span (`otel.kind = client`) and carry `traceparent`. Metrics need `otel.enabled` and `otel.export_unit_metrics`.
|
||||
4. **Logs**: when `otel.export_logs = true`, `logs_export.rs` runs a journal follow plus per-container docker follow tasks, reconciled against the Docker events stream (start/die/destroy) with backoff, so containers that come and go are tracked. Journal priority maps to OTel severity (emerg/alert/crit to FATAL, err ERROR, warning WARN, notice/info INFO, debug DEBUG); docker stderr is WARN, stdout INFO. Attributes: `systemd.unit`, `log.syslog.identifier`, `process.pid`, `container.name`, `log.iostream`. `otel.logs.journal_units` / `docker_containers` narrow the scope (empty = all).
|
||||
|
||||
Shutdown cancels the tasks and flushes all providers.
|
||||
|
||||
## Consolidator (`peers/`)
|
||||
|
||||
Opt-in (`[peers] enabled = true`): an instance reads other `slinuxm` instances declared in config. Without it there is no registry, no background task, no peer route or gauge, and 8 MCP tools. The registry keeps peer status in memory; two checks per peer (TCP connect, authenticated `GET /api/v1/ping`) run in background loops and SIGHUP reloads the peer list in place. Operator docs: [`docs/consolidator.md`](docs/consolidator.md). Decisions: DEC-13, DEC-14.
|
||||
|
||||
## OpenAPI (`openapi.rs`)
|
||||
|
||||
`openapi::document(peers)` is the single builder behind `GET /api/v1/openapi.json` and `slinuxm openapi [--peers]`. `docs/openapi.json` is the `--peers` output. See DEC-15.
|
||||
|
||||
## Auth and state (`auth/`, `db.rs`)
|
||||
|
||||
- SQLite at `auth.db_path` (default `/var/lib/skyg-linux-tracker/db.sqlite`). A server-created directory is 0700 and the file 0600; an existing directory is never chmod'd (a group/world-accessible one only logs a warning). WAL mode plus `busy_timeout`, because the token CLI and the server share the DB. Under systemd, `StateDirectory=` creates the directory with the right owner.
|
||||
@@ -178,7 +198,8 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
|
||||
| DEC-11 | No declarative or bootstrap tokens in v1 | Decided 2026-10-16 |
|
||||
| DEC-12 | TLS terminated in-process with rustls | Decided 2026-10-16 |
|
||||
| DEC-13 | Outbound peer credentials are external files | Decided 2026-10-19 |
|
||||
| DEC-14 | Consolidator (peers) design | Decided 2026-10-19 |
|
||||
| DEC-14 | Consolidator (peers) design | Decided 2026-10-19, implemented 2026-10-20 |
|
||||
| DEC-15 | Generated OpenAPI document | Decided 2026-10-20 |
|
||||
|
||||
- **DEC-1 name.** The plan used three names (repo `linux-system-monitor`, service `skyg-linux-tracker`, CLI `skyg`). The binary, CLI and `[[bin]]` are `slinuxm`; tokens use the `slinuxm_` prefix. Unchanged: product name `skyg-linux-tracker`, unit `skyg-linux-tracker.service`, state dir `/var/lib/skyg-linux-tracker`, config `/etc/skyg-linux-tracker.toml`, env prefix `SKYG_`.
|
||||
- **DEC-2 traits and fakes.** `SystemdSource`, `JournalSource`, `DockerSource` live in `src/sources/mod.rs`, fakes in `src/sources/fake.rs`, `AppState` holds `Arc<dyn ...>` (via `async-trait`). Surfaces can be built and tested without systemd or Docker, at the cost of about 100 extra lines.
|
||||
@@ -193,8 +214,11 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
|
||||
- **DEC-11 tokens.** Inbound tokens only (outbound: DEC-13). Printed once, never stored in plaintext; no `bootstrapTokens` option and no import of pre-hashed tokens.
|
||||
- **DEC-12 TLS.** Bearer tokens over plain HTTP are readable on a LAN, which is the intended deployment, so TLS is native (`server.tls.*`, SIGHUP reload so ACME/sops rotation needs no restart). A reverse proxy still works. Off by default; nothing changes when it is off.
|
||||
|
||||
- **DEC-13 outbound credentials.** To call a peer the consolidator must replay a plaintext bearer token, so DEC-11's hash-only storage cannot apply. `slinuxm` never persists a peer token: config holds only a `token_file` path (on NixOS an agenix path delivered via `LoadCredential`), read into memory with redacted `Debug` and re-read on each check so rotation needs no restart. It does not protect against root on the consolidator; mitigate with one read-only token per consolidator. Full text: `plan/phase-5-consolidator/decisions.md`.
|
||||
- **DEC-14 consolidator design.** Peers are declarative (config / NixOS module, SIGHUP reload, no DB table). Two checks per peer: TCP connect and an authenticated `GET /api/v1/ping` (401 reports `api.up=true, auth=rejected`; older peers fall back to `/healthz`, `auth=unknown`). TCP 10s/3s, API 30s/5s, two failures to flip down, state in memory. REST: status plus a GET-only allowlisted pass-through under `/api/v1/peers/{peer}/...`. MCP: optional `peer` argument plus `list_peers`/`get_peer` (10 tools only when `peers.enabled`). No aggregation and no chaining in v1. Peer failures reuse `Unavailable`; a peer's 401/403 is never surfaced as `Unauthorized`. Four OTel gauges. SSRF: config-only URLs, no redirects, `deny_cidrs` at connect time, webpki roots plus optional `ca_file`, no skip-verify, plain http to non-loopback needs `allow_plain_http`. Any valid inbound token may read peer data (no scopes). HTTP client is reqwest with rustls/ring unless openssl appears (decided in B1).
|
||||
- **DEC-13 outbound credentials.** To call a peer the consolidator must replay a plaintext bearer token, so DEC-11's hash-only storage cannot apply. `slinuxm` never persists a peer token: config holds only a `token_file` path (on NixOS an agenix path delivered via `LoadCredential`), read into memory with redacted `Debug` and re-read on each check so rotation needs no restart. It does not protect against root on the consolidator; mitigate with one read-only token per consolidator. Full text: [`docs/workstreams/P5-consolidator/decisions.md`](docs/workstreams/P5-consolidator/decisions.md). There is one token loader, `peers::secrets::load_token`, used by startup validation, `peer check` and every request: it accepts a regular file only, requires owner-only permissions (with an exemption for `$CREDENTIALS_DIRECTORY`) and rejects CR, LF and NUL so a token cannot split a header.
|
||||
- **DEC-14 consolidator design.** Peers are declarative (config / NixOS module, SIGHUP reload, no DB table). Two checks per peer: TCP connect and an authenticated `GET /api/v1/ping` (401 reports `api.up=true, auth=rejected`; older peers fall back to `/healthz`, `auth=unknown`). TCP 10s/3s, API 30s/5s, two failures to flip down, state in memory. REST: status plus a GET-only allowlisted pass-through under `/api/v1/peers/{peer}/...`. MCP: optional `peer` argument plus `list_peers`/`get_peer` (10 tools only when `peers.enabled`). No aggregation and no chaining in v1. Peer failures reuse `Unavailable`; a peer's 401/403 is never surfaced as `Unauthorized`. Four OTel gauges. SSRF: config-only URLs, no redirects, `deny_cidrs` at connect time, webpki roots plus optional `ca_file`, no skip-verify, plain http to non-loopback needs `allow_plain_http`. Any valid inbound token may read peer data (no scopes).
|
||||
- **HTTP client outcome.** `reqwest` 0.13 with `rustls-no-provider`; the ring provider and webpki roots are passed to the client explicitly, so nothing is installed process-wide and `cargo tree -i openssl` stays empty. Redirects are off and the system proxy is ignored.
|
||||
- **SSRF at connect time.** The host is resolved once, every address is checked against `deny_cidrs` after `to_canonical()` (so `::ffff:169.254.169.254` matches the IPv4 range), one denied address refuses the whole name, and the checked set is pinned with `resolve_to_addrs`, which closes DNS rebinding. The same `deny_networks` / `denied` code runs at config validation and at connect time. The default `deny_cidrs` covers both families (`169.254.0.0/16`, `0.0.0.0/8`, `fe80::/10`, `::/128`, `fd00:ec2::254/128`); private LAN ranges stay allowed.
|
||||
- **DEC-15 generated OpenAPI.** The document is generated so it cannot drift from the code. REST paths are declared on the handlers with `#[utoipa::path]` (utoipa 6, OpenAPI 3.1). DTO schemas are reflected from the existing `schemars::JsonSchema` derives through a bridge in `openapi.rs`, so one derive serves MCP and OpenAPI; only payloads that exist as `serde_json` literals (error body, health) are written by hand and compared with real output in tests. MCP is not REST, so the tools go in the `x-mcp-tools` extension, built from the tool router's own schemas. Peer paths and the two peer tools appear only when peers are enabled. `tests/openapi.rs` is the drift guard: every router route must be documented, `x-mcp-tools` must match `tools/list`, and `docs/openapi.json` must equal `slinuxm openapi --peers` (regenerate with `cargo run -- openapi --peers > docs/openapi.json`). The route is authenticated like the rest of `/api/v1`.
|
||||
|
||||
## Design notes and gotchas
|
||||
|
||||
@@ -204,7 +228,7 @@ Corrections found in the original design review and still worth knowing when cha
|
||||
- **`ExecMainStatus` and `NRestarts` are `Service` properties** (R2), absent for timers, sockets and mounts, hence `Option` DTO fields.
|
||||
- **`/healthz` must stay public** (R3). The auth layer sits on the protected router only, merged with a public router.
|
||||
- **axum 0.8 routes use `/{name}`** (R4). The old `:name` syntax panics at startup.
|
||||
- **There are 8 MCP tools** (R5). Adding a ninth is a deliberate change; the tool-list snapshot test catches accidental ones.
|
||||
- **There are 8 MCP tools, or 10 with `peers.enabled`** (R5). Changing the count is a deliberate change; the tool-list snapshot test guards both tables.
|
||||
- **Metric allowlists and `otel.headers` are config keys** (R6) and documented in `config.example.toml`.
|
||||
- **No openssl** (R7). Gate: `cargo tree -i openssl` prints nothing.
|
||||
- **Runtime sqlx queries** (R8, DEC-3).
|
||||
@@ -218,7 +242,7 @@ Corrections found in the original design review and still worth knowing when cha
|
||||
|
||||
## Verification
|
||||
|
||||
A release is verified by hand on a real host with these six checks (last full run: minipc1, 2026-10-19; #5 is still open as I6-5 in [`TODO.md`](TODO.md)).
|
||||
A release is verified by hand on a real host with these six checks (last full run: minipc1, 2026-10-19; #5 is still open as I6-5 in [`TODO.md`](TODO.md)). With peers enabled, also run two instances against each other, cross-check a real peer, and confirm the peer gauges in the collector; the last two are still open (M6 in `TODO.md`).
|
||||
|
||||
1. `cargo build` inside `devenv shell`; unit tests for config precedence and DTO mapping.
|
||||
2. Run locally: `cargo run -- serve`; create a token with `cargo run -- token create <name>`.
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
The single place for work tracking. **Tick boxes here only.** Design lives in [`ARCHITECTURE.md`](ARCHITECTURE.md). Archived workstream design notes and logs are in [`docs/workstreams/`](docs/workstreams/). Plans for the next big thing go in [`plan/`](plan/README.md).
|
||||
|
||||
_Last updated: 2026-10-19_
|
||||
_Last updated: 2026-10-20_
|
||||
|
||||
## Status
|
||||
|
||||
The build is functionally complete and merged to `main`. REST, MCP, OTel, TLS and the NixOS module are implemented. Verification #1–#4 and #6 passed live on minipc1 (2026-10-19). The WS-H nix gate passed on 2026-10-19. Phase 5 (consolidator) is planned and starting; everything else open is in the Backlog.
|
||||
The build is functionally complete and merged to `main`. REST, MCP, OTel, TLS and the NixOS module are implemented. Verification #1–#4 and #6 passed live on minipc1 (2026-10-19). The WS-H nix gate passed on 2026-10-19. Phase 5 (consolidator, optional peers) and the generated OpenAPI doc are merged; the Phase 5 record is archived in [`docs/workstreams/P5-consolidator/`](docs/workstreams/P5-consolidator/README.md). Everything open is in the Backlog.
|
||||
|
||||
| Milestone | Gate | Status |
|
||||
|---|---|---|
|
||||
@@ -16,25 +16,7 @@ The build is functionally complete and merged to `main`. REST, MCP, OTel, TLS an
|
||||
| M3 Release | Verification #1–#6 pass. Unit file and README shipped. | Partial: #1–#4 and #6 pass, unit installed on minipc1; needs #5 (I6-5) |
|
||||
| M4 NixOS | `nix flake check` passes including the VM test. `:1984` serves and a token is minted with the system-installed CLI. | ✅ 2026-10-19: `nix build` and `nix flake check` (incl. VM test, plain + TLS) pass; see [WS-H log](docs/workstreams/WS-H-nixos.md#log) |
|
||||
| M5 TLS | HTTPS serves REST and `/mcp`, SIGHUP reloads certs, no openssl. | Done |
|
||||
|
||||
## Phase 5: Consolidator (in progress)
|
||||
|
||||
Plan: [`plan/phase-5-consolidator/`](plan/phase-5-consolidator/README.md). Decisions accepted 2026-10-19 (DEC-13, DEC-14). Work loop: `.claude/skills/phase-loop`. Task text lives in each `ws-*.md`; tick here only.
|
||||
|
||||
| Milestone | Gate | Status |
|
||||
|---|---|---|
|
||||
| M6 Consolidator | Phase 5 exit criteria; peer-less instance unchanged (8 MCP tools); `nix flake check` incl. the peers VM test | Not started |
|
||||
|
||||
- [ ] **WS-T** tests: T1 T2 T3 T4 T5 T6 (peers.nix written) · [x] T7 `dev/test.nu` runner
|
||||
- [x] T1..T6 written in `nix/tests/peers.nix`; promoted to `checks` by F2
|
||||
- [ ] **WS-A** config: [x] A0 stubs · [x] A1 config · [x] A2 validation · [x] A3 secrets loader · [x] A4 `peer` CLI
|
||||
- [ ] **WS-B** registry: [x] B1 client · [x] B2 health loops · [x] B3 status model · [x] B4 SIGHUP reload · [x] B5 transport + SSRF guard
|
||||
- [ ] **WS-C** REST: [x] C1 status routes · [x] C2 pass-through · [x] C3 `x-slinuxm-peer` header · [x] C4 error mapping
|
||||
- [ ] **WS-D** MCP: [x] D1 `peer` arg · [x] D2 `list_peers`/`get_peer` · [x] D3 instructions
|
||||
- [ ] **WS-E** telemetry: [x] E1 gauges · [x] E2 client spans and propagation
|
||||
- [x] **WS-F** NixOS and docs: [x] F1 module · [x] F2 promote VM test · [x] F3 `tests/peers.rs` · [x] F4 README, `docs/consolidator.md`
|
||||
- [x] **WS-G** (stand-alone) generated OpenAPI doc for REST and MCP: [x] G1 REST spec · [x] G2 MCP `x-mcp-tools` · [x] G3 `/api/v1/openapi.json` + `slinuxm openapi` · [x] G4 drift guard, `docs/openapi.json`
|
||||
- [ ] **Final review** and fold-in: move `plan/phase-5-consolidator` to `docs/workstreams/`, collapse into the Completed table, add Backlog entries (D8 fleet aggregation, scoped tokens, health history, runtime peer management)
|
||||
| M6 Consolidator | Phase 5 exit criteria; peer-less instance unchanged (8 MCP tools); `nix flake check` incl. the peers VM test | Met, except two live checks still open: **P5-1** minipc1 cross-check needs a user-minted token, **P5-2** OTel peer-gauge check via `devenv up` not yet recorded (both in the Backlog) |
|
||||
|
||||
## In progress / Review
|
||||
|
||||
@@ -58,12 +40,24 @@ Parked, not scheduled. Each has a reason. Nothing here blocks the current work.
|
||||
| **F-1** | Cap concurrent follow streams | Security review 2026-10-16; not scheduled |
|
||||
| **F-2** | Bound line and message length | Security review 2026-10-16; not scheduled |
|
||||
| **F-3** | Unit hardening extras | Security review 2026-10-16; needs a clean-host test first |
|
||||
| **P5-1** | minipc1 cross-check of the consolidator against a real peer | Needs a read-only token minted by the user on minipc1; agents never mint tokens on real hosts |
|
||||
| **P5-2** | Record the OTel peer-gauge check (`devenv up`, Verification step 5 with peers) | Not yet run and recorded; no automated test asserts the exported peer metrics end to end |
|
||||
| **D8** | Fleet aggregation (merged views across peers) | Out of scope for v1 (DEC-14: no aggregation, no chaining); needs a design for partial failure and ordering |
|
||||
| **P5-3** | Scoped tokens (per-peer or read-class scopes) | Any valid inbound token may read peer data (DEC-14); scopes need a token schema change and a policy decision |
|
||||
| **P5-4** | Peer health history | State is in memory only by design; history needs storage or an external TSDB, and the OTel gauges already cover it |
|
||||
| **P5-5** | Runtime peer management (add/remove without editing config) | Peers are declarative so no write path or DB table exists (DEC-14); would need a write path against the read-only rule |
|
||||
|
||||
- [ ] **C7** *(nice-to-have)* Smoke test against the Podman socket
|
||||
- [ ] **I6-5** Verification #5 OTel smoke test against a working collector (see the [verification checklist](ARCHITECTURE.md#verification))
|
||||
- [ ] **B-1** Docker log-follow SSE live check
|
||||
- [ ] **B-2** REST, auth and TLS live check against minipc1
|
||||
- [ ] **X-1** *(external)* Fix or investigate `opentelemetry-collector.service` / `var-lib-loki.mount` on minipc1
|
||||
- [ ] **P5-1** minipc1 cross-check: run a consolidator against minipc1 with a read-only token the user mints there (`list_peers`, `get_peer`, one pass-through)
|
||||
- [ ] **P5-2** OTel peer gauges: run `devenv up`, enable `[otel]` with peers, confirm `peer.up`, `peer.api.auth_ok`, `peer.check.duration_seconds`, `peer.last_change_timestamp_seconds` reach the collector, and record the result
|
||||
- [ ] **D8** Fleet aggregation across peers
|
||||
- [ ] **P5-3** Scoped tokens
|
||||
- [ ] **P5-4** Peer health history
|
||||
- [ ] **P5-5** Runtime peer management
|
||||
- [ ] **F-1** Cap concurrent follow streams. Each journal follow, `tail_journal` call or docker follow pins a `spawn_blocking` thread for up to `limits.max_follow_secs`. Add a global semaphore shared by REST and MCP (suggested 16) returning 429/503 when full. A client that stops reading may hold the thread past the deadline (untested); add a write timeout or a hard `tokio::time::timeout` around the producer.
|
||||
- [ ] **F-2** Bound line and message length. Docker `LineSplitter` and journal `MESSAGE` are buffered without limit before the 256 KiB result cap applies. Truncate per line (suggested 64 KiB, with a visible marker) and cap total bytes collected.
|
||||
- [ ] **F-3** Unit hardening: `ProtectKernelLogs`, `ProtectHostname`, `RemoveIPC`, `LimitNOFILE`, `TasksMax`, `MemoryMax`, narrower `RestrictAddressFamilies`, `PrivateUsers` (check journal group access). Test under the hardened unit on a clean host before enabling. Document how the service user gets read access to the TLS key.
|
||||
@@ -85,6 +79,9 @@ Design notes, owned files and logs for each are archived under [`docs/workstream
|
||||
| [P3](docs/workstreams/P3-integration.md) | Integration and hardening | One axum server, negative tests, hardened unit, README; I6 verified on minipc1 (#1–#4, #6) | I1..I6 (I6-5 in Backlog) | 2026-10-19 |
|
||||
| [WS-I](docs/workstreams/WS-I-tls.md) | Native TLS (rustls) | `server.tls.*`, SIGHUP reload, HTTPS tests, live `curl --cacert` check | T1..T8 | merged to `main` |
|
||||
| [WS-H](docs/workstreams/WS-H-nixos.md) | NixOS package, module, VM test | H1..H8 merged (PR #1, 34da657); gate passed 2026-10-19 | H1..H8 | merged; gate passed 2026-10-19 |
|
||||
| [P5](docs/workstreams/P5-consolidator/README.md) | Consolidator: optional peers (WS-T, A..F) | Declarative peers with TCP and API health checks, `/api/v1/peers` status and GET pass-through, `peer` argument and `list_peers`/`get_peer` (10 MCP tools with peers, 8 without), four OTel gauges, NixOS module option, SSRF guard, peers VM test; peer-less instance unchanged | T1..T7, A0..A4, B1..B5, C1..C4, D1..D3, E1..E2, F1..F4 (P5-1, P5-2 in Backlog) | 2026-10-20 |
|
||||
| [WS-G (OpenAPI)](docs/workstreams/WS-G-openapi.md) | Generated OpenAPI 3.1 doc (stand-alone, after P5) | `utoipa` paths plus schemars bridge, `x-mcp-tools`, `GET /api/v1/openapi.json`, `slinuxm openapi [--peers]`, drift test, `docs/openapi.json` | G1..G4 | 2026-10-20 |
|
||||
| [WS-H (final fixes)](docs/workstreams/WS-H-final-fixes.md) | Phase 5 final-review fixes | One token loader, one set of peer helpers, IPv4-mapped deny check, IPv6 `deny_cidrs`, client span kind, flaky test fixes, docs corrections | review items | 2026-10-20 |
|
||||
|
||||
### Done (archive)
|
||||
|
||||
@@ -101,5 +98,8 @@ All ticked. One line per workstream; the full task text is on each card.
|
||||
- **P3** — serve wiring and shutdown (I1); negative tests (I2); systemd unit, verified with `systemd-analyze security --offline` (1.5 OK) and installed as a system unit on minipc1, 2026-10-19 (I3); README (I4); release build, `ldd` clean (I5); manual Verification #1–#4 and #6 on minipc1, 2026-10-19; #5 deferred as I6-5 (I6).
|
||||
- **WS-I** — `server.tls.*` config (T1); rustls with pinned provider (T2); SIGHUP reload (T3); `https://` MCP origins (T4); non-loopback-without-TLS warning (T5); self-signed cert tests (T6); README TLS section (T7); live check (T8).
|
||||
- **WS-H** — `nix/package.nix` (H1); `flake.nix` (H2); module options (H3); service definition (H4); system-wide CLI with root guard (H5); firewall options and eval assertion (H6); README NixOS section (H7); VM test (H8). Gate passed 2026-10-19 (build, flake check, VM test).
|
||||
- **P5** — runner `dev/dev-test.nu` and peers VM test (WS-T); config, validation, secrets loader, `peer` CLI (WS-A); registry, health loops, status model, SIGHUP reload, transport with SSRF guard (WS-B); status routes, pass-through, `x-slinuxm-peer`, error mapping (WS-C); `peer` argument, `list_peers`/`get_peer`, instructions (WS-D); gauges, client spans and propagation (WS-E); NixOS module, promoted VM test, `tests/peers.rs`, README and `docs/consolidator.md` (WS-F).
|
||||
- **WS-G (OpenAPI)** — REST spec (G1); MCP `x-mcp-tools` (G2); route and `slinuxm openapi` (G3); drift guard and `docs/openapi.json` (G4).
|
||||
- **WS-H (final fixes)** — see the [record](docs/workstreams/WS-H-final-fixes.md).
|
||||
|
||||
Early decisions (DEC-1..DEC-8) were accepted before work started; all decisions are recorded in [`ARCHITECTURE.md`](ARCHITECTURE.md#decisions).
|
||||
+5
-1
@@ -9,6 +9,7 @@ Root files: [`README.md`](../README.md) (install and usage), [`ARCHITECTURE.md`]
|
||||
| [`api.md`](api.md) | Full REST route table, MCP tools/prompts/resources, client setup, Origin and Host checks |
|
||||
| [`openapi.json`](openapi.json) | Generated OpenAPI 3.1 description of the REST API and MCP endpoint; regenerate with `cargo run -- openapi --peers > docs/openapi.json` |
|
||||
| [`tls.md`](tls.md) | Native TLS: configuration, self-signed example, SIGHUP rotation, ACME and sops paths |
|
||||
| [`consolidator.md`](consolidator.md) | Peers (consolidator): config, agenix tokens, threat model, firewall, reload |
|
||||
|
||||
## Workstream records (archived)
|
||||
|
||||
@@ -27,5 +28,8 @@ Root files: [`README.md`](../README.md) (install and usage), [`ARCHITECTURE.md`]
|
||||
| [P3 Integration](workstreams/P3-integration.md) | 3 | E, F, G |
|
||||
| [WS-I TLS](workstreams/WS-I-tls.md) | 4 | P3 |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | 4 | P3, WS-I (gate result pending) |
|
||||
| [P5 Consolidator](workstreams/P5-consolidator/README.md) | 5 | WS-H, WS-I (folder: contracts, decisions, WS-T and A to F) |
|
||||
| [WS-G OpenAPI](workstreams/WS-G-openapi.md) | 5 (stand-alone) | P5 |
|
||||
| [WS-H final fixes](workstreams/WS-H-final-fixes.md) | 5 | P5 final review |
|
||||
|
||||
Dependency order: P0, then A to D in parallel, then E to G in parallel, then P3, then WS-I, then WS-H.
|
||||
Dependency order: P0, then A to D in parallel, then E to G in parallel, then P3, then WS-I, then WS-H. Phase 5 (P5) came after, then the OpenAPI doc and the final fixes.
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Draft |
|
||||
| Status | Done |
|
||||
| Owner | |
|
||||
| Date | 2026-10-19 |
|
||||
| Depends on | Phase 4 / WS-H (NixOS module and VM test) done |
|
||||
|
||||
|
||||
This phase is a folder so workstreams can be claimed and worked in parallel by separate agents or people. Start here, then read [contracts.md](contracts.md) and your workstream file only. Rules: every workstream edits only its own files (see its "Do not touch" list); shared interfaces change only through contracts.md. How the folder works: [../README.md](../README.md).
|
||||
This phase is a folder so workstreams can be claimed and worked in parallel by separate agents or people. Start here, then read [contracts.md](contracts.md) and your workstream file only. Rules: every workstream edits only its own files (see its "Do not touch" list); shared interfaces change only through contracts.md. How the folder works: [plan/README.md](../../../plan/README.md).
|
||||
|
||||
## Goal
|
||||
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+2
-2
@@ -1,6 +1,6 @@
|
||||
# Planning the next phase
|
||||
|
||||
`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.
|
||||
`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. The Phase 5 plan is archived in [`../docs/workstreams/P5-consolidator/`](../docs/workstreams/P5-consolidator/README.md).
|
||||
|
||||
Where other things live:
|
||||
|
||||
@@ -13,7 +13,7 @@ Where other things live:
|
||||
|
||||
## Phase folder layout
|
||||
|
||||
Each phase is a folder `plan/<short-name>/` (for example `plan/phase-5-consolidator/`) so workstreams can be worked in parallel by separate agents or people:
|
||||
Each phase is a folder `plan/<short-name>/` (for example `plan/phase-6-example/`) so workstreams can be worked in parallel by separate agents or people:
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
|
||||
Reference in new issue
Block a user