1mod 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
22pub(crate) const ENABLED: bool = !cfg!(feature = "server");
25
26pub(crate) const STALE: i64 = i64::MIN;
29
30const OWNER_KEY: &str = "\u{1f}owner";
32
33#[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 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 pub fn name(&self) -> &str {
66 &self.name
67 }
68
69 pub fn share_for(mut self, duration: Duration) -> Self {
75 self.share_for = duration;
76 self
77 }
78
79 pub fn keep_for(mut self, duration: Duration) -> Self {
83 self.keep_for = duration;
84 self
85 }
86
87 pub fn revalidate_on_focus(mut self, on: bool) -> Self {
93 self.revalidate_on_focus = on;
94 self
95 }
96
97 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
111pub fn use_client_cache(config: CacheConfig) {
128 use_hook(move || {
129 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
147async 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 static OWNER_SET: Cell<bool> = const { Cell::new(false) };
181 static STORE_OWNED: Cell<Option<bool>> = const { Cell::new(None) };
184}
185
186pub(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
255pub 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
304pub 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
335pub 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
349pub fn invalidate_cached_key(key: &CacheKey) {
351 mark_stale(|candidate| candidate == key);
352}
353
354pub fn invalidate_cached_name(name: &str) {
357 mark_stale(|key| key.name() == name);
358}
359
360pub fn invalidate_all_cached() {
364 mark_stale(|_| true);
365}
366
367pub 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
393pub 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
406pub 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 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 *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 #[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 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}