Files
skyg-linux-tracker/plan/workstreams/P0-foundation.md
T
2026-10-15 17:07:03 -04:00

5.5 KiB
Raw Blame History

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.

  • 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.