Skip to main content

docsrs_cli/
cache.rs

1//! XDG disk cache for successful HTTP GET bodies between process invocations.
2//!
3//! Cache key = SHA-256(url || NUL || parser_version || NUL || accept).
4//! Each entry stores body bytes plus metadata with body checksum; corrupt or
5//! expired entries are discarded and re-fetched.
6//!
7//! Budget: optional `max_bytes` evicts oldest entries after each successful put.
8//! `ttl == 0` means entries never hit (always re-fetch).
9//!
10//! Poisoned-entry guards: body reads are capped by [`HARD_MAX_BODY_BYTES`] (and the
11//! cache soft budget); meta JSON reads are capped by [`MAX_CACHE_META_BYTES`]. Both
12//! paths use fallible `try_reserve_exact` before filling buffers (never unbounded
13//! `fs::read` / `fs::read_to_string` on attacker-controlled sizes).
14
15use std::fs;
16use std::io::{Read, Write};
17use std::path::{Path, PathBuf};
18use std::time::{Duration, SystemTime, UNIX_EPOCH};
19
20use bytes::Bytes;
21use reqwest::{StatusCode, Url};
22use serde::{Deserialize, Serialize};
23use sha2::{Digest, Sha256};
24use tracing::debug;
25
26use crate::config::HARD_MAX_BODY_BYTES;
27use crate::error::{AppError, AppResult, ErrorKind};
28use crate::http::HttpResponse;
29
30/// Bump when HTML/JSON parse semantics change so stale entries are ignored.
31pub const CACHE_PARSER_VERSION: &str = "1";
32/// Default entry TTL (24 hours).
33pub const DEFAULT_CACHE_TTL_SECS: u64 = 86_400;
34/// Default on-disk budget (256 MiB). `0` means unlimited.
35pub const DEFAULT_MAX_CACHE_BYTES: u64 = 256 * 1024 * 1024;
36/// Hard ceiling for on-disk cache meta JSON (poisoned-entry guard).
37///
38/// Legitimate `CacheMeta` is a few hundred bytes (URLs + digests). A multi-KiB
39/// ceiling leaves headroom while blocking multi-GiB `read_to_string` aborts.
40pub const MAX_CACHE_META_BYTES: u64 = 64 * 1024;
41/// On-disk layout version under the cache root.
42const CACHE_LAYOUT: &str = "http/v1";
43
44/// Disk cache rooted at an XDG (or override) directory.
45#[derive(Debug, Clone)]
46pub struct DiskCache {
47    root: PathBuf,
48    ttl: Duration,
49    /// Soft cap on total body+meta bytes under `http/v1`. `0` = unlimited.
50    max_bytes: u64,
51}
52
53/// Aggregate cache inventory for `cache stats` / doctor.
54#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
55pub struct CacheStats {
56    /// Absolute cache root path.
57    pub root: String,
58    /// On-disk layout subdirectory (for example `http/v1`).
59    pub layout: String,
60    /// Number of complete cache entries (meta+body pairs).
61    pub entries: u64,
62    /// Total bytes used by meta and body files.
63    pub total_bytes: u64,
64    /// Configured soft budget (`0` = unlimited).
65    pub max_bytes: u64,
66    /// Configured TTL in seconds.
67    pub ttl_secs: u64,
68    /// Parser version used for cache keys.
69    pub parser_version: String,
70}
71
72/// Result of `cache clear`.
73#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
74pub struct CacheClearResult {
75    /// Absolute cache root path that was cleared.
76    pub root: String,
77    /// Number of entries removed.
78    pub removed_entries: u64,
79    /// Bytes reclaimed from deleted files.
80    pub freed_bytes: u64,
81}
82
83#[derive(Debug, Clone, Serialize, Deserialize)]
84struct CacheMeta {
85    url: String,
86    parser_version: String,
87    accept: String,
88    status: u16,
89    content_type: Option<String>,
90    final_url: String,
91    stored_at_unix: u64,
92    body_sha256: String,
93    /// SHA-256 of the cache key material (url + parser + accept).
94    input_sha256: String,
95}
96
97#[derive(Debug)]
98struct EntryOnDisk {
99    key: String,
100    stored_at_unix: u64,
101    bytes: u64,
102}
103
104impl DiskCache {
105    /// Create a cache at `root` with the given TTL and byte budget.
106    pub fn new(root: PathBuf, ttl: Duration, max_bytes: u64) -> Self {
107        Self {
108            root,
109            ttl,
110            max_bytes,
111        }
112    }
113
114    /// Absolute cache root directory.
115    pub fn root(&self) -> &Path {
116        &self.root
117    }
118
119    /// Configured entry time-to-live.
120    pub fn ttl(&self) -> Duration {
121        self.ttl
122    }
123
124    /// Soft size budget in bytes (`0` = unlimited).
125    pub fn max_bytes(&self) -> u64 {
126        self.max_bytes
127    }
128
129    fn entry_dir(&self) -> PathBuf {
130        self.root.join(CACHE_LAYOUT)
131    }
132
133    fn paths_for_key(&self, key_hex: &str) -> (PathBuf, PathBuf) {
134        let dir = self.entry_dir();
135        (
136            dir.join(format!("{key_hex}.meta.json")),
137            dir.join(format!("{key_hex}.bin")),
138        )
139    }
140
141    /// Look up a successful GET response. Returns `None` on miss, expire, or corrupt entry.
142    pub fn get(&self, url: &Url, accept: &str) -> Option<HttpResponse> {
143        // TTL 0 = never serve from disk (always re-fetch).
144        if self.ttl.as_secs() == 0 {
145            return None;
146        }
147        let input_sha = input_checksum(url.as_str(), CACHE_PARSER_VERSION, accept);
148        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, accept);
149        let (meta_path, body_path) = self.paths_for_key(&key);
150        if !meta_path.is_file() || !body_path.is_file() {
151            return None;
152        }
153        let Some(meta) = read_meta_file(&meta_path) else {
154            debug!(%key, "cache miss: meta unreadable or over cap");
155            return None;
156        };
157        if meta.parser_version != CACHE_PARSER_VERSION {
158            debug!(%key, "cache miss: parser version mismatch");
159            let _ = self.remove_entry(&key);
160            return None;
161        }
162        if meta.url != url.as_str() || meta.accept != accept {
163            debug!(%key, "cache miss: url/accept mismatch");
164            let _ = self.remove_entry(&key);
165            return None;
166        }
167        if meta.input_sha256 != input_sha {
168            debug!(%key, "cache miss: input checksum mismatch");
169            let _ = self.remove_entry(&key);
170            return None;
171        }
172        let now = unix_now();
173        if now.saturating_sub(meta.stored_at_unix) >= self.ttl.as_secs() {
174            debug!(%key, "cache miss: expired");
175            let _ = self.remove_entry(&key);
176            return None;
177        }
178        // Refuse oversized on-disk bodies before allocating (OOM / corrupt entry guard).
179        // Cap is the min of cache budget (or default soft budget when unlimited) and the
180        // product hard body ceiling — a poisoned cache cannot force multi-GiB or
181        // above-HARD_MAX_BODY_BYTES reads even if max_cache_bytes is 0/unlimited.
182        let body_len = fs::metadata(&body_path).ok()?.len();
183        let budget = if self.max_bytes > 0 {
184            self.max_bytes
185        } else {
186            DEFAULT_MAX_CACHE_BYTES
187        };
188        let read_cap = budget.min(HARD_MAX_BODY_BYTES);
189        if body_len > read_cap {
190            debug!(%key, body_len, read_cap, "cache miss: body exceeds read budget");
191            let _ = self.remove_entry(&key);
192            return None;
193        }
194        // Fallible reserve before reading: size is already capped by HARD_MAX_BODY_BYTES,
195        // but try_reserve_exact avoids with_capacity/fs::read abort paths on OOM.
196        // On reserve or I/O failure treat as miss (best-effort cache).
197        // body_len <= HARD_MAX_BODY_BYTES (10 MiB) always fits usize on supported targets.
198        let n = usize::try_from(body_len).ok()?;
199        let mut buf = Vec::new();
200        if let Err(e) = buf.try_reserve_exact(n) {
201            debug!(%key, body_len, error = %e, "cache miss: failed to reserve body buffer");
202            return None;
203        }
204        buf.resize(n, 0);
205        {
206            let mut file = fs::File::open(&body_path).ok()?;
207            if file.read_exact(&mut buf).is_err() {
208                debug!(%key, "cache miss: body read failed");
209                return None;
210            }
211        }
212        let body_sha = sha256_hex(&buf);
213        if body_sha != meta.body_sha256 {
214            debug!(%key, "cache miss: body checksum mismatch");
215            let _ = self.remove_entry(&key);
216            return None;
217        }
218        let final_url = Url::parse(&meta.final_url).ok()?;
219        let status = StatusCode::from_u16(meta.status).ok()?;
220        debug!(%key, "cache hit");
221        Some(HttpResponse {
222            status,
223            final_url,
224            body: Bytes::from(buf),
225            content_type: meta.content_type,
226            cache_hit: true,
227        })
228    }
229
230    /// Persist a successful response. Best-effort; failures are non-fatal at call sites.
231    ///
232    /// # Errors
233    ///
234    /// Returns [`ErrorKind::Internal`] on filesystem create/write/rename failures or
235    /// when cache metadata cannot be serialized.
236    pub fn put(&self, url: &Url, accept: &str, resp: &HttpResponse) -> AppResult<()> {
237        if !resp.status.is_success() {
238            return Ok(());
239        }
240        // Soft budget: never store a single body that already exceeds the cap.
241        // (A just-written entry is never self-evicted, so oversized puts would stick forever.)
242        if self.max_bytes > 0 && (resp.body.len() as u64) > self.max_bytes {
243            debug!(
244                body = resp.body.len(),
245                max = self.max_bytes,
246                "cache skip: body exceeds max_bytes"
247            );
248            return Ok(());
249        }
250        let dir = self.entry_dir();
251        fs::create_dir_all(&dir).map_err(|e| {
252            AppError::with_source(
253                ErrorKind::Internal,
254                format!("failed to create cache dir {}", dir.display()),
255                e,
256            )
257        })?;
258        crate::platform::restrict_private_dir(&dir);
259        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, accept);
260        let input_sha = input_checksum(url.as_str(), CACHE_PARSER_VERSION, accept);
261        let body_sha = sha256_hex(resp.body.as_ref());
262        let meta = CacheMeta {
263            url: url.as_str().to_string(),
264            parser_version: CACHE_PARSER_VERSION.to_string(),
265            accept: accept.to_string(),
266            status: resp.status.as_u16(),
267            content_type: resp.content_type.clone(),
268            final_url: resp.final_url.as_str().to_string(),
269            stored_at_unix: unix_now(),
270            body_sha256: body_sha,
271            input_sha256: input_sha,
272        };
273        let (meta_path, body_path) = self.paths_for_key(&key);
274        let meta_tmp = meta_path.with_extension("meta.json.tmp");
275        let body_tmp = body_path.with_extension("bin.tmp");
276
277        // RAII: remove temps on any early return / panic; disarmed after successful renames.
278        struct TempCleanup {
279            paths: [PathBuf; 2],
280            armed: bool,
281        }
282        impl Drop for TempCleanup {
283            fn drop(&mut self) {
284                if !self.armed {
285                    return;
286                }
287                for p in &self.paths {
288                    if p.as_os_str().is_empty() {
289                        continue;
290                    }
291                    let _ = fs::remove_file(p);
292                }
293            }
294        }
295        // Move temps into RAII guard — no PathBuf clone; create/rename borrow `temps.paths`.
296        let mut temps = TempCleanup {
297            paths: [body_tmp, meta_tmp],
298            armed: true,
299        };
300
301        {
302            let mut f = fs::File::create(&temps.paths[0]).map_err(|e| {
303                AppError::with_source(ErrorKind::Internal, "cache body temp create", e)
304            })?;
305            f.write_all(resp.body.as_ref())
306                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache body write", e))?;
307            f.sync_all()
308                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache body sync", e))?;
309        }
310        {
311            // Compact JSON (RFC 8259) for machine meta — pretty is only for human markdown paths.
312            let text = serde_json::to_string(&meta).map_err(|e| {
313                AppError::with_source(ErrorKind::Internal, "cache meta serialize", e)
314            })?;
315            let mut f = fs::File::create(&temps.paths[1]).map_err(|e| {
316                AppError::with_source(ErrorKind::Internal, "cache meta temp create", e)
317            })?;
318            f.write_all(text.as_bytes())
319                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache meta write", e))?;
320            f.sync_all()
321                .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache meta sync", e))?;
322        }
323
324        fs::rename(&temps.paths[0], &body_path)
325            .map_err(|e| AppError::with_source(ErrorKind::Internal, "cache body rename", e))?;
326        crate::platform::restrict_private_file(&body_path);
327        // body temp is gone; only meta temp remains if the next rename fails.
328        temps.paths[0] = PathBuf::new();
329        fs::rename(&temps.paths[1], &meta_path).map_err(|e| {
330            // Best-effort: body already renamed; leave it for next put or eviction.
331            AppError::with_source(ErrorKind::Internal, "cache meta rename", e)
332        })?;
333        crate::platform::restrict_private_file(&meta_path);
334        temps.armed = false;
335        debug!(%key, "cache store");
336        self.enforce_max_bytes(Some(&key));
337        Ok(())
338    }
339
340    /// Remove every entry under `http/v1` (temps included).
341    ///
342    /// # Errors
343    ///
344    /// Returns [`ErrorKind::Internal`] when the cache directory cannot be read.
345    pub fn clear(&self) -> AppResult<CacheClearResult> {
346        let dir = self.entry_dir();
347        let mut removed_entries = 0u64;
348        let mut freed_bytes = 0u64;
349        if dir.is_dir() {
350            for entry in fs::read_dir(&dir).map_err(|e| {
351                AppError::with_source(ErrorKind::Internal, "cache clear read_dir", e)
352            })? {
353                let entry = entry.map_err(|e| {
354                    AppError::with_source(ErrorKind::Internal, "cache clear entry", e)
355                })?;
356                let path = entry.path();
357                let len = entry.metadata().map(|m| m.len()).unwrap_or(0);
358                if path.is_file() {
359                    // Count complete pairs by .meta.json files.
360                    if path
361                        .file_name()
362                        .and_then(|n| n.to_str())
363                        .is_some_and(|n| n.ends_with(".meta.json"))
364                    {
365                        removed_entries = removed_entries.saturating_add(1);
366                    }
367                    freed_bytes = freed_bytes.saturating_add(len);
368                    let _ = fs::remove_file(&path);
369                }
370            }
371        }
372        Ok(CacheClearResult {
373            root: self.root.display().to_string(),
374            removed_entries,
375            freed_bytes,
376        })
377    }
378
379    /// Inventory of on-disk entries and budget.
380    pub fn stats(&self) -> CacheStats {
381        let entries = self.scan_entries();
382        let total_bytes = entries.iter().map(|e| e.bytes).sum();
383        CacheStats {
384            root: self.root.display().to_string(),
385            layout: CACHE_LAYOUT.to_string(),
386            entries: entries.len() as u64,
387            total_bytes,
388            max_bytes: self.max_bytes,
389            ttl_secs: self.ttl.as_secs(),
390            parser_version: CACHE_PARSER_VERSION.to_string(),
391        }
392    }
393
394    fn scan_entries(&self) -> Vec<EntryOnDisk> {
395        let dir = self.entry_dir();
396        let mut out = Vec::new();
397        let Ok(rd) = fs::read_dir(&dir) else {
398            return out;
399        };
400        for entry in rd.flatten() {
401            let path = entry.path();
402            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
403                continue;
404            };
405            let Some(key) = name.strip_suffix(".meta.json") else {
406                continue;
407            };
408            let (meta_path, body_path) = self.paths_for_key(key);
409            if !meta_path.is_file() || !body_path.is_file() {
410                continue;
411            }
412            let meta_len = fs::metadata(&meta_path).map(|m| m.len()).unwrap_or(0);
413            let body_len = fs::metadata(&body_path).map(|m| m.len()).unwrap_or(0);
414            // Cap + fallible read (same helper as get): poisoned meta must not
415            // force unbounded allocation during stats/evict scans.
416            let stored_at = read_meta_file(&meta_path)
417                .map(|m| m.stored_at_unix)
418                .unwrap_or(0);
419            out.push(EntryOnDisk {
420                key: key.to_string(),
421                stored_at_unix: stored_at,
422                bytes: meta_len.saturating_add(body_len),
423            });
424        }
425        out
426    }
427
428    /// Evict oldest entries until total size is within `max_bytes`.
429    /// Never deletes `keep_key` (the entry just written): a single large body
430    /// may temporarily exceed the soft budget.
431    fn enforce_max_bytes(&self, keep_key: Option<&str>) {
432        if self.max_bytes == 0 {
433            return;
434        }
435        loop {
436            let mut entries = self.scan_entries();
437            let total: u64 = entries.iter().map(|e| e.bytes).sum();
438            if total <= self.max_bytes {
439                break;
440            }
441            entries.sort_by_key(|e| e.stored_at_unix);
442            let victim = entries
443                .iter()
444                .find(|e| keep_key.is_none_or(|k| k != e.key.as_str()));
445            let Some(v) = victim else {
446                // Only keep_key remains (or empty); stop even if still over budget.
447                break;
448            };
449            debug!(key = %v.key, "cache evict for budget");
450            let _ = self.remove_entry(&v.key);
451        }
452    }
453
454    fn remove_entry(&self, key_hex: &str) -> AppResult<()> {
455        let (meta_path, body_path) = self.paths_for_key(key_hex);
456        let _ = fs::remove_file(meta_path);
457        let _ = fs::remove_file(body_path);
458        Ok(())
459    }
460}
461
462/// Resolve cache root: override, env, `DOCSRS_CLI_HOME/cache`, then XDG cache home.
463///
464/// Precedence:
465/// 1. Explicit override (`--cache-dir` / caller)
466/// 2. `DOCSRS_CLI_CACHE_DIR`
467/// 3. `{DOCSRS_CLI_HOME}/cache` when `DOCSRS_CLI_HOME` is set
468/// 4. `directories::ProjectDirs` cache dir
469pub fn resolve_cache_dir(override_dir: Option<PathBuf>) -> Option<PathBuf> {
470    resolve_cache_dir_with_source(override_dir).0
471}
472
473/// Resolve cache root and report which layer won.
474pub fn resolve_cache_dir_with_source(
475    override_dir: Option<PathBuf>,
476) -> (Option<PathBuf>, crate::config::PathSource) {
477    use crate::config::PathSource;
478    if let Some(p) = override_dir {
479        return (Some(p), PathSource::CliOrEnv);
480    }
481    if let Some(p) = std::env::var_os("DOCSRS_CLI_CACHE_DIR") {
482        return (Some(PathBuf::from(p)), PathSource::CliOrEnv);
483    }
484    if let Some(h) = std::env::var_os("DOCSRS_CLI_HOME") {
485        return (Some(PathBuf::from(h).join("cache")), PathSource::HomeSandbox);
486    }
487    if let Some(p) = directories::ProjectDirs::from("", "", crate::config::APP_NAME)
488        .map(|d| d.cache_dir().to_path_buf())
489    {
490        return (Some(p), PathSource::Xdg);
491    }
492    (None, PathSource::Unresolved)
493}
494
495fn key_hex(url: &str, parser_version: &str, accept: &str) -> String {
496    input_checksum(url, parser_version, accept)
497}
498
499/// Read and parse a cache meta file with a hard size ceiling and fallible reserve.
500///
501/// Returns `None` on missing file, oversize, OOM reserve, I/O error, or JSON parse
502/// failure (best-effort cache semantics — treat as miss).
503fn read_meta_file(path: &Path) -> Option<CacheMeta> {
504    let len = fs::metadata(path).ok()?.len();
505    if len > MAX_CACHE_META_BYTES {
506        debug!(
507            path = %path.display(),
508            len,
509            cap = MAX_CACHE_META_BYTES,
510            "cache meta exceeds cap"
511        );
512        return None;
513    }
514    let n = usize::try_from(len).ok()?;
515    let mut buf = Vec::new();
516    if let Err(e) = buf.try_reserve_exact(n) {
517        debug!(
518            path = %path.display(),
519            len,
520            error = %e,
521            "cache meta reserve failed"
522        );
523        return None;
524    }
525    buf.resize(n, 0);
526    {
527        let mut file = fs::File::open(path).ok()?;
528        if file.read_exact(&mut buf).is_err() {
529            return None;
530        }
531    }
532    serde_json::from_slice(&buf).ok()
533}
534
535fn input_checksum(url: &str, parser_version: &str, accept: &str) -> String {
536    let mut h = Sha256::new();
537    h.update(url.as_bytes());
538    h.update([0u8]);
539    h.update(parser_version.as_bytes());
540    h.update([0u8]);
541    h.update(accept.as_bytes());
542    hex_encode(h.finalize())
543}
544
545fn sha256_hex(bytes: &[u8]) -> String {
546    let mut h = Sha256::new();
547    h.update(bytes);
548    hex_encode(h.finalize())
549}
550
551fn hex_encode(bytes: impl AsRef<[u8]>) -> String {
552    const HEX: &[u8; 16] = b"0123456789abcdef";
553    let bytes = bytes.as_ref();
554    let mut out = String::with_capacity(bytes.len() * 2);
555    for &b in bytes {
556        out.push(HEX[(b >> 4) as usize] as char);
557        out.push(HEX[(b & 0xf) as usize] as char);
558    }
559    out
560}
561
562fn unix_now() -> u64 {
563    SystemTime::now()
564        .duration_since(UNIX_EPOCH)
565        .map(|d| d.as_secs())
566        .unwrap_or(0)
567}
568
569#[cfg(test)]
570mod tests {
571    use super::*;
572
573    fn sample_resp(url: &Url, body: &'static [u8]) -> HttpResponse {
574        HttpResponse {
575            status: StatusCode::OK,
576            final_url: url.clone(),
577            body: Bytes::from_static(body),
578            content_type: Some("text/html".into()),
579            cache_hit: false,
580        }
581    }
582
583    #[test]
584    fn ttl_zero_never_hits() {
585        let dir = tempfile::tempdir().unwrap();
586        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(0), 0);
587        let url = Url::parse("https://crates.io/api/v1/crates?q=x").unwrap();
588        let resp = sample_resp(&url, b"{}");
589        cache.put(&url, "application/json", &resp).unwrap();
590        assert!(cache.get(&url, "application/json").is_none());
591    }
592
593    #[test]
594    fn expired_entry_is_miss() {
595        let dir = tempfile::tempdir().unwrap();
596        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(10), 0);
597        let url = Url::parse("https://crates.io/api/v1/crates?q=x").unwrap();
598        let resp = sample_resp(&url, b"{}");
599        cache.put(&url, "application/json", &resp).unwrap();
600        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "application/json");
601        let (meta_path, _) = cache.paths_for_key(&key);
602        let mut meta: CacheMeta =
603            serde_json::from_str(&fs::read_to_string(&meta_path).unwrap()).unwrap();
604        meta.stored_at_unix = 1;
605        fs::write(&meta_path, serde_json::to_string(&meta).unwrap()).unwrap();
606        let short = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(1), 0);
607        assert!(short.get(&url, "application/json").is_none());
608    }
609
610    #[test]
611    fn body_tamper_is_miss() {
612        let dir = tempfile::tempdir().unwrap();
613        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
614        let url = Url::parse("https://docs.rs/x/1/x/all.html").unwrap();
615        let resp = sample_resp(&url, b"original");
616        cache.put(&url, "text/html", &resp).unwrap();
617        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
618        let (_, body_path) = cache.paths_for_key(&key);
619        fs::write(&body_path, b"tampered").unwrap();
620        assert!(cache.get(&url, "text/html").is_none());
621    }
622
623    #[test]
624    fn get_refuses_body_over_max_bytes() {
625        // Write with unlimited budget, then read with a tight max_bytes so get
626        // rejects before allocating the oversized body.
627        let dir = tempfile::tempdir().unwrap();
628        let writer = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
629        let url = Url::parse("https://docs.rs/big/1/big/index.html").unwrap();
630        let body = vec![b'z'; 200];
631        writer
632            .put(
633                &url,
634                "text/html",
635                &HttpResponse {
636                    status: StatusCode::OK,
637                    final_url: url.clone(),
638                    body: Bytes::from(body),
639                    content_type: Some("text/html".into()),
640            cache_hit: false,
641        },
642            )
643            .unwrap();
644        let reader = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 50);
645        assert!(reader.get(&url, "text/html").is_none());
646    }
647
648    #[test]
649    fn get_refuses_body_over_hard_max_even_when_budget_unlimited() {
650        // Poison the cache with a body larger than HARD_MAX_BODY_BYTES while
651        // max_bytes=0 (unlimited). get must still refuse before fs::read.
652        use crate::config::HARD_MAX_BODY_BYTES;
653        let dir = tempfile::tempdir().unwrap();
654        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
655        let url = Url::parse("https://docs.rs/poison/1/p/index.html").unwrap();
656        let tiny = sample_resp(&url, b"ok");
657        cache.put(&url, "text/html", &tiny).unwrap();
658        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
659        let (meta_path, body_path) = cache.paths_for_key(&key);
660        // Overwrite body with oversized payload; keep meta checksum wrong so we
661        // would fail checksum if we ever read — but size guard must fire first.
662        let over = (HARD_MAX_BODY_BYTES as usize).saturating_add(1);
663        fs::write(&body_path, vec![b'P'; over]).unwrap();
664        assert!(meta_path.is_file());
665        assert!(cache.get(&url, "text/html").is_none());
666    }
667
668    #[test]
669    fn get_refuses_meta_over_cap() {
670        // Poison meta with a payload larger than MAX_CACHE_META_BYTES; get must
671        // miss without unbounded read_to_string.
672        let dir = tempfile::tempdir().unwrap();
673        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
674        let url = Url::parse("https://docs.rs/poison-meta/1/p/index.html").unwrap();
675        let tiny = sample_resp(&url, b"ok");
676        cache.put(&url, "text/html", &tiny).unwrap();
677        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
678        let (meta_path, _body_path) = cache.paths_for_key(&key);
679        let over = (MAX_CACHE_META_BYTES as usize).saturating_add(1);
680        fs::write(&meta_path, vec![b'{'; over]).unwrap();
681        assert!(meta_path.is_file());
682        assert!(cache.get(&url, "text/html").is_none());
683        // stats/evict scan must also tolerate poisoned meta (no panic/OOM path).
684        let stats = cache.stats();
685        assert_eq!(stats.entries, 1);
686    }
687
688    #[test]
689    fn input_checksum_stable() {
690        let a = input_checksum("https://docs.rs/a", "1", "text/html");
691        let b = input_checksum("https://docs.rs/a", "1", "text/html");
692        let c = input_checksum("https://docs.rs/a", "2", "text/html");
693        assert_eq!(a, b);
694        assert_ne!(a, c);
695        assert_eq!(a.len(), 64);
696    }
697
698    #[test]
699    fn non_success_not_stored() {
700        let dir = tempfile::tempdir().unwrap();
701        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
702        let url = Url::parse("https://docs.rs/missing").unwrap();
703        let resp = HttpResponse {
704            status: StatusCode::NOT_FOUND,
705            final_url: url.clone(),
706            body: Bytes::from_static(b"nope"),
707            content_type: None,
708            cache_hit: false,
709        };
710        cache.put(&url, "text/html", &resp).unwrap();
711        assert!(cache.get(&url, "text/html").is_none());
712    }
713
714    #[test]
715    fn clear_removes_all_entries() {
716        let dir = tempfile::tempdir().unwrap();
717        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
718        for (i, body) in [(1, b"a" as &[u8]), (2, b"bb"), (3, b"ccc")] {
719            let url = Url::parse(&format!("https://docs.rs/c{i}/1/c{i}/index.html")).unwrap();
720            cache
721                .put(&url, "text/html", &sample_resp(&url, body))
722                .unwrap();
723        }
724        let before = cache.stats();
725        assert_eq!(before.entries, 3);
726        assert!(before.total_bytes > 0);
727        let cleared = cache.clear().unwrap();
728        assert_eq!(cleared.removed_entries, 3);
729        assert!(cleared.freed_bytes > 0);
730        let after = cache.stats();
731        assert_eq!(after.entries, 0);
732        assert_eq!(after.total_bytes, 0);
733    }
734
735    #[test]
736    fn max_bytes_evicts_oldest() {
737        let dir = tempfile::tempdir().unwrap();
738        // Budget fits one ~200B body+meta pair but not two.
739        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 700);
740        let u1 = Url::parse("https://docs.rs/a/1/a/index.html").unwrap();
741        let u2 = Url::parse("https://docs.rs/b/1/b/index.html").unwrap();
742        let body1 = vec![b'x'; 200];
743        let body2 = vec![b'y'; 200];
744        cache
745            .put(
746                &u1,
747                "text/html",
748                &HttpResponse {
749                    status: StatusCode::OK,
750                    final_url: u1.clone(),
751                    body: Bytes::from(body1),
752                    content_type: Some("text/html".into()),
753            cache_hit: false,
754        },
755            )
756            .unwrap();
757        std::thread::sleep(Duration::from_millis(20));
758        cache
759            .put(
760                &u2,
761                "text/html",
762                &HttpResponse {
763                    status: StatusCode::OK,
764                    final_url: u2.clone(),
765                    body: Bytes::from(body2),
766                    content_type: Some("text/html".into()),
767            cache_hit: false,
768        },
769            )
770            .unwrap();
771        let stats = cache.stats();
772        assert!(stats.entries <= 1, "stats={stats:?}");
773        assert!(stats.total_bytes <= 700, "stats={stats:?}");
774        // Newest entry is preserved; oldest was evicted for budget.
775        assert!(cache.get(&u2, "text/html").is_some());
776        assert!(cache.get(&u1, "text/html").is_none());
777    }
778
779    #[test]
780    fn max_bytes_skips_body_larger_than_budget() {
781        let dir = tempfile::tempdir().unwrap();
782        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 100);
783        let url = Url::parse("https://docs.rs/big/1/big/index.html").unwrap();
784        let body = vec![b'z'; 500];
785        cache
786            .put(
787                &url,
788                "text/html",
789                &HttpResponse {
790                    status: StatusCode::OK,
791                    final_url: url.clone(),
792                    body: Bytes::from(body),
793                    content_type: Some("text/html".into()),
794            cache_hit: false,
795        },
796            )
797            .unwrap();
798        let stats = cache.stats();
799        assert_eq!(stats.entries, 0, "stats={stats:?}");
800        assert_eq!(stats.total_bytes, 0, "stats={stats:?}");
801        assert!(cache.get(&url, "text/html").is_none());
802    }
803}