Skip to main content

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}