Module containers 

Structs

ContainerCacheEntry

A cached container listing for a single host. engine_version is the daemon’s Server.Version captured during the last refresh, surfaced in the host detail panel; None means the version sub-call did not return or the cache was written by an older purple build.

ContainerError

Error from a container listing operation. Preserves the detected runtime even when the ps command fails so it can be cached for future calls.

ContainerInfo

Metadata for a single container (from docker ps -a / podman ps -a).

ContainerInspect

Parsed subset of docker inspect <id> (or podman inspect). Only the fields purple’s container detail panel renders are extracted; the rest of the JSON document is discarded so cache size stays bounded.

ContainerListing

Parsed result of a container listing command. engine_version is the daemon’s Server.Version (best-effort, None when the version sub-call failed or the remote runtime predates the engine sentinel).

MountInfo

NetworkInfo

Enums

ContainerAction

Actions that can be performed on a container.

ContainerRuntime

Supported container runtimes.

Functions

container_action_command

Build the shell command to perform an action on a container.

container_inspect_command

Build the SSH command string for inspecting a single container.

container_list_command

Build the SSH command string for listing containers. Output is the container NDJSON, then the ##purple:engine## sentinel, then the daemon version on its own line. The version subcall is suffixed with || true so its failure cannot mask a docker ps error: the chain surfaces ps’s exit code, while a missing version line just yields engine_version: None downstream.

container_logs_command

Build the <runtime> logs --tail <n> <id> command. The --tail cap is enforced server-side so the SSH stream stays bounded even on a noisy container.

exit_code_meaning

Translate a non-zero docker/podman exit code into a short human-readable hint. Returns None for codes without a well-known meaning so the UI can fall back to the bare number. Exit 0 has no entry because the detail panel only annotates failed exits. Sources: docker docs + Linux signal table.

fetch_container_inspect

Synchronously fetch + parse container inspect. Validates the container ID before issuing the SSH call.

fetch_container_logs

Synchronously fetch logs and split into lines. Returns the raw captured stdout split on \n so the renderer does not have to re-parse. Empty trailing lines are dropped.

fetch_containers

Fetch container list synchronously via SSH. Follows the fetch_remote_listing pattern.

format_relative_time

Format a Unix timestamp as a human-readable relative time string. Honours demo_flag::now_secs() when demo mode is active so visual regression goldens stay byte-stable across long-running test processes (same pattern as history::format_time_ago).

format_uptime_short

Format a duration in seconds as a compact label (12s, 5m, 2h, 3d). Used for the in-border staleness badge where width is precious and the surrounding label (synced) already says “ago” without the suffix.

load_container_cache

Load container cache from ~/.purple/container_cache.jsonl. Malformed lines are silently ignored. Duplicate aliases: last-write-wins.

parse_container_cache_content

Parse container cache from JSONL content string (for demo/test use).

parse_container_inspect

Parse docker inspect <id> stdout into ContainerInspect. The command always returns a JSON array; we take the first element. Missing fields degrade to defaults rather than fail so a partial response still renders something useful.

parse_container_output

Parse the stdout of a container listing command.

parse_container_ps

Parse NDJSON output from docker ps --format '{{json .}}' or podman ps --format '{{json .}}'. Used by tests and the public crate API exposed via lib.rs; the live SSH path streams through parse_container_output directly, so the binary build sees this helper as unused and the lint must be silenced.

parse_runtime

Detect runtime from command output by matching the LAST non-empty trimmed line. Only “docker” or “podman” are accepted. MOTD-resilient. Currently unused (sentinel-based detection handles this inline) but kept as a public utility for potential future two-step detection paths.

parse_uptime_from_status

Parse a Docker Up … status string into a compact uptime label. Returns None for any non-running state (Exited, Created, Restarting, Paused without an Up prefix, empty). Cells render <1m for sub-minute uptimes, 1m / 5m / 12h / 5w / 3mo / 2y otherwise. Format follows Docker’s units.HumanDuration.

save_container_cache

Save container cache to ~/.purple/container_cache.jsonl via atomic write.

spawn_container_action

Spawn a background thread to perform a container action (start/stop/restart). Validates the container ID before executing.

spawn_container_inspect_listing

Spawn a background thread to run container inspect. Mirrors the spawn_container_listing pattern so the call site looks identical.

spawn_container_listing

Spawn a background thread to fetch container listings. Follows the spawn_remote_listing pattern.

spawn_container_logs_fetch

Spawn a background thread to run container logs. Same shape as spawn_container_inspect_listing. In demo mode the SSH call is short-circuited with a deterministic synthetic log stream so the logs viewer (and its / search) is exercisable without a remote.

truncate_str

Truncate a string to at most max characters. Appends “..” if truncated.

validate_container_id

Validate a container ID or name. Accepts ASCII alphanumeric, hyphen, underscore, dot. Rejects empty, non-ASCII, shell metacharacters, colon.