From 2404d9dd9595ec30ced28e8a9a04cfbab6049369 Mon Sep 17 00:00:00 2001 From: Ari Sosnovsky Date: Thu, 15 Oct 2026 17:47:01 -0400 Subject: [PATCH] WS-C: bollard docker source and docker_ps example Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs --- TODO.md | 12 +- examples/docker_ps.rs | 75 +++++ plan/workstreams/WS-C-docker.md | 3 +- src/sources/docker.rs | 532 ++++++++++++++++++++++++++++++-- 4 files changed, 597 insertions(+), 25 deletions(-) create mode 100644 examples/docker_ps.rs diff --git a/TODO.md b/TODO.md index aa672f9..fcbd0fb 100644 --- a/TODO.md +++ b/TODO.md @@ -44,12 +44,12 @@ Design: [`plan.md`](plan.md) · Review fixes: [`plan/review.md`](plan/review.md) - [ ] **B6** Test: the follow thread exits after its receiver is dropped ### WS-C docker · [card](plan/workstreams/WS-C-docker.md) -- [ ] **C1** Lazy `bollard::Docker` on the configured socket. Missing or denied socket maps to `Unavailable`. -- [ ] **C2** `ps()`: list + concurrent bounded inspect (health, uptime, restarts, image) -- [ ] **C3** `container_status(name)` -- [ ] **C4** `logs(name, follow, tail, since)` stream that stops on drop or shutdown -- [ ] **C5** `tail` capped by config -- [ ] **C6** `examples/docker_ps.rs` + log follow +- [x] **C1** Lazy `bollard::Docker` on the configured socket. Missing or denied socket maps to `Unavailable`. +- [x] **C2** `ps()`: list + concurrent bounded inspect (health, uptime, restarts, image) +- [x] **C3** `container_status(name)` +- [x] **C4** `logs(name, follow, tail, since)` stream that stops on drop or shutdown +- [x] **C5** `tail` capped by config +- [x] **C6** `examples/docker_ps.rs` + log follow - [ ] **C7** *(nice-to-have)* Smoke test against the Podman socket ### WS-D auth + DB · [card](plan/workstreams/WS-D-auth.md) diff --git a/examples/docker_ps.rs b/examples/docker_ps.rs new file mode 100644 index 0000000..cd6b6eb --- /dev/null +++ b/examples/docker_ps.rs @@ -0,0 +1,75 @@ +//! Print `ps` as JSON, or stream container logs. +//! +//! Usage: `docker_ps [--socket PATH] [--running] [--logs NAME [--follow] [--tail N]]` + +use std::path::PathBuf; + +use skyg_linux_tracker::config::Config; +use skyg_linux_tracker::sources::docker::BollardDocker; +use skyg_linux_tracker::sources::{DockerSource, LogLine, LogOptions, LogStream}; +use tokio_util::sync::CancellationToken; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let mut socket: Option = None; + let mut logs: Option = None; + let mut follow = false; + let mut all = true; + let mut tail: Option = None; + let mut args = std::env::args().skip(1); + while let Some(a) = args.next() { + match a.as_str() { + "--socket" => socket = args.next().map(PathBuf::from), + "--logs" => logs = args.next(), + "--follow" | "-f" => follow = true, + "--running" => all = false, + "--all" | "-a" => all = true, + "--tail" => tail = args.next().and_then(|v| v.parse().ok()), + other => anyhow::bail!("unknown argument '{other}'"), + } + } + + let mut config = Config::default(); + if let Some(s) = socket { + config.sources.docker_socket = s; + } + let shutdown = CancellationToken::new(); + let docker = BollardDocker::new(&config, shutdown.clone()); + + let Some(name) = logs else { + let ps = docker.ps(all).await?; + println!("{}", serde_json::to_string_pretty(&ps)?); + return Ok(()); + }; + + let opts = LogOptions { tail, since: None }; + if !follow { + for l in docker.logs(&name, &opts).await? { + print_line(&l); + } + return Ok(()); + } + let mut rx = docker.follow_logs(&name, &opts).await?; + loop { + tokio::select! { + _ = tokio::signal::ctrl_c() => { + shutdown.cancel(); + break; + } + line = rx.recv() => match line { + Some(l) => print_line(&l), + None => break, + }, + } + } + Ok(()) +} + +fn print_line(l: &LogLine) { + let tag = match l.stream { + LogStream::Stdout => "out", + LogStream::Stderr => "err", + }; + let ts = l.ts.map(|t| t.to_string()).unwrap_or_default(); + println!("{ts} [{tag}] {}", l.message); +} diff --git a/plan/workstreams/WS-C-docker.md b/plan/workstreams/WS-C-docker.md index 00cb7f6..3083dc0 100644 --- a/plan/workstreams/WS-C-docker.md +++ b/plan/workstreams/WS-C-docker.md @@ -2,7 +2,7 @@ | Field | Value | |---|---| -| Status | Backlog | +| Status | Review | | Owner | — | | Phase | 1 (parallel) | | Depends on | P0 | @@ -42,3 +42,4 @@ Tick these in [`TODO.md`](../../TODO.md). ## Log - 2026-10-15: Card created. +- 2026-10-15: Implemented C1-C6 on branch `ws-c/docker-source`. Verified against the real docker socket (ps, logs, follow). C7 skipped: no Podman socket on this host. `ps` uses `buffered(8)` (ordered) instead of `buffer_unordered`. Names are validated to `[A-Za-z0-9_.-]`. Non-readable log drivers are rejected up front from inspect (BadRequest naming the driver). diff --git a/src/sources/docker.rs b/src/sources/docker.rs index c68f169..d3e1d0e 100644 --- a/src/sources/docker.rs +++ b/src/sources/docker.rs @@ -1,46 +1,542 @@ -//! Docker source over the unix socket via `bollard` (WS-C owns this file). +//! Docker source over the unix socket via `bollard` (WS-C). //! -//! STUB: signatures are final, bodies are `todo!()`. -//! Notes for WS-C: build the client lazily. A missing or denied socket maps to -//! `AppError::Unavailable` per request and never fails startup (review G9). +//! The client is built lazily on first use, so a missing or denied socket +//! never fails startup (review G9). Every call retries the connection until it +//! succeeds, and maps backend absence to `AppError::Unavailable`. + +use std::io::ErrorKind; +use std::path::PathBuf; +use std::sync::Mutex; use async_trait::async_trait; +use bollard::container::LogOutput; +use bollard::errors::Error as BollardError; +use bollard::models::{ContainerInspectResponse, ContainerStateStatusEnum}; +use bollard::query_parameters::{ + InspectContainerOptions, ListContainersOptionsBuilder, LogsOptions, LogsOptionsBuilder, +}; +use bollard::{Docker, API_DEFAULT_VERSION}; +use futures::stream::{self, StreamExt}; +use jiff::Timestamp; use tokio::sync::mpsc; use tokio_util::sync::CancellationToken; -use super::{ContainerStatus, ContainerSummary, DockerSource, LogLine, LogOptions}; +use super::{ + clamp_count, ContainerStatus, ContainerSummary, DockerSource, LogLine, LogOptions, LogStream, +}; use crate::config::Config; use crate::error::AppError; -pub struct BollardDocker {} +/// Request timeout for ordinary API calls, in seconds. +const API_TIMEOUT_SECS: u64 = 30; +/// Timeout for follow streams, which are long-lived. +const FOLLOW_TIMEOUT_SECS: u64 = 24 * 60 * 60; +/// Concurrent `inspect` calls during `ps`. +const INSPECT_CONCURRENCY: usize = 8; +/// Lines queued towards a follow consumer. +const FOLLOW_CHANNEL: usize = 256; +/// Log drivers the Docker API can read back. +const READABLE_DRIVERS: [&str; 3] = ["json-file", "local", "journald"]; + +pub struct BollardDocker { + socket: PathBuf, + max_tail: usize, + shutdown: CancellationToken, + client: Mutex>, +} impl BollardDocker { - /// Must not fail or block. Reads `sources.docker_socket` and + /// Never fails or blocks. Reads `sources.docker_socket` and /// `limits.max_tail` from `config`. Follow tasks stop on `shutdown`. - pub fn new(_config: &Config, _shutdown: CancellationToken) -> Self { - Self {} + pub fn new(config: &Config, shutdown: CancellationToken) -> Self { + Self { + socket: config.sources.docker_socket.clone(), + max_tail: config.limits.max_tail, + shutdown, + client: Mutex::new(None), + } + } + + fn socket_name(&self) -> String { + self.socket.display().to_string() + } + + fn connect(&self, timeout: u64) -> Result { + let path = self.socket.to_string_lossy(); + Docker::connect_with_unix(&path, timeout, API_DEFAULT_VERSION) + .map_err(|e| map_error(&e, &self.socket_name())) + } + + /// The cached client, connecting on first successful use. + fn client(&self) -> Result { + let mut guard = self.client.lock().unwrap_or_else(|p| p.into_inner()); + if let Some(c) = guard.as_ref() { + return Ok(c.clone()); + } + let c = self.connect(API_TIMEOUT_SECS)?; + *guard = Some(c.clone()); + Ok(c) + } + + fn log_options(&self, opts: &LogOptions, follow: bool) -> LogsOptions { + let tail = clamp_count(opts.tail, self.max_tail); + let mut b = LogsOptionsBuilder::new() + .follow(follow) + .stdout(true) + .stderr(true) + .timestamps(true) + .tail(&tail.to_string()); + if let Some(since) = opts.since { + let secs = since.as_second().clamp(0, i64::from(i32::MAX)); + b = b.since(i32::try_from(secs).unwrap_or(i32::MAX)); + } + b.build() } } #[async_trait] impl DockerSource for BollardDocker { - async fn ps(&self, _all: bool) -> Result, AppError> { - todo!("WS-C C2") + async fn ps(&self, all: bool) -> Result, AppError> { + let docker = self.client()?; + let socket = self.socket_name(); + let opts = ListContainersOptionsBuilder::new().all(all).build(); + let list = docker + .list_containers(Some(opts)) + .await + .map_err(|e| map_error(&e, &socket))?; + let ids: Vec = list.into_iter().filter_map(|c| c.id).collect(); + + // `buffered` keeps the daemon's listing order while running concurrently. + let results: Vec<_> = stream::iter(ids) + .map(|id| { + let docker = docker.clone(); + async move { + docker + .inspect_container(&id, None::) + .await + } + }) + .buffered(INSPECT_CONCURRENCY) + .collect() + .await; + + let now = Timestamp::now(); + let mut out = Vec::with_capacity(results.len()); + for r in results { + match r { + Ok(inspect) => out.push(summary_from_inspect(&inspect, now)), + // Removed between list and inspect. + Err(BollardError::DockerResponseServerError { + status_code: 404, .. + }) => {} + Err(e) => return Err(map_error(&e, &socket)), + } + } + Ok(out) } - async fn container_status(&self, _name: &str) -> Result { - todo!("WS-C C3") + async fn container_status(&self, name: &str) -> Result { + let name = normalize_name(name)?; + let docker = self.client()?; + let inspect = inspect(&docker, &name, &self.socket_name()).await?; + Ok(status_from_inspect(&inspect, Timestamp::now())) } - async fn logs(&self, _name: &str, _opts: &LogOptions) -> Result, AppError> { - todo!("WS-C C4") + async fn logs(&self, name: &str, opts: &LogOptions) -> Result, AppError> { + let name = normalize_name(name)?; + let docker = self.client()?; + let socket = self.socket_name(); + check_log_driver(&inspect(&docker, &name, &socket).await?, &name)?; + let mut s = Box::pin(docker.logs(&name, Some(self.log_options(opts, false)))); + let mut splitter = LineSplitter::default(); + let mut lines = Vec::new(); + while let Some(item) = s.next().await { + let frame = item.map_err(|e| map_container_error(&e, &socket, &name))?; + splitter.push(frame, &mut |l| lines.push(l)); + } + splitter.finish(&mut |l| lines.push(l)); + Ok(lines) } async fn follow_logs( &self, - _name: &str, - _opts: &LogOptions, + name: &str, + opts: &LogOptions, ) -> Result, AppError> { - todo!("WS-C C4") + let name = normalize_name(name)?; + // Dedicated client: follow streams outlive the ordinary request timeout. + let docker = self.connect(FOLLOW_TIMEOUT_SECS)?; + check_log_driver(&inspect(&docker, &name, &self.socket_name()).await?, &name)?; + let mut s = Box::pin(docker.logs(&name, Some(self.log_options(opts, true)))); + + let (tx, rx) = mpsc::channel(FOLLOW_CHANNEL); + let shutdown = self.shutdown.clone(); + tokio::spawn(async move { + let mut splitter = LineSplitter::default(); + 'outer: loop { + let next = tokio::select! { + biased; + () = shutdown.cancelled() => break, + () = tx.closed() => break, + next = s.next() => next, + }; + let frame = match next { + Some(Ok(frame)) => frame, + Some(Err(e)) => { + tracing::warn!(error = %e, container = %name, "docker log follow ended"); + break; + } + None => break, + }; + let mut batch = Vec::new(); + splitter.push(frame, &mut |l| batch.push(l)); + for line in batch { + tokio::select! { + biased; + () = shutdown.cancelled() => break 'outer, + sent = tx.send(line) => { + if sent.is_err() { + break 'outer; + } + } + } + } + } + // Dropping `s` closes the HTTP connection and ends the daemon-side stream. + }); + Ok(rx) + } +} + +// ---------------------------------------------------------------- helpers + +/// Strip the leading `/` and reject names that could alter the request path. +fn normalize_name(name: &str) -> Result { + let n = name.trim().trim_start_matches('/'); + let valid = !n.is_empty() + && n.len() <= 255 + && n.chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '.' | '-')); + if valid { + Ok(n.to_owned()) + } else { + Err(AppError::BadRequest(format!( + "invalid container name '{name}'" + ))) + } +} + +async fn inspect( + docker: &Docker, + name: &str, + socket: &str, +) -> Result { + docker + .inspect_container(name, None::) + .await + .map_err(|e| map_container_error(&e, socket, name)) +} + +/// Reject log reads for drivers the API cannot serve, naming the driver. +fn check_log_driver(i: &ContainerInspectResponse, name: &str) -> Result<(), AppError> { + let driver = i + .host_config + .as_ref() + .and_then(|h| h.log_config.as_ref()) + .and_then(|l| l.typ.as_deref()) + .unwrap_or(""); + if driver.is_empty() || READABLE_DRIVERS.contains(&driver) { + Ok(()) + } else { + Err(AppError::BadRequest(format!( + "logs unavailable for '{name}': log driver '{driver}' cannot be read through the Docker API" + ))) + } +} + +/// Map a bollard error that is not specific to one container. +fn map_error(e: &BollardError, socket: &str) -> AppError { + match e { + BollardError::DockerResponseServerError { + status_code, + message, + } => match *status_code { + 401 | 403 => AppError::Unavailable(format!("docker denied access: {message}")), + 404 => AppError::NotFound(message.clone()), + 400 => AppError::BadRequest(message.clone()), + _ => AppError::Internal(format!("docker API error {status_code}: {message}")), + }, + BollardError::IOError { err } => match err.kind() { + ErrorKind::NotFound => { + AppError::Unavailable(format!("docker socket {socket} not found")) + } + ErrorKind::PermissionDenied => { + AppError::Unavailable(format!("permission denied on docker socket {socket}")) + } + ErrorKind::ConnectionRefused => { + AppError::Unavailable(format!("connection refused on docker socket {socket}")) + } + _ => AppError::Unavailable(format!("docker socket {socket}: {err}")), + }, + BollardError::SocketNotFoundError(_) => { + AppError::Unavailable(format!("docker socket {socket} not found")) + } + BollardError::RequestTimeoutError => { + AppError::Unavailable(format!("docker socket {socket}: request timed out")) + } + // Transport-level failures mean the daemon is unreachable. + BollardError::HyperResponseError { .. } + | BollardError::HyperLegacyError { .. } + | BollardError::HttpClientError { .. } => { + AppError::Unavailable(format!("docker socket {socket} unreachable: {e}")) + } + other => AppError::Internal(format!("docker: {other}")), + } +} + +fn map_container_error(e: &BollardError, socket: &str, name: &str) -> AppError { + match e { + BollardError::DockerResponseServerError { + status_code: 404, .. + } => AppError::NotFound(format!("container '{name}' not found")), + other => map_error(other, socket), + } +} + +fn parse_ts(s: &str) -> Option { + // Never-started containers report year 0001. + s.parse::().ok().filter(|t| t.as_second() > 0) +} + +fn summary_from_inspect(i: &ContainerInspectResponse, now: Timestamp) -> ContainerSummary { + let state = i.state.as_ref(); + let state_name = state + .and_then(|s| s.status) + .map_or("unknown", state_str) + .to_owned(); + let health = state + .and_then(|s| s.health.as_ref()) + .and_then(|h| h.status) + .map(|h| h.to_string()) + .filter(|h| !h.is_empty() && h != "none"); + let started_at = state + .and_then(|s| s.started_at.as_deref()) + .and_then(parse_ts); + let uptime_seconds = match (state_name == "running", started_at) { + (true, Some(t)) => { + Some(u64::try_from((now.as_second() - t.as_second()).max(0)).unwrap_or(0)) + } + _ => None, + }; + let image = i + .config + .as_ref() + .and_then(|c| c.image.clone()) + .filter(|s| !s.is_empty()) + .or_else(|| i.image.clone()) + .unwrap_or_default(); + ContainerSummary { + id: i.id.clone().unwrap_or_default(), + name: i + .name + .as_deref() + .unwrap_or_default() + .trim_start_matches('/') + .to_owned(), + image, + state: state_name, + health, + created: i.created.as_ref().and_then(|c| c.to_string().parse().ok()), + started_at, + uptime_seconds, + restart_count: i.restart_count.and_then(|n| u64::try_from(n).ok()), + } +} + +fn status_from_inspect(i: &ContainerInspectResponse, now: Timestamp) -> ContainerStatus { + let state = i.state.as_ref(); + let health_output = state + .and_then(|s| s.health.as_ref()) + .and_then(|h| h.log.as_ref()) + .and_then(|l| l.last()) + .and_then(|r| r.output.clone()); + ContainerStatus { + summary: summary_from_inspect(i, now), + finished_at: state + .and_then(|s| s.finished_at.as_deref()) + .and_then(parse_ts), + exit_code: state.and_then(|s| s.exit_code), + oom_killed: state.and_then(|s| s.oom_killed), + health_output, + } +} + +fn state_str(s: ContainerStateStatusEnum) -> &'static str { + use ContainerStateStatusEnum as S; + match s { + S::EMPTY => "unknown", + S::CREATED => "created", + S::RUNNING => "running", + S::PAUSED => "paused", + S::RESTARTING => "restarting", + S::REMOVING => "removing", + S::EXITED => "exited", + S::DEAD => "dead", + S::STOPPING => "stopping", + } +} + +/// Reassembles log frames into lines, one buffer per stream. +#[derive(Default)] +struct LineSplitter { + out: Vec, + err: Vec, +} + +impl LineSplitter { + fn push(&mut self, frame: LogOutput, emit: &mut dyn FnMut(LogLine)) { + let (stream, buf, bytes) = match frame { + LogOutput::StdErr { message } => (LogStream::Stderr, &mut self.err, message), + LogOutput::StdOut { message } | LogOutput::Console { message } => { + (LogStream::Stdout, &mut self.out, message) + } + LogOutput::StdIn { .. } => return, + }; + buf.extend_from_slice(&bytes); + while let Some(pos) = buf.iter().position(|b| *b == b'\n') { + let line: Vec = buf.drain(..=pos).collect(); + emit(parse_line(stream, &line[..line.len() - 1])); + } + } + + /// Flush any unterminated trailing lines. + fn finish(&mut self, emit: &mut dyn FnMut(LogLine)) { + for (stream, buf) in [ + (LogStream::Stdout, &mut self.out), + (LogStream::Stderr, &mut self.err), + ] { + if !buf.is_empty() { + emit(parse_line(stream, buf)); + buf.clear(); + } + } + } +} + +/// Parse `" "` produced by `timestamps=true`. +fn parse_line(stream: LogStream, raw: &[u8]) -> LogLine { + let text = String::from_utf8_lossy(raw); + let text = text.strip_suffix('\r').unwrap_or(&text); + if let Some((head, rest)) = text.split_once(' ') { + if let Ok(ts) = head.parse::() { + return LogLine { + stream, + ts: Some(ts), + message: rest.to_owned(), + }; + } + } + LogLine { + stream, + ts: None, + message: text.to_owned(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn frame_out(s: &str) -> LogOutput { + LogOutput::StdOut { + message: s.to_owned().into(), + } + } + + #[test] + fn names() { + assert_eq!(normalize_name("/web-1").unwrap(), "web-1"); + assert_eq!(normalize_name("web.1_x").unwrap(), "web.1_x"); + assert!(normalize_name("").is_err()); + assert!(normalize_name("a/b").is_err()); + assert!(normalize_name("a?b").is_err()); + } + + #[test] + fn line_parsing_and_splitting() { + let mut sp = LineSplitter::default(); + let mut got = Vec::new(); + sp.push(frame_out("2026-10-15T12:00:00.123456789Z hel"), &mut |l| { + got.push(l) + }); + assert!(got.is_empty()); + sp.push( + frame_out("lo\n2026-10-15T12:00:01Z two\npartial"), + &mut |l| got.push(l), + ); + assert_eq!(got.len(), 2); + assert_eq!(got[0].message, "hello"); + assert!(got[0].ts.is_some()); + assert_eq!(got[1].message, "two"); + sp.finish(&mut |l| got.push(l)); + assert_eq!(got[2].message, "partial"); + assert_eq!(got[2].ts, None); + } + + #[test] + fn error_mapping() { + let nf = BollardError::DockerResponseServerError { + status_code: 404, + message: "no such".into(), + }; + assert!(matches!( + map_container_error(&nf, "s", "c"), + AppError::NotFound(_) + )); + let denied = BollardError::IOError { + err: std::io::Error::from(ErrorKind::PermissionDenied), + }; + assert!(matches!(map_error(&denied, "s"), AppError::Unavailable(_))); + let refused = BollardError::IOError { + err: std::io::Error::from(ErrorKind::ConnectionRefused), + }; + assert!(matches!(map_error(&refused, "s"), AppError::Unavailable(_))); + } + + #[test] + fn log_driver_check() { + let mut i = ContainerInspectResponse::default(); + assert!(check_log_driver(&i, "c").is_ok()); + i.host_config = Some(bollard::models::HostConfig { + log_config: Some(bollard::models::HostConfigLogConfig { + typ: Some("syslog".into()), + config: None, + }), + ..Default::default() + }); + match check_log_driver(&i, "c") { + Err(AppError::BadRequest(m)) => assert!(m.contains("syslog")), + other => panic!("unexpected {other:?}"), + } + } + + #[tokio::test] + async fn missing_socket_is_unavailable() { + let mut cfg = Config::default(); + cfg.sources.docker_socket = PathBuf::from("/nonexistent/docker.sock"); + let d = BollardDocker::new(&cfg, CancellationToken::new()); + assert!(matches!(d.ps(true).await, Err(AppError::Unavailable(_)))); + assert!(matches!( + d.container_status("x").await, + Err(AppError::Unavailable(_)) + )); + assert!(matches!( + d.logs("x", &LogOptions::default()).await, + Err(AppError::Unavailable(_)) + )); + assert!(matches!( + d.follow_logs("x", &LogOptions::default()).await, + Err(AppError::Unavailable(_)) + )); } }