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 pub(crate) max_entries: usize,
49 pub(crate) max_bytes: usize,
50}
51
52impl CacheConfig {
53 pub fn new(name: impl Into<Cow<'static, str>>) -> Self {
57 Self {
58 name: name.into(),
59 share_for: Duration::from_secs(2),
60 keep_for: Duration::from_secs(7 * 24 * 60 * 60),
61 revalidate_on_focus: true,
62 focus_gap: Duration::from_secs(30),
63 max_entries: 256,
64 max_bytes: 32 * 1024 * 1024,
65 }
66 }
67
68 pub fn name(&self) -> &str {
70 &self.name
71 }
72
73 pub fn max_entries(mut self, count: usize) -> Self {
75 self.max_entries = count;
76 self
77 }
78
79 pub fn max_bytes(mut self, bytes: usize) -> Self {
82 self.max_bytes = bytes;
83 self
84 }
85
86 pub fn share_for(mut self, duration: Duration) -> Self {
92 self.share_for = duration;
93 self
94 }
95
96 pub fn keep_for(mut self, duration: Duration) -> Self {
100 self.keep_for = duration;
101 self
102 }
103
104 pub fn revalidate_on_focus(mut self, on: bool) -> Self {
110 self.revalidate_on_focus = on;
111 self
112 }
113
114 pub fn focus_gap(mut self, duration: Duration) -> Self {
117 self.focus_gap = duration;
118 self
119 }
120}
121
122static CONFIG: OnceLock<CacheConfig> = OnceLock::new();
123
124pub(crate) fn config() -> &'static CacheConfig {
125 CONFIG.get_or_init(|| CacheConfig::new("g3-cache"))
126}
127
128pub fn use_client_cache(config: CacheConfig) {
145 use_hook(move || {
146 if !ENABLED {
149 return;
150 }
151 if CONFIG.set(config).is_err() {
152 tracing::warn!(
153 "g3-cache: `use_client_cache` ran more than once, or after the first cached \
154 read; the later settings are ignored. Call it once, first thing in the root \
155 component."
156 );
157 }
158 if self::config().revalidate_on_focus {
159 spawn(revalidate_on_focus());
160 }
161 });
162}
163
164async fn revalidate_on_focus() {
168 const SCRIPT: &str = r#"
169 const send = () => dioxus.send(null);
170 document.addEventListener("visibilitychange", () => {
171 if (document.visibilityState === "visible") send();
172 });
173 window.addEventListener("focus", send);
174 window.addEventListener("online", send);
175 await new Promise(() => {});
176 "#;
177 let mut events = document::eval(SCRIPT);
178 let mut last = now_ms();
179 while events.recv::<()>().await.is_ok() {
180 let gap = i64::try_from(config().focus_gap.as_millis()).unwrap_or(i64::MAX);
181 if now_ms().saturating_sub(last) >= gap {
182 last = now_ms();
183 invalidate_all_cached();
184 }
185 }
186}
187
188struct MemoryEntry {
189 value: Rc<dyn Any>,
190 fetched_at: i64,
191 accessed: u64,
192 bytes: usize,
193 measure: fn(&dyn Any) -> usize,
194}
195
196thread_local! {
197 static OWNER_GENERATION: Cell<u64> = const { Cell::new(0) };
198 static ACCESS: Cell<u64> = const { Cell::new(0) };
199 static MEMORY: RefCell<BTreeMap<CacheKey, MemoryEntry>> = const { RefCell::new(BTreeMap::new()) };
200 static OWNER_SET: Cell<bool> = const { Cell::new(false) };
203 static STORE_OWNED: Cell<Option<bool>> = const { Cell::new(None) };
206}
207
208pub(crate) fn owner_generation() -> u64 {
209 OWNER_GENERATION.get()
210}
211
212fn next_access() -> u64 {
213 let next = ACCESS.get().wrapping_add(1);
214 ACCESS.set(next);
215 next
216}
217
218fn trim_memory(memory: &mut BTreeMap<CacheKey, MemoryEntry>, limits: &CacheConfig) {
219 while memory.len() > limits.max_entries
220 || memory.values().map(|entry| entry.bytes).sum::<usize>() > limits.max_bytes
221 {
222 let Some(key) = memory
223 .iter()
224 .min_by_key(|(_, entry)| entry.accessed)
225 .map(|(key, _)| key.clone())
226 else {
227 break;
228 };
229 memory.remove(&key);
230 }
231}
232
233pub(crate) static EPOCH: GlobalSignal<u64> = Signal::global(|| 0);
237
238pub(crate) fn now_ms() -> i64 {
239 chrono::Utc::now().timestamp_millis()
240}
241
242pub(crate) fn remembered<T: Clone + 'static>(key: &CacheKey) -> Option<(T, i64)> {
243 if !ENABLED {
244 return None;
245 }
246 MEMORY.with_borrow_mut(|memory| {
247 let entry = memory.get_mut(key)?;
248 entry.accessed = next_access();
249 let value = entry.value.downcast_ref::<T>()?.clone();
250 Some((value, entry.fetched_at))
251 })
252}
253
254pub(crate) fn remember<T: Serialize + 'static>(key: &CacheKey, value: T, fetched_at: i64) {
255 if ENABLED {
256 let Ok(bytes) = serde_json::to_vec(&value).map(|json| json.len()) else {
257 return;
258 };
259 if bytes > config().max_bytes || config().max_entries == 0 {
260 MEMORY.with_borrow_mut(|memory| memory.remove(key));
261 return;
262 }
263 let entry = MemoryEntry {
264 value: Rc::new(value),
265 fetched_at,
266 accessed: next_access(),
267 bytes,
268 measure: |value| {
269 value
270 .downcast_ref::<T>()
271 .and_then(|value| serde_json::to_vec(value).ok())
272 .map_or(usize::MAX, |json| json.len())
273 },
274 };
275 MEMORY.with_borrow_mut(|memory| {
276 memory.insert(key.clone(), entry);
277 trim_memory(memory, config());
278 });
279 }
280}
281
282#[derive(serde::Serialize, serde::Deserialize)]
283struct Stored<T> {
284 saved_at: i64,
285 value: T,
286}
287
288pub(crate) async fn restore<T: serde::de::DeserializeOwned>(key: &CacheKey) -> Option<T> {
289 let generation = owner_generation();
290 if !ENABLED || !store_owned().await {
291 return None;
292 }
293 let stored: Stored<T> = serde_json::from_str(&store::load(&key.storage_key()).await?).ok()?;
294 if generation != owner_generation() {
295 return None;
296 }
297 let keep_for = i64::try_from(config().keep_for.as_millis()).unwrap_or(i64::MAX);
298 (now_ms().saturating_sub(stored.saved_at) < keep_for).then_some(stored.value)
299}
300
301pub(crate) async fn persist<T: Serialize>(key: &CacheKey, value: &T) {
302 if !ENABLED || !OWNER_SET.get() {
303 return;
304 }
305 let stored = Stored {
306 saved_at: now_ms(),
307 value,
308 };
309 if let Ok(json) = serde_json::to_string(&stored) {
310 store::save(&key.storage_key(), &json, owner_generation()).await;
311 }
312}
313
314async fn store_owned() -> bool {
315 let generation = owner_generation();
316 if let Some(owned) = STORE_OWNED.get() {
317 return owned;
318 }
319 let owned = store::load(OWNER_KEY)
320 .await
321 .is_some_and(|owner| !owner.is_empty());
322 if generation != owner_generation() {
323 return false;
324 }
325 STORE_OWNED.set(Some(owned));
326 owned
327}
328
329pub async fn set_cache_owner(owner: Option<String>) {
348 if !ENABLED {
349 return;
350 }
351 let generation = owner_generation().wrapping_add(1);
352 OWNER_GENERATION.set(generation);
353 OWNER_SET.set(false);
354 STORE_OWNED.set(Some(false));
355 MEMORY.with_borrow_mut(BTreeMap::clear);
356 *EPOCH.write() += 1;
357 let owner = owner.unwrap_or_default();
358 let stored_owner = store::load(OWNER_KEY).await;
359 if generation != owner_generation() {
360 return;
361 }
362 if !owner.is_empty() && stored_owner.as_deref() == Some(owner.as_str()) {
363 STORE_OWNED.set(Some(true));
364 OWNER_SET.set(true);
365 store::prune(generation).await;
366 *EPOCH.write() += 1;
367 return;
368 }
369 store::clear(generation).await;
370 if generation != owner_generation() {
371 return;
372 }
373 store::save(OWNER_KEY, &owner, generation).await;
374 if generation != owner_generation() {
375 return;
376 }
377 STORE_OWNED.set(Some(!owner.is_empty()));
378 OWNER_SET.set(!owner.is_empty());
379 *EPOCH.write() += 1;
380}
381
382fn mark_stale(matches: impl Fn(&CacheKey) -> bool) {
383 if !ENABLED {
384 return;
385 }
386 MEMORY.with_borrow_mut(|memory| {
387 for (key, entry) in memory.iter_mut() {
388 if matches(key) {
389 entry.fetched_at = STALE;
390 }
391 }
392 });
393 *EPOCH.write() += 1;
394}
395
396pub fn invalidate_cached<F, Args>(server_fn: F)
419where
420 F: CacheableFn<Args>,
421{
422 let _ = server_fn;
423 let name = crate::key::fn_name::<F>();
424 mark_stale(|key| key.name() == name);
425}
426
427pub fn invalidate_cached_call<F, Args>(server_fn: F, args: Args)
433where
434 F: CacheableFn<Args>,
435 Args: Serialize,
436{
437 let target = CacheKey::of(&server_fn, &args);
438 mark_stale(|key| *key == target);
439}
440
441pub fn invalidate_cached_key(key: &CacheKey) {
443 mark_stale(|candidate| candidate == key);
444}
445
446pub fn invalidate_cached_name(name: &str) {
449 mark_stale(|key| key.name() == name);
450}
451
452pub fn invalidate_all_cached() {
456 mark_stale(|_| true);
457}
458
459pub fn update_cached<F, Args>(server_fn: F, args: Args, update: impl FnOnce(&mut F::Output)) -> bool
477where
478 F: CacheableFn<Args>,
479 Args: Serialize,
480 F::Output: Clone + 'static,
481{
482 update_cached_key(&CacheKey::of(&server_fn, &args), update)
483}
484
485pub fn update_all_cached<F, Args>(server_fn: F, mut update: impl FnMut(&mut F::Output)) -> usize
489where
490 F: CacheableFn<Args>,
491 F::Output: Clone + 'static,
492{
493 let _ = server_fn;
494 let name = crate::key::fn_name::<F>();
495 edit_entries(|key| key.name() == name, &mut update)
496}
497
498pub fn update_cached_key<T: Clone + 'static>(key: &CacheKey, update: impl FnOnce(&mut T)) -> bool {
500 let mut update = Some(update);
501 edit_entries(|candidate| candidate == key, &mut |value: &mut T| {
502 if let Some(update) = update.take() {
503 update(value);
504 }
505 }) > 0
506}
507
508fn edit_entries<T: Clone + 'static>(
509 matches: impl Fn(&CacheKey) -> bool,
510 update: &mut dyn FnMut(&mut T),
511) -> usize {
512 if !ENABLED {
513 return 0;
514 }
515 let edited = MEMORY.with_borrow_mut(|memory| {
516 let mut edited = 0;
517 for (key, entry) in memory.iter_mut() {
518 if !matches(key) {
519 continue;
520 }
521 let Some(current) = entry.value.downcast_ref::<T>() else {
522 continue;
523 };
524 let mut value = current.clone();
528 update(&mut value);
529 entry.bytes = (entry.measure)(&value);
530 entry.accessed = next_access();
531 entry.value = Rc::new(value);
532 edited += 1;
533 }
534 trim_memory(memory, config());
535 edited
536 });
537 if edited > 0 {
538 *EPOCH.write() += 1;
542 }
543 edited
544}
545
546#[cfg(all(test, not(feature = "server")))]
547mod tests {
548 use super::*;
549 use dioxus::prelude::*;
550 use std::sync::atomic::{AtomicUsize, Ordering};
551
552 static FETCHES: AtomicUsize = AtomicUsize::new(0);
553
554 #[test]
555 fn capacity_evicts_the_least_recently_read_payload() {
556 MEMORY.with_borrow_mut(BTreeMap::clear);
557 for name in ["old", "recent", "new"] {
558 remember(&CacheKey::new(name), vec![1_u8; 8], 100);
559 }
560 remembered::<Vec<u8>>(&CacheKey::new("old")).unwrap();
561 MEMORY.with_borrow_mut(|memory| {
562 trim_memory(memory, &CacheConfig::new("test").max_entries(2))
563 });
564 assert!(remembered::<Vec<u8>>(&CacheKey::new("recent")).is_none());
565 assert!(remembered::<Vec<u8>>(&CacheKey::new("old")).is_some());
566 MEMORY
567 .with_borrow_mut(|memory| trim_memory(memory, &CacheConfig::new("test").max_bytes(1)));
568 assert!(MEMORY.with_borrow(BTreeMap::is_empty));
569 }
570
571 #[tokio::test(flavor = "current_thread")]
572 async fn an_owner_switch_hides_a_mounted_answer_before_refetch() {
573 let first_generation = owner_generation();
574 remember(&CacheKey::new("owner-switch"), first_generation, STALE);
575 let mut dom = VirtualDom::new(|| {
576 let cached = use_cached_key(CacheKey::new("owner-switch"), || {
577 let generation = owner_generation();
578 async move { Ok(generation) }
579 });
580 use_context_provider(|| cached);
581 let _ = cached.read();
582 rsx! {}
583 });
584 dom.rebuild_in_place();
585 settle(&mut dom).await;
586 let cached = dom.in_scope(ScopeId::APP, consume_context::<Cached<u64>>);
587 assert_eq!(
588 dom.in_runtime(|| cached.peek().as_ref().unwrap().as_ref().unwrap().to_owned()),
589 first_generation
590 );
591 dom.in_scope(ScopeId::APP, || {
592 spawn(async move {
593 set_cache_owner(Some("another-account".into())).await;
594 assert!(cached.peek().is_none());
596 })
597 });
598 settle(&mut dom).await;
599 let answer =
600 dom.in_runtime(|| cached.peek().as_ref().unwrap().as_ref().unwrap().to_owned());
601 assert_eq!(answer, first_generation + 1);
602 }
603
604 fn key() -> CacheKey {
605 CacheKey::new("numbers")
606 }
607
608 #[derive(Props, Clone, PartialEq)]
609 struct Shown {
610 shown: Signal<Option<Vec<u32>>>,
611 pending: Signal<bool>,
612 }
613
614 #[component]
615 fn Reader(props: Shown) -> Element {
616 let Shown {
617 mut shown,
618 mut pending,
619 } = props;
620 let numbers = use_cached_key(key(), || async {
621 FETCHES.fetch_add(1, Ordering::SeqCst);
622 Ok(vec![1, 2, 3])
623 });
624 let value = numbers
625 .read()
626 .as_ref()
627 .and_then(|result| result.as_ref().ok())
628 .cloned();
629 if *shown.peek() != value {
630 shown.set(value);
631 }
632 if *pending.peek() != numbers.pending() {
633 pending.set(numbers.pending());
634 }
635 rsx! {}
636 }
637
638 async fn settle(dom: &mut VirtualDom) {
639 for _ in 0..20 {
640 tokio::select! {
641 () = dom.wait_for_work() => { dom.render_immediate(&mut dioxus_core::NoOpMutations); }
642 () = tokio::time::sleep(std::time::Duration::from_millis(20)) => return,
643 }
644 }
645 }
646
647 #[tokio::test(flavor = "current_thread")]
649 async fn an_update_shows_at_once_and_an_invalidation_reconciles_it() {
650 let mut dom = VirtualDom::new(|| {
651 let shown = use_signal(|| None);
652 let pending = use_signal(|| false);
653 use_context_provider(|| (shown, pending));
654 rsx! { Reader { shown, pending } }
655 });
656 dom.rebuild_in_place();
657 settle(&mut dom).await;
658 let (shown, pending) = dom.in_scope(ScopeId::APP, || {
659 consume_context::<(Signal<Option<Vec<u32>>>, Signal<bool>)>()
660 });
661 assert_eq!(dom.in_runtime(|| shown()), Some(vec![1, 2, 3]));
662 assert_eq!(FETCHES.load(Ordering::SeqCst), 1);
663 assert!(!dom.in_runtime(|| pending()));
664
665 let edited =
666 dom.in_runtime(|| update_cached_key(&key(), |numbers: &mut Vec<u32>| numbers.push(4)));
667 assert!(edited);
668 settle(&mut dom).await;
669 assert_eq!(dom.in_runtime(|| shown()), Some(vec![1, 2, 3, 4]));
670 assert_eq!(
671 FETCHES.load(Ordering::SeqCst),
672 1,
673 "an update must not refetch"
674 );
675
676 assert!(
678 !dom.in_runtime(|| update_cached_key(&CacheKey::new("absent"), |_: &mut Vec<u32>| {}))
679 );
680
681 dom.in_runtime(|| invalidate_cached_key(&key()));
682 settle(&mut dom).await;
683 assert_eq!(
684 dom.in_runtime(|| shown()),
685 Some(vec![1, 2, 3]),
686 "the refetch replaces the guess"
687 );
688 assert_eq!(FETCHES.load(Ordering::SeqCst), 2);
689 assert!(!dom.in_runtime(|| pending()));
690 }
691}