Struct Store 

pub struct Store { /* private fields */ }

The global content-addressable store, owned by aube.

Default location: $XDG_DATA_HOME/aube/store/v1/files/ (falling back to ~/.local/share/aube/store/v1/files/). Files are stored by BLAKE3 hash with two-char hex directory sharding. (Tarball-level integrity is still SHA-512 because that’s the format the npm registry returns; the per-file CAS key is an internal choice.)

Layout under the store-version directory (v1/):

• v1/files/ — CAS shards, content-addressed by BLAKE3 hex
• v1/index/ — cached package indexes (kept next to files/ so a single backup/mount captures the whole store; matches pnpm’s ~/.pnpm-store/v11/{files,index.db} grouping)

cache_dir (the cacheDir setting, default: the platform cache dir) still holds genuinely regenerable caches: the global virtual store and packument metadata.

Implementations

impl Store

pub fn ensure_shards_exist(&self) -> Result<(), Error>

Ensure every two-char shard directory under the CAS root exists. CAS files live under <root>/<ab>/<cdef...> for 256 possible prefixes. Running this once before a batch of import_bytes calls lets the per-file hot path skip the mkdirp(parent) stat entirely (the parent is guaranteed to exist). On APFS that removes ~7.5k redundant stat syscalls per cold install — the mkdirp inside xx::file::write was the #1 stat hotspot in a dtrace profile.

Cheap to call repeatedly: each create_dir_all is a no-op when the directory already exists, but callers should still hoist the call out of tight loops.

pub fn import_bytes( &self, content: &[u8], executable: bool, ) -> Result<StoredFile, Error>

Import a single file’s content into the store. Returns the stored file info.

Hot path on cold installs: callers should invoke Store::ensure_shards_exist once before a batch of imports so this function can skip the per-file mkdirp. When shards don’t exist yet, the create_new open will fail with NotFound; we fall back to the slow path for correctness.

pub fn import_bytes_gated( &self, rel_path: &str, content: &[u8], executable: bool, ) -> Result<StoredFile, Error>

Import a tar entry’s content, applying OS-level transparent compression to the entries the store-compression gate selects.

When AUBE_COMPRESS_STORE is unset this is exactly Store::import_bytes — same CAS key, same write path. When it is set and rel_path + size match the gate, the entry is first unwrapped if it is a napi --compress hybrid (so the CAS stores the raw .node, not the wrapper) and then written into the CAS as a transparently-compressed file in ONE pass via decmpfs::compress_bytes — never a write-then-read-back. The kernel decompresses on read, so the stored file keeps its logical size and exact bytes; cas_file_matches_len and the BLAKE3 CAS key are computed against that logical content, unchanged.

Fail-soft: compress_bytes itself falls back to a plain atomic write on an unsupported FS or any backend error, so a matched entry always lands. The gate firing only changes how the bytes are stored, never whether they are.

impl Store

pub fn load_index( &self, name: &str, version: &str, integrity: Option<&str>, ) -> Option<PackageIndex>

Load a cached package index, if it exists.

integrity, when Some, is the registry-advertised SRI digest (sha512-, or legacy sha1- / sha256- / sha384-) of the tarball these cache files came from — part of the cache key so the same (name, version) resolved from different sources (npm registry vs. github codeload vs. a proxy that served different bytes) can’t alias on disk and return each other’s file lists to the linker. None falls back to an unsuffixed <name>@<version>.json key so packages fetched through a registry proxy that strips dist.integrity can still warm-install — an integrity-less setup is already a degraded mode the user opted into via strict-store-integrity=false.

pub fn load_index_verified( &self, name: &str, version: &str, integrity: Option<&str>, ) -> Option<PackageIndex>

Load a package index, optionally verifying that all store files still exist. The verified variant is slower (stat per file) but detects a corrupted store.

pub fn invalidate_cached_index( &self, name: &str, version: &str, integrity: Option<&str>, ) -> Result<bool, Error>

Delete the cached package index for (name, version, integrity) if it exists. Used as a recovery hatch when the linker discovers a CAS shard referenced by the index has gone missing — the cached JSON points at a dead store_path, so the next install must re-derive the index by re-importing the tarball.

Ok(true) when an entry was removed; Ok(false) when there was nothing to remove (or the coordinate was invalid). Errors surface only on real I/O failure, not on the missing-file case.

pub fn save_index( &self, name: &str, version: &str, integrity: Option<&str>, index: &PackageIndex, ) -> Result<(), Error>

Save a package index to the cache.

See load_index for the semantics of integrity and the integrity-less fallback.

impl Store

pub fn import_directory(&self, dir: &Path) -> Result<PackageIndex, Error>

Import every file under a directory into the store, producing a PackageIndex keyed by paths relative to dir. Used by file: deps pointing at an on-disk package directory. Common noise (.git, node_modules) is skipped so local packages don’t drag the target’s own installed deps into the virtual store.

pub fn import_tarball( &self, tarball_bytes: &[u8], ) -> Result<PackageIndex, Error>

Import a tarball (.tgz) into the store. Returns a PackageIndex mapping relative paths to stored files.

