Skip to main content

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}