WS-C: bollard docker source and docker_ps example

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
This commit is contained in:
ariandClaude Sonnet 5.5 committed 2026-10-15 17:47:01 -04:00
1 parent 2687ef5c33
commit 2404d9dd95
4 files changed
+597 -25

No files matched your search

+6 -6
View File
@@ -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)
+75
View File
@@ -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<PathBuf> = None;
let mut logs: Option<String> = None;
let mut follow = false;
let mut all = true;
let mut tail: Option<usize> = 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);
}
+2 -1
View File
@@ -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).
+514 -18
View File
@@ -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<Option<Docker>>,
}
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<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()))
}
/// The cached client, connecting on first successful use.
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> {
todo!("WS-C C2")
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) => return Err(map_error(&e, &socket)),
}
}
Ok(out)
}
async fn container_status(&self, _name: &str) -> Result<ContainerStatus, AppError> {
todo!("WS-C C3")
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> {
todo!("WS-C C4")
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)
}
async fn follow_logs(
&self,
_name: &str,
_opts: &LogOptions,
name: &str,
opts: &LogOptions,
) -> Result<mpsc::Receiver<LogLine>, 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<String, AppError> {
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<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()),
_ => 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("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(_))
));
}
}