pub struct Lifecycle { /* private fields */ }Expand description
A connected handle to the local dockerd Engine API. Never a remote/TCP Docker endpoint — this always runs containers on the same host the substrate itself is running on, like any other service on the box.
Implementations§
Source§impl Lifecycle
impl Lifecycle
Sourcepub async fn connect() -> Result<Self, SubstrateError>
pub async fn connect() -> Result<Self, SubstrateError>
Connect to the local Docker daemon (the Unix socket on Linux —
bollard’s own platform default) and confirm it’s actually
reachable with a cheap ping, rather than surfacing a confusing
failure on the first real call.
Sourcepub async fn pull_image(&self, image: &str) -> Result<(), SubstrateError>
pub async fn pull_image(&self, image: &str) -> Result<(), SubstrateError>
Pull image, driving the streamed pull response to completion.
Docker’s pull API is a no-op-but-still-valid stream when the image
is already cached, so no special-casing is needed for that case.
Sourcepub async fn run(&self, spec: &ContainerSpec) -> Result<String, SubstrateError>
pub async fn run(&self, spec: &ContainerSpec) -> Result<String, SubstrateError>
Create and start a container per spec. On any failure after the
container was created, best-effort removes it — never leaves a
created-but-never-started container behind for a caller’s retry to
trip over on a name conflict.
Sourcepub async fn stop(
&self,
container_id: &str,
timeout: Duration,
) -> Result<(), SubstrateError>
pub async fn stop( &self, container_id: &str, timeout: Duration, ) -> Result<(), SubstrateError>
Stop a container, giving it timeout to shut down cleanly before
dockerd kills it.
Sourcepub async fn remove(
&self,
container_id: &str,
force: bool,
) -> Result<(), SubstrateError>
pub async fn remove( &self, container_id: &str, force: bool, ) -> Result<(), SubstrateError>
Remove a container. force kills it first if still running
(docker rm -f semantics) rather than requiring a separate stop.
Sourcepub async fn stop_and_remove(
&self,
container_id: &str,
timeout: Duration,
) -> Result<(), SubstrateError>
pub async fn stop_and_remove( &self, container_id: &str, timeout: Duration, ) -> Result<(), SubstrateError>
Stop then remove — the common cleanup composition, idempotent against “already gone” (a not-found from either step is not an error: a caller cleaning up after a partially-failed run should not itself fail because there was nothing left to clean up).
Sourcepub async fn wait_until_running(
&self,
container_id: &str,
timeout: Duration,
) -> Result<(), SubstrateError>
pub async fn wait_until_running( &self, container_id: &str, timeout: Duration, ) -> Result<(), SubstrateError>
Poll until the container’s State.Running is true and stays
true past a short grace period, or timeout elapses. See this
module’s doc for exactly what this does and doesn’t prove.
Sourcepub async fn ensure_network(&self, name: &str) -> Result<(), SubstrateError>
pub async fn ensure_network(&self, name: &str) -> Result<(), SubstrateError>
Idempotently make sure the user-defined bridge network name
exists, for ContainerSpec::network. List-then-create, with a
create that loses a race to another caller (409) treated as success.
dockerd’s name filter is a substring match, so the exact name is
re-checked here.
Sourcepub async fn published_host_port(
&self,
container_id: &str,
container_port: u16,
protocol: Protocol,
) -> Result<Option<u16>, SubstrateError>
pub async fn published_host_port( &self, container_id: &str, container_port: u16, protocol: Protocol, ) -> Result<Option<u16>, SubstrateError>
The host port dockerd bound for container_port/protocol on a
running container, if any — how a caller learns the port when the
PortMapping left host_port as None. Returns the first
binding when the port is published on several interfaces.
Sourcepub async fn inspect(
&self,
container_id: &str,
) -> Result<ContainerInspectResponse, SubstrateError>
pub async fn inspect( &self, container_id: &str, ) -> Result<ContainerInspectResponse, SubstrateError>
Raw inspect_container passthrough, for callers that need more
than this module’s own convenience accessors.
Sourcepub async fn container_ref(
&self,
container_id: &str,
) -> Result<ContainerRef, SubstrateError>
pub async fn container_ref( &self, container_id: &str, ) -> Result<ContainerRef, SubstrateError>
Resolve a ContainerRef for a currently-running container — the
concrete slice principal.rs’s own doc flags as deferred to
lifecycle. Resolves container_id/uid from the container’s
real host pid via dockerd’s own inspect + /proc, then composes
cgroup::resolve_cgroup_path and mount::resolve_mount_namespace
to fill in the optional facts.
cgroup/mount_ns resolution is best-effort: a failure there
(e.g. the real, documented permission boundary
mount::resolve_mount_namespace hits against a root-owned
container when called by a non-root caller) is logged and leaves
that field None, rather than failing the whole ContainerRef —
they were already Options for exactly this reason. A failure to
resolve the container’s pid/uid at all is fatal: those two
fields are not optional on ContainerRef.