haz-cache 0.2.0

Content-addressed cache for haz task outputs using BLAKE3.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

//! Content-addressable cache for `haz` task outputs, stdout, and
//! stderr.
//!
//! Implements the model defined in chapter 9 of the specification:
//! cache-key composition (`CACHE-001..009`), on-disk entry layout
//! (`CACHE-010..013`), lookup (`CACHE-014..016`), two-phase store
//! (`CACHE-017..018`), restoration (`CACHE-019..020`), and
//! invalidation (`CACHE-021..022`).
//!
//! The whole machinery is engineered to satisfy the central
//! `CACHE-023` correctness claim: a cache hit MUST be
//! observationally equivalent to a fresh run. Every other rule in
//! chapter 9 (canonical key derivation, atomic publish, schema-
//! mismatch invalidation, ...) exists to keep that invariant.
//!
//! The cache is content-addressed: a task's identity (project name,
//! task name) does NOT contribute to its key. Two tasks with
//! byte-identical inputs, identical commands, and identical
//! environments produce equal keys and MAY share a single entry on
//! disk.
//!
//! # Module map
//!
//! - [`hasher`]: dispatch over the two specification-recognised
//!   hash functions (BLAKE3 by default, SHA-256 by opt-in).
//! - [`key`]: cache-key type, schema-version prefix, and canonical
//!   serialisation of the key's components.
//! - [`hex`]: lowercase-hex encoding/decoding for 32-byte digests
//!   shared by the cache key and the manifest.
//! - [`manifest`]: on-disk manifest format (`CACHE-011`),
//!   serialised as JSON.
//! - [`layout`]: pure path-computation helpers for the sharded
//!   entry layout (`CACHE-010`).
//! - [`reader`]: the [`CacheReader`] handle bound to a
//!   [`haz_vfs::Filesystem`] and a workspace root; read-only
//!   surface of the cache.
//! - [`writer`]: the [`CacheWriter`] handle bound to a
//!   [`haz_vfs::WritableFilesystem`] and a workspace root; write-
//!   side surface, composing a [`CacheReader`] for reads.
//! - [`lookup`]: [`CacheReader::lookup`] per `CACHE-014`..`CACHE-016`.
//! - [`store`]: [`CacheWriter::store`] per `CACHE-017`..`CACHE-018`.
//! - [`restore`]: [`CacheWriter::restore`] per `CACHE-019`..`CACHE-020`.
//! - [`clean`]: [`CacheWriter::clear`] and [`CacheWriter::clean`]
//!   per `CACHE-021`..`CACHE-022` and `AUX-022`..`AUX-027`.
//! - [`info`]: [`CacheReader::info`] read-only introspection per
//!   `AUX-017`..`AUX-021`.

#![deny(missing_docs)]

pub mod clean;
pub mod hasher;
pub mod hex;
pub mod info;
pub mod key;
pub mod layout;
pub mod lookup;
pub mod manifest;
pub mod reader;
pub mod restore;
pub mod store;
pub mod writer;

pub use clean::{
    CleanError, CleanFailure, CleanOptions, CleanOutcome, CleanReport, EvictedEntry, EvictionMode,
};
pub use hasher::Hasher;
pub use hex::HexError;
pub use info::{CacheInfoError, CacheInfoReport, SchemaPrefix};
pub use key::{
    CHAPTER_REVISION, CacheKey, CacheKeyBuilder, CacheKeyInputs, EnvContribution, InputFile,
    PredecessorStreams, hash_function_id, schema_version_prefix,
};
pub use lookup::{CacheLookupError, CacheLookupStatus};
pub use manifest::{HashFunctionLabel, Manifest, ManifestParseError, OutputBlob};
pub use reader::CacheReader;
pub use restore::{RestoreError, RestoredStreams};
pub use store::{StoreError, StoreInputs, StoredOutput};
pub use writer::CacheWriter;