Struct BundleBuilder 

pub struct BundleBuilder { /* private fields */ }

Builder for OCI container bundles

Creates the directory structure and config.json required for OCI-compliant container runtimes like runc or youki.

Example

let dirs = zlayer_paths::ZLayerDirs::system_default();
let builder = BundleBuilder::new(dirs.bundles().join("mycontainer"))
    .with_rootfs(dirs.rootfs().join("myimage"));

let bundle_path = builder.build(&container_id, &service_spec).await?;

Implementations

impl BundleBuilder

pub fn new(bundle_dir: PathBuf) -> Self

Create a new BundleBuilder with the specified bundle directory

The bundle directory will be created if it doesn’t exist. The structure will be:

{bundle_dir}/
├── config.json
└── rootfs/  (symlink to actual rootfs or mount point)

pub fn for_container(container_id: &ContainerId) -> Self

Create a BundleBuilder for a container in the default bundle location

pub fn with_rootfs(self, rootfs_path: PathBuf) -> Self

Set the rootfs path (from unpacked image layers)

This path will be symlinked into the bundle as rootfs/

pub fn with_hostname(self, hostname: String) -> Self

Set a custom hostname for the container

pub fn with_env(self, key: String, value: String) -> Self

Add extra environment variables

pub fn with_cwd(self, cwd: String) -> Self

Set the working directory

pub fn with_args(self, args: Vec<String>) -> Self

Set the command/args to run

pub fn with_volume_paths(self, volume_paths: HashMap<String, PathBuf>) -> Self

Set pre-resolved volume paths from StorageManager

These are used to map named/anonymous/S3 volumes to their host paths when building storage mounts in the OCI spec.

pub fn with_image_config(self, config: ImageConfig) -> Self

Set the OCI image configuration (entrypoint, cmd, env, workdir, user)

When set, the image config provides defaults for the container process that are used when the deployment spec doesn’t override them.

pub fn with_host_network(self, host_network: bool) -> Self

Enable host networking mode

When true, the container will NOT get its own network namespace and will share the host’s network stack. This is equivalent to Docker’s --network host. Use this when overlay networking is unavailable or not desired.

pub fn with_secrets_provider(self, provider: Arc<dyn SecretsProvider>) -> Self

Set the secrets provider for resolving $S: prefixed environment variables

When set, environment variables with $S:secret-name syntax will be resolved from this provider at bundle creation time.

pub fn with_deployment_scope(self, scope: String) -> Self

Set the deployment scope for secret lookups

This is typically the deployment name and is used as the scope when resolving $S: prefixed environment variables.

pub fn with_socket_mount(self, path: impl Into<String>) -> Self

Set a host-side Unix socket path to bind-mount into the container at the default ZLayer socket path (read-only).

pub fn bundle_dir(&self) -> &Path

Get the bundle directory path

pub async fn build( &self, container_id: &ContainerId, spec: &ServiceSpec, ) -> Result<PathBuf>

Build the OCI bundle from a ServiceSpec

Creates the bundle directory structure and generates config.json based on the provided service specification.

Returns

The path to the bundle directory on success

Errors

• AgentError::CreateFailed if directory creation fails
• AgentError::InvalidSpec if the OCI spec generation fails

pub async fn build_spec_only( &self, container_id: &ContainerId, spec: &ServiceSpec, volume_paths: &HashMap<String, PathBuf>, ) -> Result<Spec>

Render the OCI runtime spec without creating a bundle directory or writing config.json.

Used by the WSL2 delegate runtime (runtimes/wsl2_delegate.rs): the Windows host renders the spec, then streams the JSON into the WSL distro filesystem where youki will consume it. The bundle path passed to BundleBuilder::new is purely informational in that flow; this method never touches the filesystem.

Errors

Returns AgentError::InvalidSpec if the spec generation fails.

pub async fn write_config( &self, container_id: &ContainerId, spec: &ServiceSpec, ) -> Result<PathBuf>

Generate the OCI spec and write config.json to the bundle directory

Unlike build(), this does NOT create the bundle directory or set up rootfs. Use this when the bundle directory and rootfs already exist (e.g., rootfs was extracted directly by LayerUnpacker).

Errors

Returns an error if the OCI spec cannot be built or config.json cannot be written.

Returns

The path to the bundle directory on success

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

Clean up a bundle directory

Removes the bundle directory and all its contents.

Errors

Returns an error if the bundle directory cannot be removed.

Trait Implementations

impl Clone for BundleBuilder

fn clone(&self) -> BundleBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BundleBuilder

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

Formats the value using the given formatter.