Skip to main content

rustango/
cache_fragment.rs

1//! Fragment caching: cache one rendered piece of a page.
2//!
3//! Tera has no custom block tags, only filters and functions, so a
4//! lazy `{% cache 500 sidebar %}…{% endcache %}` block is not
5//! possible. Instead, cache the fragment in your handler with
6//! [`cached_render`] and pass the string into the template.
7//!
8//! ```ignore
9//! use std::time::Duration;
10//! use rustango::cache::Cache;
11//! use rustango::cache_fragment::cached_render;
12//!
13//! async fn render_sidebar(cache: &dyn Cache) -> String {
14//!     cached_render(
15//!         cache,
16//!         "sidebar:articles",
17//!         Some(Duration::from_secs(300)),
18//!         || async {
19//!             // heavy work — happens only on miss
20//!             render_expensive_sidebar().await
21//!         },
22//!     )
23//!     .await
24//! }
25//! ```
26//!
27//! ## Cache errors
28//!
29//! A backend failure is treated as a miss: the closure runs and the
30//! caller still gets a value. Fragment caching is only a speed-up, so
31//! a brief Redis outage should not turn into a 500. Failures are
32//! logged with `tracing::warn`.
33//!
34//! ## Security
35//!
36//! The key is yours to choose. If a fragment shows per-user or
37//! per-tenant data, put the user or tenant id in the key, or one
38//! viewer's HTML will be served to another.
39//!
40//! [`cached_render`]: crate::cache_fragment::cached_render
41
42use std::time::Duration;
43
44use crate::cache::Cache;
45
46/// Return the cached fragment for `key`, or compute and store it.
47///
48/// `compute` runs only on a miss or a cache error. Pass the result to
49/// your template as a variable, such as `{{ sidebar_html | safe }}`.
50///
51/// `ttl` follows `Cache::set`: `None` stores with no expiry.
52///
53/// A cache error is logged and treated as a miss, so the caller always
54/// gets a value.
55pub async fn cached_render<F, Fut>(
56    cache: &dyn Cache,
57    key: &str,
58    ttl: Option<Duration>,
59    compute: F,
60) -> String
61where
62    F: FnOnce() -> Fut,
63    Fut: std::future::Future<Output = String>,
64{
65    match cache.get(key).await {
66        Ok(Some(hit)) => return hit,
67        Ok(None) => {}
68        Err(e) => {
69            tracing::warn!(
70                cache_key = %key,
71                error = %e,
72                "cache_fragment: backend `get` failed; recomputing",
73            );
74        }
75    }
76    let computed = compute().await;
77    if let Err(e) = cache.set(key, &computed, ttl).await {
78        tracing::warn!(
79            cache_key = %key,
80            error = %e,
81            "cache_fragment: backend `set` failed; serving fresh value anyway",
82        );
83    }
84    computed
85}
86
87/// Build a stable cache key from a fragment name and the values the
88/// fragment varies on.
89///
90/// Shape: `template.cache.{name}.{hash}`. Order matters, so
91/// `["a", "b"]` and `["b", "a"]` give different keys.
92///
93/// Use it with [`cached_render`] to invalidate a fragment by hand:
94///
95/// ```ignore
96/// use rustango::cache_fragment::make_template_fragment_key;
97///
98/// // Build the key for the per-user sidebar fragment.
99/// let key = make_template_fragment_key("sidebar", &[&user_id.to_string()]);
100/// cache.delete(&key).await?;  // invalidate when underlying data changes
101/// ```
102#[must_use]
103pub fn make_template_fragment_key(fragment_name: &str, vary_on: &[&str]) -> String {
104    use sha2::{Digest, Sha256};
105    // Length-prefixed, not `:`-joined: `["a:b","c"]` and `["a","b:c"]`
106    // must not share a key (#1884).
107    let mut hasher = Sha256::new();
108    for part in vary_on {
109        hasher.update((part.len() as u64).to_le_bytes());
110        hasher.update(part.as_bytes());
111    }
112    // SHA-256 cut to 32 hex chars: a short key, and no extra
113    // dependency for a weaker hash.
114    let digest = hasher.finalize();
115    let hex: String = digest.iter().take(16).fold(String::new(), |mut s, b| {
116        use std::fmt::Write as _;
117        let _ = write!(s, "{b:02x}");
118        s
119    });
120    format!("template.cache.{fragment_name}.{hex}")
121}
122
123#[cfg(test)]
124mod fragment_key_tests {
125    use super::*;
126
127    #[test]
128    fn key_includes_template_cache_prefix_and_fragment_name() {
129        let k = make_template_fragment_key("sidebar", &[]);
130        assert!(k.starts_with("template.cache.sidebar."));
131    }
132
133    #[test]
134    fn a_separator_inside_a_value_cannot_collide() {
135        assert_ne!(
136            make_template_fragment_key("f", &["a:b", "c"]),
137            make_template_fragment_key("f", &["a", "b:c"]),
138        );
139    }
140
141    #[test]
142    fn key_is_deterministic_for_same_inputs() {
143        let a = make_template_fragment_key("sidebar", &["42", "en"]);
144        let b = make_template_fragment_key("sidebar", &["42", "en"]);
145        assert_eq!(a, b);
146    }
147
148    #[test]
149    fn key_changes_with_vary_on_values() {
150        let a = make_template_fragment_key("sidebar", &["42"]);
151        let b = make_template_fragment_key("sidebar", &["43"]);
152        assert_ne!(a, b);
153    }
154
155    #[test]
156    fn key_changes_with_fragment_name() {
157        let a = make_template_fragment_key("sidebar", &["42"]);
158        let b = make_template_fragment_key("header", &["42"]);
159        assert_ne!(a, b);
160    }
161
162    #[test]
163    fn key_empty_vary_on_works() {
164        // No vary_on still gives a stable key.
165        let k = make_template_fragment_key("static_block", &[]);
166        assert!(k.starts_with("template.cache.static_block."));
167    }
168
169    #[test]
170    fn key_hash_segment_is_32_hex_chars() {
171        let k = make_template_fragment_key("x", &["1"]);
172        let hash = k.rsplit('.').next().unwrap();
173        assert_eq!(hash.len(), 32);
174        assert!(hash.chars().all(|c| c.is_ascii_hexdigit()));
175    }
176
177    #[test]
178    fn key_order_of_vary_on_matters() {
179        // vary_on is ordered, not a set.
180        let a = make_template_fragment_key("x", &["a", "b"]);
181        let b = make_template_fragment_key("x", &["b", "a"]);
182        assert_ne!(a, b);
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189    use crate::cache::{Cache, InMemoryCache};
190    use async_trait::async_trait;
191    use std::sync::atomic::{AtomicUsize, Ordering};
192    use std::sync::Arc;
193
194    #[tokio::test]
195    async fn miss_invokes_compute_and_stores() {
196        let cache = InMemoryCache::new();
197        let calls = Arc::new(AtomicUsize::new(0));
198        let calls_clone = Arc::clone(&calls);
199        let out = cached_render(&cache, "k1", None, move || {
200            let calls = Arc::clone(&calls_clone);
201            async move {
202                calls.fetch_add(1, Ordering::SeqCst);
203                "computed".to_owned()
204            }
205        })
206        .await;
207        assert_eq!(out, "computed");
208        assert_eq!(calls.load(Ordering::SeqCst), 1);
209        // It really landed in the cache.
210        let stored = cache.get("k1").await.unwrap();
211        assert_eq!(stored.as_deref(), Some("computed"));
212    }
213
214    #[tokio::test]
215    async fn hit_returns_cached_without_recomputing() {
216        let cache = InMemoryCache::new();
217        cache.set("k2", "from-cache", None).await.unwrap();
218        let calls = Arc::new(AtomicUsize::new(0));
219        let calls_clone = Arc::clone(&calls);
220        let out = cached_render(&cache, "k2", None, move || {
221            let calls = Arc::clone(&calls_clone);
222            async move {
223                calls.fetch_add(1, Ordering::SeqCst);
224                "recomputed".to_owned()
225            }
226        })
227        .await;
228        assert_eq!(out, "from-cache");
229        assert_eq!(
230            calls.load(Ordering::SeqCst),
231            0,
232            "compute should not run on hit"
233        );
234    }
235
236    #[tokio::test]
237    async fn ttl_is_passed_through_to_backend() {
238        let cache = InMemoryCache::new();
239        cached_render(&cache, "k3", Some(Duration::from_millis(20)), || async {
240            "with-ttl".to_owned()
241        })
242        .await;
243        assert_eq!(cache.get("k3").await.unwrap().as_deref(), Some("with-ttl"));
244        tokio::time::sleep(Duration::from_millis(30)).await;
245        // InMemoryCache checks the TTL on get.
246        assert!(
247            cache.get("k3").await.unwrap().is_none(),
248            "entry should have expired"
249        );
250    }
251
252    // A backend where get and set always fail.
253    struct ExplodingCache;
254    #[async_trait]
255    impl Cache for ExplodingCache {
256        async fn touch(
257            &self,
258            _: &str,
259            _: Option<std::time::Duration>,
260        ) -> Result<bool, crate::cache::CacheError> {
261            Ok(false)
262        }
263        async fn get(&self, _: &str) -> Result<Option<String>, crate::cache::CacheError> {
264            Err(crate::cache::CacheError::Connection("boom".into()))
265        }
266        async fn set(
267            &self,
268            _: &str,
269            _: &str,
270            _: Option<Duration>,
271        ) -> Result<(), crate::cache::CacheError> {
272            Err(crate::cache::CacheError::Connection("boom".into()))
273        }
274        async fn delete(&self, _: &str) -> Result<(), crate::cache::CacheError> {
275            Ok(())
276        }
277        async fn exists(&self, _: &str) -> Result<bool, crate::cache::CacheError> {
278            Ok(false)
279        }
280        async fn clear(&self) -> Result<(), crate::cache::CacheError> {
281            Ok(())
282        }
283    }
284
285    #[tokio::test]
286    async fn cache_get_failure_recomputes_and_returns() {
287        let cache = ExplodingCache;
288        let out = cached_render(&cache, "k4", None, || async { "fresh".to_owned() }).await;
289        assert_eq!(out, "fresh");
290    }
291
292    #[tokio::test]
293    async fn cache_set_failure_still_returns_computed_value() {
294        // Both get and set fail; the caller still gets a string.
295        let cache = ExplodingCache;
296        let out = cached_render(&cache, "k5", Some(Duration::from_secs(60)), || async {
297            "still-fresh".to_owned()
298        })
299        .await;
300        assert_eq!(out, "still-fresh");
301    }
302
303    #[tokio::test]
304    async fn compute_runs_only_once_for_repeated_hits() {
305        let cache = InMemoryCache::new();
306        let calls = Arc::new(AtomicUsize::new(0));
307        for _ in 0..5 {
308            let calls_clone = Arc::clone(&calls);
309            let _ = cached_render(&cache, "k6", None, move || {
310                let calls = Arc::clone(&calls_clone);
311                async move {
312                    calls.fetch_add(1, Ordering::SeqCst);
313                    "x".to_owned()
314                }
315            })
316            .await;
317        }
318        assert_eq!(
319            calls.load(Ordering::SeqCst),
320            1,
321            "compute ran once across 5 calls"
322        );
323    }
324}