//! Docker source over the unix socket via `bollard`. //! //! 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::{ clamp_count, ContainerStatus, ContainerSummary, DockerSource, LogLine, LogOptions, LogStream, }; use crate::config::Config; use crate::error::AppError; /// 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; 4] = ["json-file", "local", "journald", "k8s-file"]; pub struct BollardDocker { socket: PathBuf, max_tail: usize, shutdown: CancellationToken, client: Mutex>, } impl BollardDocker { /// Never fails or blocks. 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())) } 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> { 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) => { tracing::warn!(error = %e, "skipping container that failed to inspect"); } } } Ok(out) } 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> { 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) } /// The receiver closes on shutdown, consumer drop, daemon stream end or a /// stream error. End and error are indistinguishable to the consumer /// (errors are logged). A trailing unterminated line is flushed first. async fn follow_logs( &self, name: &str, opts: &LogOptions, ) -> Result, AppError> { 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 mut batch = Vec::new(); let mut finished = false; match next { Some(Ok(frame)) => splitter.push(frame, &mut |l| batch.push(l)), Some(Err(e)) => { tracing::warn!(error = %e, container = %name, "docker log follow ended"); finished = true; } None => finished = true, } if finished { splitter.finish(&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; } } } } if finished { break; } } // Dropping `s` closes the HTTP connection and ends the daemon-side stream. }); Ok(rx) } } /// 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.len() <= 255 && n.chars().next().is_some_and(|c| c.is_ascii_alphanumeric()) && 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()), 501 => AppError::BadRequest(message.clone()), 500 if message.to_ascii_lowercase().contains("logging driver") => { 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("..").is_err()); assert!(normalize_name("-x").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 summary_mapping() { use bollard::models::{ContainerState, Health, HealthStatusEnum}; let i = ContainerInspectResponse { id: Some("abc".into()), name: Some("/web".into()), restart_count: Some(2), state: Some(ContainerState { status: Some(ContainerStateStatusEnum::RUNNING), started_at: Some("2026-10-15T12:00:00Z".into()), health: Some(Health { status: Some(HealthStatusEnum::HEALTHY), ..Default::default() }), ..Default::default() }), ..Default::default() }; let now: Timestamp = "2026-10-15T12:01:00Z".parse().unwrap(); let s = summary_from_inspect(&i, now); assert_eq!(s.name, "web"); assert_eq!(s.state, "running"); assert_eq!(s.health.as_deref(), Some("healthy")); assert_eq!(s.uptime_seconds, Some(60)); assert_eq!(s.restart_count, Some(2)); } #[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(_)) )); } }