Skip to main content

ferrlabs_cache/
swr.rs

1use crate::CachePool;
2use fred::prelude::*;
3use serde::{Deserialize, Serialize};
4use std::future::Future;
5use std::time::{Duration, SystemTime, UNIX_EPOCH};
6
7#[derive(Serialize, Deserialize)]
8struct Envelope<T> {
9    ts_ms: u64,
10    payload: T,
11}
12
13fn now_ms() -> u64 {
14    // ms-since-epoch overflows u64 only ~584 million years from now.
15    #[allow(clippy::cast_possible_truncation)]
16    let ms = SystemTime::now()
17        .duration_since(UNIX_EPOCH)
18        .unwrap_or_default()
19        .as_millis() as u64;
20    ms
21}
22
23pub struct Swr<'a> {
24    pub pool: &'a CachePool,
25    pub key: &'a str,
26    pub fresh_ttl: Duration,
27    pub hard_ttl: Duration,
28    pub lock_ttl: Duration,
29    pub bypass: bool,
30}
31
32impl Swr<'_> {
33    async fn store<T: Serialize>(&self, value: &T) -> anyhow::Result<()> {
34        let env = Envelope {
35            ts_ms: now_ms(),
36            payload: value,
37        };
38        let json = serde_json::to_string(&env)?;
39        // hard_ttl is caller-configured and expected to be a small, sane duration
40        // (seconds-to-hours range), far below i64::MAX milliseconds.
41        #[allow(clippy::cast_possible_truncation)]
42        let px = self.hard_ttl.as_millis() as i64;
43        self.pool
44            .set::<(), _, _>(self.key, json, Some(Expiration::PX(px)), None, false)
45            .await?;
46        Ok(())
47    }
48
49    /// `SET lock NX PX lock_ttl`, true when the lock was acquired.
50    async fn try_lock(&self, lock_key: &str) -> bool {
51        // lock_ttl is caller-configured and expected to be a small, sane duration
52        // (seconds-to-minutes range), far below i64::MAX milliseconds.
53        #[allow(clippy::cast_possible_truncation)]
54        let px = self.lock_ttl.as_millis() as i64;
55        match self
56            .pool
57            .set::<fred::types::Value, _, _>(
58                lock_key,
59                "1",
60                Some(Expiration::PX(px)),
61                Some(SetOptions::NX),
62                false,
63            )
64            .await
65        {
66            Ok(v) => !v.is_null(),
67            Err(_) => false,
68        }
69    }
70
71    pub async fn get_or_load<T, F, Fut>(&self, loader: F) -> anyhow::Result<T>
72    where
73        T: Serialize + for<'de> Deserialize<'de> + Send + 'static,
74        F: Fn() -> Fut + Send + Sync + 'static,
75        Fut: Future<Output = anyhow::Result<T>> + Send + 'static,
76    {
77        let loader = std::sync::Arc::new(loader);
78
79        if self.bypass {
80            let v = (loader)().await?;
81            let _ = self.store(&v).await;
82            return Ok(v);
83        }
84
85        // Read; any Valkey error degrades to an inline load.
86        let raw: Option<String> = match self.pool.get(self.key).await {
87            Ok(v) => v,
88            Err(e) => {
89                tracing::warn!(error = %e, key = self.key, "Valkey GET failed, loading directly");
90                return (loader)().await;
91            }
92        };
93
94        let lock_key = format!("{}:lock", self.key);
95
96        if let Some(raw) = raw {
97            if let Ok(env) = serde_json::from_str::<Envelope<T>>(&raw) {
98                let age = Duration::from_millis(now_ms().saturating_sub(env.ts_ms));
99                if age < self.fresh_ttl {
100                    return Ok(env.payload); // fresh
101                }
102                // stale: serve the old value now, refresh in the background
103                // (cluster-wide single-flight through a Valkey lock).
104                spawn_refresh::<T, F, Fut>(
105                    self.pool.clone(),
106                    self.key.to_string(),
107                    lock_key,
108                    self.hard_ttl,
109                    self.lock_ttl,
110                    loader.clone(),
111                );
112                return Ok(env.payload);
113            }
114        }
115
116        // miss: single-flight. The lock winner loads and stores; the losers
117        // poll briefly for the value to appear, and load themselves as a
118        // last resort (never an unbounded wait).
119        if self.try_lock(&lock_key).await {
120            // Release the lock whether the loader succeeds OR fails, otherwise it
121            // leaks for the whole lock_ttl and blocks concurrent readers.
122            return match (loader)().await {
123                Ok(v) => {
124                    let _ = self.store(&v).await;
125                    let _: Result<(), _> = self.pool.del(&lock_key).await;
126                    Ok(v)
127                }
128                Err(e) => {
129                    let _: Result<(), _> = self.pool.del(&lock_key).await;
130                    Err(e)
131                }
132            };
133        }
134
135        let poll_interval = Duration::from_millis(25);
136        let max_polls = (self.lock_ttl.as_millis() / poll_interval.as_millis().max(1)).max(1);
137        for _ in 0..max_polls {
138            tokio::time::sleep(poll_interval).await;
139            if let Ok(Some(raw)) = self.pool.get::<Option<String>, _>(self.key).await {
140                if let Ok(env) = serde_json::from_str::<Envelope<T>>(&raw) {
141                    let age = Duration::from_millis(now_ms().saturating_sub(env.ts_ms));
142                    if age < self.fresh_ttl {
143                        return Ok(env.payload);
144                    }
145                }
146            }
147        }
148
149        // Last resort: the lock holder did not finish in time.
150        let v = (loader)().await?;
151        let _ = self.store(&v).await;
152        Ok(v)
153    }
154}
155
156/// Refreshes `key` in the background, with cluster-wide single-flight through
157/// `lock_key` (`SET NX PX`). Only the lock winner reloads; the others return
158/// immediately without doing anything.
159fn spawn_refresh<T, F, Fut>(
160    pool: CachePool,
161    key: String,
162    lock_key: String,
163    hard_ttl: Duration,
164    lock_ttl: Duration,
165    loader: std::sync::Arc<F>,
166) where
167    T: Serialize + for<'de> Deserialize<'de> + Send + 'static,
168    F: Fn() -> Fut + Send + Sync + 'static,
169    Fut: Future<Output = anyhow::Result<T>> + Send + 'static,
170{
171    tokio::spawn(async move {
172        // single-flight: only the lock winner refreshes.
173        // lock_ttl/hard_ttl are caller-configured and expected to be small,
174        // sane durations, far below i64::MAX milliseconds.
175        #[allow(clippy::cast_possible_truncation)]
176        let px = lock_ttl.as_millis() as i64;
177        let got = matches!(
178            pool.set::<fred::types::Value, _, _>(
179                &lock_key,
180                "1",
181                Some(Expiration::PX(px)),
182                Some(SetOptions::NX),
183                false,
184            )
185            .await,
186            Ok(v) if !v.is_null()
187        );
188        if !got {
189            return;
190        }
191        match (loader)().await {
192            Ok(v) => {
193                let json = serde_json::to_string(&Envelope {
194                    ts_ms: now_ms(),
195                    payload: &v,
196                })
197                .ok();
198                if let Some(json) = json {
199                    #[allow(clippy::cast_possible_truncation)]
200                    let hard_px = hard_ttl.as_millis() as i64;
201                    let _ = pool
202                        .set::<(), _, _>(&key, json, Some(Expiration::PX(hard_px)), None, false)
203                        .await;
204                }
205            }
206            Err(e) => tracing::warn!(error = %e, key = %key, "background SWR refresh failed"),
207        }
208        let _: Result<(), _> = pool.del(&lock_key).await;
209    });
210}
211
212#[cfg(test)]
213mod tests {
214    use super::*;
215    use std::sync::Arc;
216    use std::sync::atomic::{AtomicU32, Ordering};
217    use std::time::Duration;
218
219    async fn pool() -> Option<crate::CachePool> {
220        let url = std::env::var("TEST_VALKEY_URL").ok()?;
221        crate::connect(&crate::CacheConfig {
222            url,
223            pool_size: 2,
224            ca_cert_path: None,
225            password: None,
226        })
227        .await
228        .ok()
229    }
230
231    #[tokio::test]
232    async fn miss_then_fresh_hit_calls_loader_once() {
233        let Some(pool) = pool().await else {
234            return;
235        };
236        let key = "test:swr:fresh";
237        let _: Result<(), _> = pool.del(key).await;
238        let calls = Arc::new(AtomicU32::new(0));
239        let mk = |calls: Arc<AtomicU32>| {
240            move || {
241                let calls = calls.clone();
242                async move {
243                    calls.fetch_add(1, Ordering::SeqCst);
244                    Ok::<u32, anyhow::Error>(42)
245                }
246            }
247        };
248        let swr = || Swr {
249            pool: &pool,
250            key,
251            fresh_ttl: Duration::from_secs(60),
252            hard_ttl: Duration::from_secs(120),
253            lock_ttl: Duration::from_secs(30),
254            bypass: false,
255        };
256        assert_eq!(swr().get_or_load(mk(calls.clone())).await.unwrap(), 42); // miss
257        assert_eq!(swr().get_or_load(mk(calls.clone())).await.unwrap(), 42); // fresh hit
258        assert_eq!(
259            calls.load(Ordering::SeqCst),
260            1,
261            "loader called exactly once"
262        );
263    }
264
265    #[tokio::test]
266    async fn bypass_forces_reload() {
267        let Some(pool) = pool().await else {
268            return;
269        };
270        let key = "test:swr:bypass";
271        let _: Result<(), _> = pool.del(key).await;
272        let calls = Arc::new(AtomicU32::new(0));
273        let mk = |calls: Arc<AtomicU32>| {
274            move || {
275                let calls = calls.clone();
276                async move {
277                    calls.fetch_add(1, Ordering::SeqCst);
278                    Ok::<u32, anyhow::Error>(7)
279                }
280            }
281        };
282        let mut s = Swr {
283            pool: &pool,
284            key,
285            fresh_ttl: Duration::from_secs(60),
286            hard_ttl: Duration::from_secs(120),
287            lock_ttl: Duration::from_secs(30),
288            bypass: false,
289        };
290        s.get_or_load(mk(calls.clone())).await.unwrap();
291        s.bypass = true;
292        s.get_or_load(mk(calls.clone())).await.unwrap();
293        assert_eq!(calls.load(Ordering::SeqCst), 2);
294    }
295
296    #[tokio::test]
297    async fn stale_serves_old_and_refreshes_once() {
298        let Some(pool) = pool().await else {
299            return;
300        };
301        let key = "test:swr:stale";
302        let _: Result<(), _> = pool.del(key).await;
303        let calls = Arc::new(AtomicU32::new(0));
304        let mk = |calls: Arc<AtomicU32>, val: u32| {
305            move || {
306                let calls = calls.clone();
307                async move {
308                    calls.fetch_add(1, Ordering::SeqCst);
309                    Ok::<u32, anyhow::Error>(val)
310                }
311            }
312        };
313        // very short fresh_ttl, so the entry goes stale almost immediately.
314        let swr = |b: bool| Swr {
315            pool: &pool,
316            key,
317            fresh_ttl: Duration::from_millis(1),
318            hard_ttl: Duration::from_secs(120),
319            lock_ttl: Duration::from_secs(30),
320            bypass: b,
321        };
322        assert_eq!(
323            swr(false).get_or_load(mk(calls.clone(), 1)).await.unwrap(),
324            1
325        ); // miss => 1 call
326        tokio::time::sleep(Duration::from_millis(5)).await;
327        // 3 concurrent stale reads: all return the old value, ONE refresh only.
328        // (bound to named variables: `swr(false)` inline as a `tokio::join!`
329        // argument would be a temporary dropped before being polled, see
330        // E0716.)
331        let (s1, s2, s3) = (swr(false), swr(false), swr(false));
332        let (a, b, c) = tokio::join!(
333            s1.get_or_load(mk(calls.clone(), 2)),
334            s2.get_or_load(mk(calls.clone(), 2)),
335            s3.get_or_load(mk(calls.clone(), 2)),
336        );
337        assert_eq!(
338            (a.unwrap(), b.unwrap(), c.unwrap()),
339            (1, 1, 1),
340            "stale served immediately"
341        );
342        tokio::time::sleep(Duration::from_millis(50)).await; // let the refresh finish
343        assert_eq!(calls.load(Ordering::SeqCst), 2, "1 miss + a single refresh");
344    }
345
346    #[tokio::test]
347    async fn miss_loader_error_releases_lock() {
348        let Some(pool) = pool().await else {
349            return;
350        };
351        let key = "test:swr:miss-err";
352        let lock_key = format!("{key}:lock");
353        let _: Result<(), _> = pool.del(key).await;
354        let _: Result<(), _> = pool.del(lock_key.as_str()).await;
355        let swr = || Swr {
356            pool: &pool,
357            key,
358            fresh_ttl: Duration::from_secs(60),
359            hard_ttl: Duration::from_secs(120),
360            // short: even on a regression the fallback poll does not block long.
361            lock_ttl: Duration::from_secs(5),
362            bypass: false,
363        };
364        // miss + failing loader: Err is returned, but the lock MUST be released.
365        let err = swr()
366            .get_or_load(|| async { Err::<u32, anyhow::Error>(anyhow::anyhow!("boom")) })
367            .await;
368        assert!(err.is_err(), "failing loader propagates Err");
369        // Direct proof: the single-flight lock does not leak.
370        let exists: i64 = pool.exists(lock_key.as_str()).await.unwrap();
371        assert_eq!(exists, 0, "lock released after a loader error (no leak)");
372        // Indirect proof: a second call (loader OK) loads immediately, without
373        // waiting for lock_ttl to expire.
374        let start = std::time::Instant::now();
375        let v = swr()
376            .get_or_load(|| async { Ok::<u32, anyhow::Error>(99) })
377            .await
378            .unwrap();
379        assert_eq!(v, 99);
380        assert!(
381            start.elapsed() < Duration::from_secs(1),
382            "second read is immediate (lock not leaked)"
383        );
384    }
385}