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