Skip to main content

spec_driven_docs/self_depend/
cache.rs

1//! The per-checkout cache behind the version check.
2//!
3//! The check runs from the project's shell entry, which fires on every
4//! directory entry. It reads this cache and nothing else, unless a refresh
5//! is due. A refresh is due seven days after the last success, or one hour
6//! after a failed attempt, and it runs under a lock beside the cache so two
7//! shells read the network once.
8
9use camino::{Utf8Path, Utf8PathBuf};
10use jiff::{SignedDuration, Timestamp};
11use serde::{Deserialize, Serialize};
12
13use crate::domain::ownership::Sha256;
14use crate::domain::paths::{SELF_DEPEND_CACHE_DIR, SELF_DEPEND_STAMP_DIR};
15
16/// How long a success holds before the next refresh is due.
17pub const REFRESH_AFTER: SignedDuration = SignedDuration::from_hours(7 * 24);
18/// How long a failed attempt holds before the next refresh is due.
19pub const RETRY_AFTER: SignedDuration = SignedDuration::from_hours(1);
20
21/// What the cache records for one checkout.
22///
23/// Times are RFC 3339 text on disk and compared as times.
24#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
25pub struct Entry {
26    /// When the last refresh started, success or failure.
27    #[serde(default)]
28    pub last_attempt: Option<String>,
29    /// When the last refresh read the latest release.
30    #[serde(default)]
31    pub last_success: Option<String>,
32    /// The latest release the last success found.
33    #[serde(default)]
34    pub latest: Option<String>,
35    /// Why the last attempt failed, where it failed.
36    #[serde(default)]
37    pub error: Option<String>,
38}
39
40fn time(text: Option<&String>) -> Option<Timestamp> {
41    text.and_then(|text| text.parse().ok())
42}
43
44impl Entry {
45    /// When the last attempt started.
46    #[must_use]
47    pub fn attempted_at(&self) -> Option<Timestamp> {
48        time(self.last_attempt.as_ref())
49    }
50
51    /// When the last success happened.
52    #[must_use]
53    pub fn succeeded_at(&self) -> Option<Timestamp> {
54        time(self.last_success.as_ref())
55    }
56
57    /// When a failed attempt allows the next try, where the last attempt
58    /// failed.
59    #[must_use]
60    pub fn next_try(&self) -> Option<Timestamp> {
61        self.error.as_ref()?;
62        self.attempted_at()?
63            .checked_add(RETRY_AFTER)
64            .ok()?
65            .round(jiff::Unit::Second)
66            .ok()
67    }
68
69    /// The latest release found, as a version.
70    #[must_use]
71    pub fn latest_version(&self) -> Option<semver::Version> {
72        self.latest.as_deref()?.parse().ok()
73    }
74}
75
76/// The digest that keys one checkout: its absolute path, so two checkouts
77/// of one project keep two caches.
78fn key(target: &Utf8Path) -> String {
79    let digest = Sha256::of(target.as_str().as_bytes());
80    digest.as_str()[..16].to_string()
81}
82
83/// Where the cache for one target lives under the cache root.
84#[must_use]
85pub fn path(cache_root: &Utf8Path, target: &Utf8Path) -> Utf8PathBuf {
86    cache_root
87        .join(SELF_DEPEND_CACHE_DIR)
88        .join(format!("{}.json", key(target)))
89}
90
91/// The lock beside one cache file.
92#[must_use]
93pub fn lock_path(cache: &Utf8Path) -> Utf8PathBuf {
94    cache.with_extension("lock")
95}
96
97/// The entry the cache records, where one is readable.
98#[must_use]
99pub fn read(path: &Utf8Path) -> Option<Entry> {
100    serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok()
101}
102
103/// Record one entry.
104///
105/// # Errors
106///
107/// The I/O error where the cache cannot be written.
108///
109/// The caller holds the lock, so a scratch file left beside the cache is
110/// one a killed check left, and it is removed first: otherwise the
111/// exclusive scratch create would refuse every later write.
112pub fn write(path: &Utf8Path, entry: &Entry) -> std::io::Result<()> {
113    if let Some(parent) = path.parent() {
114        std::fs::create_dir_all(parent)?;
115    }
116    match std::fs::remove_file(scratch_path(path)) {
117        Ok(()) => {}
118        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
119        Err(error) => return Err(error),
120    }
121    let mut text = serde_json::to_string_pretty(entry).map_err(std::io::Error::other)?;
122    text.push('\n');
123    crate::adapters::fs::write_atomic(path, text.as_bytes())
124}
125
126/// The scratch file [`crate::adapters::fs::write_atomic`] writes beside
127/// one cache file.
128fn scratch_path(path: &Utf8Path) -> Utf8PathBuf {
129    path.with_extension(format!("{}.sdd-tmp", path.extension().unwrap_or_default()))
130}
131
132/// Whether a refresh is due at `now`.
133///
134/// After a failed attempt, a refresh is due only one hour after that
135/// attempt. Otherwise it is due where the cache is missing, where no
136/// success is recorded yet, or where the last success is seven days old.
137///
138/// SATISFIES acquisition:the-check-refreshes-weekly-and-retries-hourly
139#[must_use]
140pub fn due(entry: Option<&Entry>, now: Timestamp) -> bool {
141    let Some(entry) = entry else {
142        return true;
143    };
144    if entry.error.is_some() {
145        return entry
146            .attempted_at()
147            .is_none_or(|attempt| now.duration_since(attempt) >= RETRY_AFTER);
148    }
149    entry
150        .succeeded_at()
151        .is_none_or(|success| now.duration_since(success) >= REFRESH_AFTER)
152}
153
154/// A held refresh lock: an advisory lock on the lock file, which closing
155/// the file releases, and which the kernel releases when a process dies.
156/// The lock file itself stays in place.
157#[derive(Debug)]
158pub struct Lock {
159    _file: std::fs::File,
160}
161
162/// Take the refresh lock, or learn that another check holds it.
163///
164/// `Ok(None)` means another process holds the lock and refreshes the
165/// cache, so this check reads the cache alone.
166///
167/// # Errors
168///
169/// The I/O error where the lock file cannot be opened or locked for a
170/// reason other than another holder.
171pub fn try_lock(path: &Utf8Path) -> std::io::Result<Option<Lock>> {
172    if let Some(parent) = path.parent() {
173        std::fs::create_dir_all(parent)?;
174    }
175    let file = std::fs::OpenOptions::new()
176        .write(true)
177        .create(true)
178        .truncate(false)
179        .open(path)?;
180    match file.try_lock() {
181        Ok(()) => Ok(Some(Lock { _file: file })),
182        Err(std::fs::TryLockError::WouldBlock) => Ok(None),
183        Err(std::fs::TryLockError::Error(error)) => Err(error),
184    }
185}
186
187/// The retired daily stamps under the state root: every `*.stamp` file in
188/// the stamp folder, and nothing else.
189#[must_use]
190pub fn retired_stamps(state_root: &Utf8Path) -> Vec<Utf8PathBuf> {
191    let dir = state_root.join(SELF_DEPEND_STAMP_DIR);
192    let Ok(entries) = dir.read_dir_utf8() else {
193        return Vec::new();
194    };
195    let mut found: Vec<Utf8PathBuf> = entries
196        .filter_map(Result::ok)
197        .filter(|entry| entry.file_type().is_ok_and(|kind| kind.is_file()))
198        .map(|entry| entry.path().to_owned())
199        .filter(|path| path.extension() == Some("stamp"))
200        .collect();
201    found.sort();
202    found
203}
204
205#[cfg(test)]
206mod tests {
207    #![allow(clippy::unwrap_used, reason = "a test panics as its failure signal")]
208
209    use super::*;
210
211    fn at(now: Timestamp, ago: SignedDuration) -> Option<String> {
212        now.checked_sub(ago).ok().map(|time| time.to_string())
213    }
214
215    /// VERIFIES acquisition:the-check-refreshes-weekly-and-retries-hourly
216    #[test]
217    fn a_refresh_is_due_weekly_after_success_and_hourly_after_failure() {
218        let now = Timestamp::now();
219        assert!(due(None, now));
220        assert!(due(Some(&Entry::default()), now));
221        let fresh = Entry {
222            last_attempt: at(now, SignedDuration::from_hours(6 * 24)),
223            last_success: at(now, SignedDuration::from_hours(6 * 24)),
224            latest: Some("1.0.0".to_string()),
225            error: None,
226        };
227        assert!(!due(Some(&fresh), now));
228        let week = Entry {
229            last_success: at(now, REFRESH_AFTER),
230            ..fresh
231        };
232        assert!(due(Some(&week), now));
233        let failed = Entry {
234            last_attempt: at(now, SignedDuration::from_mins(59)),
235            last_success: at(now, SignedDuration::from_hours(8 * 24)),
236            latest: None,
237            error: Some("down".to_string()),
238        };
239        assert!(!due(Some(&failed), now));
240        let hour = Entry {
241            last_attempt: at(now, RETRY_AFTER),
242            ..failed
243        };
244        assert!(due(Some(&hour), now));
245    }
246
247    #[test]
248    fn two_checkouts_keep_two_caches() {
249        let root = Utf8Path::new("/cache");
250        assert_ne!(
251            path(root, Utf8Path::new("/work/a")),
252            path(root, Utf8Path::new("/work/b"))
253        );
254        let one = path(root, Utf8Path::new("/work/a"));
255        assert_eq!(lock_path(&one).extension(), Some("lock"));
256    }
257
258    #[test]
259    fn a_leftover_scratch_file_does_not_block_the_cache() {
260        let dir = tempfile::tempdir().unwrap();
261        let root = Utf8Path::from_path(dir.path()).unwrap();
262        let cache = root.join("x.json");
263        std::fs::write(scratch_path(&cache), "half").unwrap();
264        let entry = Entry {
265            latest: Some("1.0.0".to_string()),
266            ..Entry::default()
267        };
268        write(&cache, &entry).unwrap();
269        assert_eq!(read(&cache), Some(entry));
270        assert!(!scratch_path(&cache).exists());
271    }
272
273    #[test]
274    fn a_second_lock_on_the_file_fails_while_the_first_is_held() {
275        let dir = tempfile::tempdir().unwrap();
276        let root = Utf8Path::from_path(dir.path()).unwrap();
277        let lock = root.join("x.lock");
278        let held = try_lock(&lock).unwrap();
279        assert!(held.is_some());
280        assert!(
281            try_lock(&lock).unwrap().is_none(),
282            "a held lock was taken twice"
283        );
284        drop(held);
285        assert!(lock.exists(), "releasing the lock removed its file");
286        assert!(try_lock(&lock).unwrap().is_some());
287    }
288}