Skip to main content

docsrs_cli/cache/
mod.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 [`crate::config::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//!
15//! Layout (SRP): `types` · `hex` · `meta` · `paths` · `disk` (all crate-internal).
16//! `disk` splits further by operation: `disk::read` (serve or refuse a hit),
17//! `disk::store` (durable write), `disk::maintain` (inventory and eviction).
18
19mod disk;
20mod hex;
21mod meta;
22mod paths;
23mod types;
24
25pub use disk::DiskCache;
26pub use paths::{resolve_cache_dir, resolve_cache_dir_with_source};
27pub use types::{
28    CACHE_PARSER_VERSION, CacheClearResult, CacheStats, DEFAULT_CACHE_TTL_SECS,
29    DEFAULT_MAX_CACHE_BYTES, MAX_CACHE_META_BYTES,
30};
31
32#[cfg(test)]
33mod tests {
34    use super::disk::DiskCache;
35    use super::hex::{input_checksum, is_cache_key_hex, key_hex};
36    use super::types::{CACHE_PARSER_VERSION, CacheMeta, MAX_CACHE_META_BYTES};
37    use crate::http::HttpResponse;
38    use bytes::Bytes;
39    use reqwest::{StatusCode, Url};
40    use std::fs;
41    use std::time::Duration;
42
43    fn sample_resp(url: &Url, body: &'static [u8]) -> HttpResponse {
44        HttpResponse {
45            status: StatusCode::OK,
46            final_url: url.clone(),
47            body: Bytes::from_static(body),
48            content_type: Some("text/html".into()),
49            cache_hit: false,
50        }
51    }
52
53    #[test]
54    fn ttl_zero_never_hits() {
55        let dir = tempfile::tempdir().unwrap();
56        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(0), 0, false);
57        let url = Url::parse("https://crates.io/api/v1/crates?q=x").unwrap();
58        let resp = sample_resp(&url, b"{}");
59        cache.put(&url, "application/json", &resp).unwrap();
60        assert!(cache.get(&url, "application/json").is_none());
61    }
62
63    #[test]
64    fn expired_entry_is_miss() {
65        let dir = tempfile::tempdir().unwrap();
66        let cache = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(10), 0, false);
67        let url = Url::parse("https://crates.io/api/v1/crates?q=x").unwrap();
68        let resp = sample_resp(&url, b"{}");
69        cache.put(&url, "application/json", &resp).unwrap();
70        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "application/json");
71        let (meta_path, _) = cache.paths_for_key(&key).expect("valid key");
72        let mut meta: CacheMeta =
73            serde_json::from_str(&fs::read_to_string(&meta_path).unwrap()).unwrap();
74        meta.stored_at_unix = 1;
75        fs::write(&meta_path, serde_json::to_string(&meta).unwrap()).unwrap();
76        let short = DiskCache::new(dir.path().to_path_buf(), Duration::from_secs(1), 0, false);
77        assert!(short.get(&url, "application/json").is_none());
78    }
79
80    #[test]
81    fn body_tamper_is_miss() {
82        let dir = tempfile::tempdir().unwrap();
83        let cache = DiskCache::new(
84            dir.path().to_path_buf(),
85            Duration::from_secs(3600),
86            0,
87            false,
88        );
89        let url = Url::parse("https://docs.rs/x/1/x/all.html").unwrap();
90        let resp = sample_resp(&url, b"original");
91        cache.put(&url, "text/html", &resp).unwrap();
92        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
93        let (_, body_path) = cache.paths_for_key(&key).expect("valid key");
94        fs::write(&body_path, b"tampered").unwrap();
95        assert!(cache.get(&url, "text/html").is_none());
96    }
97
98    #[test]
99    fn get_refuses_body_over_max_bytes() {
100        let dir = tempfile::tempdir().unwrap();
101        let writer = DiskCache::new(
102            dir.path().to_path_buf(),
103            Duration::from_secs(3600),
104            0,
105            false,
106        );
107        let url = Url::parse("https://docs.rs/big/1/big/index.html").unwrap();
108        let body = vec![b'z'; 200];
109        writer
110            .put(
111                &url,
112                "text/html",
113                &HttpResponse {
114                    status: StatusCode::OK,
115                    final_url: url.clone(),
116                    body: Bytes::from(body),
117                    content_type: Some("text/html".into()),
118                    cache_hit: false,
119                },
120            )
121            .unwrap();
122        let reader = DiskCache::new(
123            dir.path().to_path_buf(),
124            Duration::from_secs(3600),
125            50,
126            false,
127        );
128        assert!(reader.get(&url, "text/html").is_none());
129    }
130
131    #[test]
132    fn get_refuses_body_over_hard_max_even_when_budget_unlimited() {
133        use crate::config::HARD_MAX_BODY_BYTES;
134        let dir = tempfile::tempdir().unwrap();
135        let cache = DiskCache::new(
136            dir.path().to_path_buf(),
137            Duration::from_secs(3600),
138            0,
139            false,
140        );
141        let url = Url::parse("https://docs.rs/poison/1/p/index.html").unwrap();
142        let tiny = sample_resp(&url, b"ok");
143        cache.put(&url, "text/html", &tiny).unwrap();
144        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
145        let (meta_path, body_path) = cache.paths_for_key(&key).expect("valid key");
146        let over = (HARD_MAX_BODY_BYTES as usize).saturating_add(1);
147        fs::write(&body_path, vec![b'P'; over]).unwrap();
148        assert!(meta_path.is_file());
149        assert!(cache.get(&url, "text/html").is_none());
150    }
151
152    #[test]
153    fn get_refuses_meta_over_cap() {
154        let dir = tempfile::tempdir().unwrap();
155        let cache = DiskCache::new(
156            dir.path().to_path_buf(),
157            Duration::from_secs(3600),
158            0,
159            false,
160        );
161        let url = Url::parse("https://docs.rs/poison-meta/1/p/index.html").unwrap();
162        let tiny = sample_resp(&url, b"ok");
163        cache.put(&url, "text/html", &tiny).unwrap();
164        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
165        let (meta_path, _body_path) = cache.paths_for_key(&key).expect("valid key");
166        let over = (MAX_CACHE_META_BYTES as usize).saturating_add(1);
167        fs::write(&meta_path, vec![b'{'; over]).unwrap();
168        assert!(meta_path.is_file());
169        assert!(cache.get(&url, "text/html").is_none());
170        let stats = cache.stats();
171        assert_eq!(stats.entries, 1);
172    }
173
174    #[test]
175    fn input_checksum_stable() {
176        let a = input_checksum("https://docs.rs/a", "1", "text/html");
177        let b = input_checksum("https://docs.rs/a", "1", "text/html");
178        let c = input_checksum("https://docs.rs/a", "2", "text/html");
179        assert_eq!(a, b);
180        assert_ne!(a, c);
181        assert_eq!(a.len(), 64);
182        assert!(is_cache_key_hex(&a));
183        assert!(!is_cache_key_hex(".."));
184        assert!(!is_cache_key_hex(""));
185        assert!(!is_cache_key_hex(&"g".repeat(64)));
186    }
187
188    #[test]
189    fn non_success_not_stored() {
190        let dir = tempfile::tempdir().unwrap();
191        let cache = DiskCache::new(
192            dir.path().to_path_buf(),
193            Duration::from_secs(3600),
194            0,
195            false,
196        );
197        let url = Url::parse("https://docs.rs/missing").unwrap();
198        let resp = HttpResponse {
199            status: StatusCode::NOT_FOUND,
200            final_url: url.clone(),
201            body: Bytes::from_static(b"nope"),
202            content_type: None,
203            cache_hit: false,
204        };
205        cache.put(&url, "text/html", &resp).unwrap();
206        assert!(cache.get(&url, "text/html").is_none());
207    }
208
209    #[test]
210    fn clear_removes_all_entries() {
211        let dir = tempfile::tempdir().unwrap();
212        let cache = DiskCache::new(
213            dir.path().to_path_buf(),
214            Duration::from_secs(3600),
215            0,
216            false,
217        );
218        for (i, body) in [(1, b"a" as &[u8]), (2, b"bb"), (3, b"ccc")] {
219            let url = Url::parse(&format!("https://docs.rs/c{i}/1/c{i}/index.html")).unwrap();
220            cache
221                .put(&url, "text/html", &sample_resp(&url, body))
222                .unwrap();
223        }
224        let before = cache.stats();
225        assert_eq!(before.entries, 3);
226        assert!(before.total_bytes > 0);
227        let cleared = cache.clear().unwrap();
228        assert_eq!(cleared.removed_entries, 3);
229        assert!(cleared.freed_bytes > 0);
230        let after = cache.stats();
231        assert_eq!(after.entries, 0);
232        assert_eq!(after.total_bytes, 0);
233    }
234
235    #[test]
236    fn max_bytes_evicts_oldest() {
237        let dir = tempfile::tempdir().unwrap();
238        let cache = DiskCache::new(
239            dir.path().to_path_buf(),
240            Duration::from_secs(3600),
241            700,
242            false,
243        );
244        let u1 = Url::parse("https://docs.rs/a/1/a/index.html").unwrap();
245        let u2 = Url::parse("https://docs.rs/b/1/b/index.html").unwrap();
246        let body1 = vec![b'x'; 200];
247        let body2 = vec![b'y'; 200];
248        cache
249            .put(
250                &u1,
251                "text/html",
252                &HttpResponse {
253                    status: StatusCode::OK,
254                    final_url: u1.clone(),
255                    body: Bytes::from(body1),
256                    content_type: Some("text/html".into()),
257                    cache_hit: false,
258                },
259            )
260            .unwrap();
261        std::thread::sleep(Duration::from_millis(20));
262        cache
263            .put(
264                &u2,
265                "text/html",
266                &HttpResponse {
267                    status: StatusCode::OK,
268                    final_url: u2.clone(),
269                    body: Bytes::from(body2),
270                    content_type: Some("text/html".into()),
271                    cache_hit: false,
272                },
273            )
274            .unwrap();
275        let stats = cache.stats();
276        assert!(stats.entries <= 1, "stats={stats:?}");
277        assert!(stats.total_bytes <= 700, "stats={stats:?}");
278        assert!(cache.get(&u2, "text/html").is_some());
279        assert!(cache.get(&u1, "text/html").is_none());
280    }
281
282    #[test]
283    fn max_bytes_skips_body_larger_than_budget() {
284        let dir = tempfile::tempdir().unwrap();
285        let cache = DiskCache::new(
286            dir.path().to_path_buf(),
287            Duration::from_secs(3600),
288            100,
289            false,
290        );
291        let url = Url::parse("https://docs.rs/big/1/big/index.html").unwrap();
292        let body = vec![b'z'; 500];
293        cache
294            .put(
295                &url,
296                "text/html",
297                &HttpResponse {
298                    status: StatusCode::OK,
299                    final_url: url.clone(),
300                    body: Bytes::from(body),
301                    content_type: Some("text/html".into()),
302                    cache_hit: false,
303                },
304            )
305            .unwrap();
306        let stats = cache.stats();
307        assert_eq!(stats.entries, 0, "stats={stats:?}");
308        assert_eq!(stats.total_bytes, 0, "stats={stats:?}");
309        assert!(cache.get(&url, "text/html").is_none());
310    }
311
312    #[test]
313    fn meta_unknown_field_is_miss() {
314        let dir = tempfile::tempdir().unwrap();
315        let cache = DiskCache::new(
316            dir.path().to_path_buf(),
317            Duration::from_secs(3600),
318            0,
319            false,
320        );
321        let url = Url::parse("https://docs.rs/extra/1/e/index.html").unwrap();
322        cache
323            .put(&url, "text/html", &sample_resp(&url, b"ok"))
324            .unwrap();
325        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
326        let (meta_path, _) = cache.paths_for_key(&key).expect("valid key");
327        let mut v: serde_json::Value =
328            serde_json::from_str(&fs::read_to_string(&meta_path).unwrap()).unwrap();
329        v.as_object_mut()
330            .unwrap()
331            .insert("evil_extra".into(), serde_json::json!(true));
332        fs::write(&meta_path, serde_json::to_string(&v).unwrap()).unwrap();
333        assert!(cache.get(&url, "text/html").is_none());
334    }
335
336    #[test]
337    fn meta_bad_digest_shape_is_miss() {
338        let dir = tempfile::tempdir().unwrap();
339        let cache = DiskCache::new(
340            dir.path().to_path_buf(),
341            Duration::from_secs(3600),
342            0,
343            false,
344        );
345        let url = Url::parse("https://docs.rs/baddigest/1/b/index.html").unwrap();
346        cache
347            .put(&url, "text/html", &sample_resp(&url, b"ok"))
348            .unwrap();
349        let key = key_hex(url.as_str(), CACHE_PARSER_VERSION, "text/html");
350        let (meta_path, _) = cache.paths_for_key(&key).expect("valid key");
351        let mut meta: CacheMeta =
352            serde_json::from_str(&fs::read_to_string(&meta_path).unwrap()).unwrap();
353        meta.body_sha256 = "not-hex".into();
354        fs::write(&meta_path, serde_json::to_string(&meta).unwrap()).unwrap();
355        assert!(cache.get(&url, "text/html").is_none());
356    }
357}