Two-phase: serial tar walk that stages (rel_path, content, executable) triples (the tar reader is inherently sequential), then a CAS-write batch. When the staged batch crosses [PARALLEL_IMPORT_THRESHOLD] entries, the writes fan out via rayon::par_iter — the per-file CAS path is O_CREAT|O_EXCL and uses a shared &Store, so parallel writers are race-safe by construction (EEXIST on content collision is a success path because BLAKE3 paths are content-addressed).

AUBE_DISABLE_PARALLEL_IMPORT=1 forces the serial path. Use it as a regression killswitch if a future rayon scope inversion (linker symlink pass running concurrently) shows contention. Below the threshold the small-tarball overhead of rayon dispatch outweighs the win, so the cutover is conditional.

pub fn import_tarball_reader<R: Read>( &self, compressed_reader: R, ) -> Result<PackageIndex, Error>

Streaming variant. Accepts any compressed-tarball Read source so callers can pipe HTTP body chunks straight through without buffering the whole archive into memory first. Caps and CAS publish semantics match import_tarball exactly.

impl Store

pub fn default_location() -> Result<Self, Error>

Open the store at the platform default location (see dirs::store_dir and dirs::cache_dir).

aube’s own CLI resolves storeDir / cacheDir / globalVirtualStoreDir first and goes through Store::with_dirs; this is the entry point for embedders that just want the same directories a default install would use.

pub fn with_root(root: PathBuf) -> Result<Self, Error>

Open the store with an explicit CAS root, keeping the platform cache dir for the global virtual store and packument caches. Equivalent to with_dirs(root, dirs::cache_dir()).

pub fn with_dirs(root: PathBuf, cache_dir: PathBuf) -> Self

Open the store with an explicit CAS root and cache dir. Used when a user overrides storeDir (the CAS) and/or cacheDir (the global virtual store + packument caches); the two are independent settings, but the global virtual store hardlinks out of the CAS, so a caller pointing them at different volumes gives up the hardlink fast path.

root is the CAS shard directory (<storeDir>/v1/files), not the user-facing store dir. The global virtual store lands under cache_dir unless Store::with_virtual_store_dir moves it.

pub fn with_virtual_store_dir(self, dir: PathBuf) -> Self

Point the global virtual store somewhere other than <cache_dir>/virtual-store (the globalVirtualStoreDir setting). The path is used verbatim.

pub fn at(root: PathBuf) -> Self

Open the store at a specific path (cache dir derived from store root). Used by tests that need a fully isolated layout; production code should prefer with_dirs.

pub fn root(&self) -> &Path

pub fn store_v1_dir(&self) -> PathBuf

The store-version directory containing files/ and index/.

For the default layout this is <storeDir>/v1/ (parent of root, which is the files/ subdir). Matches the granularity of pnpm store path — a single cache-mount or backup covering this directory captures both the CAS shards and the cached package indexes, so they cannot drift apart.

Falls back to root itself when root has no parent (only possible at the filesystem root, which is never a real store).

pub fn index_dir(&self) -> PathBuf

Directory for cached package indexes. Lives next to files/ at <v1_dir>/index/ so the whole store is one mount/backup unit. Public so introspection commands (aube find-hash, aube store status, aube store prune) can walk it directly.

pub fn legacy_index_dir(&self) -> PathBuf

Legacy index location at $XDG_CACHE_HOME/aube/index/, where aube wrote cached package indexes before they were moved next to the CAS files. Used only by [migrate_legacy_index_dir]; new code should always go through [index_dir].

pub fn legacy_index_migration_needed(&self) -> bool

Whether opening this store for writes would migrate the legacy index.

pub fn maintenance_lock_path(&self) -> PathBuf

pub fn prepare_for_write(&self) -> Result<(), Error>

Acquire the shared writer lease and perform any pending legacy-index migration. The lease is retained by this Store and all of its clones.

pub fn lock_for_maintenance(&self) -> Result<StoreMaintenanceGuard, Error>

Acquire an exclusive lease for a complete prune plan/apply operation.

pub fn migrate_legacy_index_for_maintenance( &self, _guard: &StoreMaintenanceGuard, )

Apply the legacy-index migration while an exclusive maintenance lease is held. Used by real prune after its candidate plan is complete.

pub fn virtual_store_dir(&self) -> PathBuf

Directory for the global virtual store (materialized packages). <cacheDir>/virtual-store/ unless globalVirtualStoreDir moved it, so it follows cacheDir by default.

pub fn packument_cache_dir(&self) -> PathBuf

Directory for cached packument metadata (abbreviated/corgi format). Versioned so we can bump the schema without breaking old caches — old caches at older versions stay around until manually pruned.

pub fn packument_full_cache_dir(&self) -> PathBuf

Directory for cached full packument JSON (non-corgi) used by human-facing commands like aube view that need fields the resolver doesn’t parse (description, repository, license, keywords, maintainers). Separate from packument_cache_dir because the corgi and full responses have different shapes.

pub fn has(&self, integrity: &str) -> bool

Check if a file with the given integrity hash exists in the store.

pub fn file_path_from_integrity(&self, integrity: &str) -> Option<PathBuf>

Get the path to a file in the store by its integrity hash.

pub fn file_path_from_hex(&self, hex_hash: &str) -> PathBuf

Get the path to a file in the store by its hex hash.

Trait Implementations

impl Clone for Store

fn clone(&self) -> Store

Returns a duplicate of the value.

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

Performs copy-assignment from source.