Struct DockerClient 

pub struct DockerClient { /* private fields */ }

Implementations

impl DockerClient

pub fn connect() -> Result<Self>

Open a Docker connection using the platform’s default socket / pipe. The handle is cheap to clone (refcounted internally).

Errors

Returns HmError::Docker when bollard cannot resolve a local Docker endpoint (no socket on DOCKER_HOST, no Windows pipe, etc.).

pub async fn ping(&self) -> Result<()>

Round-trip the daemon to confirm reachability.

Errors

Returns HmError::Docker if the ping request fails (daemon stopped, socket revoked, version negotiation failure).

pub async fn image_exists(&self, tag: &str) -> Result<bool>

True if tag resolves to a locally-cached image.

Errors

Returns HmError::Docker if the list_images API call fails (daemon unreachable, malformed filter).

pub async fn list_images_by_reference( &self, reference: &str, ) -> Result<Vec<String>>

List all repo_tags from images that have at least one tag matching reference (e.g. "harmont-local/build" matches harmont-local/build:abc123).

Errors

Returns HmError::Docker if the list_images API call fails.

pub async fn pull_image(&self, tag: &str) -> Result<()>

Pull tag from its registry, surfacing the daemon’s progress stream as Docker errors.

Errors

Returns HmError::Docker if any chunk of the pull stream reports an error (registry not reachable, image not found, auth required).

pub async fn start_long_lived( &self, image: &str, env: &[String], workdir: &str, name: &str, ) -> Result<String>

Start a long-lived container that runs sh -c 'sleep infinity' so later execs land in a stable shell. Returns the container ID.

Errors

Returns HmError::Docker if the container cannot be created (image not pulled, name conflict, OCI runtime failure) or if start_container rejects the create.

pub async fn start_long_lived_with_mounts( &self, image: &str, env: &[String], workdir: &str, name: &str, binds: &[String], ) -> Result<String>

Like Self::start_long_lived but with bind mounts via HostConfig.

Each entry in binds is a Docker bind-mount string of the form "/host/path:/container/path" (with an optional :ro suffix).

Errors

Returns HmError::Docker if the container cannot be created (image not pulled, name conflict, OCI runtime failure) or if start_container rejects the create.

pub async fn exec_streaming( &self, container_id: &str, cmd: &[String], env: &[String], workdir: &str, out: &mut (impl AsyncWrite + Send + Unpin), ) -> Result<i64>

Exec a command inside a running container and stream stdout+stderr to out. Returns the command’s exit code.

Errors

Returns HmError::Docker if create_exec / start_exec / inspect_exec fail, or surfaces an anyhow error if writing a log frame to out fails.

pub async fn exec_streaming_stdin( &self, container_id: &str, cmd: &[String], env: &[String], workdir: &str, stdin_bytes: &[u8], out: &mut (impl AsyncWrite + Send + Unpin), ) -> Result<i64>

Like Self::exec_streaming, but also pipes stdin_bytes into the exec’d process’s stdin (closing it after the write so the process sees EOF). Used to stream a tar archive into tar -xzf - when hydrating /workspace in a fresh chain-root container.

Errors

Returns HmError::Docker if any of the exec lifecycle calls fail, or surfaces an anyhow error if writing stdin or output frames fails.

pub async fn commit_container( &self, container_id: &str, tag: &str, ) -> Result<String>

Commit a running container to an image tag. Returns the tag, which is a valid image reference once the daemon’s commit succeeds.

We don’t return the daemon’s image ID: bollard 0.18’s Commit stub deserialises the response as {"id": ...}, but the Docker daemon returns {"Id": ...} (capital I). The image is committed correctly either way; the tag is the canonical reference and is what every caller actually uses.

Errors

Returns HmError::Docker if commit_container fails (paused container, daemon I/O failure).

Panics

Panics if tag.splitn(2, ':') produces neither one nor two parts. splitn is total for non-empty input, so this branch is only reachable for the empty string, which the caller never passes.

pub async fn remove_image(&self, image: &str) -> Result<()>

Force-remove an image by tag. Used for end-of-run pruning of ephemeral parent-snapshot tags committed during this process’s run. Best-effort callers should swallow the error themselves; failures here are non-fatal.

Errors

Returns HmError::Docker if remove_image fails (image missing, still referenced by a running container, daemon I/O failure).

pub async fn tag_image(&self, source: &str, new_tag: &str) -> Result<()>

Add an additional tag to an existing image.

source is the existing image reference (tag or ID) and new_tag is the desired repo:tag string. If new_tag contains no :, the Docker-default tag "latest" is used.

Errors

Returns HmError::Docker if tag_image fails (source image not found, daemon I/O failure).

pub async fn export_image(&self, image: &str, dest: &Path) -> Result<()>

Export a Docker image to a tar file on disk.

Streams the image layer data from the daemon and writes it to dest using a buffered writer.

Errors

Returns HmError::Docker if the daemon’s export stream fails, or an I/O error if writing to dest fails.

pub async fn import_image(&self, src: &Path) -> Result<()>

Import a Docker image from a tar file on disk.

Reads the full tar file into memory and loads it into the daemon via the image import API.

Errors

Returns HmError::Docker if the daemon rejects the import stream, or an I/O error if reading src fails.

pub async fn list_images_by_prefix(&self, prefix: &str) -> Result<Vec<String>>

List all image tags whose name starts with prefix.

Uses the Docker reference filter with a glob pattern and then post-filters the returned repo_tags to those that truly begin with prefix. The result is sorted lexicographically.

Errors

Returns HmError::Docker if the list_images API call fails (daemon unreachable, malformed filter).

pub async fn stop_remove(&self, container_id: &str)

pub async fn list_containers_by_label( &self, k: &str, v: &str, ) -> Result<Vec<ContainerSummary>>

List container summaries filtered by a single label k=v predicate.

Errors

Returns HmError::Docker when list_containers fails.

Trait Implementations

impl Clone for DockerClient

fn clone(&self) -> DockerClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DockerClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.