Module cache_layout 

Shared layout and safety rules for the on-disk extraction cache.

The runtime and the packer CLI both read and write this cache. They used to answer “where is it, and is it safe to use” independently, and drifted: one required an absolute env-derived path and a 0700 uid-owned directory, the other happily fell back to a shared /tmp. Both now go through here.

The current user id is a parameter rather than a call, so this crate stays dependency-free; each caller already has a way to ask the OS.

Layout under the resolved root:

pkg/<id>              extracted package tree
pkg/.<id>.ready       completion marker, written only after a full extract
pkg/.<id>.tmp         extraction scratch, renamed to pkg/<id> on success
cas/<aa>/<hash>       content blob, hardlinked into package trees
meta/<id>             last-used timestamp
lock/<id>             in-use lock, held shared for an instance's lifetime
lock/<id>.extract     extraction mutex

Functions

cas_lock_path

Store-wide lock separating extraction from collection.

ensure_safe_dir

Ensure dir is a 0700 directory owned by uid, creating it atomically at that mode when absent. Returns false if it exists as a symlink or as another user’s directory, which are never chmod’d through; a real directory we own but with loose permissions is tightened in place.

extract_lock_path

Extraction mutex for package_id, distinct from the in-use lock so a second runner waits only for extraction, not for the first instance’s whole lifetime.

is_safe_owned_dir

True if path is a real directory (not a symlink) owned by uid with no group or other permission bits. Uses symlink_metadata, so a planted symlink is rejected rather than followed.

lock_path

In-use lock for package_id, held shared for an instance’s lifetime.

meta_path

Last-used timestamp for package_id.

pkg_dir

Extracted tree for package_id.

ready_marker

Completion marker for package_id. Its presence is what distinguishes a fully extracted tree from one an interrupted run left behind.

resolve_root

Resolve the cache root, or None when no safe location can be established. Callers MUST treat None as a refusal rather than substituting a guess: a shared world-writable fallback is what this function exists to prevent.