1use std::time::Duration;
43
44use crate::cache::Cache;
45
46pub 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#[must_use]
103pub fn make_template_fragment_key(fragment_name: &str, vary_on: &[&str]) -> String {
104 use sha2::{Digest, Sha256};
105 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 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 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 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 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 assert!(
247 cache.get("k3").await.unwrap().is_none(),
248 "entry should have expired"
249 );
250 }
251
252 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 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}