Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
63 lines
5.5 KiB
Markdown
63 lines
5.5 KiB
Markdown
# 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).
|