haz_cache/
lib.rs

1//! Content-addressable cache for `haz` task outputs, stdout, and
2//! stderr.
3//!
4//! Implements the model defined in chapter 9 of the specification:
5//! cache-key composition (`CACHE-001..009`), on-disk entry layout
6//! (`CACHE-010..013`), lookup (`CACHE-014..016`), two-phase store
7//! (`CACHE-017..018`), restoration (`CACHE-019..020`), and
8//! invalidation (`CACHE-021..022`).
9//!
10//! The whole machinery is engineered to satisfy the central
11//! `CACHE-023` correctness claim: a cache hit MUST be
12//! observationally equivalent to a fresh run. Every other rule in
13//! chapter 9 (canonical key derivation, atomic publish, schema-
14//! mismatch invalidation, ...) exists to keep that invariant.
15//!
16//! The cache is content-addressed: a task's identity (project name,
17//! task name) does NOT contribute to its key. Two tasks with
18//! byte-identical inputs, identical commands, and identical
19//! environments produce equal keys and MAY share a single entry on
20//! disk.
21//!
22//! # Module map
23//!
24//! - [`hasher`]: dispatch over the two specification-recognised
25//!   hash functions (BLAKE3 by default, SHA-256 by opt-in).
26//! - [`key`]: cache-key type, schema-version prefix, and canonical
27//!   serialisation of the key's components.
28//! - [`hex`]: lowercase-hex encoding/decoding for 32-byte digests
29//!   shared by the cache key and the manifest.
30//! - [`manifest`]: on-disk manifest format (`CACHE-011`),
31//!   serialised as JSON.
32//! - [`layout`]: pure path-computation helpers for the sharded
33//!   entry layout (`CACHE-010`).
34//! - [`reader`]: the [`CacheReader`] handle bound to a
35//!   [`haz_vfs::Filesystem`] and a workspace root; read-only
36//!   surface of the cache.
37//! - [`writer`]: the [`CacheWriter`] handle bound to a
38//!   [`haz_vfs::WritableFilesystem`] and a workspace root; write-
39//!   side surface, composing a [`CacheReader`] for reads.
40//! - [`lookup`]: [`CacheReader::lookup`] per `CACHE-014`..`CACHE-016`.
41//! - [`store`]: [`CacheWriter::store`] per `CACHE-017`..`CACHE-018`.
42//! - [`restore`]: [`CacheWriter::restore`] per `CACHE-019`..`CACHE-020`.
43//! - [`clean`]: [`CacheWriter::clear`] and [`CacheWriter::clean`]
44//!   per `CACHE-021`..`CACHE-022` and `AUX-022`..`AUX-027`.
45//! - [`info`]: [`CacheReader::info`] read-only introspection per
46//!   `AUX-017`..`AUX-021`.
47
48#![deny(missing_docs)]
49
50pub mod clean;
51pub mod hasher;
52pub mod hex;
53pub mod info;
54pub mod key;
55pub mod layout;
56pub mod lookup;
57pub mod manifest;
58pub mod reader;
59pub mod restore;
60pub mod store;
61pub mod writer;
62
63pub use clean::{
64    CleanError, CleanFailure, CleanOptions, CleanOutcome, CleanReport, EvictedEntry, EvictionMode,
65};
66pub use hasher::Hasher;
67pub use hex::HexError;
68pub use info::{CacheInfoError, CacheInfoReport, SchemaPrefix};
69pub use key::{
70    CHAPTER_REVISION, CacheKey, CacheKeyBuilder, CacheKeyInputs, EnvContribution, InputFile,
71    PredecessorStreams, hash_function_id, schema_version_prefix,
72};
73pub use lookup::{CacheLookupError, CacheLookupStatus};
74pub use manifest::{HashFunctionLabel, Manifest, ManifestParseError, OutputBlob};
75pub use reader::CacheReader;
76pub use restore::{RestoreError, RestoredStreams};
77pub use store::{StoreError, StoreInputs, StoredOutput};
78pub use writer::CacheWriter;
haz_cache/lib.rs

haz_cache/
lib.rs
