Files
skyg-linux-tracker/plan/workstreams/P3-integration.md
T

63 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).