Files
skyg-linux-tracker/docs/workstreams/WS-C-docker.md
T
2026-10-19 14:14:29 -04:00

2.5 KiB

WS-C — docker source

Field Value
Status Done
Owner —
Phase 1 (parallel)
Depends on P0
Blocks WS-E, WS-F, WS-G (to finish)
Owned files src/sources/docker.rs, examples/docker_ps.rs

Goal

Implement DockerSource over the Docker or Podman API with bollard on a unix socket. A missing Docker never breaks the rest of the service.

Tasks

Tick these in TODO.md.

  • C1 Construct with Docker::connect_with_unix(socket, timeout, API_DEFAULT_VERSION). Construction must not fail when the socket is absent (review G9). Map connection-refused, not-found and permission-denied to AppError::Unavailable with a clear message on each call.
  • C2 ps():
    • list_containers(all = true).
    • Then inspect_container for each one concurrently, bounded with buffer_unordered(8).
    • Map State.Health.Status, State.StartedAt (to uptime seconds), RestartCount, image, and status.
  • C3 container_status(name) uses inspect only. A 404 maps to NotFound.
  • C4 logs(name, follow, tail, since, token) returns a boxed Stream<Item = Result<LogLine>>. Use stdout, stderr and timestamps = true, parse the timestamp prefix, and keep the stream type (stdout or stderr). The stream ends when dropped or when the token fires.
  • C5 Clamp tail to limits.max_tail.
  • C6 examples/docker_ps.rs prints ps as JSON. --logs NAME [--follow] streams logs.
  • C7 (nice-to-have) Run the example against /run/podman/podman.sock and note any field differences.

Done when

  • The example matches docker ps -a and shows health and uptime for containers with healthchecks.
  • Following logs streams live, and Ctrl-C exits cleanly.
  • With docker_socket pointed at a missing path, every call returns Unavailable and nothing panics.

Notes

  • Container names from the API have a leading /. Strip it in DTOs and accept names with or without it.
  • docker logs only works for the json-file, local and journald log drivers. Others return an API error, which should map to BadRequest with the driver named.

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).