Skip to main content

Crate g3_cache

Crate g3_cache 

Source
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.

ClientServerCDN
ForShowing the last known data at once, then refreshing itNot repeating slow or rate-limited workAnswering identical public requests without reaching the server
HoldsOne user’s data, on one deviceAnswers shared by every request, in one server processWhole HTTP responses shared by every visitor
Refreshed byScreen opens, invalidate_cached, app focusExpiry onlyExpiry only
APIuse_cachedcache_shared(server = ..), ServerCachecache_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 off

Then, 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 than toggle_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

MistakeCaught
Passing a closure where a server function is expectedPanics on first use, with the fix
#[cache_shared] on a function that binds a session, auth, user or cookie extractorCompile error
#[cache_shared] on a function whose body reads FullstackContextCompile error
#[cache_shared] on a POST, PUT, PATCH, DELETE or #[server]Compile error
#[cache_shared] placed below #[get], or with a malformed durationCompile error
#[cache_shared] in a server build without g3-cache/serverWarning naming the fix; runs uncached
A shared response carrying a session cookieRemoved at runtime by cdn_cache_guard
An error response being cached at the CDN or on the serverNever cached
Persisting data before knowing whose it isMemory 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 changedNot 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 keyNot caught. Put the user’s id in K
Toggle-style mutations acting on stale stateNot caught. Prefer “set to” mutations
Missing CDN ruleNot 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_guard and the server and cdn modules. 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§

CacheConfig
Settings for the client cache, given once to use_client_cache.
CacheKey
Names one cached read: a name for what is read, plus the arguments its answer depends on.
CacheOptions
Per-read settings for use_cached_with and use_cached_key_with.
Cached
A cached read’s current answer, returned by use_cached. Copy, like a signal.

Traits§

CacheableFn
A server function (or any async fn returning dioxus::Result) that can be passed by name to use_cached and invalidate_cached.

Functions§

invalidate_all_cached
Refetches every cached read. Always correct after a mutation, but every mounted screen refetches everything it shows; prefer invalidate_cached for 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_fn with exactly these args.
invalidate_cached_key
Refetches the read cached under exactly key.
invalidate_cached_name
Refetches every read cached under a CacheKey named name, whatever its arguments.
set_cache_owner
Tells the cache whose data it holds: the signed-in user’s id, or None when signed out. Call it whenever the signed-in user is known or changes, including on sign-out.
update_all_cached
update_cached for every cached call of server_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_fn with exactly these args, 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_cached for a read cached under a CacheKey you 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_cached otherwise.
use_cached_key_with
use_cached_key with per-read CacheOptions.
use_cached_with
use_cached with per-read CacheOptions.
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.