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 sibling `.tmp` file
6//! 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 simply misses and the graph is rebuilt fresh.
10
11use std::path::Path;
12
13use serde::{Deserialize, Serialize};
14
15use super::{GRAPH_CACHE_VERSION, GraphCacheManifest};
16use crate::graph::ModuleGraph;
17
18/// Filename of the persisted graph cache inside the cache directory.
19const GRAPH_CACHE_FILE: &str = "graph-cache.bin";
20
21/// On-disk graph cache entry: a manifest plus the graph it validates.
22#[derive(Serialize, Deserialize)]
23pub struct GraphCacheStore {
24    /// Schema version. Checked on load; a mismatch misses so a stale file from
25    /// an older binary is never deserialized into the wrong shape.
26    pub version: u32,
27    /// Inputs that must match the current run for the graph to be trusted.
28    pub manifest: GraphCacheManifest,
29    /// The previously-built graph. Its `namespace_imported` bitset is
30    /// `#[serde(skip)]`, so the loader reconstructs it from the edge set.
31    pub graph: ModuleGraph,
32}
33
34impl GraphCacheStore {
35    /// Load the persisted graph cache from `cache_dir`.
36    ///
37    /// Returns `None` when the file is missing, undecodable, or written for a
38    /// different `GRAPH_CACHE_VERSION`. The caller compares the loaded
39    /// manifest against the current inputs via [`GraphCacheManifest::matches_inputs`]
40    /// before trusting the graph.
41    #[must_use]
42    pub fn load(cache_dir: &Path) -> Option<Self> {
43        let cache_file = cache_dir.join(GRAPH_CACHE_FILE);
44        let data = std::fs::read(&cache_file).ok()?;
45        let mut store: Self = match postcard::from_bytes(&data) {
46            Ok(store) => store,
47            Err(_) => {
48                tracing::info!(
49                    "Graph cache format upgraded, rebuilding (one-time cost after version bump)"
50                );
51                return None;
52            }
53        };
54        if store.version != GRAPH_CACHE_VERSION {
55            tracing::info!(
56                "Graph cache format upgraded, rebuilding (one-time cost after version bump)"
57            );
58            return None;
59        }
60        // `namespace_imported` is `#[serde(skip)]`; rebuild it from the persisted
61        // edges so the loaded graph is byte-identical to a fresh build.
62        store.graph.reconstruct_namespace_imported();
63        Some(store)
64    }
65
66    /// Persist this graph cache to `cache_dir`, best-effort.
67    ///
68    /// Creates the cache directory, writes a `.gitignore`, encodes the store
69    /// with postcard, and writes `graph-cache.bin` atomically. Every IO error
70    /// is logged at debug and swallowed; the graph cache must never fail the
71    /// surrounding analysis run.
72    pub fn save(&self, cache_dir: &Path) {
73        if let Err(error) = std::fs::create_dir_all(cache_dir) {
74            tracing::debug!("Failed to create graph cache dir: {error}");
75            return;
76        }
77        if let Err(error) = write_cache_gitignore(cache_dir) {
78            tracing::debug!("Failed to write graph cache .gitignore: {error}");
79            // Continue: a missing .gitignore does not invalidate the cache file.
80        }
81
82        let encoded = match postcard::to_allocvec(self) {
83            Ok(bytes) => bytes,
84            Err(error) => {
85                tracing::debug!("Failed to encode graph cache: {error}");
86                return;
87            }
88        };
89
90        let cache_file = cache_dir.join(GRAPH_CACHE_FILE);
91        if let Err(error) = atomic_write(&cache_file, &encoded) {
92            tracing::debug!("Failed to write graph cache: {error}");
93        }
94    }
95}
96
97/// Write `.fallow/.gitignore` (`*\n`) so the cache directory is never committed.
98fn write_cache_gitignore(cache_dir: &Path) -> std::io::Result<()> {
99    std::fs::write(cache_dir.join(".gitignore"), "*\n")
100}
101
102/// Write `data` atomically via a sibling `.tmp` file, best-effort fsync, then
103/// rename. Copied from the extraction cache store so the two caches share the
104/// same crash-safe write semantics.
105fn atomic_write(cache_file: &Path, data: &[u8]) -> std::io::Result<()> {
106    let tmp_file = match cache_file.file_name() {
107        Some(name) => cache_file.with_file_name({
108            let mut s = name.to_os_string();
109            s.push(".tmp");
110            s
111        }),
112        None => {
113            return Err(std::io::Error::new(
114                std::io::ErrorKind::InvalidInput,
115                "graph cache file path has no filename component",
116            ));
117        }
118    };
119
120    {
121        use std::io::Write as _;
122        let mut f = std::fs::File::create(&tmp_file)?;
123        f.write_all(data)?;
124        let _ = f.sync_all();
125    }
126
127    std::fs::rename(&tmp_file, cache_file)
128}
fallow_graph/cache/store.rs

fallow_graph/cache/
store.rs
