Skip to main content

tea_coding_tools/web_fetch/
cache.rs

1use std::collections::BTreeMap;
2use std::fmt;
3use std::mem::size_of;
4use std::sync::{Mutex, MutexGuard};
5use std::time::Duration;
6
7use tokio::time::Instant;
8
9use super::{
10    FetchBodyLimits, FetchHttpConfig, FetchProviderError, FetchProviderErrorCode, FetchResult,
11};
12
13/// Default lifetime of a normalized fetch cache entry.
14pub const DEFAULT_FETCH_CACHE_TTL: Duration = Duration::from_mins(5);
15/// Maximum configurable fetch cache entry lifetime.
16pub const MAX_FETCH_CACHE_TTL: Duration = Duration::from_hours(1);
17/// Default maximum number of normalized fetch cache entries.
18pub const DEFAULT_FETCH_CACHE_ENTRIES: usize = 64;
19/// Absolute maximum number of normalized fetch cache entries.
20pub const MAX_FETCH_CACHE_ENTRIES: usize = 1_024;
21/// Default aggregate logical bytes retained by the fetch cache.
22pub const DEFAULT_FETCH_CACHE_TOTAL_BYTES: usize = 8 * 1024 * 1024;
23/// Absolute aggregate logical byte limit for the fetch cache.
24pub const MAX_FETCH_CACHE_TOTAL_BYTES: usize = 64 * 1024 * 1024;
25/// Default maximum logical bytes retained by one fetch cache entry.
26pub const DEFAULT_FETCH_CACHE_ENTRY_BYTES: usize = 1024 * 1024;
27/// Absolute logical byte limit for one fetch cache entry.
28pub const MAX_FETCH_CACHE_ENTRY_BYTES: usize = 4 * 1024 * 1024;
29
30const MAX_FETCH_CACHE_SCOPE_BYTES: usize = 4 * 1024;
31const CACHE_ENTRY_OVERHEAD_BYTES: usize = 512;
32
33/// Independently bounded TTL, entry-count, and byte limits for fetch caching.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub struct FetchCacheConfig {
36    ttl: Duration,
37    entries: usize,
38    total_bytes: usize,
39    entry_bytes: usize,
40}
41
42impl FetchCacheConfig {
43    /// Creates a bounded cache configuration.
44    ///
45    /// # Errors
46    ///
47    /// Rejects zero values, values above absolute limits, or a per-entry byte
48    /// limit larger than the aggregate byte limit.
49    pub fn new(
50        ttl: Duration,
51        max_entries: usize,
52        max_total_bytes: usize,
53        max_entry_bytes: usize,
54    ) -> Result<Self, FetchProviderError> {
55        if ttl.is_zero()
56            || ttl > MAX_FETCH_CACHE_TTL
57            || !(1..=MAX_FETCH_CACHE_ENTRIES).contains(&max_entries)
58            || !(1..=MAX_FETCH_CACHE_TOTAL_BYTES).contains(&max_total_bytes)
59            || !(1..=MAX_FETCH_CACHE_ENTRY_BYTES).contains(&max_entry_bytes)
60            || max_entry_bytes > max_total_bytes
61        {
62            return Err(FetchProviderError::new(
63                FetchProviderErrorCode::InvalidConfiguration,
64            ));
65        }
66        Ok(Self {
67            ttl,
68            entries: max_entries,
69            total_bytes: max_total_bytes,
70            entry_bytes: max_entry_bytes,
71        })
72    }
73
74    /// Returns the entry lifetime.
75    #[must_use]
76    pub const fn ttl(self) -> Duration {
77        self.ttl
78    }
79
80    /// Returns the maximum entry count.
81    #[must_use]
82    pub const fn max_entries(self) -> usize {
83        self.entries
84    }
85
86    /// Returns the aggregate logical byte limit.
87    #[must_use]
88    pub const fn max_total_bytes(self) -> usize {
89        self.total_bytes
90    }
91
92    /// Returns the per-entry logical byte limit.
93    #[must_use]
94    pub const fn max_entry_bytes(self) -> usize {
95        self.entry_bytes
96    }
97}
98
99impl Default for FetchCacheConfig {
100    fn default() -> Self {
101        Self {
102            ttl: DEFAULT_FETCH_CACHE_TTL,
103            entries: DEFAULT_FETCH_CACHE_ENTRIES,
104            total_bytes: DEFAULT_FETCH_CACHE_TOTAL_BYTES,
105            entry_bytes: DEFAULT_FETCH_CACHE_ENTRY_BYTES,
106        }
107    }
108}
109
110/// Cache isolation boundary supplied by the upper-layer workspace and profile.
111#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
112pub struct FetchCacheScope {
113    workspace: String,
114    profile: String,
115}
116
117impl FetchCacheScope {
118    /// Creates an opaque bounded workspace/profile cache scope.
119    ///
120    /// # Errors
121    ///
122    /// Rejects empty, oversized, NUL-containing, or control-containing values.
123    pub fn new(
124        workspace: impl Into<String>,
125        profile: impl Into<String>,
126    ) -> Result<Self, FetchProviderError> {
127        let workspace = validate_scope_component(workspace.into())?;
128        let profile = validate_scope_component(profile.into())?;
129        Ok(Self { workspace, profile })
130    }
131}
132
133impl fmt::Debug for FetchCacheScope {
134    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
135        formatter
136            .debug_struct("FetchCacheScope")
137            .field("workspace_bytes", &self.workspace.len())
138            .field("profile_bytes", &self.profile.len())
139            .finish_non_exhaustive()
140    }
141}
142
143fn validate_scope_component(value: String) -> Result<String, FetchProviderError> {
144    if value.is_empty()
145        || value.len() > MAX_FETCH_CACHE_SCOPE_BYTES
146        || value.chars().any(char::is_control)
147    {
148        Err(FetchProviderError::new(
149            FetchProviderErrorCode::InvalidConfiguration,
150        ))
151    } else {
152        Ok(value)
153    }
154}
155
156/// Non-sensitive fetch cache occupancy snapshot.
157#[derive(Debug, Clone, Copy, PartialEq, Eq)]
158pub struct FetchCacheStats {
159    entries: usize,
160    logical_bytes: usize,
161}
162
163impl FetchCacheStats {
164    /// Returns the current entry count.
165    #[must_use]
166    pub const fn entries(self) -> usize {
167        self.entries
168    }
169
170    /// Returns the current bounded logical byte count.
171    #[must_use]
172    pub const fn logical_bytes(self) -> usize {
173        self.logical_bytes
174    }
175}
176
177/// Shared bounded in-memory cache of normalized fetch results.
178pub struct FetchResultCache {
179    config: FetchCacheConfig,
180    state: Mutex<CacheState>,
181}
182
183impl FetchResultCache {
184    /// Creates an empty normalized-result cache.
185    #[must_use]
186    pub fn new(config: FetchCacheConfig) -> Self {
187        Self {
188            config,
189            state: Mutex::new(CacheState::default()),
190        }
191    }
192
193    /// Returns a non-sensitive occupancy snapshot after purging expired entries.
194    #[must_use]
195    pub fn stats(&self) -> FetchCacheStats {
196        let mut state = self.lock_state();
197        state.purge_expired(Instant::now());
198        FetchCacheStats {
199            entries: state.entries.len(),
200            logical_bytes: state.logical_bytes,
201        }
202    }
203
204    /// Removes every cache entry without exposing its key or body.
205    pub fn clear(&self) {
206        *self.lock_state() = CacheState::default();
207    }
208
209    pub(crate) fn get(&self, key: &FetchCacheKey) -> Option<FetchResult> {
210        self.get_at(key, Instant::now())
211    }
212
213    fn get_at(&self, key: &FetchCacheKey, now: Instant) -> Option<FetchResult> {
214        let mut state = self.lock_state();
215        state.purge_expired(now);
216        if !state.entries.contains_key(key) {
217            return None;
218        }
219        let access = state.next_access();
220        let entry = state
221            .entries
222            .get_mut(key)
223            .expect("cache key existence was checked while holding the lock");
224        entry.last_access = access;
225        Some(entry.result.clone())
226    }
227
228    pub(crate) fn insert(&self, key: FetchCacheKey, result: FetchResult) {
229        self.insert_at(key, result, Instant::now());
230    }
231
232    fn insert_at(&self, key: FetchCacheKey, result: FetchResult, now: Instant) {
233        let logical_bytes = key
234            .logical_bytes()
235            .saturating_add(result_logical_bytes(&result));
236        if logical_bytes > self.config.max_entry_bytes()
237            || logical_bytes > self.config.max_total_bytes()
238        {
239            return;
240        }
241
242        let mut state = self.lock_state();
243        state.purge_expired(now);
244        state.remove(&key);
245        while state.entries.len() >= self.config.max_entries()
246            || state.logical_bytes.saturating_add(logical_bytes) > self.config.max_total_bytes()
247        {
248            if !state.evict_least_recently_used() {
249                break;
250            }
251        }
252        let last_access = state.next_access();
253        state.logical_bytes = state.logical_bytes.saturating_add(logical_bytes);
254        state.entries.insert(
255            key,
256            CacheEntry {
257                result,
258                expires_at: now + self.config.ttl(),
259                last_access,
260                logical_bytes,
261            },
262        );
263    }
264
265    fn lock_state(&self) -> MutexGuard<'_, CacheState> {
266        self.state
267            .lock()
268            .unwrap_or_else(std::sync::PoisonError::into_inner)
269    }
270}
271
272impl fmt::Debug for FetchResultCache {
273    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
274        formatter
275            .debug_struct("FetchResultCache")
276            .field("config", &self.config)
277            .field("stats", &self.stats())
278            .finish_non_exhaustive()
279    }
280}
281
282#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
283pub(crate) struct FetchCacheKey {
284    scope: FetchCacheScope,
285    url: String,
286    max_chars: usize,
287    policy: FetchCachePolicyKey,
288}
289
290#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
291pub(crate) struct FetchCachePolicyKey {
292    policy_version: u32,
293    http_config: FetchHttpConfig,
294    body_limits: FetchBodyLimits,
295    accept: &'static str,
296    accept_encoding: &'static str,
297}
298
299impl FetchCacheKey {
300    pub(crate) fn new(
301        scope: FetchCacheScope,
302        url: String,
303        max_chars: usize,
304        policy: FetchCachePolicyKey,
305    ) -> Self {
306        Self {
307            scope,
308            url,
309            max_chars,
310            policy,
311        }
312    }
313
314    fn logical_bytes(&self) -> usize {
315        CACHE_ENTRY_OVERHEAD_BYTES
316            .saturating_add(self.scope.workspace.len())
317            .saturating_add(self.scope.profile.len())
318            .saturating_add(self.url.len())
319            .saturating_add(self.policy.accept.len())
320            .saturating_add(self.policy.accept_encoding.len())
321            .saturating_add(size_of::<usize>())
322            .saturating_add(size_of::<FetchCachePolicyKey>())
323    }
324}
325
326impl FetchCachePolicyKey {
327    pub(crate) const fn new(
328        policy_version: u32,
329        http_config: FetchHttpConfig,
330        body_limits: FetchBodyLimits,
331        accept: &'static str,
332        accept_encoding: &'static str,
333    ) -> Self {
334        Self {
335            policy_version,
336            http_config,
337            body_limits,
338            accept,
339            accept_encoding,
340        }
341    }
342}
343
344#[derive(Default)]
345struct CacheState {
346    entries: BTreeMap<FetchCacheKey, CacheEntry>,
347    logical_bytes: usize,
348    access: u64,
349}
350
351impl CacheState {
352    fn purge_expired(&mut self, now: Instant) {
353        let expired = self
354            .entries
355            .iter()
356            .filter_map(|(key, entry)| (entry.expires_at <= now).then_some(key.clone()))
357            .collect::<Vec<_>>();
358        for key in expired {
359            self.remove(&key);
360        }
361    }
362
363    fn remove(&mut self, key: &FetchCacheKey) {
364        if let Some(entry) = self.entries.remove(key) {
365            self.logical_bytes = self.logical_bytes.saturating_sub(entry.logical_bytes);
366        }
367    }
368
369    fn evict_least_recently_used(&mut self) -> bool {
370        let key = self
371            .entries
372            .iter()
373            .min_by_key(|(_, entry)| entry.last_access)
374            .map(|(key, _)| key.clone());
375        if let Some(key) = key {
376            self.remove(&key);
377            true
378        } else {
379            false
380        }
381    }
382
383    fn next_access(&mut self) -> u64 {
384        if self.access == u64::MAX {
385            for (index, entry) in self.entries.values_mut().enumerate() {
386                entry.last_access = u64::try_from(index).unwrap_or(u64::MAX - 1);
387            }
388            self.access = u64::try_from(self.entries.len()).unwrap_or(u64::MAX - 1);
389        }
390        let access = self.access;
391        self.access = self.access.saturating_add(1);
392        access
393    }
394}
395
396struct CacheEntry {
397    result: FetchResult,
398    expires_at: Instant,
399    last_access: u64,
400    logical_bytes: usize,
401}
402
403fn result_logical_bytes(result: &FetchResult) -> usize {
404    result
405        .requested_url()
406        .len()
407        .saturating_add(result.final_url().len())
408        .saturating_add(result.title().map_or(0, str::len))
409        .saturating_add(result.mime_type().len())
410        .saturating_add(result.body().len())
411        .saturating_add(
412            result
413                .redirects()
414                .iter()
415                .map(|redirect| {
416                    redirect
417                        .from()
418                        .len()
419                        .saturating_add(redirect.to().len())
420                        .saturating_add(size_of::<u16>())
421                })
422                .fold(0_usize, usize::saturating_add),
423        )
424}
425
426#[cfg(test)]
427mod tests {
428    use super::*;
429
430    fn scope() -> FetchCacheScope {
431        FetchCacheScope::new("workspace", "profile").unwrap()
432    }
433
434    fn key(policy_version: u32, accept_encoding: &'static str) -> FetchCacheKey {
435        FetchCacheKey::new(
436            scope(),
437            "https://example.com/guide".to_owned(),
438            100,
439            FetchCachePolicyKey::new(
440                policy_version,
441                FetchHttpConfig::production(),
442                FetchBodyLimits::default(),
443                "text/plain",
444                accept_encoding,
445            ),
446        )
447    }
448
449    fn result() -> FetchResult {
450        FetchResult::new(
451            "https://example.com/guide",
452            "https://example.com/guide",
453            "text/plain; charset=utf-8",
454            "cached body",
455        )
456        .unwrap()
457    }
458
459    #[test]
460    fn expiry_policy_version_and_negotiation_invalidate_entries_without_sleeping() {
461        let ttl = Duration::from_secs(5);
462        let cache = FetchResultCache::new(FetchCacheConfig::new(ttl, 4, 4096, 2048).unwrap());
463        let now = Instant::now();
464        let cached_key = key(1, "identity");
465        cache.insert_at(cached_key.clone(), result(), now);
466
467        assert!(cache.get_at(&cached_key, now).is_some());
468        assert!(cache.get_at(&key(2, "identity"), now).is_none());
469        assert!(cache.get_at(&key(1, "gzip"), now).is_none());
470        assert!(cache.get_at(&cached_key, now + ttl).is_none());
471        assert_eq!(cache.stats().entries(), 0);
472    }
473}