Struct GlobalCache 

pub struct GlobalCache { /* private fields */ }

On-disk global cache for OCI layers and EROFS images.

Layout:

~/.microsandbox/cache/manifests/<sha256-of-ref>.json       # manifest + config metadata
~/.microsandbox/cache/tmp/<blob>.part                      # partial downloads
~/.microsandbox/cache/tmp/<blob>.download.lock             # download flock files
~/.microsandbox/cache/tmp/<blob>.work/                     # materialization work dirs
~/.microsandbox/cache/layers/<diff_id_safe>.erofs          # per-layer EROFS
~/.microsandbox/cache/layers/<diff_id_safe>.erofs.lock     # materialization flock
~/.microsandbox/cache/fsmeta/<manifest_safe>.erofs         # fsmeta EROFS (fsmerge metadata)
~/.microsandbox/cache/fsmeta/<manifest_safe>.erofs.lock    # materialization flock
~/.microsandbox/cache/vmdk/<manifest_safe>.vmdk            # VMDK descriptor
~/.microsandbox/cache/vmdk/<manifest_safe>.vmdk.lock       # materialization flock

Implementations

impl GlobalCache

pub fn operation(&self) -> Self

Start an operation scope. Its clones retain admitted entries until all clones are dropped. Keep this scope through publication of durable catalog ownership, including sandbox rows.

pub fn lease_paths(&self, paths: Vec<PathBuf>) -> ImageResult<Vec<StorageLease>>

Protect entries in stable path order. The returned leases cover this call’s reader; an operation scope additionally retains them through its caller’s publication.

pub async fn lease_paths_async( &self, paths: Vec<PathBuf>, ) -> ImageResult<Vec<StorageLease>>

Async counterpart of Self::lease_paths.

pub fn metadata_paths( &self, metadata: &CachedImageMetadata, ) -> ImageResult<Vec<PathBuf>>

All independently reclaimable entries belonging to this immutable manifest.

impl GlobalCache

pub fn new(cache_dir: &Path) -> ImageResult<Self>

Create a new GlobalCache using the provided cache directory.

Creates all subdirectories if they don’t exist.

pub async fn new_async(cache_dir: &Path) -> ImageResult<Self>

Create a new GlobalCache using async filesystem operations.

pub fn layers_dir(&self) -> &Path

Root layer EROFS cache directory.

pub fn layer_erofs_path(&self, diff_id: &Digest) -> PathBuf

Path to the per-layer EROFS image for a given diff_id.

pub fn layer_erofs_lock_path(&self, diff_id: &Digest) -> PathBuf

Path to the materialization lock for a layer EROFS image.

pub fn is_layer_materialized(&self, diff_id: &Digest) -> bool

Check if a layer EROFS image exists.

pub fn all_layers_materialized(&self, diff_ids: &[Digest]) -> bool

Check if all given layer diff_ids have materialized EROFS images.

pub fn fsmeta_dir(&self) -> &Path

Root fsmeta EROFS cache directory.

pub fn fsmeta_erofs_path(&self, manifest_digest: &Digest) -> PathBuf

Path to the fsmeta EROFS image for a given manifest digest.

pub fn fsmeta_erofs_lock_path(&self, manifest_digest: &Digest) -> PathBuf

Path to the materialization lock for a fsmeta EROFS image.

pub fn is_fsmeta_materialized(&self, manifest_digest: &Digest) -> bool

Check if a fsmeta EROFS image exists.

pub fn vmdk_dir(&self) -> &Path

Root VMDK cache directory.

pub fn vmdk_path(&self, manifest_digest: &Digest) -> PathBuf

Path to the VMDK descriptor for a given manifest digest.

pub fn vmdk_lock_path(&self, manifest_digest: &Digest) -> PathBuf

Path to the materialization lock for a VMDK descriptor.

pub fn is_vmdk_materialized(&self, manifest_digest: &Digest) -> bool

Check if a VMDK descriptor exists for a given manifest digest.

pub fn rewrite_vmdk( &self, manifest_digest: &Digest, layer_diff_ids: &[Digest], ) -> ImageResult<()>

Rewrite the VMDK descriptor for a manifest digest so its extents are this cache’s fsmeta and layer EROFS files.

Descriptors reference extents by absolute path, so one copied from another cache must be regenerated rather than reused.

pub fn flat_ref_path(&self, manifest_digest: &Digest) -> PathBuf

Path to the manifest-keyed flat rootfs reference.

pub fn flat_blob_path(&self, artifact_digest: &Digest) -> PathBuf

Path to the immutable content-addressed raw ext4 artifact.

pub fn flat_lock_path(&self, derivation_digest: &Digest) -> PathBuf

Path to the per-derivation flat materialization lock.

pub fn flat_work_dir(&self, derivation_digest: &Digest) -> PathBuf

Same-filesystem work directory for one flat-rootfs derivation.

pub fn publish_flat_blob( &self, candidate: &Path, artifact_digest: &Digest, expected_size: u64, ) -> ImageResult<PathBuf>

Publish a synchronized candidate as an immutable content-addressed blob.

pub fn read_flat_ref( &self, manifest_digest: &Digest, ) -> ImageResult<Option<FlatRootfsRef>>

Read and validate the manifest-keyed flat rootfs reference.

pub fn write_flat_ref( &self, manifest_digest: &Digest, reference: &FlatRootfsRef, ) -> ImageResult<()>

Atomically replace a flat rootfs reference after its immutable blob is durable.

pub fn tmp_dir(&self) -> &Path

Root staging directory.

pub fn part_path(&self, blob_digest: &Digest) -> PathBuf

Path to the partial download file for a blob.

pub fn download_lock_path(&self, blob_digest: &Digest) -> PathBuf

Path to the download lock file for a blob.

pub fn work_dir(&self, key: &Digest) -> PathBuf

Path to the materialization work directory for an EROFS build.

pub fn manifests_dir(&self) -> &Path

Root manifest metadata directory.

pub fn image_lock_path(&self, reference: &Reference) -> PathBuf

Path to the pull lock file for an image reference.

pub fn read_image_metadata( &self, reference: &Reference, ) -> ImageResult<Option<CachedImageMetadata>>

Read cached metadata for an image reference.

pub async fn read_image_metadata_async( &self, reference: &Reference, ) -> ImageResult<Option<CachedImageMetadata>>

Read and admit metadata without blocking the async executor on locks.

pub async fn write_image_metadata_async( &self, reference: &Reference, metadata: &CachedImageMetadata, ) -> ImageResult<()>

Publish metadata from an owned worker so cancellation cannot release its gate while the filesystem replacement is still in flight.

pub async fn install_image_metadata_if_compatible_async( &self, reference: &Reference, archived_bytes: Vec<u8>, ) -> ImageResult<()>

Install archived metadata without replacing an equivalent local entry. Recheck under the same publication gate used by image pulls, so a concurrent retag cannot be lost.

pub fn delete_image_metadata(&self, reference: &Reference) -> ImageResult<()>

Delete cached metadata for an image reference.

pub async fn delete_image_metadata_async( &self, reference: &Reference, ) -> ImageResult<()>

Delete cached metadata for an image reference using async filesystem I/O.

pub fn image_metadata_path(&self, reference: &Reference) -> PathBuf

Path to the cached metadata file for an image reference.

pub fn tar_path(&self, digest: &Digest) -> PathBuf

Path to the cached compressed tarball for a layer blob.

Trait Implementations

impl Clone for GlobalCache

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.