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}