Skip to main content

docsrs_cli/cache/
disk.rs

1//! Disk cache get/put/clear/stats/evict.
2
3use std::fs;
4use std::io::{Read, Write};
5use std::path::{Path, PathBuf};
6use std::time::{Duration, SystemTime, UNIX_EPOCH};
7
8use bytes::Bytes;
9use reqwest::{StatusCode, Url};
10use tracing::debug;
11
12use crate::config::HARD_MAX_BODY_BYTES;
13use crate::error::{AppError, AppResult, ErrorKind};
14use crate::http::HttpResponse;
15
16use super::hex::{input_checksum, is_cache_key_hex, key_hex, sha256_hex};
17use super::meta::read_meta_file;
18use super::types::{
19    CACHE_LAYOUT, CACHE_PARSER_VERSION, CacheClearResult, CacheMeta, CacheStats,
20    DEFAULT_MAX_CACHE_BYTES, EntryOnDisk,
21};
22
23/// Disk cache rooted at an XDG (or override) directory.
24#[derive(Debug, Clone)]
25pub struct DiskCache {
26    root: PathBuf,
27    ttl: Duration,
28    /// Soft cap on total body+meta bytes under `http/v1`. `0` = unlimited.
29    max_bytes: u64,
30    /// Same SSRF loopback policy as the owning [`crate::config::Config`].
31    allow_loopback: bool,
32}
33
34impl DiskCache {
35    /// Create a cache at `root` with the given TTL, byte budget, and loopback policy.
36    pub fn new(root: PathBuf, ttl: Duration, max_bytes: u64, allow_loopback: bool) -> Self {
37        Self {
38            root,
39            ttl,
40            max_bytes,
41            allow_loopback,
42        }
43    }
44
45    /// Absolute cache root directory.
46    pub fn root(&self) -> &Path {
47        &self.root
48    }
49
50    /// Configured entry time-to-live.
51    pub fn ttl(&self) -> Duration {
52        self.ttl
53    }
54
55    /// Soft size budget in bytes (`0` = unlimited).
56    pub fn max_bytes(&self) -> u64 {
57        self.max_bytes
58    }
59
60    fn entry_dir(&self) -> PathBuf {
61        self.root.join(CACHE_LAYOUT)
62    }
63
64    /// Build meta/body paths only for SHA-256 hex keys (64 lowercase hex digits).
65    ///
66    /// Refuses path traversal / odd filenames that could appear if on-disk names
67    /// are tampered (scan_entries reads directory entries as keys).
68    pub(super) fn paths_for_key(&self, key_hex_str: &str) -> Option<(PathBuf, PathBuf)> {
69        if !is_cache_key_hex(key_hex_str) {
70            debug!(%key_hex_str, "refuse cache path: key is not sha256 hex");
71            return None;
72        }
73        let dir = self.entry_dir();
74        Some((
75            dir.join(format!("{key_hex_str}.meta.json")),
76            dir.join(format!("{key_hex_str}.bin")),
77        ))
78    }
79
80    /// Look up a successful GET response. Returns `None` on miss, expire, or corrupt entry.
81    pub fn get(&self, url: &Url, accept: &str) -> Option<HttpResponse> {
82        // TTL 0 = never serve from disk (always re-fetch).
83        if self.ttl.as_secs() == 0 {
84            return None;
85        }
86        let input_sha = input_checksum(url.as_str(), CACHE_PARSER_VERSION, accept);
87        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, accept);
88        let (meta_path, body_path) = self.paths_for_key(&key)?;
89        if !meta_path.is_file() || !body_path.is_file() {
90            return None;
91        }
92        let Some(meta) = read_meta_file(&meta_path) else {
93            debug!(%key, "cache miss: meta unreadable or over cap");
94            return None;
95        };
96        // Best-effort eviction on miss paths: cleanup IO must not turn a cache miss
97        // into a hard error (get returns Option; put/clear use AppResult).
98        if meta.parser_version != CACHE_PARSER_VERSION {
99            debug!(%key, "cache miss: parser version mismatch");
100            let _ = self.remove_entry(&key);
101            return None;
102        }
103        if meta.url != url.as_str() || meta.accept != accept {
104            debug!(%key, "cache miss: url/accept mismatch");
105            let _ = self.remove_entry(&key);
106            return None;
107        }
108        if meta.input_sha256 != input_sha {
109            debug!(%key, "cache miss: input checksum mismatch");
110            let _ = self.remove_entry(&key);
111            return None;
112        }
113        let now = unix_now();
114        if now.saturating_sub(meta.stored_at_unix) >= self.ttl.as_secs() {
115            debug!(%key, "cache miss: expired");
116            let _ = self.remove_entry(&key);
117            return None;
118        }
119        // Refuse oversized on-disk bodies before allocating (OOM / corrupt entry guard).
120        let body_len = fs::metadata(&body_path).ok()?.len();
121        let budget = if self.max_bytes > 0 {
122            self.max_bytes
123        } else {
124            DEFAULT_MAX_CACHE_BYTES
125        };
126        let read_cap = budget.min(HARD_MAX_BODY_BYTES);
127        if body_len > read_cap {
128            debug!(%key, body_len, read_cap, "cache miss: body exceeds read budget");
129            let _ = self.remove_entry(&key);
130            return None;
131        }
132        let n = usize::try_from(body_len).ok()?;
133        let mut buf = Vec::new();
134        if let Err(e) = buf.try_reserve_exact(n) {
135            debug!(%key, body_len, error = %e, "cache miss: failed to reserve body buffer");
136            return None;
137        }
138        buf.resize(n, 0);
139        {
140            let mut file = fs::File::open(&body_path).ok()?;
141            if file.read_exact(&mut buf).is_err() {
142                debug!(%key, "cache miss: body read failed");
143                return None;
144            }
145        }
146        let body_sha = sha256_hex(&buf);
147        if body_sha != meta.body_sha256 {
148            debug!(%key, "cache miss: body checksum mismatch");
149            let _ = self.remove_entry(&key);
150            return None;
151        }
152        let final_url = Url::parse(&meta.final_url).ok()?;
153        // Poisoned meta could claim an off-allowlist final_url; refuse the hit.
154        if !crate::http::is_allowed_host(&final_url, self.allow_loopback) {
155            debug!(%key, final = %final_url, "cache miss: final_url not allowlisted");
156            let _ = self.remove_entry(&key);
157            return None;
158        }
159        let status = StatusCode::from_u16(meta.status).ok()?;
160        debug!(%key, "cache hit");
161        Some(HttpResponse {
162            status,
163            final_url,
164            body: Bytes::from(buf),
165            content_type: meta.content_type,
166            cache_hit: true,
167        })
168    }
169
170    /// Persist a successful response. Best-effort; failures are non-fatal at call sites.
171    ///
172    /// # Errors
173    ///
174    /// Returns [`ErrorKind::Internal`] on filesystem create/write/rename failures or
175    /// when cache metadata cannot be serialized.
176    pub fn put(&self, url: &Url, accept: &str, resp: &HttpResponse) -> AppResult<()> {
177        if !resp.status.is_success() {
178            return Ok(());
179        }
180        // Soft budget: never store a single body that already exceeds the cap.
181        if self.max_bytes > 0 && (resp.body.len() as u64) > self.max_bytes {
182            debug!(
183                body = resp.body.len(),
184                max = self.max_bytes,
185                "cache skip: body exceeds max_bytes"
186            );
187            return Ok(());
188        }
189        let dir = self.entry_dir();
190        fs::create_dir_all(&dir).map_err(|e| {
191            AppError::with_source(
192                ErrorKind::Internal,
193                format!("failed to create cache dir {}", dir.display()),
194                e,
195            )
196        })?;
197        crate::platform::restrict_private_dir(&dir);
198        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, accept);
199        let input_sha = input_checksum(url.as_str(), CACHE_PARSER_VERSION, accept);
200        let body_sha = sha256_hex(resp.body.as_ref());
201        let meta = CacheMeta {
202            url: url.as_str().to_string(),
203            parser_version: CACHE_PARSER_VERSION.to_string(),
204            accept: accept.to_string(),
205            status: resp.status.as_u16(),
206            content_type: resp.content_type.clone(),
207            final_url: resp.final_url.as_str().to_string(),
208            stored_at_unix: unix_now(),
209            body_sha256: body_sha,
210            input_sha256: input_sha,
211        };
212        let (meta_path, body_path) = self.paths_for_key(&key).ok_or_else(|| {
213            AppError::new(
214                ErrorKind::Internal,
215                "cache key is not valid sha256 hex (internal invariant broken)",
216            )
217        })?;
218        let meta_tmp = meta_path.with_extension("meta.json.tmp");
219        let body_tmp = body_path.with_extension("bin.tmp");
220
221        // RAII: remove temps on any early return / panic; disarmed after successful renames.
222        struct TempCleanup {
223            paths: [PathBuf; 2],
224            armed: bool,
225        }
226        impl Drop for TempCleanup {
227            fn drop(&mut self) {
228                if !self.armed {
229                    return;
230                }
231                for p in &self.paths {
232                    if p.as_os_str().is_empty() {
233                        continue;
234                    }
235                    let _ = fs::remove_file(p);
236                }
237            }
238        }
239        let mut temps = TempCleanup {
240            paths: [body_tmp, meta_tmp],
241            armed: true,
242        };
243
244        {
245            let mut f = fs::File::create(&temps.paths[0]).map_err(|e| {
246                AppError::with_source(ErrorKind::Internal, "cache body temp create", e)
247            })?;
248            f.write_all(resp.body.as_ref())
249                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache body write", e))?;
250            f.sync_all()
251                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache body sync", e))?;
252        }
253        {
254            let text = serde_json::to_string(&meta).map_err(|e| {
255                AppError::with_source(ErrorKind::Internal, "cache meta serialize", e)
256            })?;
257            let mut f = fs::File::create(&temps.paths[1]).map_err(|e| {
258                AppError::with_source(ErrorKind::Internal, "cache meta temp create", e)
259            })?;
260            f.write_all(text.as_bytes())
261                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache meta write", e))?;
262            f.sync_all()
263                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache meta sync", e))?;
264        }
265
266        fs::rename(&temps.paths[0], &body_path)
267            .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache body rename", e))?;
268        crate::platform::restrict_private_file(&body_path);
269        temps.paths[0] = PathBuf::new();
270        fs::rename(&temps.paths[1], &meta_path).map_err(|e| {
271            AppError::with_source(ErrorKind::Internal, "cache meta rename", e)
272        })?;
273        crate::platform::restrict_private_file(&meta_path);
274        temps.armed = false;
275        debug!(%key, "cache store");
276        self.enforce_max_bytes(Some(&key));
277        Ok(())
278    }
279
280    /// Remove every entry under `http/v1` (temps included).
281    ///
282    /// # Errors
283    ///
284    /// Returns [`ErrorKind::Internal`] when the cache directory cannot be read.
285    pub fn clear(&self) -> AppResult<CacheClearResult> {
286        let dir = self.entry_dir();
287        let mut removed_entries = 0u64;
288        let mut freed_bytes = 0u64;
289        if dir.is_dir() {
290            for entry in fs::read_dir(&dir).map_err(|e| {
291                AppError::with_source(ErrorKind::Internal, "cache clear read_dir", e)
292            })? {
293                let entry = entry.map_err(|e| {
294                    AppError::with_source(ErrorKind::Internal, "cache clear entry", e)
295                })?;
296                let path = entry.path();
297                let len = entry.metadata().map(|m| m.len()).unwrap_or(0);
298                if path.is_file() {
299                    if path
300                        .file_name()
301                        .and_then(|n| n.to_str())
302                        .is_some_and(|n| n.ends_with(".meta.json"))
303                    {
304                        removed_entries = removed_entries.saturating_add(1);
305                    }
306                    freed_bytes = freed_bytes.saturating_add(len);
307                    let _ = fs::remove_file(&path);
308                }
309            }
310        }
311        Ok(CacheClearResult {
312            root: self.root.display().to_string(),
313            removed_entries,
314            freed_bytes,
315        })
316    }
317
318    /// Inventory of on-disk entries and budget.
319    pub fn stats(&self) -> CacheStats {
320        let entries = self.scan_entries();
321        let total_bytes = entries.iter().map(|e| e.bytes).sum();
322        CacheStats {
323            root: self.root.display().to_string(),
324            layout: CACHE_LAYOUT.to_string(),
325            entries: entries.len() as u64,
326            total_bytes,
327            max_bytes: self.max_bytes,
328            ttl_secs: self.ttl.as_secs(),
329            parser_version: CACHE_PARSER_VERSION.to_string(),
330        }
331    }
332
333    fn scan_entries(&self) -> Vec<EntryOnDisk> {
334        let dir = self.entry_dir();
335        let mut out = Vec::new();
336        let Ok(rd) = fs::read_dir(&dir) else {
337            return out;
338        };
339        for entry in rd.flatten() {
340            let path = entry.path();
341            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
342                continue;
343            };
344            let Some(key) = name.strip_suffix(".meta.json") else {
345                continue;
346            };
347            let Some((meta_path, body_path)) = self.paths_for_key(key) else {
348                continue;
349            };
350            if !meta_path.is_file() || !body_path.is_file() {
351                continue;
352            }
353            let meta_len = fs::metadata(&meta_path).map(|m| m.len()).unwrap_or(0);
354            let body_len = fs::metadata(&body_path).map(|m| m.len()).unwrap_or(0);
355            let stored_at = read_meta_file(&meta_path)
356                .map(|m| m.stored_at_unix)
357                .unwrap_or(0);
358            out.push(EntryOnDisk {
359                key: key.to_string(),
360                stored_at_unix: stored_at,
361                bytes: meta_len.saturating_add(body_len),
362            });
363        }
364        out
365    }
366
367    /// Evict oldest entries until total size is within `max_bytes`.
368    /// Never deletes `keep_key` (the entry just written).
369    fn enforce_max_bytes(&self, keep_key: Option<&str>) {
370        if self.max_bytes == 0 {
371            return;
372        }
373        loop {
374            let mut entries = self.scan_entries();
375            let total: u64 = entries.iter().map(|e| e.bytes).sum();
376            if total <= self.max_bytes {
377                break;
378            }
379            entries.sort_by_key(|e| e.stored_at_unix);
380            let victim = entries
381                .iter()
382                .find(|e| keep_key.is_none_or(|k| k != e.key.as_str()));
383            let Some(v) = victim else {
384                break;
385            };
386            debug!(key = %v.key, "cache evict for budget");
387            let _ = self.remove_entry(&v.key);
388        }
389    }
390
391    fn remove_entry(&self, key_hex_str: &str) -> AppResult<()> {
392        let Some((meta_path, body_path)) = self.paths_for_key(key_hex_str) else {
393            return Ok(());
394        };
395        let _ = fs::remove_file(meta_path);
396        let _ = fs::remove_file(body_path);
397        Ok(())
398    }
399}
400
401fn unix_now() -> u64 {
402    SystemTime::now()
403        .duration_since(UNIX_EPOCH)
404        .map(|d| d.as_secs())
405        .unwrap_or(0)
406}