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

12 KiB
Raw Permalink Blame History

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.

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