1#![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#[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#[derive(Debug, Clone, PartialEq, Eq)]
67pub struct CacheEntry {
68 pub value: Arc<[u8]>,
69 pub created: SystemTime,
70 pub revalidate: Option<Duration>,
72 pub tags: Vec<String>,
73 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
137pub 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 fn delete_tag<'a>(&'a self, tag: &'a str) -> BoxFuture<'a, Result<usize, CacheError>>;
147 fn clear(&self) -> BoxFuture<'_, Result<(), CacheError>>;
148}
149
150#[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#[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 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 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 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
240pub fn install_global(cache: Cache) -> bool {
243 GLOBAL.set(cache).is_ok()
244}
245
246pub fn global() -> &'static Cache {
248 GLOBAL.get_or_init(Cache::default)
249}
250
251pub 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
261pub async fn revalidate_path(path: &str) {
263 let _ = global().revalidate_path(path).await;
264}
265
266pub async fn revalidate_tag(tag: &str) {
268 let _ = global().revalidate_tag(tag).await;
269}
270
271pub 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}