Struct RedpandaGuard 

pub struct RedpandaGuard(/* private fields */);

The running guard for a RedpandaContainer.

Implementations

impl RedpandaGuard

pub fn bootstrap_servers(&self) -> String

The PLAINTEXT:// bootstrap-servers address for the running broker (EXTERNAL listener).

pub fn schema_registry_url(&self) -> String

The schema registry’s base URI for the running broker.

pub async fn stop(self) -> Result<()>

Stops and removes the container, releasing its host ports.

Methods from Deref<Target = ContainerGuard>

pub fn network(&self) -> Option<&Arc<Network>>

The network this container joined, if any — a module may use this to resolve a sibling’s alias from the guard itself rather than needing to keep a separate Network reference around.

pub fn host(&self) -> &str

The host address published ports are reachable on — always loopback.

pub fn name(&self) -> &str

The backend-facing sandbox name (e.g. rz-<run-id>-<seq>, or rz-reuse-<12hex> for a reuse container — see Container::reuse). This is always the human-readable ledger/reaping name, on every backend — never the docker daemon’s opaque container id — matching what the diagnostics report and the reaping ledger both name this sandbox.

pub fn get_mapped_port(&self, guest_port: u16) -> Result<u16, RightsizeError>

The host port guest_port is published on.

Distinguishes two failure causes: if this guard isn’t running (stopped, or never successfully started), the error says so; if it IS running but guest_port was never declared via with_exposed_ports, the error says the port isn’t exposed.

pub async fn logs(&self) -> Result<String, RightsizeError>

The full logs captured so far. Requires the container to be running.

pub async fn exec(&self, cmd: &[&str]) -> Result<ExecResult, RightsizeError>

Runs cmd inside the running container and returns its exit code and captured output.

pub async fn copy_file_to_container( &self, host_path: impl AsRef<Path>, container_path: &str, ) -> Result<(), RightsizeError>

Copies host_path (a file or directory) into this RUNNING container at container_path — the RUNTIME counterpart to a start-time Container::with_copy_file_to_container mount, usable any time after start() rather than only pre-boot. container_path must be absolute (both backend CLIs require a NAME:/abs/path shape); its parent directory is created in the guest first (mkdir -p), so the destination never has to pre-exist. Directory semantics match cp -r/docker cp/msb copy themselves: copying a directory to an absent destination produces the destination as a copy of the source (contents under the destination, not nested one level deeper).

Requires this guard to currently be running and container_path to be absolute — both checked BEFORE any backend call, same state-error shape as Self::exec/Self::logs. Works on a reuse container (it’s an ordinary runtime operation), but mutates shared reused state and is NOT part of the reuse identity hash — see the reuse docs.

pub async fn copy_content_to_container( &self, content: impl AsRef<[u8]>, container_path: &str, ) -> Result<(), RightsizeError>

Convenience for Self::copy_file_to_container when the content to copy in only exists in memory: writes content to a private (mode 0600 on unix) temp file, delegates to Self::copy_file_to_container, and removes the temp file afterward regardless of the outcome. No streaming protocol — this is exactly the file path, minus the caller having to manage one.

pub async fn copy_file_from_container( &self, container_path: &str, host_path: impl AsRef<Path>, ) -> Result<(), RightsizeError>

The reverse direction of Self::copy_file_to_container: copies container_path (a file or directory) out of this RUNNING container to host_path. host_path’s parent directory is created on the host first (via the stdlib), so the destination never has to pre-exist. Same running/absolute-path checks as the copy-in direction, in the same order, before any backend call.

pub async fn checkpoint(&self) -> Result<Checkpoint, RightsizeError>

Checkpoints this RUNNING container via the active backend’s own create_checkpoint mechanism (docker: image commit; microsandbox: disk snapshot), and returns a Checkpoint carrying the resulting ref, which backend created it, and this container’s full spec (see Checkpoint’s own doc for the “filesystem capture, not memory” semantics and Container::from_checkpoint for restoring from the result).

Gated on crate::backend::Capabilities::checkpoint BEFORE any backend call: on a backend that doesn’t support it (a test double only — both real backends do), this returns RightsizeError::CheckpointUnsupported without ever reaching create_checkpoint. Requires this guard to currently be running — a state error otherwise, same shape as Self::exec/Self::logs.

When the backend’s checkpoint mechanism restarts the sandbox’s workload (capabilities().checkpoint_restarts_workload — microsandbox’s stop/ snapshot/start cycle reboots the guest), this re-installs this container’s network links (if any were installed at start() time — a reboot kills msb’s emulated exec-tunnel links along with everything else in the guest) and then re-runs the container’s own configured wait strategy before returning, so a caller never gets back a false-ready or unreachable-by-alias container. Docker’s image commit leaves the container undisturbed, so neither re-installation nor re-wait runs there.

pub async fn checkpoint_named( &self, name: &str, ) -> Result<Checkpoint, RightsizeError>

Named counterpart to Self::checkpoint: everything that method does (the capability gate, the running-guard check, the backend create_checkpoint call, and — on a backend whose checkpoint mechanism restarts the workload — the network-relink-then-rewait dance) applies here identically, PLUS a durable, rediscoverable registry entry under name (see the checkpoints docs’ “Reusing checkpoints across runs” section and Checkpoint::find/Checkpoint::list/Checkpoint::remove).

name must match ^[a-z0-9][a-z0-9-]{0,40}$ — RightsizeError::InvalidCheckpointName before any backend call or registry I/O otherwise, the same up-front gate every named-checkpoint entry point shares.

Re-checkpointing an existing name REPLACES it: if the registry already has an entry for name, this best-effort removes that entry’s backend-native artifact BEFORE taking the new checkpoint — but only when that entry’s backend matches the currently active one, mirroring Checkpoint::find’s own same-backend gate. If the entry belongs to a different backend, the removal call is skipped outright (the active backend has no business operating on a ref format it didn’t create) and that artifact is left behind under its original backend. Either way, the registry entry itself is rewritten once the new checkpoint succeeds. Latest wins in the registry; a skipped cross-backend artifact has to be cleaned up manually under the backend that created it (see the checkpoints docs’ cross-run section).

The registry write happens ONLY after the backend checkpoint itself has succeeded — a create_checkpoint failure leaves any existing registry entry for name exactly as it was (already removed above, in the replace case — so a failed re-checkpoint does lose the old entry; there is no atomic “keep the old one if the new one fails” here, matching the backend-level reality that the old artifact was already best-effort torn down before the new one was attempted).

pub async fn follow_output( &self, consumer: impl Fn(String) + Send + Sync + 'static, ) -> Result<FollowHandle, RightsizeError>

Streams log lines to consumer as they’re produced. Closing (or dropping) the returned crate::backend::FollowHandle halts delivery — no further lines reach consumer afterward, even if the container keeps running.

pub fn is_running(&self) -> bool

True from a successful start() until stop(); false before the first start() and after.

Trait Implementations

impl Deref for RedpandaGuard

type Target = ContainerGuard

The resulting type after dereferencing.

fn deref(&self) -> &ContainerGuard

Dereferences the value.