Skip to main content

next_rust_cache/
lib.rs

1//! Cache abstraction used for incremental static regeneration (ISR), the
2//! data cache and optimized assets.
3//!
4//! * [`CacheStore`] – the storage trait. Implement it to plug in Redis,
5//!   Memcached, a CDN KV store, ... The framework never requires Redis.
6//! * [`MemoryStore`] – bounded in-memory LRU store (default).
7//! * [`FileStore`] – persistent store on local disk.
8//! * [`Cache`] – typed convenience API over any store.
9
10#![forbid(unsafe_code)]
11
12use std::collections::BTreeMap;
13use std::fmt;
14use std::future::Future;
15use std::pin::Pin;
16use std::sync::{Arc, OnceLock};
17use std::time::{Duration, SystemTime};
18
19use serde::de::DeserializeOwned;
20use serde::{Deserialize, Serialize};
21
22mod file;
23mod memory;
24
25pub use file::FileStore;
26pub use memory::MemoryStore;
27
28pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
29
30/// Cache key. Namespaces used by the framework: `page:<path>`, `data:<key>`,
31/// `image:<hash>`.
32#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
33pub struct CacheKey(pub String);
34
35impl CacheKey {
36    pub fn new(key: impl Into<String>) -> Self {
37        CacheKey(key.into())
38    }
39
40    pub fn page(path: &str) -> Self {
41        CacheKey(format!("page:{path}"))
42    }
43
44    pub fn data(key: &str) -> Self {
45        CacheKey(format!("data:{key}"))
46    }
47
48    pub fn as_str(&self) -> &str {
49        &self.0
50    }
51}
52
53impl fmt::Display for CacheKey {
54    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
55        f.write_str(&self.0)
56    }
57}
58
59impl From<&str> for CacheKey {
60    fn from(s: &str) -> Self {
61        CacheKey(s.to_owned())
62    }
63}
64
65/// A cached value with freshness information.
66#[derive(Debug, Clone, PartialEq, Eq)]
67pub struct CacheEntry {
68    pub value: Arc<[u8]>,
69    pub created: SystemTime,
70    /// Entry becomes *stale* (not invalid) after this long. `None` = never.
71    pub revalidate: Option<Duration>,
72    pub tags: Vec<String>,
73    /// Free-form metadata (e.g. response headers, status).
74    pub meta: BTreeMap<String, String>,
75}
76
77impl CacheEntry {
78    pub fn new(value: impl Into<Arc<[u8]>>) -> Self {
79        CacheEntry {
80            value: value.into(),
81            created: SystemTime::now(),
82            revalidate: None,
83            tags: Vec::new(),
84            meta: BTreeMap::new(),
85        }
86    }
87
88    pub fn revalidate(mut self, after: Option<Duration>) -> Self {
89        self.revalidate = after;
90        self
91    }
92
93    pub fn tags<I: IntoIterator<Item = S>, S: Into<String>>(mut self, tags: I) -> Self {
94        self.tags = tags.into_iter().map(Into::into).collect();
95        self
96    }
97
98    pub fn meta(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
99        self.meta.insert(k.into(), v.into());
100        self
101    }
102
103    pub fn age(&self) -> Duration {
104        SystemTime::now().duration_since(self.created).unwrap_or_default()
105    }
106
107    pub fn is_stale(&self) -> bool {
108        self.revalidate.is_some_and(|r| self.age() >= r)
109    }
110}
111
112#[derive(Debug)]
113pub enum CacheError {
114    Io(std::io::Error),
115    Serde(String),
116    Backend(String),
117}
118
119impl fmt::Display for CacheError {
120    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
121        match self {
122            CacheError::Io(e) => write!(f, "cache i/o error: {e}"),
123            CacheError::Serde(e) => write!(f, "cache serialization error: {e}"),
124            CacheError::Backend(e) => write!(f, "cache backend error: {e}"),
125        }
126    }
127}
128
129impl std::error::Error for CacheError {}
130
131impl From<std::io::Error> for CacheError {
132    fn from(e: std::io::Error) -> Self {
133        CacheError::Io(e)
134    }
135}
136
137/// Storage backend.
138///
139/// Implementations must be safe to share between threads. Stale entries are
140/// returned by `get` (stale-while-revalidate is decided by the caller).
141pub trait CacheStore: Send + Sync + 'static {
142    fn get<'a>(&'a self, key: &'a CacheKey) -> BoxFuture<'a, Result<Option<CacheEntry>, CacheError>>;
143    fn set(&self, key: CacheKey, entry: CacheEntry) -> BoxFuture<'_, Result<(), CacheError>>;
144    fn delete<'a>(&'a self, key: &'a CacheKey) -> BoxFuture<'a, Result<bool, CacheError>>;
145    /// Delete every entry carrying `tag`; returns the number removed.
146    fn delete_tag<'a>(&'a self, tag: &'a str) -> BoxFuture<'a, Result<usize, CacheError>>;
147    fn clear(&self) -> BoxFuture<'_, Result<(), CacheError>>;
148}
149
150/// Options for [`Cache::get_or_insert_json`].
151#[derive(Debug, Clone, Default)]
152pub struct CacheOptions {
153    pub revalidate: Option<Duration>,
154    pub tags: Vec<String>,
155}
156
157impl CacheOptions {
158    pub fn revalidate(secs: u64) -> Self {
159        CacheOptions { revalidate: Some(Duration::from_secs(secs)), tags: Vec::new() }
160    }
161
162    pub fn tag(mut self, tag: impl Into<String>) -> Self {
163        self.tags.push(tag.into());
164        self
165    }
166}
167
168/// Typed cache API over a shared store.
169#[derive(Clone)]
170pub struct Cache {
171    store: Arc<dyn CacheStore>,
172}
173
174impl fmt::Debug for Cache {
175    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
176        f.write_str("Cache")
177    }
178}
179
180impl Default for Cache {
181    fn default() -> Self {
182        Cache::new(MemoryStore::new(10_000))
183    }
184}
185
186impl Cache {
187    pub fn new(store: impl CacheStore) -> Self {
188        Cache { store: Arc::new(store) }
189    }
190
191    pub fn from_arc(store: Arc<dyn CacheStore>) -> Self {
192        Cache { store }
193    }
194
195    pub fn store(&self) -> &Arc<dyn CacheStore> {
196        &self.store
197    }
198
199    /// Memoize a serializable value. Stale values are recomputed inline;
200    /// errors from `f` are returned and nothing is cached.
201    pub async fn get_or_insert_json<T, E, F, Fut>(&self, key: &str, opts: CacheOptions, f: F) -> Result<T, E>
202    where
203        T: Serialize + DeserializeOwned,
204        F: FnOnce() -> Fut,
205        Fut: Future<Output = Result<T, E>>,
206    {
207        let key = CacheKey::data(key);
208        if let Ok(Some(entry)) = self.store.get(&key).await
209            && !entry.is_stale()
210            && let Ok(v) = serde_json::from_slice(&entry.value)
211        {
212            return Ok(v);
213        }
214        let value = f().await?;
215        if let Ok(bytes) = serde_json::to_vec(&value) {
216            let entry = CacheEntry::new(bytes).revalidate(opts.revalidate).tags(opts.tags);
217            let _ = self.store.set(key, entry).await;
218        }
219        Ok(value)
220    }
221
222    /// Invalidate a cached page (ISR) so the next request re-renders it.
223    pub async fn revalidate_path(&self, path: &str) -> Result<bool, CacheError> {
224        let path = if path.len() > 1 { path.trim_end_matches('/') } else { path };
225        self.store.delete(&CacheKey::page(path)).await
226    }
227
228    /// Invalidate every page and data entry tagged with `tag`.
229    pub async fn revalidate_tag(&self, tag: &str) -> Result<usize, CacheError> {
230        self.store.delete_tag(tag).await
231    }
232
233    pub async fn invalidate(&self, key: &str) -> Result<bool, CacheError> {
234        self.store.delete(&CacheKey::data(key)).await
235    }
236}
237
238static GLOBAL: OnceLock<Cache> = OnceLock::new();
239
240/// Install the process-wide cache (done by the server at startup).
241/// Returns `false` if one was already installed.
242pub fn install_global(cache: Cache) -> bool {
243    GLOBAL.set(cache).is_ok()
244}
245
246/// The process-wide cache (an in-memory default if none was installed).
247pub fn global() -> &'static Cache {
248    GLOBAL.get_or_init(Cache::default)
249}
250
251/// Memoize `f` in the global data cache.
252pub async fn cache<T, E, F, Fut>(key: &str, opts: CacheOptions, f: F) -> Result<T, E>
253where
254    T: Serialize + DeserializeOwned,
255    F: FnOnce() -> Fut,
256    Fut: Future<Output = Result<T, E>>,
257{
258    global().get_or_insert_json(key, opts, f).await
259}
260
261/// Re-render `path` on its next request.
262pub async fn revalidate_path(path: &str) {
263    let _ = global().revalidate_path(path).await;
264}
265
266/// Invalidate all entries tagged `tag`.
267pub async fn revalidate_tag(tag: &str) {
268    let _ = global().revalidate_tag(tag).await;
269}
270
271/// Remove a data-cache entry.
272pub async fn invalidate(key: &str) {
273    let _ = global().invalidate(key).await;
274}
275
276#[cfg(test)]
277mod tests {
278    use super::*;
279
280    async fn exercise(store: impl CacheStore) {
281        let cache = Cache::new(store);
282        let mut calls = 0;
283        for _ in 0..3 {
284            let v: Result<u32, ()> = cache
285                .get_or_insert_json("answer", CacheOptions::revalidate(60).tag("math"), || {
286                    calls += 1;
287                    async { Ok(42) }
288                })
289                .await;
290            assert_eq!(v, Ok(42));
291        }
292        assert_eq!(calls, 1);
293        assert_eq!(cache.revalidate_tag("math").await.unwrap(), 1);
294        let v: Result<u32, ()> = cache.get_or_insert_json("answer", CacheOptions::default(), || async { Ok(7) }).await;
295        assert_eq!(v, Ok(7));
296
297        let store = cache.store();
298        let entry = CacheEntry::new(b"<html>".to_vec()).tags(["posts"]).meta("status", "200");
299        store.set(CacheKey::page("/blog"), entry.clone()).await.unwrap();
300        let got = store.get(&CacheKey::page("/blog")).await.unwrap().unwrap();
301        assert_eq!(&*got.value, b"<html>");
302        assert_eq!(got.meta["status"], "200");
303        assert!(cache.revalidate_path("/blog/").await.unwrap());
304        assert!(store.get(&CacheKey::page("/blog")).await.unwrap().is_none());
305
306        let stale =
307            CacheEntry { created: SystemTime::now() - Duration::from_secs(120), ..CacheEntry::new(b"x".to_vec()) }
308                .revalidate(Some(Duration::from_secs(60)));
309        assert!(stale.is_stale());
310        store.set(CacheKey::new("s"), stale).await.unwrap();
311        assert!(store.get(&CacheKey::new("s")).await.unwrap().unwrap().is_stale());
312        store.clear().await.unwrap();
313        assert!(store.get(&CacheKey::new("s")).await.unwrap().is_none());
314    }
315
316    #[tokio::test]
317    async fn memory_store() {
318        exercise(MemoryStore::new(100)).await;
319    }
320
321    #[tokio::test]
322    async fn file_store() {
323        let dir = std::env::temp_dir().join(format!("nr-cache-{}", std::process::id()));
324        exercise(FileStore::new(&dir)).await;
325        let _ = std::fs::remove_dir_all(dir);
326    }
327
328    #[tokio::test]
329    async fn memory_store_evicts_least_recently_used() {
330        let store = MemoryStore::new(2);
331        store.set("a".into(), CacheEntry::new(b"1".to_vec())).await.unwrap();
332        store.set("b".into(), CacheEntry::new(b"2".to_vec())).await.unwrap();
333        store.get(&"a".into()).await.unwrap();
334        store.set("c".into(), CacheEntry::new(b"3".to_vec())).await.unwrap();
335        assert!(store.get(&"a".into()).await.unwrap().is_some());
336        assert!(store.get(&"b".into()).await.unwrap().is_none());
337    }
338}