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