Skip to main content

Lifecycle

Struct Lifecycle 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more