Skip to main content

sisa_caching_redis/
store.rs

1//! The Redis store.
2
3use std::{
4    sync::Arc,
5    time::{Duration, SystemTime},
6};
7
8use redis::{Client, IntoConnectionInfo, aio::ConnectionManager};
9
10use sisa_caching_core::{
11    cache::{CacheEntry, CacheError, CacheStore, CacheValue, KEY_SEPARATOR, KeyPrefix},
12    clock::{Clock, SystemClock},
13    locker::Locker,
14    metrics::{Layer, METRICS, Reads},
15    settings::CacheSettings,
16};
17
18use crate::{
19    connection::{RedisConnection, connection_config},
20    error::RedisCacheError,
21    settings::RedisCacheSettings,
22};
23
24const VALUE: &str = "value";
25const CREATED_AT: &str = "created_at";
26const TTL_MS: &str = "ttl_ms";
27
28/// The longest TTL stored, in ms: half of what `PEXPIRE` takes, leaving room for the server's
29/// clock. Anything longer, millions of years, is stored as no TTL.
30const MAX_TTL_MS: u64 = i64::MAX as u64 / 2;
31
32/// The JSON value and origin metadata of one entry's hash.
33type StoredFields = (Option<Vec<u8>>, Option<u64>, Option<u64>);
34
35/// Escapes the characters that `SCAN MATCH` reads as a pattern.
36fn escape_glob(text: &str) -> String {
37    let mut escaped = String::with_capacity(text.len());
38
39    for character in text.chars() {
40        if "*?[]\\".contains(character) {
41            escaped.push('\\');
42        }
43        escaped.push(character);
44    }
45
46    escaped
47}
48
49/// The entry a hash's fields and its `PTTL` reply hold, counting its time left from
50/// `requested_at`, or `None` when the key is missing or has expired.
51fn stored_entry<CV: CacheValue>(
52    (encoded_value, created_at_ms, ttl_ms): StoredFields,
53    pttl_ms: i64,
54    requested_at: SystemTime,
55) -> serde_json::Result<Option<CacheEntry<CV>>> {
56    // PTTL is -1 for a key without expiry and -2 for a missing one.
57    let Some(encoded_value) = encoded_value.filter(|_| pttl_ms >= -1) else {
58        return Ok(None);
59    };
60    // No expiry, or a deadline past what the platform's clock can hold, which never comes.
61    let expires_at = u64::try_from(pttl_ms)
62        .ok()
63        .and_then(|ms| requested_at.checked_add(Duration::from_millis(ms)));
64    // A creation time past what the platform's clock can hold, which only another writer can
65    // store, reads as the epoch, as a missing one does.
66    let created_at = created_at_ms
67        .and_then(|ms| SystemTime::UNIX_EPOCH.checked_add(Duration::from_millis(ms)))
68        .unwrap_or(SystemTime::UNIX_EPOCH);
69    let entry = CacheEntry::new(
70        serde_json::from_slice(&encoded_value)?,
71        created_at,
72        ttl_ms.map(Duration::from_millis),
73    )
74    .with_expires_at(expires_at);
75
76    Ok((!entry.is_expired(SystemClock.now())).then_some(entry))
77}
78
79/// A store on a Redis-family server. One store holds values of every type as JSON; `get::<User>`
80/// and `set(&key, user, None)` name the type per call. Reads decode the JSON into the type you
81/// name, and nothing in Redis records a Rust type, so other languages can share the keys.
82///
83/// Connect it to a single server with a `ConnectionManager`, to a Redis Cluster with a
84/// `ClusterConnection`, or behind Sentinel with a
85/// [`SentinelConnection`](crate::connection::SentinelConnection). On a cluster, `remove_prefix`
86/// and `clear` scan every primary.
87#[derive(Clone)]
88pub struct RedisCacheStore<Conn = ConnectionManager>
89where
90    Conn: RedisConnection,
91{
92    conn: Conn,
93    name: KeyPrefix,
94    settings: RedisCacheSettings,
95    locker: Arc<Locker>,
96    reads: &'static Reads,
97}
98
99// Shows the name and the settings; never the connection or a value.
100impl<Conn: RedisConnection> std::fmt::Debug for RedisCacheStore<Conn> {
101    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
102        formatter
103            .debug_struct("RedisCacheStore")
104            .field("name", &self.name)
105            .field("settings", &self.settings)
106            .finish_non_exhaustive()
107    }
108}
109
110impl<Conn> RedisCacheStore<Conn>
111where
112    Conn: RedisConnection,
113{
114    /// A store named `name`, such as `app` or `tenant:eu`, on `conn`. Fails with
115    /// [`CacheError::InvalidKey`] when the name is empty or has an empty level. A
116    /// `ConnectionManager` reconnects after a lost connection.
117    ///
118    /// On a Redis Cluster, give it a cluster connection. The client finds the other nodes from the
119    /// one it is given:
120    ///
121    /// ```no_run
122    /// use sisa_caching_redis::{RedisCacheStore, redis::cluster::ClusterClient};
123    ///
124    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
125    /// let client = ClusterClient::new(vec!["redis://10.0.0.1:6379"])?;
126    /// let cache = RedisCacheStore::new("app", client.get_async_connection().await?)?;
127    /// # Ok(())
128    /// # }
129    /// ```
130    pub fn new(name: &str, conn: Conn) -> Result<Self, CacheError> {
131        let name = KeyPrefix::new(name)?;
132
133        Ok(Self {
134            reads: METRICS.reads(&name, Layer::Redis),
135            name,
136            conn,
137            settings: RedisCacheSettings::default(),
138            locker: Arc::default(),
139        })
140    }
141
142    /// Replaces the store's settings. Fails when one is out of range, such as a TTL over 365
143    /// days, so a bad value stops setup instead of a later write.
144    pub fn with_settings(mut self, settings: RedisCacheSettings) -> Result<Self, CacheError> {
145        settings.validate()?;
146        self.settings = settings;
147
148        Ok(self)
149    }
150
151    /// The settings the store runs with.
152    pub fn settings(&self) -> &RedisCacheSettings {
153        &self.settings
154    }
155
156    async fn unlink(&self, prefix: Option<&str>) -> crate::error::Result<usize> {
157        let scope = escape_glob(&self.name.format_scope());
158        let pattern = match prefix {
159            Some(prefix) => format!("{scope}{}{KEY_SEPARATOR}*", escape_glob(prefix)),
160            None => format!("{scope}*"),
161        };
162
163        let mut conn = self.conn.clone();
164        let mut removed = 0;
165        let batch_size = self.settings.redis.scan_batch_size;
166
167        // `SCAN` sees one node's keys, so each primary of a cluster is walked on its own.
168        for node in conn.primaries().await? {
169            let mut cursor: u64 = 0;
170
171            loop {
172                let scan = redis::cmd("SCAN")
173                    .arg(cursor)
174                    .arg("MATCH")
175                    .arg(&pattern)
176                    .arg("COUNT")
177                    .arg(batch_size)
178                    .to_owned();
179                let reply = conn.query_node(node.as_ref(), &scan).await?;
180                let (next, keys): (u64, Vec<Vec<u8>>) =
181                    redis::from_redis_value(reply.extract_error()?)
182                        .map_err(redis::RedisError::from)?;
183
184                // A cluster connection splits `UNLINK` by slot itself.
185                if !keys.is_empty() {
186                    removed += redis::cmd("UNLINK")
187                        .arg(&keys)
188                        .query_async::<usize>(&mut conn)
189                        .await?;
190                }
191
192                if next == 0 {
193                    break;
194                }
195
196                cursor = next;
197            }
198        }
199
200        Ok(removed)
201    }
202}
203
204impl RedisCacheStore {
205    /// Connects to one server, such as `redis://127.0.0.1:6379`, or `rediss://` for TLS with the
206    /// `tls-rustls` or `tls-native-tls` feature. `info` is a URL or a `redis::ConnectionInfo`.
207    /// The connection is built with [`connection_config`]: while the server is down a call fails
208    /// at once, and the next one connects again. For other timeouts, or for a cluster or
209    /// Sentinel, build the connection and use `new`.
210    pub async fn connect(name: &str, info: impl IntoConnectionInfo) -> crate::error::Result<Self> {
211        Self::from_client(name, Client::open(info)?).await
212    }
213
214    /// Like [`connect`](Self::connect), on a client built by hand, such as one that trusts a
215    /// private CA or shows a client certificate:
216    ///
217    /// ```no_run
218    /// # #[cfg(feature = "tls-rustls")]
219    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
220    /// use sisa_caching_redis::{
221    ///     RedisCacheStore,
222    ///     redis::{Client, ClientTlsConfig, TlsCertificates},
223    /// };
224    ///
225    /// let client = Client::build_with_tls(
226    ///     "rediss://cache.internal:6380",
227    ///     TlsCertificates {
228    ///         client_tls: Some(ClientTlsConfig {
229    ///             client_cert: std::fs::read("client.crt")?,
230    ///             client_key: std::fs::read("client.key")?,
231    ///         }),
232    ///         root_cert: Some(std::fs::read("ca.crt")?),
233    ///     },
234    /// )?;
235    /// let cache = RedisCacheStore::from_client("app", client).await?;
236    /// # Ok(())
237    /// # }
238    /// ```
239    pub async fn from_client(name: &str, client: Client) -> crate::error::Result<Self> {
240        KeyPrefix::validate(name)?;
241
242        let conn = ConnectionManager::new_with_config(client, connection_config()).await?;
243
244        Ok(Self::new(name, conn)?)
245    }
246}
247
248// Marks this as one of the stores that may implement `CacheStore`.
249impl<Conn: RedisConnection> sisa_caching_core::sealed::Sealed for RedisCacheStore<Conn> {}
250
251// The cache API, one Redis hash per key.
252impl<Conn> CacheStore for RedisCacheStore<Conn>
253where
254    Conn: RedisConnection,
255{
256    type Error = RedisCacheError;
257    // Redis counts the TTL itself, so the store has no clock to swap.
258    type Clock = SystemClock;
259
260    fn name(&self) -> &KeyPrefix {
261        &self.name
262    }
263
264    fn cache_settings(&self) -> &CacheSettings {
265        &self.settings.common
266    }
267
268    fn locker(&self) -> &Locker {
269        &self.locker
270    }
271
272    fn clock(&self) -> &SystemClock {
273        &SystemClock
274    }
275
276    #[tracing::instrument(level = "debug", name = "redis get", skip_all, fields(key = %self.name.format_key(key)), err(level = "debug"))]
277    async fn get_entry<CV: CacheValue>(
278        &self,
279        key: &str,
280    ) -> crate::error::Result<Option<CacheEntry<CV>>> {
281        let redis_key = self.name.format_key(key);
282        let mut conn = self.conn.clone();
283        // The countdown starts before the request, so a slow reply can only shorten it.
284        let requested_at = SystemClock.now();
285        let (fields, pttl_ms): (StoredFields, i64) = redis::pipe()
286            .atomic()
287            .cmd("HMGET")
288            .arg(&redis_key)
289            .arg(VALUE)
290            .arg(CREATED_AT)
291            .arg(TTL_MS)
292            .cmd("PTTL")
293            .arg(&redis_key)
294            .query_async(&mut conn)
295            .await?;
296        let entry = stored_entry(fields, pttl_ms, requested_at);
297
298        // Data that doesn't decode is a miss too: the caller gets no value.
299        self.reads.record(matches!(entry, Ok(Some(_))));
300
301        Ok(entry?)
302    }
303
304    #[tracing::instrument(level = "debug", name = "redis set", skip_all, fields(key = %self.name.format_key(key)), err(level = "debug"))]
305    async fn set_entry<CV: CacheValue>(
306        &self,
307        key: &str,
308        entry: CacheEntry<CV>,
309    ) -> crate::error::Result<()> {
310        let redis_key = self.name.format_key(key);
311        let encoded_value = serde_json::to_vec(&entry.value)?;
312        let created_at = entry
313            .created_at()
314            .duration_since(SystemTime::UNIX_EPOCH)
315            .unwrap_or_default()
316            .as_millis() as u64;
317        // Whole milliseconds, rounded up, so a short TTL never becomes zero.
318        let to_ms = |ttl: Duration| {
319            u64::try_from(ttl.as_nanos().div_ceil(1_000_000))
320                .ok()
321                .filter(|ms| *ms <= MAX_TTL_MS)
322        };
323        let ttl_ms = entry.ttl().and_then(to_ms);
324        let remaining_ms = entry.remaining_ttl(SystemClock.now()).and_then(to_ms);
325        let mut conn = self.conn.clone();
326        let mut pipe = redis::pipe();
327
328        pipe.atomic().cmd("DEL").arg(&redis_key).ignore();
329
330        // An entry that has already expired only clears the key.
331        if remaining_ms != Some(0) {
332            let hset = pipe
333                .cmd("HSET")
334                .arg(&redis_key)
335                .arg(VALUE)
336                .arg(&encoded_value[..])
337                .arg(CREATED_AT)
338                .arg(created_at);
339
340            if let Some(ttl_ms) = ttl_ms {
341                hset.arg(TTL_MS).arg(ttl_ms);
342            }
343
344            hset.ignore();
345
346            if let Some(remaining_ms) = remaining_ms {
347                pipe.cmd("PEXPIRE")
348                    .arg(&redis_key)
349                    .arg(remaining_ms)
350                    .ignore();
351            }
352        }
353
354        pipe.query_async::<()>(&mut conn).await?;
355
356        Ok(())
357    }
358
359    #[tracing::instrument(level = "debug", name = "redis remove", skip_all, fields(key = %self.name.format_key(key)), err(level = "debug"))]
360    async fn remove(&self, key: &str) -> crate::error::Result<bool> {
361        let removed: usize = redis::cmd("UNLINK")
362            .arg(self.name.format_key(key))
363            .query_async(&mut self.conn.clone())
364            .await?;
365
366        Ok(removed > 0)
367    }
368
369    #[tracing::instrument(level = "debug", name = "redis remove_prefix", skip_all, fields(store = %self.name, %prefix), err(level = "debug"))]
370    async fn remove_prefix(&self, prefix: &str) -> crate::error::Result<usize> {
371        KeyPrefix::validate(prefix)?;
372
373        self.unlink(Some(prefix)).await
374    }
375
376    #[tracing::instrument(level = "debug", name = "redis clear", skip_all, fields(store = %self.name), err(level = "debug"))]
377    async fn clear(&self) -> crate::error::Result<()> {
378        self.unlink(None).await?;
379
380        Ok(())
381    }
382}
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387
388    #[test]
389    fn glob_characters_are_escaped() {
390        assert_eq!(escape_glob(r"a*b?c[d]e\f"), r"a\*b\?c\[d\]e\\f");
391        assert_eq!(escape_glob("app::user"), "app::user");
392    }
393}