g3-cache
Caching for Dioxus fullstack apps, part of the g3 stack: on the device, on the server, and at the CDN, with checks against caching the wrong thing in the wrong place.
Setup
[]
= "0.2"
[]
= ["dioxus/web", "g3-cache/web"] # IndexedDB store
= ["dioxus/mobile", "g3-cache/mobile"] # redb file store
= ["dioxus/desktop", "g3-cache/desktop"] # redb file store
= ["dioxus/server", "g3-cache/server"] # server + CDN caches; client cache off
Usage
use ;
// A screen: show the last known answer at once, refetch in the background.
let media = use_cached;
// After a mutation: refetch what it changed.
save_rating.await?;
invalidate_cached;
// Or show it at once, and let the invalidation reconcile it.
update_cached;
let saved = save_rating.await;
invalidate_cached;
// A public read: cached at the CDN and on the server for 5 minutes.
pub async
Choosing a cache
The client stores default to 256 answers and 32 MiB of JSON payload each.
Configure them with CacheConfig::max_entries and CacheConfig::max_bytes;
zero disables storage. Memory evicts the least recently read answers, while
disk evicts the oldest saved ones and removes expired answers on writes and
owner restoration. Payload bytes are an estimate, excluding allocator and
database overhead. Mounted screens still hold their displayed answer.
Owner changes hide previous answers immediately and discard old requests
that finish after the switch.
| Client | Server | CDN | |
|---|---|---|---|
| For | Showing the last known data at once | Not repeating slow or rate-limited work | Answering identical public requests without the server |
| Holds | One user's data, on one device | Shared answers, in one process | Whole shared HTTP responses |
| Refreshed by | Screen opens, invalidate_cached, app focus |
Expiry only | Expiry only |
| API | use_cached, use_cached_key |
#[cache_shared(server = ..)], ServerCache |
#[cache_shared(cdn = ..)], cdn_cache_guard |
The rule: data that depends on who is asking is cached on the client
only. Data that is the same for everyone may also be cached on the server
and at the CDN. #[cache_shared] refuses, at compile time, functions that
bind a session, auth, user or cookie extractor, and anything that isn't a
GET.
For caching part of a server function, declare a cache where it is used:
static DESCRIPTIONS: =
new;
DESCRIPTIONS.get_or_fetch.await
In the app:
use ;
// Server router: once, outside the session layer.
.layer
.layer
Only standard Cache-Control headers are sent (public, s-maxage,
private, no-cache), so any CDN or shared cache works. Most won't cache
API responses until told to (in Cloudflare, a Cache Rule making the API
paths eligible); until then nothing is cached at the CDN, which is safe.
What you still have to handle:
- Invalidate after mutations. Only the mutation knows which reads it changed.
- Write mutations as "set to", not "toggle". A device showing stale state sends what it saw; a toggle then undoes another device's change.
- Only share functions whose answer comes from their arguments. The compile-time check catches session-like extractors, not every way a function can read the visitor.
Test bed
testbed/ is a small Dioxus app using the cache API against real server
functions. just testbed builds it for the server and the browser.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.