Expand description
Caching for Dioxus fullstack apps: on the device, on the server, and at the CDN, with checks against caching the wrong thing in the wrong place.
use g3_cache::{cache_shared, invalidate_cached, use_cached};
// A screen: show the last known answer at once, refetch in the background.
let media = use_cached(get_media, (id.clone(),));
// After a mutation: refetch what it changed.
save_rating(id.clone(), score).await?;
invalidate_cached(get_my_rating);
// A public read: cached at the CDN and on the server for 5 minutes.
#[cache_shared(cdn = 300, server = "5m")]
#[get("/api/trending?media_type", db: Db)]
pub async fn get_trending(media_type: Option<MediaType>) -> Result<Vec<Media>> { .. }Every name says it is about caching, so the crate reads well through a
use statement.
§Choosing a cache
A read can be cached in three places. Each answers a different problem, and none replaces another.
| Client | Server | CDN | |
|---|---|---|---|
| For | Showing the last known data at once, then refreshing it | Not repeating slow or rate-limited work | Answering identical public requests without reaching the server |
| Holds | One user’s data, on one device | Answers shared by every request, in one server process | Whole HTTP responses shared by every visitor |
| Refreshed by | Screen opens, invalidate_cached, app focus | Expiry only | Expiry only |
| API | use_cached | cache_shared(server = ..), ServerCache | cache_shared(cdn = ..), cdn_cache_guard |
The rule: data that depends on who is asking (their ratings, their lists) is cached on the client only. Data that is the same for everyone (trending titles, a catalog) may also be cached on the server and at the CDN.
A read passes through them in order: client memory and store, then the browser’s HTTP cache and the CDN, then the server, whose own cache may answer instead of the database or an outside API.
§Setup
Enable the feature matching each build:
[dependencies]
g3-cache = "0.2"
[features]
web = ["dioxus/web", "g3-cache/web"] # IndexedDB store
mobile = ["dioxus/mobile", "g3-cache/mobile"] # redb file store
desktop = ["dioxus/desktop", "g3-cache/desktop"] # redb file store
server = ["dioxus/server", "g3-cache/server"] # server + CDN caches; client cache offThen, in the app:
use g3_cache::{CacheConfig, set_cache_owner, use_client_cache};
fn App() -> Element {
// 1. Once, first thing in the root component.
use_client_cache(CacheConfig::new("my-app"));
// 2. Whenever the signed-in user is known or changes, and on sign-out.
let user = use_server_future(get_current_user)?;
use_effect(move || {
let owner = user().and_then(|user| user.ok()).flatten().map(|user| user.id);
spawn(set_cache_owner(owner));
});
// ...
}And on the server router, once, outside the session layer:
.layer(session_layer)
.layer(g3_cache::cdn_cache_guard("/api"))§Client cache
Use use_cached in place of use_resource for data a screen shows
when it opens:
let media = use_cached(get_media, (id.clone(),));The screen shows what the device last saw (from memory, or from disk on
a cold start) and refetches in the background; the fresh answer replaces
it. After a mutation, invalidate_cached each read it changed:
save_rating(id.clone(), score).await?;
invalidate_cached(get_my_rating);
invalidate_cached(get_my_ratings);Don’t use it for reads that change with every keystroke (use
use_resource), or in a handler that must act on current server state
(call the server function directly).
§Showing a change at once
A tap that waits for a round trip feels broken. update_cached edits
what mounted screens show before the mutation is sent; the invalidation
after it replaces the guess with the server’s answer, and so also undoes
it if the mutation failed:
update_all_cached(get_feed_page, |page| page.mark_watched(&video_id));
let saved = set_watched(video_id.clone(), true).await;
invalidate_cached(get_feed_page);
saved?;Cached::pending says whether a refetch is in flight, for a
pull-to-refresh spinner over a list that is already showing.
§Several devices
The server is the only source of truth: mutations go straight to it, and nothing is written offline, so devices never need merging. The question is only how long a device shows what it saw last:
- A screen that opens shows its old copy and refetches at once.
- A screen that stayed open refetches when the app comes back into
view (
CacheConfig::revalidate_on_focus, on by default). - A tap on stale data is still sent. Write mutations so that is
harmless:
set_in_list(list, item, true)rather thantoggle_in_list(list, item), which undoes the other device’s change when this one shows old state. A full reorder should place items it was not sent after the ones it was.
§Server cache
For work worth skipping: a slow query, an outside API with a rate limit or a price. A read by id from your own database rarely is.
When the whole answer is the same for every visitor, cache the whole server function:
#[cache_shared(server = "5m")]
#[get("/api/trending?media_type", db: Db)]
pub async fn get_trending(media_type: Option<MediaType>) -> Result<Vec<Media>> { .. }Otherwise, cache the expensive part in a ServerCache static, with the
user’s id in the key when the answer depends on the user:
static DESCRIPTIONS: ServerCache<String, Option<Description>> =
ServerCache::new(Duration::from_secs(60 * 60), 10_000);Server caches only expire. Anything a user can change and then expects
to see changed should not be cached there; see server.
§CDN cache
For public GET answers read by many visitors. cache_shared(cdn = ..)
marks a function’s successful responses public; cdn_cache_guard
keeps everything else private and strips session cookies from what is
shared. Only standard Cache-Control headers are used, so any CDN works
(Cloudflare, CloudFront, Fastly, Vercel, a reverse proxy); most need a
rule making API paths eligible. See cdn for each provider.
§What is checked for you, and what is not
| Mistake | Caught |
|---|---|
| Passing a closure where a server function is expected | Panics on first use, with the fix |
#[cache_shared] on a function that binds a session, auth, user or cookie extractor | Compile error |
#[cache_shared] on a function whose body reads FullstackContext | Compile error |
#[cache_shared] on a POST, PUT, PATCH, DELETE or #[server] | Compile error |
#[cache_shared] placed below #[get], or with a malformed duration | Compile error |
#[cache_shared] in a server build without g3-cache/server | Warning naming the fix; runs uncached |
| A shared response carrying a session cookie | Removed at runtime by cdn_cache_guard |
| An error response being cached at the CDN or on the server | Never cached |
| Persisting data before knowing whose it is | Memory only until set_cache_owner |
| A shared function reading the viewer some other way (a global, a header, a query using the session) | Not caught. Only share functions whose answer comes from their arguments |
A mutation that forgets to invalidate_cached a read it changed | Not caught. The read stays stale until the screen reopens or the app regains focus |
A per-user answer in a ServerCache without the user in the key | Not caught. Put the user’s id in K |
| Toggle-style mutations acting on stale state | Not caught. Prefer “set to” mutations |
| Missing CDN rule | Not caught. Nothing is cached at the CDN; harmless |
§Features
web: the persistent store is IndexedDB.mobile: the persistent store is a redb file in the OS cache directory.desktop: the same redb store, in the user’s cache directory.server:ServerCache,cdn_cache_guardand theserverandcdnmodules. Turns the client cache off: one server process renders for every visitor, so nothing per-user may be kept there.
With none of web, mobile or desktop, the client cache works in
memory only.
Re-exports§
pub use cdn::cdn_cache_guard;pub use server::ServerCache;
Modules§
- cdn
- CDN caching: whole responses kept by a shared HTTP cache (Cloudflare, CloudFront, Fastly, a reverse proxy) and served to every visitor without reaching the server. See the crate docs for when to use it.
- server
- In-process server caches: answers kept in the server’s memory and shared by every request. See the crate docs for when to use one.
Structs§
- Cache
Config - Settings for the client cache, given once to
use_client_cache. - Cache
Key - Names one cached read: a
namefor what is read, plus the arguments its answer depends on. - Cache
Options - Per-read settings for
use_cached_withanduse_cached_key_with. - Cached
- A cached read’s current answer, returned by
use_cached.Copy, like a signal.
Traits§
- Cacheable
Fn - A server function (or any
async fnreturningdioxus::Result) that can be passed by name touse_cachedandinvalidate_cached.
Functions§
- invalidate_
all_ cached - Refetches every cached read. Always correct after a mutation, but every
mounted screen refetches everything it shows; prefer
invalidate_cachedfor the reads the mutation changes. - invalidate_
cached - Refetches every cached call of
server_fn, whatever its arguments. - invalidate_
cached_ call - Refetches one cached call:
server_fnwith exactly theseargs. - invalidate_
cached_ key - Refetches the read cached under exactly
key. - invalidate_
cached_ name - Refetches every read cached under a
CacheKeynamedname, whatever its arguments. - set_
cache_ owner - Tells the cache whose data it holds: the signed-in user’s id, or
Nonewhen signed out. Call it whenever the signed-in user is known or changes, including on sign-out. - update_
all_ cached update_cachedfor every cached call ofserver_fn, whatever its arguments: a video marked watched in every cached page of a feed, say. Returns how many answers were edited.- update_
cached - Edits the cached answer of one call,
server_fnwith exactly theseargs, in place, so a change shows at once rather than after the mutation’s round trip. Returns whether there was an answer to edit. - update_
cached_ key update_cachedfor a read cached under aCacheKeyyou named.- use_
cached - Reads a server function through the client cache. This is the hook to use for data a screen shows when it opens.
- use_
cached_ key - Reads through the client cache under a key you name. Use it for a read
that is not one server function call: several calls combined, or data
from somewhere else. Prefer
use_cachedotherwise. - use_
cached_ key_ with use_cached_keywith per-readCacheOptions.- use_
cached_ with use_cachedwith per-readCacheOptions.- use_
client_ cache - Sets up the client cache. Call once, at the top of the app’s root component, before any cached read.
Attribute Macros§
- cache_
shared - Caches a server function whose answer is the same for every visitor: at the CDN, on the server, or both.