Skip to main content

g3_cache/
cdn.rs

1//! CDN caching: whole responses kept by a shared HTTP cache (Cloudflare,
2//! CloudFront, Fastly, a reverse proxy) and served to every visitor without
3//! reaching the server. See the [crate docs](crate#cdn-cache) for when to
4//! use it.
5//!
6//! Two layers:
7//!
8//! - [`cdn_cache_for`] marks one server function's successful responses
9//!   `public`. Put it on with [`cache_shared`](crate::cache_shared)`(cdn = 300)`,
10//!   which also checks the function is safe to share, rather than with
11//!   `#[middleware(..)]` directly.
12//! - [`cdn_cache_guard`] goes on the whole router, once. It keeps a session cookie
13//!   out of every shared response, and marks every other API response
14//!   `private`, so nothing is shared by accident.
15//!
16//! ```ignore
17//! let router = dioxus::server::router(App)
18//!     .layer(session_layer)
19//!     // Outside the session layer, so it sees the cookie that layer adds.
20//!     .layer(g3_cache::cdn_cache_guard("/api"));
21//! ```
22//!
23//! # Providers
24//!
25//! Only standard `Cache-Control` directives are sent (`public`, `private`,
26//! `no-cache`, `max-age`, `s-maxage`), so any CDN or shared cache that
27//! follows HTTP caching works. Providers differ in whether they cache API
28//! responses at all without being told to:
29//!
30//! | Provider | Honors `s-maxage` | Also needed |
31//! |---|---|---|
32//! | Cloudflare | Yes | A Cache Rule making the API paths "Eligible for cache"; by default it caches only static file extensions |
33//! | CloudFront | Yes | A cache policy whose TTL range allows it, with the query string in the cache key |
34//! | Fastly | Yes | Nothing (`Surrogate-Control` takes precedence when present) |
35//! | Vercel, Netlify | Yes | Nothing |
36//! | nginx, Varnish | Yes | Caching turned on for the API location |
37//!
38//! Without that setup nothing is cached at the CDN, which is safe: the
39//! responses are still correct, just not shared.
40//!
41//! Nothing clears a CDN cache when data changes; entries only expire. Each
42//! provider has its own purge API, and this crate calls none of them. A
43//! client [`invalidate_cached`](crate::invalidate_cached) refetches
44//! *through* the CDN and may get the same answer back until it expires.
45
46use axum::http::{
47    HeaderMap, HeaderValue, Method, Request, Response, StatusCode,
48    header::{CACHE_CONTROL, SET_COOKIE},
49};
50use std::{
51    future::Future,
52    pin::Pin,
53    task::{Context, Poll},
54};
55use tower_layer::Layer;
56use tower_service::Service;
57
58/// How long a browser keeps a shared response, unless set with
59/// [`CdnCacheFor::browser`]: one minute, so a browser tab rechecks sooner
60/// than the CDN does.
61const DEFAULT_BROWSER_SECS: u32 = 60;
62
63/// Marks a server function's successful `GET` responses as the same for
64/// every visitor: `Cache-Control: public, max-age=60, s-maxage=<cdn_secs>`.
65///
66/// - Only `2xx` responses are marked, so an error is never cached.
67/// - Only `GET` and `HEAD` requests are marked; a CDN never caches others.
68/// - The browser keeps its copy for at most a minute
69///   ([`browser`](CdnCacheFor::browser) to change).
70///
71/// Prefer [`cache_shared`](crate::cache_shared)`(cdn = ..)`, which adds this layer and
72/// refuses functions that read the session or are not `GET`.
73pub fn cdn_cache_for(cdn_secs: u32) -> CdnCacheFor {
74    CdnCacheFor {
75        cdn_secs,
76        browser_secs: DEFAULT_BROWSER_SECS.min(cdn_secs),
77    }
78}
79
80/// The layer [`cdn_cache_for`] returns.
81#[derive(Clone, Copy, Debug)]
82pub struct CdnCacheFor {
83    cdn_secs: u32,
84    browser_secs: u32,
85}
86
87impl CdnCacheFor {
88    /// How long a browser keeps its copy (`max-age`). Capped at the CDN
89    /// lifetime.
90    pub fn browser(mut self, secs: u32) -> Self {
91        self.browser_secs = secs.min(self.cdn_secs);
92        self
93    }
94
95    fn header(&self) -> HeaderValue {
96        let value = format!(
97            "public, max-age={}, s-maxage={}",
98            self.browser_secs, self.cdn_secs
99        );
100        HeaderValue::from_str(&value).expect("digits and ASCII are a valid header value")
101    }
102}
103
104impl<S> Layer<S> for CdnCacheFor {
105    type Service = CdnCacheForService<S>;
106
107    fn layer(&self, inner: S) -> Self::Service {
108        CdnCacheForService {
109            inner,
110            policy: *self,
111        }
112    }
113}
114
115/// The service [`CdnCacheFor`] wraps around a route.
116#[derive(Clone, Debug)]
117pub struct CdnCacheForService<S> {
118    inner: S,
119    policy: CdnCacheFor,
120}
121
122type BoxFuture<T> = Pin<Box<dyn Future<Output = T> + Send>>;
123
124impl<S, B, ResBody> Service<Request<B>> for CdnCacheForService<S>
125where
126    S: Service<Request<B>, Response = Response<ResBody>>,
127    S::Future: Send + 'static,
128{
129    type Response = Response<ResBody>;
130    type Error = S::Error;
131    type Future = BoxFuture<Result<Self::Response, Self::Error>>;
132
133    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
134        self.inner.poll_ready(cx)
135    }
136
137    fn call(&mut self, request: Request<B>) -> Self::Future {
138        let cacheable = matches!(*request.method(), Method::GET | Method::HEAD);
139        let policy = self.policy;
140        let response = self.inner.call(request);
141        Box::pin(async move {
142            let mut response = response.await?;
143            mark_shared(policy, cacheable, response.status(), response.headers_mut());
144            Ok(response)
145        })
146    }
147}
148
149fn mark_shared(policy: CdnCacheFor, cacheable: bool, status: StatusCode, headers: &mut HeaderMap) {
150    if cacheable && status.is_success() {
151        headers.insert(CACHE_CONTROL, policy.header());
152    }
153}
154
155/// The router-wide safety layer for CDN caching. Add it once, outside the
156/// session layer, whether or not any function is shared yet:
157///
158/// - A response marked `public` loses any `Set-Cookie`. The session layer
159///   can attach a cookie to any response, and a cached copy carrying one
160///   would hand that visitor's session to everyone who gets the copy.
161/// - A response to a path under `api_prefix` with no `Cache-Control` gets
162///   `private, no-cache`, so no browser or CDN reuses per-user data, and a
163///   client refetch after [`invalidate_cached`](crate::invalidate_cached) always reaches
164///   the server. Pages and static assets, outside the prefix, keep
165///   whatever headers they had.
166pub fn cdn_cache_guard(api_prefix: &'static str) -> CdnCacheGuard {
167    CdnCacheGuard { api_prefix }
168}
169
170/// The layer [`cdn_cache_guard`] returns.
171#[derive(Clone, Copy, Debug)]
172pub struct CdnCacheGuard {
173    api_prefix: &'static str,
174}
175
176impl<S> Layer<S> for CdnCacheGuard {
177    type Service = CdnCacheGuardService<S>;
178
179    fn layer(&self, inner: S) -> Self::Service {
180        CdnCacheGuardService {
181            inner,
182            api_prefix: self.api_prefix,
183        }
184    }
185}
186
187/// The service [`CdnCacheGuard`] wraps around a router.
188#[derive(Clone, Debug)]
189pub struct CdnCacheGuardService<S> {
190    inner: S,
191    api_prefix: &'static str,
192}
193
194impl<S, B, ResBody> Service<Request<B>> for CdnCacheGuardService<S>
195where
196    S: Service<Request<B>, Response = Response<ResBody>>,
197    S::Future: Send + 'static,
198{
199    type Response = Response<ResBody>;
200    type Error = S::Error;
201    type Future = BoxFuture<Result<Self::Response, Self::Error>>;
202
203    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
204        self.inner.poll_ready(cx)
205    }
206
207    fn call(&mut self, request: Request<B>) -> Self::Future {
208        let api = under_prefix(request.uri().path(), self.api_prefix);
209        let response = self.inner.call(request);
210        Box::pin(async move {
211            let mut response = response.await?;
212            apply_guard(api, response.headers_mut());
213            Ok(response)
214        })
215    }
216}
217
218fn under_prefix(path: &str, prefix: &str) -> bool {
219    path.strip_prefix(prefix.trim_end_matches('/'))
220        .is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
221}
222
223fn is_shared(headers: &HeaderMap) -> bool {
224    headers
225        .get_all(CACHE_CONTROL)
226        .iter()
227        .filter_map(|value| value.to_str().ok())
228        .flat_map(|value| value.split(','))
229        .any(|part| part.trim().eq_ignore_ascii_case("public"))
230}
231
232fn apply_guard(api: bool, headers: &mut HeaderMap) {
233    if is_shared(headers) {
234        headers.remove(SET_COOKIE);
235    } else if api && !headers.contains_key(CACHE_CONTROL) {
236        headers.insert(CACHE_CONTROL, HeaderValue::from_static("private, no-cache"));
237    }
238}
239
240#[cfg(test)]
241mod tests {
242    use super::*;
243
244    fn with_cookie(cache_control: Option<&'static str>) -> HeaderMap {
245        let mut headers = HeaderMap::new();
246        headers.insert(SET_COOKIE, HeaderValue::from_static("session=abc"));
247        if let Some(value) = cache_control {
248            headers.insert(CACHE_CONTROL, HeaderValue::from_static(value));
249        }
250        headers
251    }
252
253    #[test]
254    fn shared_responses_never_carry_a_cookie() {
255        let mut headers = with_cookie(Some("public, max-age=60, s-maxage=300"));
256        apply_guard(true, &mut headers);
257        assert!(headers.get(SET_COOKIE).is_none());
258    }
259
260    #[test]
261    fn other_api_responses_are_private_and_keep_their_cookie() {
262        let mut headers = with_cookie(None);
263        apply_guard(true, &mut headers);
264        assert!(headers.get(SET_COOKIE).is_some());
265        assert_eq!(headers[CACHE_CONTROL], "private, no-cache");
266
267        let mut explicit = with_cookie(Some("no-store"));
268        apply_guard(true, &mut explicit);
269        assert_eq!(explicit[CACHE_CONTROL], "no-store");
270    }
271
272    #[test]
273    fn pages_and_assets_keep_their_headers() {
274        let mut headers = with_cookie(None);
275        apply_guard(false, &mut headers);
276        assert!(headers.get(CACHE_CONTROL).is_none());
277    }
278
279    #[test]
280    fn prefixes_match_whole_segments() {
281        assert!(under_prefix("/api/v1/trending", "/api"));
282        assert!(under_prefix("/api", "/api/"));
283        assert!(!under_prefix("/apiary", "/api"));
284        assert!(!under_prefix("/assets/app.js", "/api"));
285    }
286
287    #[test]
288    fn only_successful_gets_are_marked() {
289        let policy = cdn_cache_for(300);
290        let mut ok = HeaderMap::new();
291        mark_shared(policy, true, StatusCode::OK, &mut ok);
292        assert_eq!(ok[CACHE_CONTROL], "public, max-age=60, s-maxage=300");
293
294        let mut error = HeaderMap::new();
295        mark_shared(policy, true, StatusCode::INTERNAL_SERVER_ERROR, &mut error);
296        assert!(error.get(CACHE_CONTROL).is_none());
297
298        let mut post = HeaderMap::new();
299        mark_shared(policy, false, StatusCode::OK, &mut post);
300        assert!(post.get(CACHE_CONTROL).is_none());
301    }
302
303    #[test]
304    fn the_browser_never_keeps_a_copy_longer_than_the_cdn() {
305        assert_eq!(
306            cdn_cache_for(30).header(),
307            "public, max-age=30, s-maxage=30"
308        );
309        assert_eq!(
310            cdn_cache_for(300).browser(600).header(),
311            "public, max-age=300, s-maxage=300"
312        );
313    }
314}