121 lines
12 KiB
Markdown
121 lines
12 KiB
Markdown
# 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()`.
|