g3_cache/lib.rs
1//! Caching for Dioxus fullstack apps: on the device, on the server, and at
2//! the CDN, with checks against caching the wrong thing in the wrong place.
3//!
4//! ```ignore
5//! use g3_cache::{cache_shared, invalidate_cached, use_cached};
6//!
7//! // A screen: show the last known answer at once, refetch in the background.
8//! let media = use_cached(get_media, (id.clone(),));
9//!
10//! // After a mutation: refetch what it changed.
11//! save_rating(id.clone(), score).await?;
12//! invalidate_cached(get_my_rating);
13//!
14//! // A public read: cached at the CDN and on the server for 5 minutes.
15//! #[cache_shared(cdn = 300, server = "5m")]
16//! #[get("/api/trending?media_type", db: Db)]
17//! pub async fn get_trending(media_type: Option<MediaType>) -> Result<Vec<Media>> { .. }
18//! ```
19//!
20//! Every name says it is about caching, so the crate reads well through a
21//! `use` statement.
22//!
23//! # Choosing a cache
24//!
25//! A read can be cached in three places. Each answers a different problem,
26//! and none replaces another.
27//!
28//! | | [Client](#client-cache) | [Server](#server-cache) | [CDN](#cdn-cache) |
29//! |---|---|---|---|
30//! | **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 |
31//! | **Holds** | One user's data, on one device | Answers shared by every request, in one server process | Whole HTTP responses shared by every visitor |
32//! | **Refreshed by** | Screen opens, [`invalidate_cached`], app focus | Expiry only | Expiry only |
33//! | **API** | [`use_cached`] | [`cache_shared`]`(server = ..)`, `ServerCache` | [`cache_shared`]`(cdn = ..)`, `cdn_cache_guard` |
34//!
35//! **The rule:** data that depends on who is asking (their ratings, their
36//! lists) is cached on the client only. Data that is the same for everyone
37//! (trending titles, a catalog) may also be cached on the server and at the
38//! CDN.
39//!
40//! A read passes through them in order: client memory and store, then the
41//! browser's HTTP cache and the CDN, then the server, whose own cache may
42//! answer instead of the database or an outside API.
43//!
44//! # Setup
45//!
46//! Enable the feature matching each build:
47//!
48//! ```toml
49//! [dependencies]
50//! g3-cache = "0.1"
51//!
52//! [features]
53//! web = ["dioxus/web", "g3-cache/web"] # IndexedDB store
54//! mobile = ["dioxus/mobile", "g3-cache/mobile"] # redb file store
55//! server = ["dioxus/server", "g3-cache/server"] # server + CDN caches; client cache off
56//! ```
57//!
58//! Then, in the app:
59//!
60//! ```ignore
61//! use g3_cache::{CacheConfig, set_cache_owner, use_client_cache};
62//!
63//! fn App() -> Element {
64//! // 1. Once, first thing in the root component.
65//! use_client_cache(CacheConfig::new("my-app"));
66//!
67//! // 2. Whenever the signed-in user is known or changes, and on sign-out.
68//! let user = use_server_future(get_current_user)?;
69//! use_effect(move || {
70//! let owner = user().and_then(|user| user.ok()).flatten().map(|user| user.id);
71//! spawn(set_cache_owner(owner));
72//! });
73//! // ...
74//! }
75//! ```
76//!
77//! And on the server router, once, outside the session layer:
78//!
79//! ```ignore
80//! .layer(session_layer)
81//! .layer(g3_cache::cdn_cache_guard("/api"))
82//! ```
83//!
84//! # Client cache
85//!
86//! Use [`use_cached`] in place of `use_resource` for data a screen shows
87//! when it opens:
88//!
89//! ```ignore
90//! let media = use_cached(get_media, (id.clone(),));
91//! ```
92//!
93//! The screen shows what the device last saw (from memory, or from disk on
94//! a cold start) and refetches in the background; the fresh answer replaces
95//! it. After a mutation, [`invalidate_cached`] each read it changed:
96//!
97//! ```ignore
98//! save_rating(id.clone(), score).await?;
99//! invalidate_cached(get_my_rating);
100//! invalidate_cached(get_my_ratings);
101//! ```
102//!
103//! Don't use it for reads that change with every keystroke (use
104//! `use_resource`), or in a handler that must act on current server state
105//! (call the server function directly).
106//!
107//! ## Several devices
108//!
109//! The server is the only source of truth: mutations go straight to it, and
110//! nothing is written offline, so devices never need merging. The question
111//! is only how long a device shows what it saw last:
112//!
113//! - **A screen that opens** shows its old copy and refetches at once.
114//! - **A screen that stayed open** refetches when the app comes back into
115//! view ([`CacheConfig::revalidate_on_focus`], on by default).
116//! - **A tap on stale data** is still sent. Write mutations so that is
117//! harmless: `set_in_list(list, item, true)` rather than
118//! `toggle_in_list(list, item)`, which undoes the other device's change
119//! when this one shows old state. A full reorder should place items it
120//! was not sent after the ones it was.
121//!
122//! # Server cache
123//!
124//! For work worth skipping: a slow query, an outside API with a rate limit
125//! or a price. A read by id from your own database rarely is.
126//!
127//! When the whole answer is the same for every visitor, cache the whole
128//! server function:
129//!
130//! ```ignore
131//! #[cache_shared(server = "5m")]
132//! #[get("/api/trending?media_type", db: Db)]
133//! pub async fn get_trending(media_type: Option<MediaType>) -> Result<Vec<Media>> { .. }
134//! ```
135//!
136//! Otherwise, cache the expensive part in a `ServerCache` static, with the
137//! user's id in the key when the answer depends on the user:
138//!
139//! ```ignore
140//! static DESCRIPTIONS: ServerCache<String, Option<Description>> =
141//! ServerCache::new(Duration::from_secs(60 * 60), 10_000);
142//! ```
143//!
144//! Server caches only expire. Anything a user can change and then expects
145//! to see changed should not be cached there; see `server`.
146//!
147//! # CDN cache
148//!
149//! For public `GET` answers read by many visitors. [`cache_shared`]`(cdn = ..)`
150//! marks a function's successful responses `public`; `cdn_cache_guard`
151//! keeps everything else private and strips session cookies from what is
152//! shared. Only standard `Cache-Control` headers are used, so any CDN works
153//! (Cloudflare, CloudFront, Fastly, Vercel, a reverse proxy); most need a
154//! rule making API paths eligible. See `cdn` for each provider.
155//!
156//! # What is checked for you, and what is not
157//!
158//! | Mistake | Caught |
159//! |---|---|
160//! | Passing a closure where a server function is expected | Panics on first use, with the fix |
161//! | `#[cache_shared]` on a function that binds a session, auth, user or cookie extractor | Compile error |
162//! | `#[cache_shared]` on a function whose body reads `FullstackContext` | Compile error |
163//! | `#[cache_shared]` on a `POST`, `PUT`, `PATCH`, `DELETE` or `#[server]` | Compile error |
164//! | `#[cache_shared]` placed below `#[get]`, or with a malformed duration | Compile error |
165//! | `#[cache_shared]` in a server build without `g3-cache/server` | Warning naming the fix; runs uncached |
166//! | A shared response carrying a session cookie | Removed at runtime by `cdn_cache_guard` |
167//! | An error response being cached at the CDN or on the server | Never cached |
168//! | Persisting data before knowing whose it is | Memory only until [`set_cache_owner`] |
169//! | 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 |
170//! | 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 |
171//! | A per-user answer in a `ServerCache` without the user in the key | **Not caught.** Put the user's id in `K` |
172//! | Toggle-style mutations acting on stale state | **Not caught.** Prefer "set to" mutations |
173//! | Missing CDN rule | **Not caught.** Nothing is cached at the CDN; harmless |
174//!
175//! # Features
176//!
177//! - `web`: the persistent store is IndexedDB.
178//! - `mobile`: the persistent store is a redb file in the OS cache directory.
179//! - `server`: `ServerCache`, `cdn_cache_guard` and the `server` and `cdn`
180//! modules. Turns the client cache off: one server process renders for
181//! every visitor, so nothing per-user may be kept there.
182//!
183//! With neither `web` nor `mobile`, the client cache works in memory only.
184
185#![warn(missing_docs)]
186
187mod client;
188mod key;
189
190#[cfg(feature = "server")]
191pub mod cdn;
192#[cfg(feature = "server")]
193pub mod server;
194
195#[cfg(feature = "server")]
196pub use cdn::cdn_cache_guard;
197#[cfg(feature = "server")]
198pub use server::ServerCache;
199
200pub use client::{
201 CacheConfig, CacheOptions, Cached, invalidate_all_cached, invalidate_cached,
202 invalidate_cached_call, invalidate_cached_key, invalidate_cached_name, set_cache_owner,
203 use_cached, use_cached_key, use_cached_key_with, use_cached_with, use_client_cache,
204};
205pub use g3_cache_macros::cache_shared;
206pub use key::{CacheKey, CacheableFn};
207
208/// Support for the code [`cache_shared`] generates. Not public API.
209#[doc(hidden)]
210pub mod __private {
211 #[cfg(feature = "server")]
212 pub use crate::cdn::cdn_cache_for;
213 #[cfg(feature = "server")]
214 pub use crate::server::__private::*;
215
216 // Stand-ins for a server build that forgot `g3-cache/server`: the
217 // function then runs uncached, with a warning that says how to fix it,
218 // instead of failing on a path that doesn't exist.
219
220 #[cfg(not(feature = "server"))]
221 #[deprecated(
222 note = "`#[cache_shared(cdn = ..)]` is not caching: add `g3-cache/server` to your app's `server` feature"
223 )]
224 pub fn cdn_cache_for(_cdn_secs: u32) -> tower_layer::Identity {
225 tower_layer::Identity::new()
226 }
227
228 #[cfg(not(feature = "server"))]
229 pub struct SharedCache<T>(std::marker::PhantomData<fn() -> T>);
230
231 #[cfg(not(feature = "server"))]
232 impl<T> SharedCache<T> {
233 #[deprecated(
234 note = "`#[cache_shared(server = ..)]` is not caching: add `g3-cache/server` to your app's `server` feature"
235 )]
236 pub const fn new(_ttl: std::time::Duration, _capacity: u64) -> Self {
237 Self(std::marker::PhantomData)
238 }
239
240 pub async fn get_or_fetch<E, Fut>(&self, _key: String, fetch: Fut) -> Result<T, E>
241 where
242 Fut: std::future::Future<Output = Result<T, E>>,
243 {
244 fetch.await
245 }
246 }
247
248 #[cfg(not(feature = "server"))]
249 pub fn args_key<A>(_args: &A) -> String {
250 String::new()
251 }
252}