fallow_graph/cache/store.rs
1//! Persisted graph-cache store: coarse all-or-nothing load / save of a
2//! previously-built [`ModuleGraph`].
3//!
4//! Mirrors the extraction cache store (`fallow_extract::cache::store`): the
5//! payload is postcard-encoded, written atomically via a uniquely named temp
6//! file plus best-effort fsync and rename, and a `.gitignore` is written alongside
7//! so `.fallow/` is never committed. Every IO error is swallowed (the graph
8//! cache is best-effort and must never fail analysis); a corrupt or
9//! version-mismatched file misses and the graph is rebuilt fresh, but the
10//! loader names WHY it missed through [`CacheRejection`] so the run can report
11//! a refusal instead of leaving it indistinguishable from a first run.
12
13use std::path::Path;
14
15use fallow_types::cache_rejection::CacheRejection;
16use fallow_types::path_guard::CacheTarget;
17use serde::{Deserialize, Serialize};
18
19use super::{CachedResolvedProject, GRAPH_CACHE_VERSION, GraphCacheManifest};
20use crate::graph::ModuleGraph;
21
22/// Filename of the persisted graph cache inside the cache directory.
23pub const GRAPH_CACHE_FILE: &str = "graph-cache.bin";
24
25/// On-disk graph cache entry: a manifest plus the graph it validates.
26#[derive(Serialize, Deserialize)]
27pub struct GraphCacheStore {
28 /// Schema version. Checked on load; a mismatch misses so a stale file from
29 /// an older binary is never deserialized into the wrong shape.
30 pub version: u32,
31 /// Inputs that must match the current run for the graph to be trusted.
32 pub manifest: GraphCacheManifest,
33 /// The previously-built graph. Its `namespace_imported` bitset is
34 /// `#[serde(skip)]`, so the loader reconstructs it from the edge set.
35 pub graph: ModuleGraph,
36 /// Resolver output aligned with the cached graph. Exact manifest hits use
37 /// it alongside the graph; stable-key resolver hits remap it and rebuild
38 /// the graph with current `FileId`s.
39 pub resolved_project: CachedResolvedProject,
40}
41
42impl GraphCacheStore {
43 /// Load the persisted graph cache from `cache_dir`.
44 ///
45 /// # Errors
46 ///
47 /// Returns the [`CacheRejection`] that decided against reuse: the file is
48 /// missing, undecodable, or written for a different
49 /// `GRAPH_CACHE_VERSION`. The caller compares the loaded manifest against
50 /// the current inputs before trusting the graph or resolver payload, and
51 /// reports its own rejection reason for that comparison.
52 ///
53 /// The version is read from the file header BEFORE the payload is
54 /// decoded. A format bump changes the encoded shape, so a blob
55 /// from the previous release fails to decode and a version comparison made
56 /// afterwards is unreachable on the one event that triggers it most: an
57 /// upgrade. `fallow doctor` reports this reason verbatim, so a routine
58 /// version bump must not read as corruption, and a file that is not a
59 /// fallow cache at all must not read as a version bump.
60 ///
61 /// A file that existed and was then refused logs at warn: the run paid the
62 /// read and the decode and reused nothing. A missing file stays quiet.
63 pub fn load(cache_dir: &Path) -> Result<Self, CacheRejection> {
64 let cache_file = cache_dir.join(GRAPH_CACHE_FILE);
65 let data = std::fs::read(&cache_file).map_err(|error| {
66 if error.kind() == std::io::ErrorKind::NotFound {
67 return CacheRejection::Absent;
68 }
69 tracing::warn!("Cache file could not be read; check the path and permissions");
70 CacheRejection::Unreadable
71 })?;
72 let payload = read_header(&data)?;
73 let mut store: Self = match postcard::from_bytes(payload) {
74 Ok(store) => store,
75 Err(_) => {
76 tracing::warn!(
77 "Graph cache carries the current format version but its payload could not be \
78 decoded, rebuilding"
79 );
80 return Err(CacheRejection::Undecodable);
81 }
82 };
83 // The header already agreed with `GRAPH_CACHE_VERSION`, so this catches
84 // only a file whose header and payload disagree.
85 if store.version != GRAPH_CACHE_VERSION {
86 tracing::warn!(
87 cached_version = store.version,
88 expected_version = GRAPH_CACHE_VERSION,
89 "Graph cache header and payload declare different format versions, rebuilding"
90 );
91 return Err(CacheRejection::VersionMismatch);
92 }
93 // `namespace_imported` is `#[serde(skip)]`; rebuild it from the persisted
94 // edges so the loaded graph is byte-identical to a fresh build.
95 store.graph.reconstruct_namespace_imported();
96 Ok(store)
97 }
98
99 /// Persist this graph cache to the cache directory of `target`, best-effort.
100 ///
101 /// Creates the cache directory, writes a `.gitignore`, encodes the store
102 /// with postcard, and writes `graph-cache.bin` atomically. Every IO error
103 /// is logged at debug and swallowed; the graph cache must never fail the
104 /// surrounding analysis run.
105 ///
106 /// A symlink that leaves the base of `target` skips the save.
107 pub fn save(&self, target: CacheTarget<'_>) {
108 if let Err(error) = target.check(&target.dir().join(GRAPH_CACHE_FILE)) {
109 tracing::debug!("Skipped the graph cache save: {error}");
110 return;
111 }
112 if let Err(error) = target.write_gitignore() {
113 tracing::debug!("Failed to write graph cache .gitignore: {error}");
114 // Continue: a missing .gitignore does not invalidate the cache file.
115 }
116
117 let encoded = match postcard::to_allocvec(self) {
118 Ok(bytes) => bytes,
119 Err(error) => {
120 tracing::debug!("Failed to encode graph cache: {error}");
121 return;
122 }
123 };
124
125 if let Err(error) = target.write_file(GRAPH_CACHE_FILE, &framed(self.version, &encoded)) {
126 tracing::debug!("Failed to write graph cache: {error}");
127 }
128 }
129}
130
131/// Marker written ahead of new graph-cache payload so the format version can
132/// be read without decoding the payload it describes.
133///
134/// Constant across format bumps: only the version field beside it moves. That
135/// lets future upgrades report an explicit version mismatch; older unframed
136/// caches still report an ambiguous decode failure.
137const GRAPH_CACHE_MAGIC: [u8; 4] = *b"FLWG";
138
139/// Bytes the framing adds ahead of the payload: the magic plus a little-endian
140/// `u32` format version.
141const GRAPH_CACHE_HEADER_LEN: usize = GRAPH_CACHE_MAGIC.len() + 4;
142
143/// Prepend the format header to an encoded payload.
144///
145/// The version comes from the store being written rather than from the
146/// constant, so the header always describes the payload behind it.
147fn framed(version: u32, payload: &[u8]) -> Vec<u8> {
148 let mut framed = Vec::with_capacity(GRAPH_CACHE_HEADER_LEN + payload.len());
149 framed.extend_from_slice(&GRAPH_CACHE_MAGIC);
150 framed.extend_from_slice(&version.to_le_bytes());
151 framed.extend_from_slice(payload);
152 framed
153}
154
155/// Split a cache file into its declared version and its payload, refusing
156/// anything this binary cannot read WITHOUT decoding it first.
157///
158/// A recognized header exposes a version mismatch without decoding. Releases
159/// before framing wrote raw payloads, so a missing header cannot distinguish
160/// an older cache from foreign or damaged data. `Undecodable` keeps that
161/// uncertainty explicit and the next successful run replaces the blob.
162fn read_header(data: &[u8]) -> Result<&[u8], CacheRejection> {
163 let Some((header, payload)) = data.split_at_checked(GRAPH_CACHE_HEADER_LEN) else {
164 tracing::warn!("Graph cache is too short to carry a format header, rebuilding");
165 return Err(CacheRejection::Undecodable);
166 };
167 let (declared_magic, declared_version) = header.split_at(GRAPH_CACHE_MAGIC.len());
168 if declared_magic != GRAPH_CACHE_MAGIC {
169 tracing::warn!("Graph cache does not carry fallow's cache framing, rebuilding");
170 return Err(CacheRejection::Undecodable);
171 }
172 // The slice is exactly four bytes; the fallback only has to be a version
173 // this binary never writes, so an impossible header is refused rather than
174 // trusted.
175 let declared = declared_version.try_into().map_or(0, u32::from_le_bytes);
176 if declared != GRAPH_CACHE_VERSION {
177 tracing::warn!(
178 cached_version = declared,
179 expected_version = GRAPH_CACHE_VERSION,
180 "Graph cache format upgraded, rebuilding (one-time cost after version bump)"
181 );
182 return Err(CacheRejection::VersionMismatch);
183 }
184 Ok(payload)
185}
186
187#[cfg(test)]
188mod tests {
189 use super::*;
190
191 /// Unframed data may come from a release predating the header. Its origin
192 /// is unknown, so the error does not establish corruption.
193 #[test]
194 fn a_blob_without_fallows_framing_is_undecodable() {
195 assert_eq!(
196 read_header(b"written-by-an-older-build").err(),
197 Some(CacheRejection::Undecodable)
198 );
199 }
200
201 #[test]
202 fn a_blob_too_short_to_carry_a_header_is_undecodable() {
203 assert_eq!(
204 read_header(&[0_u8; 3]).err(),
205 Some(CacheRejection::Undecodable)
206 );
207 }
208
209 #[test]
210 fn a_header_declaring_another_version_is_refused_without_reading_the_payload() {
211 let blob = framed(GRAPH_CACHE_VERSION + 1, b"payload");
212
213 assert_eq!(
214 read_header(&blob).err(),
215 Some(CacheRejection::VersionMismatch)
216 );
217 }
218
219 #[test]
220 fn a_header_at_the_current_version_hands_back_the_payload_it_frames() {
221 let blob = framed(GRAPH_CACHE_VERSION, b"payload");
222
223 assert_eq!(read_header(&blob), Ok(b"payload".as_slice()));
224 }
225}