tea_coding_tools/web_fetch/
cache.rs1use 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
13pub const DEFAULT_FETCH_CACHE_TTL: Duration = Duration::from_mins(5);
15pub const MAX_FETCH_CACHE_TTL: Duration = Duration::from_hours(1);
17pub const DEFAULT_FETCH_CACHE_ENTRIES: usize = 64;
19pub const MAX_FETCH_CACHE_ENTRIES: usize = 1_024;
21pub const DEFAULT_FETCH_CACHE_TOTAL_BYTES: usize = 8 * 1024 * 1024;
23pub const MAX_FETCH_CACHE_TOTAL_BYTES: usize = 64 * 1024 * 1024;
25pub const DEFAULT_FETCH_CACHE_ENTRY_BYTES: usize = 1024 * 1024;
27pub 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#[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 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 #[must_use]
76 pub const fn ttl(self) -> Duration {
77 self.ttl
78 }
79
80 #[must_use]
82 pub const fn max_entries(self) -> usize {
83 self.entries
84 }
85
86 #[must_use]
88 pub const fn max_total_bytes(self) -> usize {
89 self.total_bytes
90 }
91
92 #[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#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
112pub struct FetchCacheScope {
113 workspace: String,
114 profile: String,
115}
116
117impl FetchCacheScope {
118 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
158pub struct FetchCacheStats {
159 entries: usize,
160 logical_bytes: usize,
161}
162
163impl FetchCacheStats {
164 #[must_use]
166 pub const fn entries(self) -> usize {
167 self.entries
168 }
169
170 #[must_use]
172 pub const fn logical_bytes(self) -> usize {
173 self.logical_bytes
174 }
175}
176
177pub struct FetchResultCache {
179 config: FetchCacheConfig,
180 state: Mutex<CacheState>,
181}
182
183impl FetchResultCache {
184 #[must_use]
186 pub fn new(config: FetchCacheConfig) -> Self {
187 Self {
188 config,
189 state: Mutex::new(CacheState::default()),
190 }
191 }
192
193 #[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 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}