Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
583 lines
20 KiB
Rust
583 lines
20 KiB
Rust
//! 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<Option<Docker>>,
|
|
}
|
|
|
|
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<Docker, AppError> {
|
|
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<Docker, AppError> {
|
|
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<Vec<ContainerSummary>, 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<String> = 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::<InspectContainerOptions>)
|
|
.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<ContainerStatus, AppError> {
|
|
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<Vec<LogLine>, 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<mpsc::Receiver<LogLine>, 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<String, AppError> {
|
|
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<ContainerInspectResponse, AppError> {
|
|
docker
|
|
.inspect_container(name, None::<InspectContainerOptions>)
|
|
.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<Timestamp> {
|
|
// Never-started containers report year 0001.
|
|
s.parse::<Timestamp>().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<u8>,
|
|
err: Vec<u8>,
|
|
}
|
|
|
|
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<u8> = 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 `"<RFC3339 ts> <message>"` 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::<Timestamp>() {
|
|
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(_))
|
|
));
|
|
}
|
|
}
|