mod hook;
mod store;
pub use hook::*;
use crate::{CacheKey, CacheableFn};
use dioxus::prelude::{GlobalSignal, Signal, document, spawn, use_hook};
use serde::Serialize;
use std::{
any::Any,
borrow::Cow,
cell::{Cell, RefCell},
collections::BTreeMap,
rc::Rc,
sync::OnceLock,
time::Duration,
};
pub(crate) const ENABLED: bool = !cfg!(feature = "server");
pub(crate) const STALE: i64 = i64::MIN;
const OWNER_KEY: &str = "\u{1f}owner";
#[derive(Clone, Debug)]
pub struct CacheConfig {
pub(crate) name: Cow<'static, str>,
pub(crate) share_for: Duration,
pub(crate) keep_for: Duration,
pub(crate) revalidate_on_focus: bool,
pub(crate) focus_gap: Duration,
pub(crate) max_entries: usize,
pub(crate) max_bytes: usize,
}
impl CacheConfig {
pub fn new(name: impl Into<Cow<'static, str>>) -> Self {
Self {
name: name.into(),
share_for: Duration::from_secs(2),
keep_for: Duration::from_secs(7 * 24 * 60 * 60),
revalidate_on_focus: true,
focus_gap: Duration::from_secs(30),
max_entries: 256,
max_bytes: 32 * 1024 * 1024,
}
}
pub fn name(&self) -> &str {
&self.name
}
pub fn max_entries(mut self, count: usize) -> Self {
self.max_entries = count;
self
}
pub fn max_bytes(mut self, bytes: usize) -> Self {
self.max_bytes = bytes;
self
}
pub fn share_for(mut self, duration: Duration) -> Self {
self.share_for = duration;
self
}
pub fn keep_for(mut self, duration: Duration) -> Self {
self.keep_for = duration;
self
}
pub fn revalidate_on_focus(mut self, on: bool) -> Self {
self.revalidate_on_focus = on;
self
}
pub fn focus_gap(mut self, duration: Duration) -> Self {
self.focus_gap = duration;
self
}
}
static CONFIG: OnceLock<CacheConfig> = OnceLock::new();
pub(crate) fn config() -> &'static CacheConfig {
CONFIG.get_or_init(|| CacheConfig::new("g3-cache"))
}
pub fn use_client_cache(config: CacheConfig) {
use_hook(move || {
if !ENABLED {
return;
}
if CONFIG.set(config).is_err() {
tracing::warn!(
"g3-cache: `use_client_cache` ran more than once, or after the first cached \
read; the later settings are ignored. Call it once, first thing in the root \
component."
);
}
if self::config().revalidate_on_focus {
spawn(revalidate_on_focus());
}
});
}
async fn revalidate_on_focus() {
const SCRIPT: &str = r#"
const send = () => dioxus.send(null);
document.addEventListener("visibilitychange", () => {
if (document.visibilityState === "visible") send();
});
window.addEventListener("focus", send);
window.addEventListener("online", send);
await new Promise(() => {});
"#;
let mut events = document::eval(SCRIPT);
let mut last = now_ms();
while events.recv::<()>().await.is_ok() {
let gap = i64::try_from(config().focus_gap.as_millis()).unwrap_or(i64::MAX);
if now_ms().saturating_sub(last) >= gap {
last = now_ms();
invalidate_all_cached();
}
}
}
struct MemoryEntry {
value: Rc<dyn Any>,
fetched_at: i64,
accessed: u64,
bytes: usize,
measure: fn(&dyn Any) -> usize,
}
thread_local! {
static OWNER_GENERATION: Cell<u64> = const { Cell::new(0) };
static ACCESS: Cell<u64> = const { Cell::new(0) };
static MEMORY: RefCell<BTreeMap<CacheKey, MemoryEntry>> = const { RefCell::new(BTreeMap::new()) };
static OWNER_SET: Cell<bool> = const { Cell::new(false) };
static STORE_OWNED: Cell<Option<bool>> = const { Cell::new(None) };
}
pub(crate) fn owner_generation() -> u64 {
OWNER_GENERATION.get()
}
fn next_access() -> u64 {
let next = ACCESS.get().wrapping_add(1);
ACCESS.set(next);
next
}
fn trim_memory(memory: &mut BTreeMap<CacheKey, MemoryEntry>, limits: &CacheConfig) {
while memory.len() > limits.max_entries
|| memory.values().map(|entry| entry.bytes).sum::<usize>() > limits.max_bytes
{
let Some(key) = memory
.iter()
.min_by_key(|(_, entry)| entry.accessed)
.map(|(key, _)| key.clone())
else {
break;
};
memory.remove(&key);
}
}
pub(crate) static EPOCH: GlobalSignal<u64> = Signal::global(|| 0);
pub(crate) fn now_ms() -> i64 {
chrono::Utc::now().timestamp_millis()
}
pub(crate) fn remembered<T: Clone + 'static>(key: &CacheKey) -> Option<(T, i64)> {
if !ENABLED {
return None;
}
MEMORY.with_borrow_mut(|memory| {
let entry = memory.get_mut(key)?;
entry.accessed = next_access();
let value = entry.value.downcast_ref::<T>()?.clone();
Some((value, entry.fetched_at))
})
}
pub(crate) fn remember<T: Serialize + 'static>(key: &CacheKey, value: T, fetched_at: i64) {
if ENABLED {
let Ok(bytes) = serde_json::to_vec(&value).map(|json| json.len()) else {
return;
};
if bytes > config().max_bytes || config().max_entries == 0 {
MEMORY.with_borrow_mut(|memory| memory.remove(key));
return;
}
let entry = MemoryEntry {
value: Rc::new(value),
fetched_at,
accessed: next_access(),
bytes,
measure: |value| {
value
.downcast_ref::<T>()
.and_then(|value| serde_json::to_vec(value).ok())
.map_or(usize::MAX, |json| json.len())
},
};
MEMORY.with_borrow_mut(|memory| {
memory.insert(key.clone(), entry);
trim_memory(memory, config());
});
}
}
#[derive(serde::Serialize, serde::Deserialize)]
struct Stored<T> {
saved_at: i64,
value: T,
}
pub(crate) async fn restore<T: serde::de::DeserializeOwned>(key: &CacheKey) -> Option<T> {
let generation = owner_generation();
if !ENABLED || !store_owned().await {
return None;
}
let stored: Stored<T> = serde_json::from_str(&store::load(&key.storage_key()).await?).ok()?;
if generation != owner_generation() {
return None;
}
let keep_for = i64::try_from(config().keep_for.as_millis()).unwrap_or(i64::MAX);
(now_ms().saturating_sub(stored.saved_at) < keep_for).then_some(stored.value)
}
pub(crate) async fn persist<T: Serialize>(key: &CacheKey, value: &T) {
if !ENABLED || !OWNER_SET.get() {
return;
}
let stored = Stored {
saved_at: now_ms(),
value,
};
if let Ok(json) = serde_json::to_string(&stored) {
store::save(&key.storage_key(), &json, owner_generation()).await;
}
}
async fn store_owned() -> bool {
let generation = owner_generation();
if let Some(owned) = STORE_OWNED.get() {
return owned;
}
let owned = store::load(OWNER_KEY)
.await
.is_some_and(|owner| !owner.is_empty());
if generation != owner_generation() {
return false;
}
STORE_OWNED.set(Some(owned));
owned
}
pub async fn set_cache_owner(owner: Option<String>) {
if !ENABLED {
return;
}
let generation = owner_generation().wrapping_add(1);
OWNER_GENERATION.set(generation);
OWNER_SET.set(false);
STORE_OWNED.set(Some(false));
MEMORY.with_borrow_mut(BTreeMap::clear);
*EPOCH.write() += 1;
let owner = owner.unwrap_or_default();
let stored_owner = store::load(OWNER_KEY).await;
if generation != owner_generation() {
return;
}
if !owner.is_empty() && stored_owner.as_deref() == Some(owner.as_str()) {
STORE_OWNED.set(Some(true));
OWNER_SET.set(true);
store::prune(generation).await;
*EPOCH.write() += 1;
return;
}
store::clear(generation).await;
if generation != owner_generation() {
return;
}
store::save(OWNER_KEY, &owner, generation).await;
if generation != owner_generation() {
return;
}
STORE_OWNED.set(Some(!owner.is_empty()));
OWNER_SET.set(!owner.is_empty());
*EPOCH.write() += 1;
}
fn mark_stale(matches: impl Fn(&CacheKey) -> bool) {
if !ENABLED {
return;
}
MEMORY.with_borrow_mut(|memory| {
for (key, entry) in memory.iter_mut() {
if matches(key) {
entry.fetched_at = STALE;
}
}
});
*EPOCH.write() += 1;
}
pub fn invalidate_cached<F, Args>(server_fn: F)
where
F: CacheableFn<Args>,
{
let _ = server_fn;
let name = crate::key::fn_name::<F>();
mark_stale(|key| key.name() == name);
}
pub fn invalidate_cached_call<F, Args>(server_fn: F, args: Args)
where
F: CacheableFn<Args>,
Args: Serialize,
{
let target = CacheKey::of(&server_fn, &args);
mark_stale(|key| *key == target);
}
pub fn invalidate_cached_key(key: &CacheKey) {
mark_stale(|candidate| candidate == key);
}
pub fn invalidate_cached_name(name: &str) {
mark_stale(|key| key.name() == name);
}
pub fn invalidate_all_cached() {
mark_stale(|_| true);
}
pub fn update_cached<F, Args>(server_fn: F, args: Args, update: impl FnOnce(&mut F::Output)) -> bool
where
F: CacheableFn<Args>,
Args: Serialize,
F::Output: Clone + 'static,
{
update_cached_key(&CacheKey::of(&server_fn, &args), update)
}
pub fn update_all_cached<F, Args>(server_fn: F, mut update: impl FnMut(&mut F::Output)) -> usize
where
F: CacheableFn<Args>,
F::Output: Clone + 'static,
{
let _ = server_fn;
let name = crate::key::fn_name::<F>();
edit_entries(|key| key.name() == name, &mut update)
}
pub fn update_cached_key<T: Clone + 'static>(key: &CacheKey, update: impl FnOnce(&mut T)) -> bool {
let mut update = Some(update);
edit_entries(|candidate| candidate == key, &mut |value: &mut T| {
if let Some(update) = update.take() {
update(value);
}
}) > 0
}
fn edit_entries<T: Clone + 'static>(
matches: impl Fn(&CacheKey) -> bool,
update: &mut dyn FnMut(&mut T),
) -> usize {
if !ENABLED {
return 0;
}
let edited = MEMORY.with_borrow_mut(|memory| {
let mut edited = 0;
for (key, entry) in memory.iter_mut() {
if !matches(key) {
continue;
}
let Some(current) = entry.value.downcast_ref::<T>() else {
continue;
};
let mut value = current.clone();
update(&mut value);
entry.bytes = (entry.measure)(&value);
entry.accessed = next_access();
entry.value = Rc::new(value);
edited += 1;
}
trim_memory(memory, config());
edited
});
if edited > 0 {
*EPOCH.write() += 1;
}
edited
}
#[cfg(all(test, not(feature = "server")))]
mod tests {
use super::*;
use dioxus::prelude::*;
use std::sync::atomic::{AtomicUsize, Ordering};
static FETCHES: AtomicUsize = AtomicUsize::new(0);
#[test]
fn capacity_evicts_the_least_recently_read_payload() {
MEMORY.with_borrow_mut(BTreeMap::clear);
for name in ["old", "recent", "new"] {
remember(&CacheKey::new(name), vec![1_u8; 8], 100);
}
remembered::<Vec<u8>>(&CacheKey::new("old")).unwrap();
MEMORY.with_borrow_mut(|memory| {
trim_memory(memory, &CacheConfig::new("test").max_entries(2))
});
assert!(remembered::<Vec<u8>>(&CacheKey::new("recent")).is_none());
assert!(remembered::<Vec<u8>>(&CacheKey::new("old")).is_some());
MEMORY
.with_borrow_mut(|memory| trim_memory(memory, &CacheConfig::new("test").max_bytes(1)));
assert!(MEMORY.with_borrow(BTreeMap::is_empty));
}
#[tokio::test(flavor = "current_thread")]
async fn an_owner_switch_hides_a_mounted_answer_before_refetch() {
let first_generation = owner_generation();
remember(&CacheKey::new("owner-switch"), first_generation, STALE);
let mut dom = VirtualDom::new(|| {
let cached = use_cached_key(CacheKey::new("owner-switch"), || {
let generation = owner_generation();
async move { Ok(generation) }
});
use_context_provider(|| cached);
let _ = cached.read();
rsx! {}
});
dom.rebuild_in_place();
settle(&mut dom).await;
let cached = dom.in_scope(ScopeId::APP, consume_context::<Cached<u64>>);
assert_eq!(
dom.in_runtime(|| cached.peek().as_ref().unwrap().as_ref().unwrap().to_owned()),
first_generation
);
dom.in_scope(ScopeId::APP, || {
spawn(async move {
set_cache_owner(Some("another-account".into())).await;
assert!(cached.peek().is_none());
})
});
settle(&mut dom).await;
let answer =
dom.in_runtime(|| cached.peek().as_ref().unwrap().as_ref().unwrap().to_owned());
assert_eq!(answer, first_generation + 1);
}
fn key() -> CacheKey {
CacheKey::new("numbers")
}
#[derive(Props, Clone, PartialEq)]
struct Shown {
shown: Signal<Option<Vec<u32>>>,
pending: Signal<bool>,
}
#[component]
fn Reader(props: Shown) -> Element {
let Shown {
mut shown,
mut pending,
} = props;
let numbers = use_cached_key(key(), || async {
FETCHES.fetch_add(1, Ordering::SeqCst);
Ok(vec![1, 2, 3])
});
let value = numbers
.read()
.as_ref()
.and_then(|result| result.as_ref().ok())
.cloned();
if *shown.peek() != value {
shown.set(value);
}
if *pending.peek() != numbers.pending() {
pending.set(numbers.pending());
}
rsx! {}
}
async fn settle(dom: &mut VirtualDom) {
for _ in 0..20 {
tokio::select! {
() = dom.wait_for_work() => { dom.render_immediate(&mut dioxus_core::NoOpMutations); }
() = tokio::time::sleep(std::time::Duration::from_millis(20)) => return,
}
}
}
#[tokio::test(flavor = "current_thread")]
async fn an_update_shows_at_once_and_an_invalidation_reconciles_it() {
let mut dom = VirtualDom::new(|| {
let shown = use_signal(|| None);
let pending = use_signal(|| false);
use_context_provider(|| (shown, pending));
rsx! { Reader { shown, pending } }
});
dom.rebuild_in_place();
settle(&mut dom).await;
let (shown, pending) = dom.in_scope(ScopeId::APP, || {
consume_context::<(Signal<Option<Vec<u32>>>, Signal<bool>)>()
});
assert_eq!(dom.in_runtime(|| shown()), Some(vec![1, 2, 3]));
assert_eq!(FETCHES.load(Ordering::SeqCst), 1);
assert!(!dom.in_runtime(|| pending()));
let edited =
dom.in_runtime(|| update_cached_key(&key(), |numbers: &mut Vec<u32>| numbers.push(4)));
assert!(edited);
settle(&mut dom).await;
assert_eq!(dom.in_runtime(|| shown()), Some(vec![1, 2, 3, 4]));
assert_eq!(
FETCHES.load(Ordering::SeqCst),
1,
"an update must not refetch"
);
assert!(
!dom.in_runtime(|| update_cached_key(&CacheKey::new("absent"), |_: &mut Vec<u32>| {}))
);
dom.in_runtime(|| invalidate_cached_key(&key()));
settle(&mut dom).await;
assert_eq!(
dom.in_runtime(|| shown()),
Some(vec![1, 2, 3]),
"the refetch replaces the guess"
);
assert_eq!(FETCHES.load(Ordering::SeqCst), 2);
assert!(!dom.in_runtime(|| pending()));
}
}