Skip to main content

g3_cache/client/
mod.rs

1//! The client cache: see the [crate docs](crate#client-cache) for when to
2//! use it, and [`use_cached`] for how a read is answered.
3
4mod hook;
5mod store;
6
7pub use hook::*;
8
9use crate::{CacheKey, CacheableFn};
10use dioxus::prelude::{GlobalSignal, Signal, document, spawn, use_hook};
11use serde::Serialize;
12use std::{
13    any::Any,
14    borrow::Cow,
15    cell::{Cell, RefCell},
16    collections::BTreeMap,
17    rc::Rc,
18    sync::OnceLock,
19    time::Duration,
20};
21
22/// The server renders for every visitor from one process, so nothing is
23/// cached there: every read fetches, and invalidation does nothing.
24pub(crate) const ENABLED: bool = !cfg!(feature = "server");
25
26/// The `fetched_at` of an entry that must be refetched: invalidated, or
27/// restored from the persistent store.
28pub(crate) const STALE: i64 = i64::MIN;
29
30/// Stored under this key: whose data the persistent store holds.
31const OWNER_KEY: &str = "\u{1f}owner";
32
33/// Settings for the client cache, given once to [`use_client_cache`].
34///
35/// ```
36/// use g3_cache::CacheConfig;
37/// use std::time::Duration;
38///
39/// let config = CacheConfig::new("media-mancer").keep_for(Duration::from_secs(3 * 24 * 60 * 60));
40/// ```
41#[derive(Clone, Debug)]
42pub struct CacheConfig {
43    pub(crate) name: Cow<'static, str>,
44    pub(crate) share_for: Duration,
45    pub(crate) keep_for: Duration,
46    pub(crate) revalidate_on_focus: bool,
47    pub(crate) focus_gap: Duration,
48}
49
50impl CacheConfig {
51    /// Settings with the defaults below. `name` names the persistent store
52    /// (the IndexedDB database, or the redb file on mobile), so it must be
53    /// unique to the app on a device or origin.
54    pub fn new(name: impl Into<Cow<'static, str>>) -> Self {
55        Self {
56            name: name.into(),
57            share_for: Duration::from_secs(2),
58            keep_for: Duration::from_secs(7 * 24 * 60 * 60),
59            revalidate_on_focus: true,
60            focus_gap: Duration::from_secs(30),
61        }
62    }
63
64    /// The persistent store's name.
65    pub fn name(&self) -> &str {
66        &self.name
67    }
68
69    /// How recent a fetch a screen may reuse instead of repeating it when it
70    /// opens. Default 2 s. This only merges the reads of components that
71    /// mount together (a screen and its children reading the same thing);
72    /// keep it short, since a change made without [`invalidate_cached`] shows only
73    /// once something refetches.
74    pub fn share_for(mut self, duration: Duration) -> Self {
75        self.share_for = duration;
76        self
77    }
78
79    /// How old a stored value may be and still be shown on a cold start
80    /// while its refetch runs. Default 7 days: an older list is more
81    /// misleading than a loading state.
82    pub fn keep_for(mut self, duration: Duration) -> Self {
83        self.keep_for = duration;
84        self
85    }
86
87    /// Whether returning to the app (the tab or window regaining focus, the
88    /// app coming back to the foreground, the network coming back) refetches
89    /// every mounted read. Default on. This is what shows changes made on
90    /// another device on a screen that stayed open; see the
91    /// [crate docs](crate#several-devices).
92    pub fn revalidate_on_focus(mut self, on: bool) -> Self {
93        self.revalidate_on_focus = on;
94        self
95    }
96
97    /// The least time between two refetches caused by focus. Default 30 s,
98    /// so switching windows back and forth doesn't refetch every time.
99    pub fn focus_gap(mut self, duration: Duration) -> Self {
100        self.focus_gap = duration;
101        self
102    }
103}
104
105static CONFIG: OnceLock<CacheConfig> = OnceLock::new();
106
107pub(crate) fn config() -> &'static CacheConfig {
108    CONFIG.get_or_init(|| CacheConfig::new("g3-cache"))
109}
110
111/// Sets up the client cache. Call once, at the top of the app's root
112/// component, before any cached read.
113///
114/// ```ignore
115/// fn App() -> Element {
116///     g3_cache::use_client_cache(g3_cache::CacheConfig::new("media-mancer"));
117///     // ...
118/// }
119/// ```
120///
121/// Without it, reads are still cached with default settings, but a store
122/// named `g3-cache` is shared with any other g3 app on the same origin, and
123/// nothing refetches on focus.
124///
125/// Persisting reads to disk also needs [`set_cache_owner`]: until the app has
126/// said whose data this is, the cache keeps everything in memory only.
127pub fn use_client_cache(config: CacheConfig) {
128    use_hook(move || {
129        // The server renders the root component once per request, and has
130        // no client cache to configure.
131        if !ENABLED {
132            return;
133        }
134        if CONFIG.set(config).is_err() {
135            tracing::warn!(
136                "g3-cache: `use_client_cache` ran more than once, or after the first cached \
137                 read; the later settings are ignored. Call it once, first thing in the root \
138                 component."
139            );
140        }
141        if self::config().revalidate_on_focus {
142            spawn(revalidate_on_focus());
143        }
144    });
145}
146
147/// Refetches every mounted read whenever the app comes back into view.
148/// Page visibility and focus events reach the webview on mobile as well as
149/// the browser, so one listener covers every client.
150async fn revalidate_on_focus() {
151    const SCRIPT: &str = r#"
152        const send = () => dioxus.send(null);
153        document.addEventListener("visibilitychange", () => {
154            if (document.visibilityState === "visible") send();
155        });
156        window.addEventListener("focus", send);
157        window.addEventListener("online", send);
158        await new Promise(() => {});
159    "#;
160    let mut events = document::eval(SCRIPT);
161    let mut last = now_ms();
162    while events.recv::<()>().await.is_ok() {
163        let gap = i64::try_from(config().focus_gap.as_millis()).unwrap_or(i64::MAX);
164        if now_ms().saturating_sub(last) >= gap {
165            last = now_ms();
166            invalidate_all_cached();
167        }
168    }
169}
170
171struct MemoryEntry {
172    value: Rc<dyn Any>,
173    fetched_at: i64,
174}
175
176thread_local! {
177    static MEMORY: RefCell<BTreeMap<CacheKey, MemoryEntry>> = const { RefCell::new(BTreeMap::new()) };
178    /// Whether this run has called `set_cache_owner`, which allows writing to the
179    /// persistent store.
180    static OWNER_SET: Cell<bool> = const { Cell::new(false) };
181    /// Whether the persistent store holds a signed-in owner's data, which
182    /// allows reading it. Checked once, on the first restore.
183    static STORE_OWNED: Cell<Option<bool>> = const { Cell::new(None) };
184}
185
186/// Bumped by every invalidation and by [`set_cache_owner`]; every cached read
187/// subscribes to it, so each rechecks its entry (cheaply, unless the entry
188/// was invalidated).
189pub(crate) static EPOCH: GlobalSignal<u64> = Signal::global(|| 0);
190
191pub(crate) fn now_ms() -> i64 {
192    chrono::Utc::now().timestamp_millis()
193}
194
195pub(crate) fn remembered<T: Clone + 'static>(key: &CacheKey) -> Option<(T, i64)> {
196    if !ENABLED {
197        return None;
198    }
199    MEMORY.with_borrow(|memory| {
200        let entry = memory.get(key)?;
201        let value = entry.value.downcast_ref::<T>()?.clone();
202        Some((value, entry.fetched_at))
203    })
204}
205
206pub(crate) fn remember<T: 'static>(key: &CacheKey, value: T, fetched_at: i64) {
207    if ENABLED {
208        let entry = MemoryEntry {
209            value: Rc::new(value),
210            fetched_at,
211        };
212        MEMORY.with_borrow_mut(|memory| memory.insert(key.clone(), entry));
213    }
214}
215
216#[derive(serde::Serialize, serde::Deserialize)]
217struct Stored<T> {
218    saved_at: i64,
219    value: T,
220}
221
222pub(crate) async fn restore<T: serde::de::DeserializeOwned>(key: &CacheKey) -> Option<T> {
223    if !ENABLED || !store_owned().await {
224        return None;
225    }
226    let stored: Stored<T> = serde_json::from_str(&store::load(&key.storage_key()).await?).ok()?;
227    let keep_for = i64::try_from(config().keep_for.as_millis()).unwrap_or(i64::MAX);
228    (now_ms().saturating_sub(stored.saved_at) < keep_for).then_some(stored.value)
229}
230
231pub(crate) async fn persist<T: Serialize>(key: &CacheKey, value: &T) {
232    if !ENABLED || !OWNER_SET.get() {
233        return;
234    }
235    let stored = Stored {
236        saved_at: now_ms(),
237        value,
238    };
239    if let Ok(json) = serde_json::to_string(&stored) {
240        store::save(&key.storage_key(), &json).await;
241    }
242}
243
244async fn store_owned() -> bool {
245    if let Some(owned) = STORE_OWNED.get() {
246        return owned;
247    }
248    let owned = store::load(OWNER_KEY)
249        .await
250        .is_some_and(|owner| !owner.is_empty());
251    STORE_OWNED.set(Some(owned));
252    owned
253}
254
255/// Tells the cache whose data it holds: the signed-in user's id, or `None`
256/// when signed out. Call it whenever the signed-in user is known or changes,
257/// including on sign-out.
258///
259/// When the owner differs from the one the persistent store was written
260/// for, or is `None`, the whole cache (memory and store) is emptied, so one
261/// person never sees another's lists on a shared device.
262///
263/// Until this is first called, the cache **keeps everything in memory
264/// only**. An app that never calls it is still safe, just without instant
265/// cold starts. A store written in an earlier run is still read on a cold
266/// start before this is called: it only ever holds the data of whoever was
267/// signed in last, and this empties it if that is no longer the case.
268pub async fn set_cache_owner(owner: Option<String>) {
269    if !ENABLED {
270        return;
271    }
272    OWNER_SET.set(true);
273    let owner = owner.unwrap_or_default();
274    if !owner.is_empty() && store::load(OWNER_KEY).await.as_deref() == Some(owner.as_str()) {
275        STORE_OWNED.set(Some(true));
276        return;
277    }
278    MEMORY.with_borrow_mut(BTreeMap::clear);
279    store::clear().await;
280    store::save(OWNER_KEY, &owner).await;
281    STORE_OWNED.set(Some(!owner.is_empty()));
282    *EPOCH.write() += 1;
283}
284
285fn mark_stale(matches: impl Fn(&CacheKey) -> bool) {
286    if !ENABLED {
287        return;
288    }
289    MEMORY.with_borrow_mut(|memory| {
290        for (key, entry) in memory.iter_mut() {
291            if matches(key) {
292                entry.fetched_at = STALE;
293            }
294        }
295    });
296    *EPOCH.write() += 1;
297}
298
299/// Refetches every cached call of `server_fn`, whatever its arguments.
300///
301/// Call it on the client after a mutation succeeds, once for each read the
302/// mutation changes. Mounted screens refetch and keep showing their old
303/// value until the new one arrives; unmounted ones refetch when they next
304/// open.
305///
306/// ```ignore
307/// save_rating(media_id.clone(), score).await?;
308/// g3_cache::invalidate_cached(get_my_rating);
309/// g3_cache::invalidate_cached(get_my_ratings);
310/// g3_cache::invalidate_cached(get_profile_stats);
311/// ```
312///
313/// Only the mutation knows which reads it affects, so this cannot be
314/// automatic. Forgetting a read leaves it stale until the next screen open
315/// or focus. When unsure, [`invalidate_all_cached`] is always correct, only
316/// slower.
317///
318/// This does not reach the server's caches or Cloudflare. Reads cached
319/// there (see [`cache_shared`](crate::cache_shared)) are refetched through them, and
320/// may come back just as old.
321pub fn invalidate_cached<F, Args>(server_fn: F)
322where
323    F: CacheableFn<Args>,
324{
325    let _ = server_fn;
326    let name = crate::key::fn_name::<F>();
327    mark_stale(|key| key.name() == name);
328}
329
330/// Refetches one cached call: `server_fn` with exactly these `args`.
331///
332/// ```ignore
333/// g3_cache::invalidate_cached_call(get_list_items, (list_id.clone(),));
334/// ```
335pub fn invalidate_cached_call<F, Args>(server_fn: F, args: Args)
336where
337    F: CacheableFn<Args>,
338    Args: Serialize,
339{
340    let target = CacheKey::of(&server_fn, &args);
341    mark_stale(|key| *key == target);
342}
343
344/// Refetches the read cached under exactly `key`.
345pub fn invalidate_cached_key(key: &CacheKey) {
346    mark_stale(|candidate| candidate == key);
347}
348
349/// Refetches every read cached under a [`CacheKey`] named `name`, whatever
350/// its arguments.
351pub fn invalidate_cached_name(name: &str) {
352    mark_stale(|key| key.name() == name);
353}
354
355/// Refetches every cached read. Always correct after a mutation, but every
356/// mounted screen refetches everything it shows; prefer [`invalidate_cached`] for
357/// the reads the mutation changes.
358pub fn invalidate_all_cached() {
359    mark_stale(|_| true);
360}