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/// Pass `None` only once you know nobody is signed in, never while still
264/// finding out: it empties the cache, so an app that says "nobody" before
265/// its session check answers starts every launch cold. Resolve the user on
266/// the server (`use_server_future`), or wait for the check.
267///
268/// Until this is first called, the cache **keeps everything in memory
269/// only**. An app that never calls it is still safe, just without instant
270/// cold starts. A store written in an earlier run is still read on a cold
271/// start before this is called: it only ever holds the data of whoever was
272/// signed in last, and this empties it if that is no longer the case.
273pub async fn set_cache_owner(owner: Option<String>) {
274    if !ENABLED {
275        return;
276    }
277    OWNER_SET.set(true);
278    let owner = owner.unwrap_or_default();
279    if !owner.is_empty() && store::load(OWNER_KEY).await.as_deref() == Some(owner.as_str()) {
280        STORE_OWNED.set(Some(true));
281        return;
282    }
283    MEMORY.with_borrow_mut(BTreeMap::clear);
284    store::clear().await;
285    store::save(OWNER_KEY, &owner).await;
286    STORE_OWNED.set(Some(!owner.is_empty()));
287    *EPOCH.write() += 1;
288}
289
290fn mark_stale(matches: impl Fn(&CacheKey) -> bool) {
291    if !ENABLED {
292        return;
293    }
294    MEMORY.with_borrow_mut(|memory| {
295        for (key, entry) in memory.iter_mut() {
296            if matches(key) {
297                entry.fetched_at = STALE;
298            }
299        }
300    });
301    *EPOCH.write() += 1;
302}
303
304/// Refetches every cached call of `server_fn`, whatever its arguments.
305///
306/// Call it on the client after a mutation succeeds, once for each read the
307/// mutation changes. Mounted screens refetch and keep showing their old
308/// value until the new one arrives; unmounted ones refetch when they next
309/// open.
310///
311/// ```ignore
312/// save_rating(media_id.clone(), score).await?;
313/// g3_cache::invalidate_cached(get_my_rating);
314/// g3_cache::invalidate_cached(get_my_ratings);
315/// g3_cache::invalidate_cached(get_profile_stats);
316/// ```
317///
318/// Only the mutation knows which reads it affects, so this cannot be
319/// automatic. Forgetting a read leaves it stale until the next screen open
320/// or focus. When unsure, [`invalidate_all_cached`] is always correct, only
321/// slower.
322///
323/// This does not reach the server's caches or Cloudflare. Reads cached
324/// there (see [`cache_shared`](crate::cache_shared)) are refetched through them, and
325/// may come back just as old.
326pub fn invalidate_cached<F, Args>(server_fn: F)
327where
328    F: CacheableFn<Args>,
329{
330    let _ = server_fn;
331    let name = crate::key::fn_name::<F>();
332    mark_stale(|key| key.name() == name);
333}
334
335/// Refetches one cached call: `server_fn` with exactly these `args`.
336///
337/// ```ignore
338/// g3_cache::invalidate_cached_call(get_list_items, (list_id.clone(),));
339/// ```
340pub fn invalidate_cached_call<F, Args>(server_fn: F, args: Args)
341where
342    F: CacheableFn<Args>,
343    Args: Serialize,
344{
345    let target = CacheKey::of(&server_fn, &args);
346    mark_stale(|key| *key == target);
347}
348
349/// Refetches the read cached under exactly `key`.
350pub fn invalidate_cached_key(key: &CacheKey) {
351    mark_stale(|candidate| candidate == key);
352}
353
354/// Refetches every read cached under a [`CacheKey`] named `name`, whatever
355/// its arguments.
356pub fn invalidate_cached_name(name: &str) {
357    mark_stale(|key| key.name() == name);
358}
359
360/// Refetches every cached read. Always correct after a mutation, but every
361/// mounted screen refetches everything it shows; prefer [`invalidate_cached`] for
362/// the reads the mutation changes.
363pub fn invalidate_all_cached() {
364    mark_stale(|_| true);
365}
366
367/// Edits the cached answer of one call, `server_fn` with exactly these
368/// `args`, in place, so a change shows at once rather than after the
369/// mutation's round trip. Returns whether there was an answer to edit.
370///
371/// ```ignore
372/// g3_cache::update_cached(get_playlist, (id.clone(),), |playlist| {
373///     playlist.videos.retain(|video| video.id != removed);
374/// });
375/// remove_from_playlist(id.clone(), removed).await?;
376/// g3_cache::invalidate_cached_call(get_playlist, (id,));
377/// ```
378///
379/// Mounted screens show the edit without refetching. It is memory only: the
380/// persistent store keeps the server's last answer, so **follow the
381/// mutation with an invalidation**, whether it succeeded or not. The
382/// refetch replaces the guess with what the server holds, which also undoes
383/// it if the mutation failed.
384pub fn update_cached<F, Args>(server_fn: F, args: Args, update: impl FnOnce(&mut F::Output)) -> bool
385where
386    F: CacheableFn<Args>,
387    Args: Serialize,
388    F::Output: Clone + 'static,
389{
390    update_cached_key(&CacheKey::of(&server_fn, &args), update)
391}
392
393/// [`update_cached`] for every cached call of `server_fn`, whatever its
394/// arguments: a video marked watched in every cached page of a feed, say.
395/// Returns how many answers were edited.
396pub fn update_all_cached<F, Args>(server_fn: F, mut update: impl FnMut(&mut F::Output)) -> usize
397where
398    F: CacheableFn<Args>,
399    F::Output: Clone + 'static,
400{
401    let _ = server_fn;
402    let name = crate::key::fn_name::<F>();
403    edit_entries(|key| key.name() == name, &mut update)
404}
405
406/// [`update_cached`] for a read cached under a [`CacheKey`] you named.
407pub fn update_cached_key<T: Clone + 'static>(key: &CacheKey, update: impl FnOnce(&mut T)) -> bool {
408    let mut update = Some(update);
409    edit_entries(|candidate| candidate == key, &mut |value: &mut T| {
410        if let Some(update) = update.take() {
411            update(value);
412        }
413    }) > 0
414}
415
416fn edit_entries<T: Clone + 'static>(
417    matches: impl Fn(&CacheKey) -> bool,
418    update: &mut dyn FnMut(&mut T),
419) -> usize {
420    if !ENABLED {
421        return 0;
422    }
423    let edited = MEMORY.with_borrow_mut(|memory| {
424        let mut edited = 0;
425        for (key, entry) in memory.iter_mut() {
426            if !matches(key) {
427                continue;
428            }
429            let Some(current) = entry.value.downcast_ref::<T>() else {
430                continue;
431            };
432            // Copied rather than edited through the `Rc`: a screen still
433            // holding the previous value must see a change arrive, not have
434            // its value altered underneath it.
435            let mut value = current.clone();
436            update(&mut value);
437            entry.value = Rc::new(value);
438            edited += 1;
439        }
440        edited
441    });
442    if edited > 0 {
443        // Mounted reads recheck their entry. It keeps its `fetched_at`, so a
444        // fresh one shows the edit without refetching and a stale one still
445        // refetches.
446        *EPOCH.write() += 1;
447    }
448    edited
449}
450
451#[cfg(all(test, not(feature = "server")))]
452mod tests {
453    use super::*;
454    use dioxus::prelude::*;
455    use std::sync::atomic::{AtomicUsize, Ordering};
456
457    static FETCHES: AtomicUsize = AtomicUsize::new(0);
458
459    fn key() -> CacheKey {
460        CacheKey::new("numbers")
461    }
462
463    #[derive(Props, Clone, PartialEq)]
464    struct Shown {
465        shown: Signal<Option<Vec<u32>>>,
466        pending: Signal<bool>,
467    }
468
469    #[component]
470    fn Reader(props: Shown) -> Element {
471        let Shown {
472            mut shown,
473            mut pending,
474        } = props;
475        let numbers = use_cached_key(key(), || async {
476            FETCHES.fetch_add(1, Ordering::SeqCst);
477            Ok(vec![1, 2, 3])
478        });
479        let value = numbers
480            .read()
481            .as_ref()
482            .and_then(|result| result.as_ref().ok())
483            .cloned();
484        if *shown.peek() != value {
485            shown.set(value);
486        }
487        if *pending.peek() != numbers.pending() {
488            pending.set(numbers.pending());
489        }
490        rsx! {}
491    }
492
493    async fn settle(dom: &mut VirtualDom) {
494        for _ in 0..20 {
495            tokio::select! {
496                () = dom.wait_for_work() => { dom.render_immediate(&mut dioxus_core::NoOpMutations); }
497                () = tokio::time::sleep(std::time::Duration::from_millis(20)) => return,
498            }
499        }
500    }
501
502    /// One test, in order: the steps share the thread-local cache.
503    #[tokio::test(flavor = "current_thread")]
504    async fn an_update_shows_at_once_and_an_invalidation_reconciles_it() {
505        let mut dom = VirtualDom::new(|| {
506            let shown = use_signal(|| None);
507            let pending = use_signal(|| false);
508            use_context_provider(|| (shown, pending));
509            rsx! { Reader { shown, pending } }
510        });
511        dom.rebuild_in_place();
512        settle(&mut dom).await;
513        let (shown, pending) = dom.in_scope(ScopeId::APP, || {
514            consume_context::<(Signal<Option<Vec<u32>>>, Signal<bool>)>()
515        });
516        assert_eq!(dom.in_runtime(|| shown()), Some(vec![1, 2, 3]));
517        assert_eq!(FETCHES.load(Ordering::SeqCst), 1);
518        assert!(!dom.in_runtime(|| pending()));
519
520        let edited =
521            dom.in_runtime(|| update_cached_key(&key(), |numbers: &mut Vec<u32>| numbers.push(4)));
522        assert!(edited);
523        settle(&mut dom).await;
524        assert_eq!(dom.in_runtime(|| shown()), Some(vec![1, 2, 3, 4]));
525        assert_eq!(
526            FETCHES.load(Ordering::SeqCst),
527            1,
528            "an update must not refetch"
529        );
530
531        // A key nothing has cached: nothing to edit, and no wasted rerun.
532        assert!(
533            !dom.in_runtime(|| update_cached_key(&CacheKey::new("absent"), |_: &mut Vec<u32>| {}))
534        );
535
536        dom.in_runtime(|| invalidate_cached_key(&key()));
537        settle(&mut dom).await;
538        assert_eq!(
539            dom.in_runtime(|| shown()),
540            Some(vec![1, 2, 3]),
541            "the refetch replaces the guess"
542        );
543        assert_eq!(FETCHES.load(Ordering::SeqCst), 2);
544        assert!(!dom.in_runtime(|| pending()));
545    }
546}