Skip to main content

fetchium_core/cache/
mod.rs

1//! Cache system — Memory LRU (moka) + SQLite disk (PRD §28).
2//!
3//! Phase 1: In-memory LRU cache using the `moka` crate.
4//! Phase 2+: Disk-backed SQLite cache for cross-session persistence.
5//!
6//! Cache key convention:
7//!   - Fetch:  "fetch:{url}"
8//!   - Search: "search:{query}:{backend}:{max_results}"
9//!   - QATBE:  "qatbe:{url}:{query}:{budget}"
10
11use moka::future::Cache;
12use serde::{Deserialize, Serialize};
13use std::sync::Arc;
14use std::time::Duration;
15use tracing::debug;
16
17/// Default TTL for cached entries (1 hour).
18const _DEFAULT_TTL_SECS: u64 = 3600;
19/// Default maximum number of entries in the memory cache.
20const _DEFAULT_MAX_ENTRIES: u64 = 1000;
21/// Maximum size of a single cached value (in bytes of JSON).
22const MAX_ENTRY_BYTES: usize = 10 * 1024 * 1024; // 10 MB
23
24/// A cached value with metadata.
25#[derive(Debug, Clone, Serialize, Deserialize)]
26pub struct CachedEntry {
27    /// The serialized JSON value.
28    pub value: serde_json::Value,
29    /// When this entry was created (Unix timestamp seconds).
30    pub created_at: u64,
31    /// Cache key for reference.
32    pub key: String,
33}
34
35/// In-memory LRU cache for fetch and search results.
36///
37/// Thread-safe and async-native via `moka`. Each entry has a TTL
38/// and the total number of entries is bounded.
39#[derive(Clone)]
40pub struct MemoryCache {
41    inner: Arc<Cache<String, CachedEntry>>,
42    enabled: bool,
43    ttl: Duration,
44}
45
46impl MemoryCache {
47    /// Create a new memory cache with the given configuration.
48    pub fn new(max_entries: u64, ttl_secs: u64, enabled: bool) -> Self {
49        let ttl = Duration::from_secs(ttl_secs);
50        let inner = Cache::builder()
51            .max_capacity(max_entries)
52            .time_to_live(ttl)
53            .time_to_idle(Duration::from_secs(ttl_secs / 2))
54            .build();
55
56        Self {
57            inner: Arc::new(inner),
58            enabled,
59            ttl,
60        }
61    }
62
63    /// Create a cache with default settings from config.
64    pub fn from_config(config: &crate::config::CacheConfig) -> Self {
65        Self::new(config.memory_max_entries, config.ttl_secs, config.enabled)
66    }
67
68    /// Get a cached value by key, if it exists and has not expired.
69    pub async fn get<T: for<'de> Deserialize<'de>>(&self, key: &str) -> Option<T> {
70        if !self.enabled {
71            return None;
72        }
73        let entry = self.inner.get(key).await?;
74        debug!("Cache HIT: {key}");
75        serde_json::from_value(entry.value).ok()
76    }
77
78    /// Store a value in the cache under the given key.
79    ///
80    /// If the serialized value exceeds MAX_ENTRY_BYTES, the entry is silently
81    /// skipped to prevent memory bloat from large pages.
82    pub async fn set<T: Serialize>(&self, key: &str, value: &T) {
83        if !self.enabled {
84            return;
85        }
86        // Single serialization pass: serialize to string for size check,
87        // then parse back to Value for storage. Avoids double-serialize.
88        let json_str = match serde_json::to_string(value) {
89            Ok(s) => s,
90            Err(e) => {
91                debug!("Cache: failed to serialize for key {key}: {e}");
92                return;
93            }
94        };
95
96        let size = json_str.len();
97        if size > MAX_ENTRY_BYTES {
98            debug!("Cache: skipping oversized entry for {key} ({size} bytes)");
99            return;
100        }
101
102        let json = match serde_json::from_str(&json_str) {
103            Ok(v) => v,
104            Err(e) => {
105                debug!("Cache: failed to re-parse for key {key}: {e}");
106                return;
107            }
108        };
109
110        let entry = CachedEntry {
111            value: json,
112            created_at: unix_now(),
113            key: key.to_string(),
114        };
115
116        self.inner.insert(key.to_string(), entry).await;
117        debug!("Cache SET: {key} ({size} bytes)");
118    }
119
120    /// Remove a specific entry from the cache.
121    pub async fn invalidate(&self, key: &str) {
122        self.inner.invalidate(key).await;
123        debug!("Cache INVALIDATE: {key}");
124    }
125
126    /// Clear all entries from the cache.
127    pub async fn clear(&self) {
128        self.inner.invalidate_all();
129        debug!("Cache CLEAR: all entries removed");
130    }
131
132    /// Return cache statistics.
133    pub fn stats(&self) -> CacheStats {
134        CacheStats {
135            entry_count: self.inner.entry_count(),
136            weighted_size: self.inner.weighted_size(),
137            ttl_secs: self.ttl.as_secs(),
138            enabled: self.enabled,
139        }
140    }
141
142    /// Whether the cache is enabled.
143    pub fn is_enabled(&self) -> bool {
144        self.enabled
145    }
146}
147
148impl std::fmt::Debug for MemoryCache {
149    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
150        f.debug_struct("MemoryCache")
151            .field("enabled", &self.enabled)
152            .field("entry_count", &self.inner.entry_count())
153            .finish()
154    }
155}
156
157/// Statistics about the current cache state.
158#[derive(Debug, Clone, Serialize, Deserialize)]
159pub struct CacheStats {
160    pub entry_count: u64,
161    pub weighted_size: u64,
162    pub ttl_secs: u64,
163    pub enabled: bool,
164}
165
166/// Hash a string component for cache keys using SHA-256 truncated to 16 hex chars.
167/// Prevents cache key injection/collision attacks from user-controlled inputs.
168fn hash_component(input: &str) -> String {
169    use sha2::{Digest, Sha256};
170    let hash = Sha256::digest(input.as_bytes());
171    format!("{:x}", hash)[..16].to_string()
172}
173
174/// Build a cache key for a fetch operation (collision-resistant).
175pub fn fetch_key(url: &str) -> String {
176    format!("fetch:{}", hash_component(url))
177}
178
179/// Build a cache key for a search operation (collision-resistant).
180pub fn search_key(query: &str, backend: &str, max_results: u32) -> String {
181    let input = format!("{query}:{backend}:{max_results}");
182    format!("search:{}", hash_component(&input))
183}
184
185/// Build a cache key for a QATBE operation (collision-resistant).
186pub fn qatbe_key(url: &str, query: &str, budget: u32) -> String {
187    let input = format!("{url}:{query}:{budget}");
188    format!("qatbe:{}", hash_component(&input))
189}
190
191/// Get current Unix timestamp in seconds.
192fn unix_now() -> u64 {
193    std::time::SystemTime::now()
194        .duration_since(std::time::UNIX_EPOCH)
195        .unwrap_or_default()
196        .as_secs()
197}
198
199#[cfg(test)]
200mod tests {
201    use super::*;
202
203    #[tokio::test]
204    async fn cache_set_and_get() {
205        let cache = MemoryCache::new(100, 3600, true);
206        let key = "test:key";
207        let value = serde_json::json!({"hello": "world", "count": 42});
208
209        cache.set(key, &value).await;
210        let retrieved: Option<serde_json::Value> = cache.get(key).await;
211        assert!(retrieved.is_some());
212        assert_eq!(retrieved.unwrap()["count"], 42);
213    }
214
215    #[tokio::test]
216    async fn disabled_cache_returns_none() {
217        let cache = MemoryCache::new(100, 3600, false);
218        cache.set("key", &"value").await;
219        let result: Option<String> = cache.get("key").await;
220        assert!(result.is_none());
221    }
222
223    #[tokio::test]
224    async fn cache_miss_returns_none() {
225        let cache = MemoryCache::new(100, 3600, true);
226        let result: Option<String> = cache.get("nonexistent:key").await;
227        assert!(result.is_none());
228    }
229
230    #[tokio::test]
231    async fn cache_invalidate() {
232        let cache = MemoryCache::new(100, 3600, true);
233        cache.set("mykey", &42u32).await;
234        cache.invalidate("mykey").await;
235        let result: Option<u32> = cache.get("mykey").await;
236        assert!(result.is_none());
237    }
238
239    #[tokio::test]
240    async fn cache_stats() {
241        let cache = MemoryCache::new(100, 3600, true);
242        cache.set("k1", &"v1").await;
243        cache.set("k2", &"v2").await;
244        let stats = cache.stats();
245        assert!(stats.enabled);
246        assert_eq!(stats.ttl_secs, 3600);
247    }
248
249    #[test]
250    fn cache_key_builders() {
251        // Keys are now hashed for collision resistance
252        let fk = fetch_key("https://example.com");
253        assert!(fk.starts_with("fetch:"));
254        assert_eq!(fk.len(), "fetch:".len() + 16); // 16 hex chars
255
256        let sk = search_key("rust", "ddg", 10);
257        assert!(sk.starts_with("search:"));
258
259        let qk = qatbe_key("https://example.com", "rust", 4000);
260        assert!(qk.starts_with("qatbe:"));
261
262        // Same input → same key (deterministic)
263        assert_eq!(fetch_key("https://example.com"), fk);
264
265        // Different input → different key
266        assert_ne!(fetch_key("https://other.com"), fk);
267    }
268}