spec_driven_docs/self_depend/
cache.rs1use 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
16pub const REFRESH_AFTER: SignedDuration = SignedDuration::from_hours(7 * 24);
18pub const RETRY_AFTER: SignedDuration = SignedDuration::from_hours(1);
20
21#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
25pub struct Entry {
26 #[serde(default)]
28 pub last_attempt: Option<String>,
29 #[serde(default)]
31 pub last_success: Option<String>,
32 #[serde(default)]
34 pub latest: Option<String>,
35 #[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 #[must_use]
47 pub fn attempted_at(&self) -> Option<Timestamp> {
48 time(self.last_attempt.as_ref())
49 }
50
51 #[must_use]
53 pub fn succeeded_at(&self) -> Option<Timestamp> {
54 time(self.last_success.as_ref())
55 }
56
57 #[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 #[must_use]
71 pub fn latest_version(&self) -> Option<semver::Version> {
72 self.latest.as_deref()?.parse().ok()
73 }
74}
75
76fn key(target: &Utf8Path) -> String {
79 let digest = Sha256::of(target.as_str().as_bytes());
80 digest.as_str()[..16].to_string()
81}
82
83#[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#[must_use]
93pub fn lock_path(cache: &Utf8Path) -> Utf8PathBuf {
94 cache.with_extension("lock")
95}
96
97#[must_use]
99pub fn read(path: &Utf8Path) -> Option<Entry> {
100 serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok()
101}
102
103pub 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
126fn scratch_path(path: &Utf8Path) -> Utf8PathBuf {
129 path.with_extension(format!("{}.sdd-tmp", path.extension().unwrap_or_default()))
130}
131
132#[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#[derive(Debug)]
158pub struct Lock {
159 _file: std::fs::File,
160}
161
162pub 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#[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 #[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 let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
292 while try_lock(&lock).unwrap().is_none() {
293 assert!(
294 std::time::Instant::now() < deadline,
295 "a released lock stayed held"
296 );
297 std::thread::sleep(std::time::Duration::from_millis(1));
298 }
299 }
300}