12 KiB
12 KiB
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.enableand the existingCLAUDE_CONFIG_DIRenterShell. Addpkgs.pkg-configandpkgs.systemd(its.devoutput provideslibsystemd.pc). Addscripts.build,scripts.runandscripts.token, which wrapscargo run -- token. Do not add openssl. Optionally addpkgs.opentelemetry-collector-contribfor G7. - P0-2 Cargo.toml. Package
skyg-linux-trackerwith[[bin]] name = "slinuxm"(DEC-1). Pin every crate needed by all phases:- Runtime:
tokio(full),tokio-util(CancellationToken),futures. - HTTP:
axum0.8,tower,tower-http(trace). - Data:
serde,serde_json,schemars,thiserror,jifforchrono. - 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.
- Runtime:
- P0-3 API spike, max half a day. Confirm against the pinned versions:
- The rmcp
StreamableHttpService::newsignature,StreamableHttpServerConfigfields, and whether it validates Origin or Host (DEC-8). - zbus_systemd
ManagerProxy,UnitProxy,ServiceProxy,TimerProxynames and property types. - The
systemdcrate journal open API,waitwith timeout, namespace support, and whetherJournalisSend. - 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.
- The rmcp
- 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 = falsewhenbindis 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 fieldsOption),TimerInfoJournalQuery,JournalEntry,Priority(0–7, parse from name or number)ContainerSummary,ContainerStatus,LogLine { stream: Stdout|Stderr, ts, message }- All derive
Serialize,JsonSchemaandDebug. Timestamps serialize as RFC3339.
- P0-7 Traits + fakes.
SystemdSource,JournalSource,DockerSource. Follow methods returnmpsc::Receiveror a boxedStream.fake.rsprovides fixture-backed implementations for tests (DEC-2). - P0-8 error.rs.
AppError { NotFound, BadRequest, Unauthorized, Unavailable, Internal }. ImplementIntoResponse(status +{"error": {"code", "message"}}) andFrom<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 beClone. - P0-10 Stubs with final signatures:
api::router(AppState) -> Routermcp::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.rsdispatchesslinuxm 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.0combination is an error.
Done when
cargo run -- serve --print-configprints the merged config, and precedence works by hand.cargo buildproducestarget/debug/slinuxm.cargo clippy -- -D warnings,cargo fmt --checkandcargo testare clean.cargo tree -i opensslandcargo tree -i openssl-sysprint 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 isStreamableHttpService<S, LocalSessionManager>(rmcp::transport::streamable_http_server::{StreamableHttpService, StreamableHttpServerConfig, session::local::LocalSessionManager}). It is atower_service::Service<Request<B>>withError = Infallible, soRouter::nest_service("/mcp", svc)works. Config is#[non_exhaustive]: build withStreamableHttpServerConfig::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'swith_json_response(false)still exists.ServerHandler::get_inforeturnsrmcp::model::ServerConfig(ServerInfois deprecated). Errors:rmcp::ErrorDatawithresource_not_found,invalid_params,invalid_request,internal_errorconstructors. 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 haveassume_defaults = false, so build with.builder(&conn).path(unit_path)).ListUnitsreturnsVec<(name, description, load_state, active_state, sub_state, followed, unit_path: OwnedObjectPath, job_id: u32, job_type, job_path)>;list_units_filtered(states)andlist_units_by_patterns(states, patterns)exist.get_unitandload_unitreturnOwnedObjectPath. 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 noListTimers. Timestamps are microseconds since epoch; 0 andu64::MAXmean unset. Needs thezbus-async-tokiofeature to run on tokio. - systemd 0.10.1 journal.
journal::OpenOptions::default().system(true).open()and.open_namespace(ns)(featuresystemd_v245) returnJournal.Journalis notSendnorSync: open it inside thespawn_blockingthread and keep it there.wait(Option<Duration>) -> JournalWaitResult { Nop, Append, Invalidate }supports a timeout. Other API:seek_tail,previous_skip,next_entry/previous_entryreturningJournalRecord = BTreeMap<String, String>,match_add(key, val),match_or,match_and,timestamp_usec,cursor.next_entryyields string values, so binaryMESSAGEfields may needget_datafor 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). Thehttp-protofeature alone has no HTTP client; an explicit client feature is needed. We enabledreqwest-rustls(plustls-ring,tls-webpki-rootsfor gRPC TLS). This pullsaws-lc-sys(C build) via reqwest but no openssl. If aws-lc is a problem,hyper-clientgives plain-http only. - Cargo tree.
cargo tree -i openssland-i openssl-sysprint "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 underclippy -D warnings. Surfaces import fromskyg_linux_tracker::.... - Added
telemetry::spawn_exporters(AppState) -> Vec<JoinHandle<()>>beyond the listedtelemetry::init, because metrics polling and log fan-out need the sources. - Added
AppState::live(config, db, shutdown)andsources::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 traitfollowmethods take no token. docker_logsis split intologs(snapshot) andfollow_logs(stream) onDockerSource.- Added
server.allowed_hosts/server.allowed_originsconfig keys for DEC-8. Confighas noOptionfields, so it serializes to TOML. Empty string or list means unset.servecurrently validates config then exits with an error "server wiring is not implemented yet (P3 I1)".--print-configworks with any subcommand and redactsotel.headersvalues.config.example.tomlwas drafted by goose (openrouter, gpt-4o-mini), then corrected by hand (invalid TOML on one line, comment layout). A test asserts it equalsConfig::default().