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 (
486            Some(PathBuf::from(h).join("cache")),
487            PathSource::HomeSandbox,
488        );
489    }
490    if let Some(p) = directories::ProjectDirs::from("", "", crate::config::APP_NAME)
491        .map(|d| d.cache_dir().to_path_buf())
492    {
493        return (Some(p), PathSource::Xdg);
494    }
495    (None, PathSource::Unresolved)
496}
497
498fn key_hex(url: &str, parser_version: &str, accept: &str) -> String {
499    input_checksum(url, parser_version, accept)
500}
501
502/// Read and parse a cache meta file with a hard size ceiling and fallible reserve.
503///
504/// Returns `None` on missing file, oversize, OOM reserve, I/O error, or JSON parse
505/// failure (best-effort cache semantics — treat as miss).
506fn read_meta_file(path: &Path) -> Option<CacheMeta> {
507    let len = fs::metadata(path).ok()?.len();
508    if len > MAX_CACHE_META_BYTES {
509        debug!(
510            path = %path.display(),
511            len,
512            cap = MAX_CACHE_META_BYTES,
513            "cache meta exceeds cap"
514        );
515        return None;
516    }
517    let n = usize::try_from(len).ok()?;
518    let mut buf = Vec::new();
519    if let Err(e) = buf.try_reserve_exact(n) {
520        debug!(
521            path = %path.display(),
522            len,
523            error = %e,
524            "cache meta reserve failed"
525        );
526        return None;
527    }
528    buf.resize(n, 0);
529    {
530        let mut file = fs::File::open(path).ok()?;
531        if file.read_exact(&mut buf).is_err() {
532            return None;
533        }
534    }
535    serde_json::from_slice(&buf).ok()
536}
537
538fn input_checksum(url: &str, parser_version: &str, accept: &str) -> String {
539    let mut h = Sha256::new();
540    h.update(url.as_bytes());
541    h.update([0u8]);
542    h.update(parser_version.as_bytes());
543    h.update([0u8]);
544    h.update(accept.as_bytes());
545    hex_encode(h.finalize())
546}
547
548fn sha256_hex(bytes: &[u8]) -> String {
549    let mut h = Sha256::new();
550    h.update(bytes);
551    hex_encode(h.finalize())
552}
553
554fn hex_encode(bytes: impl AsRef<[u8]>) -> String {
555    const HEX: &[u8; 16] = b"0123456789abcdef";
556    let bytes = bytes.as_ref();
557    let mut out = String::with_capacity(bytes.len() * 2);
558    for &b in bytes {
559        out.push(HEX[(b >> 4) as usize] as char);
560        out.push(HEX[(b & 0xf) as usize] as char);
561    }
562    out
563}
564
565fn unix_now() -> u64 {
566    SystemTime::now()
567        .duration_since(UNIX_EPOCH)
568        .map(|d| d.as_secs())
569        .unwrap_or(0)
570}
571
572#[cfg(test)]
573mod tests {
574    use super::*;
575
576    fn sample_resp(url: &Url, body: &'static [u8]) -> HttpResponse {
577        HttpResponse {
578            status: StatusCode::OK,
579            final_url: url.clone(),
580            body: Bytes::from_static(body),
581            content_type: Some("text/html".into()),
582            cache_hit: false,
583        }
584    }
585
586    #[test]
587    fn ttl_zero_never_hits() {
588        let dir = tempfile::tempdir().unwrap();
589        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(0), 0);
590        let url = Url::parse("https://crates.io/api/v1/crates?q=x").unwrap();
591        let resp = sample_resp(&url, b"{}");
592        cache.put(&url, "application/json", &resp).unwrap();
593        assert!(cache.get(&url, "application/json").is_none());
594    }
595
596    #[test]
597    fn expired_entry_is_miss() {
598        let dir = tempfile::tempdir().unwrap();
599        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(10), 0);
600        let url = Url::parse("https://crates.io/api/v1/crates?q=x").unwrap();
601        let resp = sample_resp(&url, b"{}");
602        cache.put(&url, "application/json", &resp).unwrap();
603        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "application/json");
604        let (meta_path, _) = cache.paths_for_key(&key);
605        let mut meta: CacheMeta =
606            serde_json::from_str(&fs::read_to_string(&meta_path).unwrap()).unwrap();
607        meta.stored_at_unix = 1;
608        fs::write(&meta_path, serde_json::to_string(&meta).unwrap()).unwrap();
609        let short = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(1), 0);
610        assert!(short.get(&url, "application/json").is_none());
611    }
612
613    #[test]
614    fn body_tamper_is_miss() {
615        let dir = tempfile::tempdir().unwrap();
616        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
617        let url = Url::parse("https://docs.rs/x/1/x/all.html").unwrap();
618        let resp = sample_resp(&url, b"original");
619        cache.put(&url, "text/html", &resp).unwrap();
620        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
621        let (_, body_path) = cache.paths_for_key(&key);
622        fs::write(&body_path, b"tampered").unwrap();
623        assert!(cache.get(&url, "text/html").is_none());
624    }
625
626    #[test]
627    fn get_refuses_body_over_max_bytes() {
628        // Write with unlimited budget, then read with a tight max_bytes so get
629        // rejects before allocating the oversized body.
630        let dir = tempfile::tempdir().unwrap();
631        let writer = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
632        let url = Url::parse("https://docs.rs/big/1/big/index.html").unwrap();
633        let body = vec![b'z'; 200];
634        writer
635            .put(
636                &url,
637                "text/html",
638                &HttpResponse {
639                    status: StatusCode::OK,
640                    final_url: url.clone(),
641                    body: Bytes::from(body),
642                    content_type: Some("text/html".into()),
643                    cache_hit: false,
644                },
645            )
646            .unwrap();
647        let reader = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 50);
648        assert!(reader.get(&url, "text/html").is_none());
649    }
650
651    #[test]
652    fn get_refuses_body_over_hard_max_even_when_budget_unlimited() {
653        // Poison the cache with a body larger than HARD_MAX_BODY_BYTES while
654        // max_bytes=0 (unlimited). get must still refuse before fs::read.
655        use crate::config::HARD_MAX_BODY_BYTES;
656        let dir = tempfile::tempdir().unwrap();
657        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
658        let url = Url::parse("https://docs.rs/poison/1/p/index.html").unwrap();
659        let tiny = sample_resp(&url, b"ok");
660        cache.put(&url, "text/html", &tiny).unwrap();
661        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
662        let (meta_path, body_path) = cache.paths_for_key(&key);
663        // Overwrite body with oversized payload; keep meta checksum wrong so we
664        // would fail checksum if we ever read — but size guard must fire first.
665        let over = (HARD_MAX_BODY_BYTES as usize).saturating_add(1);
666        fs::write(&body_path, vec![b'P'; over]).unwrap();
667        assert!(meta_path.is_file());
668        assert!(cache.get(&url, "text/html").is_none());
669    }
670
671    #[test]
672    fn get_refuses_meta_over_cap() {
673        // Poison meta with a payload larger than MAX_CACHE_META_BYTES; get must
674        // miss without unbounded read_to_string.
675        let dir = tempfile::tempdir().unwrap();
676        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
677        let url = Url::parse("https://docs.rs/poison-meta/1/p/index.html").unwrap();
678        let tiny = sample_resp(&url, b"ok");
679        cache.put(&url, "text/html", &tiny).unwrap();
680        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
681        let (meta_path, _body_path) = cache.paths_for_key(&key);
682        let over = (MAX_CACHE_META_BYTES as usize).saturating_add(1);
683        fs::write(&meta_path, vec![b'{'; over]).unwrap();
684        assert!(meta_path.is_file());
685        assert!(cache.get(&url, "text/html").is_none());
686        // stats/evict scan must also tolerate poisoned meta (no panic/OOM path).
687        let stats = cache.stats();
688        assert_eq!(stats.entries, 1);
689    }
690
691    #[test]
692    fn input_checksum_stable() {
693        let a = input_checksum("https://docs.rs/a", "1", "text/html");
694        let b = input_checksum("https://docs.rs/a", "1", "text/html");
695        let c = input_checksum("https://docs.rs/a", "2", "text/html");
696        assert_eq!(a, b);
697        assert_ne!(a, c);
698        assert_eq!(a.len(), 64);
699    }
700
701    #[test]
702    fn non_success_not_stored() {
703        let dir = tempfile::tempdir().unwrap();
704        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
705        let url = Url::parse("https://docs.rs/missing").unwrap();
706        let resp = HttpResponse {
707            status: StatusCode::NOT_FOUND,
708            final_url: url.clone(),
709            body: Bytes::from_static(b"nope"),
710            content_type: None,
711            cache_hit: false,
712        };
713        cache.put(&url, "text/html", &resp).unwrap();
714        assert!(cache.get(&url, "text/html").is_none());
715    }
716
717    #[test]
718    fn clear_removes_all_entries() {
719        let dir = tempfile::tempdir().unwrap();
720        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 0);
721        for (i, body) in [(1, b"a" as &[u8]), (2, b"bb"), (3, b"ccc")] {
722            let url = Url::parse(&format!("https://docs.rs/c{i}/1/c{i}/index.html")).unwrap();
723            cache
724                .put(&url, "text/html", &sample_resp(&url, body))
725                .unwrap();
726        }
727        let before = cache.stats();
728        assert_eq!(before.entries, 3);
729        assert!(before.total_bytes > 0);
730        let cleared = cache.clear().unwrap();
731        assert_eq!(cleared.removed_entries, 3);
732        assert!(cleared.freed_bytes > 0);
733        let after = cache.stats();
734        assert_eq!(after.entries, 0);
735        assert_eq!(after.total_bytes, 0);
736    }
737
738    #[test]
739    fn max_bytes_evicts_oldest() {
740        let dir = tempfile::tempdir().unwrap();
741        // Budget fits one ~200B body+meta pair but not two.
742        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 700);
743        let u1 = Url::parse("https://docs.rs/a/1/a/index.html").unwrap();
744        let u2 = Url::parse("https://docs.rs/b/1/b/index.html").unwrap();
745        let body1 = vec![b'x'; 200];
746        let body2 = vec![b'y'; 200];
747        cache
748            .put(
749                &u1,
750                "text/html",
751                &HttpResponse {
752                    status: StatusCode::OK,
753                    final_url: u1.clone(),
754                    body: Bytes::from(body1),
755                    content_type: Some("text/html".into()),
756                    cache_hit: false,
757                },
758            )
759            .unwrap();
760        std::thread::sleep(Duration::from_millis(20));
761        cache
762            .put(
763                &u2,
764                "text/html",
765                &HttpResponse {
766                    status: StatusCode::OK,
767                    final_url: u2.clone(),
768                    body: Bytes::from(body2),
769                    content_type: Some("text/html".into()),
770                    cache_hit: false,
771                },
772            )
773            .unwrap();
774        let stats = cache.stats();
775        assert!(stats.entries <= 1, "stats={stats:?}");
776        assert!(stats.total_bytes <= 700, "stats={stats:?}");
777        // Newest entry is preserved; oldest was evicted for budget.
778        assert!(cache.get(&u2, "text/html").is_some());
779        assert!(cache.get(&u1, "text/html").is_none());
780    }
781
782    #[test]
783    fn max_bytes_skips_body_larger_than_budget() {
784        let dir = tempfile::tempdir().unwrap();
785        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(3600), 100);
786        let url = Url::parse("https://docs.rs/big/1/big/index.html").unwrap();
787        let body = vec![b'z'; 500];
788        cache
789            .put(
790                &url,
791                "text/html",
792                &HttpResponse {
793                    status: StatusCode::OK,
794                    final_url: url.clone(),
795                    body: Bytes::from(body),
796                    content_type: Some("text/html".into()),
797                    cache_hit: false,
798                },
799            )
800            .unwrap();
801        let stats = cache.stats();
802        assert_eq!(stats.entries, 0, "stats={stats:?}");
803        assert_eq!(stats.total_bytes, 0, "stats={stats:?}");
804        assert!(cache.get(&url, "text/html").is_none());
805    }
806}