83 lines
5.5 KiB
Markdown
83 lines
5.5 KiB
Markdown
# P0 — Foundation
|
||
|
||
| Field | Value |
|
||
|---|---|
|
||
| Status | Ready |
|
||
| 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`.
|