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//! - [`cache`]: the [`Cache`] handle bound to a
35//!   [`haz_vfs::WritableFilesystem`] and a workspace root.
36//! - [`lookup`]: [`Cache::lookup`] per `CACHE-014`..`CACHE-016`.
37//! - [`store`]: [`Cache::store`] per `CACHE-017`..`CACHE-018`.
38//! - [`restore`]: [`Cache::restore`] per `CACHE-019`..`CACHE-020`.
39//! - [`clean`]: [`Cache::clear`] and [`Cache::clean`] per
40//!   `CACHE-021`..`CACHE-022` and `AUX-022`..`AUX-027`.
41//! - [`info`]: [`Cache::info`] read-only introspection per
42//!   `AUX-017`..`AUX-021`.
43
44#![deny(missing_docs)]
45
46pub mod cache;
47pub mod clean;
48pub mod hasher;
49pub mod hex;
50pub mod info;
51pub mod key;
52pub mod layout;
53pub mod lookup;
54pub mod manifest;
55pub mod restore;
56pub mod store;
57
58pub use cache::Cache;
59pub use clean::{CleanError, CleanOptions, CleanReport, EvictedEntry, EvictionMode};
60pub use hasher::Hasher;
61pub use hex::HexError;
62pub use info::{CacheInfoError, CacheInfoReport, SchemaPrefix};
63pub use key::{
64    CHAPTER_REVISION, CacheKey, CacheKeyBuilder, CacheKeyInputs, EnvContribution, InputFile,
65    PredecessorStreams, hash_function_id, schema_version_prefix,
66};
67pub use lookup::{CacheLookupError, CacheLookupStatus};
68pub use manifest::{HashFunctionLabel, Manifest, ManifestParseError, OutputBlob};
69pub use restore::{RestoreError, RestoredStreams};
70pub use store::{StoreError, StoreInputs, StoredOutput};
haz_cache/lib.rs

haz_cache/
lib.rs
