Skip to main content

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}