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 writeA 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_runwrites, 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 (skifandskif --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 keepsmodulesentries first, then the other namespaces, in key order, up to it. - A directory the store creates gets a
CACHEDIR.TAGand a.gitignoreof*, written only where no such file exists, and it never creates a directory namednode_modules.
Structs§
- Cache
Stats - What a cache location holds, as
statsreports it. - Clean
Report - What
cleanremoved. - Disk
Store - skif’s disk cache store: the store of one base in a cache location (see the crate documentation).
- Disk
Store Options - How a
DiskStorebehaves. - Namespace
Stats - One namespace of a store, as
statsreports it. - Store
Stats - One store of a location, as
statsreports it.
Enums§
- Finish
- What
DiskStore::finish_rundid. - Store
Error - 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
basein a location, asDiskStore::opennames its directory. - clean
- Removes the store of
basefromlocation, or withbaseNoneevery 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 readsSKIF_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/skifwhennode_modulesexists (skif never creates it), else<user_cache_dir>/skif, elseNone, for a cache in memory for the run. - stats
- What
locationholds: every store with its namespaces, entries and sizes. A missing location holds nothing, and a store that cannot be read is listed as unreadable.