rustango_cms/cache_invalidate.rs
1//! Targeted page-cache invalidation hook.
2//!
3//! The public router (see [`crate::router()`]) layers
4//! [`rustango::cache_page::CachePageLayer`] in front of CMS page
5//! responses; that layer is TTL-based and emits the response under
6//! a key derived from `(method, path, host, vary-on)`. After an
7//! admin save the public response is stale until the TTL elapses.
8//!
9//! This module defines a [`PageCacheInvalidator`] trait that the
10//! host app can register on the admin state (`crate::admin::AdminState`). When
11//! present, every admin handler that mutates a page URL fires the
12//! invalidator on the affected URLs. Hosts that don't register one
13//! keep the old TTL-only behavior — the trait is purely opt-in.
14//!
15//! Two built-in invalidators ship:
16//!
17//! - [`BoxedCacheInvalidator`] — calls [`Cache::delete`](rustango::cache::Cache::delete)
18//! on the same key shape `CachePageLayer` writes. Use when the
19//! admin handler holds an `Arc<BoxedCache>` to the same cache the
20//! public layer is using.
21//! - [`Noop`] — does nothing. Returned from `default()` so the
22//! trait object can be unconditionally invoked from handler code
23//! without `Option` plumbing.
24//!
25//! ## Key shape
26//!
27//! Mirrors the private `compute_cache_key` in `rustango::cache_page`:
28//!
29//! ```text
30//! <prefix>|<method-len>:<method>|<path-len>:<path>|<query-len>:<query>|<host-len>:<host>|...vary_on...
31//! ```
32//!
33//! For v0 we only target the unadorned GET path: query = "", no
34//! `vary_on` headers. Hosts that configure their public layer with
35//! `vary_on(...)` would need to invalidate every header
36//! combination — declare those upfront via
37//! [`BoxedCacheInvalidator::with_vary_values`].
38
39use std::sync::Arc;
40
41use async_trait::async_trait;
42use rustango::cache::BoxedCache;
43
44/// Hook called by admin handlers after a page-content mutation.
45/// Implementations should fan out to whatever cache backend the
46/// public router uses (in-memory `CachePageLayer`, Cloudflare,
47/// Varnish, …) and drop the keys identified by the URL list.
48///
49/// Failures are intentionally swallowed by the handler (cache
50/// invalidation is best-effort; a stale render is worse than a
51/// failed save). Implementations should log internally.
52#[async_trait]
53pub trait PageCacheInvalidator: Send + Sync + 'static {
54 /// Drop the cache entry for the public render of `url_path` on
55 /// the given tenant. Hosts pass the unprefixed page URL —
56 /// the implementation appends the configured URL prefix +
57 /// host(s) before computing the cache key.
58 async fn invalidate_url(&self, tenant_slug: &str, url_path: &str);
59
60 /// Drop every cache entry whose URL starts with `url_path` /
61 /// (the page itself + every descendant). Called after a slug
62 /// rename, a move, or a subtree delete.
63 async fn invalidate_subtree(&self, tenant_slug: &str, url_path: &str) {
64 // Default: fan out by enumerating the explicit URL list at
65 // the call site. Implementations that can do efficient
66 // prefix purges (Cloudflare wildcard purge, Redis SCAN +
67 // DEL on the key pattern) should override.
68 self.invalidate_url(tenant_slug, url_path).await;
69 }
70
71 /// Drop the cache entries for many page URLs at once. The
72 /// default loops over [`Self::invalidate_url`] — preserving the
73 /// per-URL behavior — but backends with a bulk-purge API
74 /// (Cloudflare `files`, Azure CDN `contentPaths`) should override
75 /// this to issue a single request instead of N. The purge fan-out
76 /// in [`crate::task_queue::purge_urls`] calls this so a batch
77 /// backend collapses a multi-URL save into one round-trip.
78 async fn invalidate_urls(&self, tenant_slug: &str, url_paths: &[String]) {
79 for url in url_paths {
80 self.invalidate_url(tenant_slug, url).await;
81 }
82 }
83}
84
85/// Supplies the OAuth2 bearer token for the cloud-CDN backends that
86/// authenticate against a Google / Azure management API.
87///
88/// Both APIs take a short-lived (~1h) access token. Production
89/// deployments should implement this against their environment's
90/// token endpoint — the GCE/GKE metadata server, a workload-identity
91/// exchange, or a refreshing `gcloud auth` / `az account` helper — so
92/// the token is renewed before it expires. `None` means "no token
93/// available right now"; the purge is then skipped (best-effort, per
94/// the [`PageCacheInvalidator`] contract).
95#[async_trait]
96pub trait AccessTokenSource: Send + Sync + 'static {
97 /// Return a fresh bearer token, or `None` to skip the purge.
98 async fn token(&self) -> Option<String>;
99}
100
101/// Fixed bearer token. Fine for one-shot scripts, short-lived jobs,
102/// and tests; **not** for a long-running server, where the token will
103/// expire (~1h) — implement [`AccessTokenSource`] against your token
104/// endpoint instead so it refreshes.
105#[derive(Debug, Clone)]
106pub struct StaticToken(pub String);
107
108#[async_trait]
109impl AccessTokenSource for StaticToken {
110 async fn token(&self) -> Option<String> {
111 Some(self.0.clone())
112 }
113}
114
115/// No-op invalidator returned from [`Arc<dyn PageCacheInvalidator>::default`].
116/// Lets handler code call `invalidator.invalidate_url(...).await`
117/// without `if let Some(...) = ...` plumbing when the host hasn't
118/// registered a real one.
119#[derive(Default, Debug, Clone, Copy)]
120pub struct Noop;
121
122#[async_trait]
123impl PageCacheInvalidator for Noop {
124 async fn invalidate_url(&self, _tenant_slug: &str, _url_path: &str) {}
125}
126
127/// Convenience constructor — returns an `Arc<dyn PageCacheInvalidator>`
128/// pointing at [`Noop`].
129#[must_use]
130pub fn noop() -> Arc<dyn PageCacheInvalidator> {
131 Arc::new(Noop)
132}
133
134/// Register an after-commit purge of `url_paths` for the enclosing
135/// [`rustango::sql::atomic`] block. The purge fires **only if
136/// the transaction commits** — on rollback the queued callback is
137/// dropped and nothing is evicted, so a failed save can never knock a
138/// still-valid entry out of the public cache.
139///
140/// `on_commit` callbacks are synchronous; the (async) purge is
141/// therefore driven on a detached `tokio::spawn` task, so the admin
142/// response isn't blocked on the purge round-trips.
143///
144/// Inside that task the purge goes through
145/// [`crate::task_queue::purge_urls`]: when a background queue is
146/// configured it dispatches a **retriable** `CachePurgeJob`; otherwise
147/// it purges **inline** in list order (the original behavior).
148///
149/// No-op (registers nothing) when `url_paths` is empty.
150///
151/// # Panics
152/// Panics if called outside an `atomic` scope — the callback would
153/// never fire. See [`rustango::sql::on_commit`].
154pub fn invalidate_urls_on_commit(
155 invalidator: Arc<dyn PageCacheInvalidator>,
156 tenant_slug: String,
157 url_paths: Vec<String>,
158) {
159 if url_paths.is_empty() {
160 return;
161 }
162 rustango::sql::on_commit(move || {
163 rustango::__private_runtime::tokio::spawn(async move {
164 crate::task_queue::purge_urls(invalidator, tenant_slug, url_paths).await;
165 });
166 });
167}
168
169/// Built-in invalidator that drops keys directly from a
170/// [`BoxedCache`]. Use when the host wires the same cache instance
171/// into both [`CachePageLayer`](rustango::cache_page::CachePageLayer) and the admin state. The key shape
172/// mirrors what [`rustango::cache_page`] writes.
173pub struct BoxedCacheInvalidator {
174 cache: BoxedCache,
175 /// Same value passed to `CachePageLayer::key_prefix(...)`.
176 key_prefix: String,
177 /// Tenant-slug → public Host header values that should be
178 /// invalidated. Most apps map each tenant to one host; some
179 /// (apex + subdomain) supply multiple. If a tenant slug isn't
180 /// in the map, the invalidator falls back to `default_hosts`.
181 hosts_by_tenant: std::collections::HashMap<String, Vec<String>>,
182 /// Fallback host list (used when a tenant isn't named in the
183 /// map). Useful for single-tenant deployments where every URL
184 /// lives under the same Host.
185 default_hosts: Vec<String>,
186 /// Vary-on header values to invalidate per combo. Empty means
187 /// the public layer didn't configure `vary_on(...)`.
188 vary_values: Vec<(String, String)>,
189}
190
191impl BoxedCacheInvalidator {
192 /// Build a new invalidator targeting `cache` with the public
193 /// router's `key_prefix`.
194 #[must_use]
195 pub fn new(cache: BoxedCache, key_prefix: impl Into<String>) -> Self {
196 Self {
197 cache,
198 key_prefix: key_prefix.into(),
199 hosts_by_tenant: std::collections::HashMap::new(),
200 default_hosts: Vec::new(),
201 vary_values: Vec::new(),
202 }
203 }
204
205 /// Map a tenant slug to one or more Host header values. Both
206 /// `acme.localhost` and `acme.localhost:8090` should be added
207 /// when the same site is reachable via both.
208 #[must_use]
209 pub fn with_tenant_hosts(
210 mut self,
211 tenant_slug: impl Into<String>,
212 hosts: impl IntoIterator<Item = String>,
213 ) -> Self {
214 self.hosts_by_tenant
215 .insert(tenant_slug.into(), hosts.into_iter().collect());
216 self
217 }
218
219 /// Fallback host list — used when a tenant slug isn't in the
220 /// per-tenant map. Set this in single-tenant deployments where
221 /// every CMS URL lives under the same Host.
222 #[must_use]
223 pub fn with_default_hosts(mut self, hosts: impl IntoIterator<Item = String>) -> Self {
224 self.default_hosts = hosts.into_iter().collect();
225 self
226 }
227
228 /// Mirror the public layer's `vary_on(...)` declarations. The
229 /// invalidator will purge the cross-product of (vary-name,
230 /// vary-value) for each URL.
231 #[must_use]
232 pub fn with_vary_values(mut self, pairs: impl IntoIterator<Item = (String, String)>) -> Self {
233 self.vary_values = pairs.into_iter().collect();
234 self
235 }
236
237 fn hosts_for(&self, tenant_slug: &str) -> &[String] {
238 self.hosts_by_tenant
239 .get(tenant_slug)
240 .map(Vec::as_slice)
241 .unwrap_or(&self.default_hosts)
242 }
243
244 fn compute_key(&self, path: &str, host: &str, tenant_slug: &str) -> String {
245 use std::fmt::Write as _;
246 let mut k = String::with_capacity(self.key_prefix.len() + 128);
247 let _ = write!(&mut k, "{}|", self.key_prefix);
248 write_lp(&mut k, "GET");
249 write_lp(&mut k, path);
250 write_lp(&mut k, "");
251 write_lp(&mut k, host);
252 // The layer keys every page on the resolved tenant after the host;
253 // without it no delete matches and pages wait out the TTL.
254 write_lp(&mut k, tenant_slug);
255 for (name, value) in &self.vary_values {
256 write_lp(&mut k, name);
257 write_lp(&mut k, value);
258 }
259 k
260 }
261}
262
263fn write_lp(buf: &mut String, s: &str) {
264 use std::fmt::Write as _;
265 let _ = write!(buf, "{}:{}|", s.len(), s);
266}
267
268#[cfg(test)]
269mod key_shape_tests {
270 use super::*;
271 use rustango::cache::NullCache;
272
273 fn fake_invalidator() -> BoxedCacheInvalidator {
274 BoxedCacheInvalidator::new(Arc::new(NullCache), "rcms:page")
275 }
276
277 /// Locks in the key shape so a framework-side change to
278 /// `compute_cache_key` becomes a hard test failure here.
279 /// The format mirrors `rustango::cache_page::compute_cache_key`:
280 /// `<prefix>|<method-len>:<method>|<path-len>:<path>|<query-len>:<query>|<host-len>:<host>|<tenant-len>:<tenant>|`
281 /// followed by any `vary_on` pairs. `tests/cache_purge_roundtrip.rs`
282 /// checks the same thing against the real layer.
283 #[test]
284 fn key_shape_matches_cache_page_layer() {
285 let inv = fake_invalidator();
286 let key = inv.compute_key("/about", "acme.localhost:8090", "acme");
287 assert_eq!(key, "rcms:page|3:GET|6:/about|0:|19:acme.localhost:8090|4:acme|");
288 }
289
290 #[test]
291 fn key_with_vary_values_appends_pairs() {
292 let inv = fake_invalidator()
293 .with_vary_values(vec![("accept-language".to_owned(), "en".to_owned())]);
294 let key = inv.compute_key("/about", "acme.localhost", "acme");
295 assert_eq!(
296 key,
297 "rcms:page|3:GET|6:/about|0:|14:acme.localhost|4:acme|15:accept-language|2:en|"
298 );
299 }
300}
301
302#[async_trait]
303impl PageCacheInvalidator for BoxedCacheInvalidator {
304 async fn invalidate_url(&self, tenant_slug: &str, url_path: &str) {
305 let hosts = self.hosts_for(tenant_slug);
306 if hosts.is_empty() {
307 tracing::debug!(
308 target: "rustango_cms::cache_invalidate",
309 tenant = %tenant_slug,
310 "no hosts configured — skipping cache invalidation"
311 );
312 return;
313 }
314 for host in hosts {
315 let key = self.compute_key(url_path, host, tenant_slug);
316 match self.cache.delete(&key).await {
317 Ok(()) => tracing::debug!(
318 target: "rustango_cms::cache_invalidate",
319 %key,
320 "purged"
321 ),
322 Err(e) => tracing::warn!(
323 target: "rustango_cms::cache_invalidate",
324 %key,
325 error = %e,
326 "cache delete failed (continuing — TTL will catch up)"
327 ),
328 }
329 }
330 }
331}
332
333#[cfg(test)]
334mod on_commit_tests {
335 use super::*;
336
337 #[test]
338 fn empty_url_list_is_a_noop_outside_atomic() {
339 // No URLs → returns before touching `on_commit`, so it must not
340 // panic even though we're not inside an `atomic` scope.
341 invalidate_urls_on_commit(noop(), "acme".to_owned(), vec![]);
342 }
343
344 #[test]
345 #[should_panic(expected = "on_commit")]
346 fn non_empty_outside_atomic_panics() {
347 // A non-empty list registers an `on_commit` callback, which the
348 // framework rejects outside an `atomic` scope — proof the helper
349 // is wired to the commit hook (and won't silently drop a purge).
350 invalidate_urls_on_commit(noop(), "acme".to_owned(), vec!["/about".to_owned()]);
351 }
352}
353
354// Behavioral commit/rollback coverage runs against a serverless
355// SQLite-in-memory pool, so it's gated on the `sqlite` feature:
356// cargo test --lib --no-default-features --features sqlite on_commit_db
357#[cfg(all(test, feature = "sqlite"))]
358mod on_commit_db_tests {
359 use super::*;
360 use rustango::sql::Pool;
361 use std::sync::Mutex;
362
363 /// Records every purged URL so the test can assert the after-commit
364 /// fan-out (and its absence on rollback).
365 struct Recorder(Arc<Mutex<Vec<String>>>);
366
367 #[async_trait]
368 impl PageCacheInvalidator for Recorder {
369 async fn invalidate_url(&self, _tenant_slug: &str, url_path: &str) {
370 self.0
371 .lock()
372 .expect("recorder mutex")
373 .push(url_path.to_owned());
374 }
375 }
376
377 async fn mem_pool() -> Pool {
378 Pool::connect("sqlite::memory:")
379 .await
380 .expect("sqlite in-memory pool")
381 }
382
383 /// The purge runs on a detached task; yield until it records at
384 /// least `n` URLs (bounded so a regression fails instead of hangs).
385 async fn wait_until(urls: &Arc<Mutex<Vec<String>>>, n: usize) -> Vec<String> {
386 for _ in 0..5000 {
387 {
388 let g = urls.lock().expect("recorder mutex");
389 if g.len() >= n {
390 return g.clone();
391 }
392 }
393 tokio::task::yield_now().await;
394 }
395 urls.lock().expect("recorder mutex").clone()
396 }
397
398 #[tokio::test]
399 async fn commit_fires_the_purge_in_order() {
400 let pool = mem_pool().await;
401 let urls = Arc::new(Mutex::new(Vec::new()));
402 let inv: Arc<dyn PageCacheInvalidator> = Arc::new(Recorder(urls.clone()));
403
404 rustango::atomic!(&pool, |_tx| {
405 invalidate_urls_on_commit(
406 inv.clone(),
407 "acme".to_owned(),
408 vec!["/about".to_owned(), "/news".to_owned()],
409 );
410 assert_eq!(rustango::sql::on_commit_pending(), 1, "one callback queued");
411 Ok::<(), rustango::sql::ExecError>(())
412 })
413 .await
414 .expect("atomic commit");
415
416 assert_eq!(
417 wait_until(&urls, 2).await,
418 vec!["/about".to_owned(), "/news".to_owned()]
419 );
420 }
421
422 #[tokio::test]
423 async fn rollback_drops_the_purge() {
424 let pool = mem_pool().await;
425 let urls = Arc::new(Mutex::new(Vec::new()));
426 let inv: Arc<dyn PageCacheInvalidator> = Arc::new(Recorder(urls.clone()));
427
428 let res = rustango::atomic!(&pool, |_tx| {
429 invalidate_urls_on_commit(inv.clone(), "acme".to_owned(), vec!["/about".to_owned()]);
430 assert_eq!(
431 rustango::sql::on_commit_pending(),
432 1,
433 "callback queued pre-rollback"
434 );
435 Err::<(), rustango::sql::ExecError>(rustango::sql::ExecError::EmptyReturning)
436 })
437 .await;
438 assert!(res.is_err(), "atomic should roll back");
439
440 // Give any (erroneously) spawned task room to run, then assert
441 // nothing was purged — the callback must have been dropped.
442 for _ in 0..50 {
443 tokio::task::yield_now().await;
444 }
445 assert!(
446 urls.lock().expect("recorder mutex").is_empty(),
447 "rollback must not purge"
448 );
449 }
450}