Skip to main content

Crate skif_cache

Crate skif_cache 

Source
Expand description

skif’s disk cache store (ADR 0007): a CacheStore over one cache location that holds a store per base.

This crate is an implementation detail of skif, re-exported as skif::cache behind the cache-disk feature; it carries no stability promise of its own. It is the one skif library crate that reads and writes files outside the FileSystem trait, and only below the cache location it is given. It reads no environment: the host passes the location and, for default_location, the platform’s per-user cache directory.

§Layout

<location>/
  CACHEDIR.TAG, .gitignore      written when skif creates the directory
  <base key>/                   one store per base (32 hex digits, see `base_key`)
    base                        the base it belongs to, for `skif cache stats`
    .lock                       the try-lock of a write
    <namespace>.bin             one file per namespace (`modules.bin`)
    <file>.<random>.tmp         a write in progress; one a killed writer left goes with the next write

A namespace file is:

magic    8 bytes   "SKIFSTOR"
format   u32 LE    2
name     u8 length, then the namespace name
schema   u32 LE    the namespace schema it was written under
count    u32 LE
records  count times, sorted by key: key [u8; 32], length u32 LE, value (skif's sealed envelope)

A file that does not match this layout in every byte, or was written under another schema, is empty; skif verifies every value it reads, so a damaged record is a miss.

§Policy

  • A base inside a git repository is identified by the git directory its worktrees share and its path in the repository, so the worktrees of one repository share a store and two repositories never do; a base outside git is identified by its absolute path.
  • DiskStore::finish_run writes, per namespace, exactly the entries the run used, so a run never prunes a namespace it did not ask for, and a namespace the run used in full is not rewritten. Runs that lint different sets of files in turn (skif and skif --production) therefore each drop what only the other used. DiskStore::finish_failed_run, for a run that did not complete, adds what the run computed and drops nothing.
  • A write takes a try-lock on the store and is skipped when another process holds it; files are written to a new temporary file with a random name, never through a link, and renamed, so a reader sees the old file or the new one. Temporary files a killed writer left are removed under the lock before the next write.
  • A namespace file larger than the cap is not read: no write leaves one, so it is not a file of this store.
  • After a write, a location over its cap drops the stores of other bases, least recently written first, unless the host turned that off (DiskStoreOptions::with_evict_others); a store that alone exceeds the cap keeps modules entries first, then the other namespaces, in key order, up to it.
  • A directory the store creates gets a CACHEDIR.TAG and a .gitignore of *, written only where no such file exists, and it never creates a directory named node_modules.

Structs§

CacheStats
What a cache location holds, as stats reports it.
CleanReport
What clean removed.
DiskStore
skif’s disk cache store: the store of one base in a cache location (see the crate documentation).
DiskStoreOptions
How a DiskStore behaves.
NamespaceStats
One namespace of a store, as stats reports it.
StoreStats
One store of a location, as stats reports it.

Enums§

Finish
What DiskStore::finish_run did.
StoreError
A store’s write failed.

Constants§

DEFAULT_MAX_SIZE
The cap of a location when the host sets none: 512 MiB.

Functions§

base_key
The key of the store of base in a location, as DiskStore::open names its directory.
clean
Removes the store of base from location, or with base None every store in it, then the location itself when nothing but skif’s own tag files is left. Only the files a store wrote are removed, from directories named like a base key that hold a store’s lock or base file, so a location shared with another tool (the downloads of the pre-commit launcher, which also reads SKIF_CACHE_DIR) keeps every file skif did not write. A missing location is clean. A store that cannot be removed does not keep the others: they are removed first.
default_location
The cache location a host uses when the user named none, given the base of the run and the platform’s per-user cache directory: <base>/node_modules/.cache/skif when node_modules exists (skif never creates it), else <user_cache_dir>/skif, else None, for a cache in memory for the run.
stats
What location holds: every store with its namespaces, entries and sizes. A missing location holds nothing, and a store that cannot be read is listed as unreadable.