g3-cache 0.2.1

Client, server and CDN caching for Dioxus fullstack apps, with guards against caching the wrong thing.
Documentation

g3-cache

CI Crates.io docs.rs License

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

[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

Usage

use g3_cache::{cache_shared, invalidate_cached, update_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);

// Or show it at once, and let the invalidation reconcile it.
update_cached(get_my_rating, (id.clone(),), |rating| *rating = Some(score));
let saved = 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>> { .. }

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: ServerCache<String, Option<Description>> =
    ServerCache::new(Duration::from_secs(60 * 60), 10_000);

DESCRIPTIONS.get_or_fetch(media_id, google_description(&media)).await

In the app:

use g3_cache::{CacheConfig, set_cache_owner, use_client_cache};

fn App() -> Element {
    // Once, first thing in the root component.
    use_client_cache(CacheConfig::new("my-app"));
    // Whenever the signed-in user is known or changes, and on sign-out:
    // spawn(set_cache_owner(user_id));
    // ...
}
// Server router: once, outside the session layer.
.layer(session_layer)
.layer(g3_cache::cdn_cache_guard("/api"))

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.