Files
2026-10-19 14:14:29 -04:00

121 lines
12 KiB
Markdown
Raw Permalink 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.
# 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 the original design:
- `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 the design review (see Design notes in ARCHITECTURE.md). 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()`.