# 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 for rmcp::ErrorData`. - **P0-9 state.rs.** `AppState { config: Arc, systemd: Arc, journal: Arc, docker: Arc, db: Option, shutdown: CancellationToken }`. Must be `Clone`. - **P0-10 Stubs with final signatures:** - `api::router(AppState) -> Router` - `mcp::service(AppState) -> StreamableHttpService<…>` - `telemetry::init(&Config) -> Result` - `auth::layer(AppState)` - `auth::tokens::run(TokenCmd, &Config) -> Result<()>` - `db::open(&Config) -> Result` - 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, session_manager: Arc, config: StreamableHttpServerConfig)`. Service type is `StreamableHttpService` (`rmcp::transport::streamable_http_server::{StreamableHttpService, StreamableHttpServerConfig, session::local::LocalSessionManager}`). It is a `tower_service::Service>` 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) -> JournalWaitResult { Nop, Append, Invalidate }` supports a timeout. Other API: `seek_tail`, `previous_skip`, `next_entry`/`previous_entry` returning `JournalRecord = BTreeMap`, `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)`; `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>` 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()`.