g3_cache/server.rs
1//! In-process server caches: answers kept in the server's memory and shared
2//! by every request. See the [crate docs](crate#server-cache) for when to
3//! use one.
4//!
5//! Two ways in:
6//!
7//! - [`cache_shared`](crate::cache_shared)`(server = "5m")` on a server
8//! function whose answer is the same for every visitor caches the whole
9//! function. The attribute checks the function looks visitor-independent.
10//! - A [`ServerCache`] static caches anything else: part of a function (an
11//! outside API call behind a database check), or a per-user answer with
12//! the user's id in the key.
13//!
14//! # What these caches cannot do
15//!
16//! - **Know about writes.** An entry lives until it expires. A per-user
17//! answer cached here comes back unchanged right after that user's own
18//! edit, even though the client invalidated and refetched. Cache only
19//! what may be stale for its whole TTL, or
20//! [`invalidate`](moka::future::Cache::invalidate) the entry in every
21//! mutation that changes it.
22//! - **Span servers.** Each process has its own copy. With several
23//! replicas, an eviction reaches only the one that handled the write.
24
25pub use moka;
26
27use std::{future::Future, hash::Hash, ops::Deref, sync::OnceLock, time::Duration};
28
29/// An in-process cache of up to `capacity` entries, each kept for `ttl`
30/// after it was fetched. Declare one as a `static`, where it is needed;
31/// it is built on first use:
32///
33/// ```
34/// use g3_cache::ServerCache;
35/// use std::time::Duration;
36///
37/// static DESCRIPTIONS: ServerCache<String, Option<String>> =
38/// ServerCache::new(Duration::from_secs(60 * 60), 10_000);
39///
40/// # async fn google_description(_id: &str) -> Result<Option<String>, String> { Ok(None) }
41/// async fn description(media_id: String) -> Result<Option<String>, String> {
42/// DESCRIPTIONS
43/// .get_or_fetch(media_id.clone(), google_description(&media_id))
44/// .await
45/// }
46/// ```
47///
48/// Each cache is its own `static` rather than one shared instance: every
49/// cache holds its own key and value types, and keeping unrelated answers
50/// apart means one can't evict another.
51///
52/// `K` must include everything the answer depends on. For an answer that
53/// depends on the signed-in user, that means the user's id: it arrives
54/// through a session extractor, not the function's arguments, so a key
55/// built from the arguments alone would give one user's answer to all.
56///
57/// The least useful entries are dropped first when full. For anything
58/// [`get_or_fetch`](Self::get_or_fetch) and
59/// [`get_or_insert`](Self::get_or_insert) don't cover, it dereferences to
60/// the underlying [moka cache](moka::future::Cache).
61pub struct ServerCache<K, V> {
62 ttl: Duration,
63 capacity: u64,
64 cache: OnceLock<moka::future::Cache<K, V>>,
65}
66
67impl<K, V> ServerCache<K, V>
68where
69 K: Hash + Eq + Send + Sync + 'static,
70 V: Clone + Send + Sync + 'static,
71{
72 /// A cache keeping up to `capacity` entries for `ttl` each. `const`, so
73 /// it can initialize a `static` directly.
74 pub const fn new(ttl: Duration, capacity: u64) -> Self {
75 Self {
76 ttl,
77 capacity,
78 cache: OnceLock::new(),
79 }
80 }
81
82 /// The cached answer for `key`, or `fetch`'s. Concurrent misses on one
83 /// key share a single `fetch`; an `Err` is returned to every waiter and
84 /// not kept, so the next call retries.
85 ///
86 /// `E` must be `Clone`, as `dioxus::CapturedError` is, since every
87 /// waiter gets a copy. For an error type that isn't (`anyhow::Error`),
88 /// use [`try_get_with`](moka::future::Cache::try_get_with) through
89 /// `Deref`, which returns it in an `Arc`.
90 pub async fn get_or_fetch<E, Fut>(&self, key: K, fetch: Fut) -> Result<V, E>
91 where
92 Fut: Future<Output = Result<V, E>>,
93 E: Clone + Send + Sync + 'static,
94 {
95 self.try_get_with(key, fetch)
96 .await
97 .map_err(|err| E::clone(&err))
98 }
99
100 /// The cached answer for `key`, or `fetch`'s, for a fetch that can't
101 /// fail. Concurrent misses on one key share a single `fetch`.
102 pub async fn get_or_insert<Fut>(&self, key: K, fetch: Fut) -> V
103 where
104 Fut: Future<Output = V>,
105 {
106 self.get_with(key, fetch).await
107 }
108}
109
110impl<K, V> Deref for ServerCache<K, V>
111where
112 K: Hash + Eq + Send + Sync + 'static,
113 V: Clone + Send + Sync + 'static,
114{
115 type Target = moka::future::Cache<K, V>;
116
117 fn deref(&self) -> &Self::Target {
118 self.cache.get_or_init(|| {
119 moka::future::Cache::builder()
120 .max_capacity(self.capacity)
121 .time_to_live(self.ttl)
122 .build()
123 })
124 }
125}
126
127/// Support for the code [`cache_shared`](crate::cache_shared) generates.
128/// Not public API.
129#[doc(hidden)]
130pub mod __private {
131 use serde::Serialize;
132
133 /// The whole-function cache behind `#[cache_shared(server = ..)]`.
134 pub type SharedCache<T> = super::ServerCache<String, T>;
135
136 /// The arguments of one call, as the key of its cached answer.
137 pub fn args_key<A: Serialize>(args: &A) -> String {
138 serde_json::to_string(args).unwrap_or_default()
139 }
140}
141
142#[cfg(test)]
143mod tests {
144 use super::ServerCache;
145 use std::{
146 sync::atomic::{AtomicU32, Ordering},
147 time::Duration,
148 };
149
150 #[tokio::test]
151 async fn answers_are_shared_and_errors_are_not_kept() {
152 static CACHE: ServerCache<u32, u32> = ServerCache::new(Duration::from_secs(60), 100);
153 static CALLS: AtomicU32 = AtomicU32::new(0);
154
155 let fetch = || async {
156 CALLS.fetch_add(1, Ordering::SeqCst);
157 Ok::<_, String>(7)
158 };
159 assert_eq!(CACHE.get_or_fetch(1, fetch()).await, Ok(7));
160 assert_eq!(CACHE.get_or_fetch(1, fetch()).await, Ok(7));
161 assert_eq!(CALLS.load(Ordering::SeqCst), 1);
162
163 let failing = async { Err::<u32, _>("down".to_string()) };
164 assert_eq!(
165 CACHE.get_or_fetch(2, failing).await,
166 Err("down".to_string())
167 );
168 assert_eq!(CACHE.get_or_fetch(2, fetch()).await, Ok(7));
169 }
170
171 #[tokio::test]
172 async fn infallible_fetches_and_moka_calls_share_the_cache() {
173 static CACHE: ServerCache<&str, u32> = ServerCache::new(Duration::from_secs(60), 100);
174 assert_eq!(CACHE.get_or_insert("a", async { 1 }).await, 1);
175 assert_eq!(CACHE.get("a").await, Some(1));
176 CACHE.invalidate("a").await;
177 assert_eq!(CACHE.get_or_insert("a", async { 2 }).await, 2);
178 }
179}