Skip to main content

ferrlabs_cache/
lib.rs

1//! Shared Valkey (Redis-compatible) connection pool for FerrLabs APIs.
2//!
3//! Mirrors `ferrlabs-db`: config-from-env plus a `connect` factory that returns
4//! a `fred` pool that reconnects on its own. A server that is unreachable at
5//! startup does not fail `connect`: the pool keeps retrying in the background,
6//! and commands time out after one second in the meantime, so callers degrade
7//! instead of hanging. Misconfiguration (TLS, auth, URL) still fails `connect`.
8//! Consumers run commands against `fred` directly —
9//! it is re-exported here so they don't take a separate `fred` dependency.
10
11use std::time::Duration;
12
13use fred::prelude::*;
14
15pub use fred;
16
17mod swr;
18pub use swr::Swr;
19
20/// `Debug` is implemented by hand (see below) rather than derived, because
21/// both `url` and `password` can carry the AUTH secret — a derived `Debug`
22/// would print it in the clear via any `{:?}` or `tracing::debug!(?config)`,
23/// defeating the entire point of keeping the password out of the logs.
24/// Do **not** replace it with `#[derive(Debug)]`.
25#[derive(Clone)]
26pub struct CacheConfig {
27    pub url: String,
28    pub pool_size: usize,
29    /// Path to a PEM-encoded CA certificate used to verify the server's TLS
30    /// certificate when `url` uses the `rediss://` scheme. Ignored for
31    /// plaintext `redis://` connections.
32    pub ca_cert_path: Option<String>,
33    /// The Valkey/Redis AUTH password, kept out of `url` entirely.
34    ///
35    /// This is the **recommended** way to supply a password: `url` becomes
36    /// credential-free (e.g. `rediss://host:6379`) and never ends up in
37    /// logs, error messages, or metrics that capture the connection string.
38    /// When set, it takes priority over any credentials embedded in `url`.
39    ///
40    /// The URL-with-credentials form (`redis://:<password>@host:port`,
41    /// percent-encoded by [`connect`]) remains supported for backward
42    /// compatibility, but it cannot represent a password containing a raw
43    /// `?` or `#`: those characters make the URL's authority/query/fragment
44    /// boundary structurally ambiguous no matter how the userinfo is
45    /// encoded. A password with `?`/`#` in it must use `password` /
46    /// `VALKEY_PASSWORD`.
47    pub password: Option<String>,
48}
49
50/// Render a connection URL in a form that is safe to log: the scheme and the
51/// host (`redis://127.0.0.1:6379`), with any userinfo — which routinely
52/// carries the AUTH password in the `redis://:<password>@host` form — and any
53/// path/query/fragment dropped entirely.
54///
55/// When the userinfo boundary cannot be located unambiguously (a password
56/// containing a raw `?`/`#` puts a delimiter *before* the real `@`; see
57/// [`percent_encode_userinfo`]), this bails out to a fully redacted value
58/// rather than risk printing a prefix of the password.
59fn redact_url(url: &str) -> String {
60    let Some(scheme_end) = url.find("://") else {
61        return "<redacted>".to_string();
62    };
63    let (scheme, rest) = url.split_at(scheme_end + 3);
64
65    // Same bounded search as `percent_encode_userinfo`: an '@' after a '?'/'#'
66    // belongs to the query/fragment, not to the userinfo.
67    let search_end = rest.find(['?', '#']).unwrap_or(rest.len());
68    let after_userinfo = match rest[..search_end].rfind('@') {
69        Some(at_pos) => &rest[at_pos + 1..],
70        None if rest.contains('@') => {
71            // There *is* an '@' but only beyond a '?'/'#': the userinfo itself
72            // contains a raw delimiter, so the authority can't be split
73            // safely. Redact wholesale — never print a partial password.
74            return format!("{scheme}<redacted>");
75        }
76        None => rest,
77    };
78
79    let host_end = after_userinfo
80        .find(['/', '?', '#'])
81        .unwrap_or(after_userinfo.len());
82    format!("{scheme}{}", &after_userinfo[..host_end])
83}
84
85/// Hand-written so the AUTH secret never reaches a log line. `password` is
86/// reduced to a presence flag (never its value, never its length), and `url`
87/// is passed through [`redact_url`] because it can embed credentials.
88impl std::fmt::Debug for CacheConfig {
89    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
90        f.debug_struct("CacheConfig")
91            .field("url", &redact_url(&self.url))
92            .field("pool_size", &self.pool_size)
93            .field("ca_cert_path", &self.ca_cert_path)
94            .field("password", &self.password.as_ref().map(|_| "<redacted>"))
95            .finish()
96    }
97}
98
99impl CacheConfig {
100    /// Reads `VALKEY_URL`/`REDIS_URL`, `VALKEY_POOL_SIZE`, `VALKEY_CA_CERT`
101    /// and `VALKEY_PASSWORD` from the environment.
102    ///
103    /// `VALKEY_PASSWORD` is the recommended way to supply a password: set it
104    /// and use a credential-free `VALKEY_URL` (e.g. `rediss://host:6379`).
105    /// The legacy URL-with-credentials form is still read and supported (see
106    /// [`CacheConfig::password`] for why it can't handle every password).
107    pub fn from_env() -> anyhow::Result<Self> {
108        let url = std::env::var("VALKEY_URL")
109            .or_else(|_| std::env::var("REDIS_URL"))
110            .map_err(|_| anyhow::anyhow!("VALKEY_URL (or REDIS_URL) not set"))?;
111        let pool_size = std::env::var("VALKEY_POOL_SIZE")
112            .ok()
113            .and_then(|v| v.parse().ok())
114            .unwrap_or(6);
115        let ca_cert_path = std::env::var("VALKEY_CA_CERT").ok();
116        let password = std::env::var("VALKEY_PASSWORD")
117            .ok()
118            .filter(|v| !v.is_empty());
119        Ok(Self {
120            url,
121            pool_size,
122            ca_cert_path,
123            password,
124        })
125    }
126}
127
128pub type CachePool = Pool;
129
130const RECONNECT_MIN_DELAY_MS: u32 = 100;
131const RECONNECT_MAX_DELAY_MS: u32 = 30_000;
132const COMMAND_TIMEOUT: Duration = Duration::from_secs(1);
133const INITIAL_CONNECT_WAIT: Duration = Duration::from_secs(5);
134
135/// Percent-encode the `user`/`password` portion of a `redis://`/`rediss://`
136/// URL's userinfo so that URL-breaking characters (`/`, `+`, `=`, `@`, `:`,
137/// `%`, ...) in a raw password — e.g. a base64-generated Valkey password —
138/// don't get misparsed as part of the host, path, or query.
139///
140/// Finding the userinfo/host boundary in a URL whose password is *not* yet
141/// encoded is a chicken-and-egg problem: the password may itself contain the
142/// very delimiters used to find the boundary. Two rules resolve it:
143///
144/// - The search for the `@` is bounded to the left of the first `?` or `#`.
145///   A query/fragment may legitimately contain `@` (e.g. fred accepts
146///   `redis://host:6379/0?node=host:port`), and an unbounded `rfind('@')`
147///   would mistake that `@` for the separator and silently drop the real
148///   host. The bound is `?`/`#` and deliberately **not** `/`: the password
149///   routinely contains `/` (that is this function's whole reason to exist),
150///   so bounding at the first `/` would find a `/` *inside* the password,
151///   truncate the authority before the real `@`, and skip encoding entirely.
152///   This relies on the password containing no raw `?`/`#` — true for the
153///   base64 (`A-Za-z0-9+/=`) and hex alphabets used to generate them.
154/// - Within that bound, the separator is the *last* `@`: the host never
155///   contains `@`, so a password that does is still split correctly.
156///
157/// The host then ends at the first `/`, `?` or `#` **at or after** that `@`;
158/// everything from there on (path/query/fragment) is passed through verbatim
159/// — never re-encoded or altered.
160///
161/// Within the userinfo, the *first* `:` separates `user` from `password`
162/// (Valkey's typical `:password` form has an empty `user`), so a password
163/// containing `:` is preserved intact.
164///
165/// URLs with no userinfo (no `@` before any `?`/`#`) are returned unchanged.
166fn percent_encode_userinfo(url: &str) -> String {
167    let Some(scheme_end) = url.find("://") else {
168        return url.to_string();
169    };
170    let (scheme, rest) = url.split_at(scheme_end + 3);
171
172    // Bound the userinfo search to the left of any query/fragment.
173    let search_end = rest.find(['?', '#']).unwrap_or(rest.len());
174    let Some(at_pos) = rest[..search_end].rfind('@') else {
175        return url.to_string();
176    };
177
178    let (userinfo, after_at) = rest.split_at(at_pos);
179    let after_at = &after_at[1..]; // drop the leading '@'
180
181    // The host runs from the '@' to the first '/', '?' or '#'.
182    let host_end = after_at.find(['/', '?', '#']).unwrap_or(after_at.len());
183    let (host_part, tail) = after_at.split_at(host_end);
184
185    // Encode everything that is not an unreserved character (RFC 3986),
186    // which in particular covers '%' itself (so an already-`%`-containing
187    // raw password isn't double-decoded), '/', '+', '=', '@', ':', '#',
188    // '?', and '&'.
189    let encode_set: &percent_encoding::AsciiSet = percent_encoding::NON_ALPHANUMERIC;
190
191    if let Some((user, pass)) = userinfo.split_once(':') {
192        let enc_user = percent_encoding::utf8_percent_encode(user, encode_set);
193        let enc_pass = percent_encoding::utf8_percent_encode(pass, encode_set);
194        format!("{scheme}{enc_user}:{enc_pass}@{host_part}{tail}")
195    } else {
196        let enc_user = percent_encoding::utf8_percent_encode(userinfo, encode_set);
197        format!("{scheme}{enc_user}@{host_part}{tail}")
198    }
199}
200
201/// Build a `rustls::ClientConfig` that trusts only the CA certificate(s)
202/// found at `ca_cert_path`, with full server certificate + hostname
203/// verification (no "accept invalid certs" escape hatch).
204fn rustls_config_with_ca(ca_cert_path: &str) -> anyhow::Result<fred::rustls::ClientConfig> {
205    let pem_bytes = std::fs::read(ca_cert_path)
206        .map_err(|e| anyhow::anyhow!("failed to read VALKEY_CA_CERT ({ca_cert_path}): {e}"))?;
207    let mut reader = std::io::BufReader::new(pem_bytes.as_slice());
208    let certs: Vec<_> = rustls_pemfile::certs(&mut reader)
209        .collect::<Result<_, _>>()
210        .map_err(|e| anyhow::anyhow!("failed to parse VALKEY_CA_CERT PEM: {e}"))?;
211    if certs.is_empty() {
212        anyhow::bail!("VALKEY_CA_CERT ({ca_cert_path}) contains no certificates");
213    }
214
215    let mut roots = fred::rustls::RootCertStore::empty();
216    for cert in certs {
217        roots
218            .add(cert)
219            .map_err(|e| anyhow::anyhow!("invalid CA certificate in VALKEY_CA_CERT: {e}"))?;
220    }
221
222    Ok(fred::rustls::ClientConfig::builder()
223        .with_root_certificates(roots)
224        .with_no_client_auth())
225}
226
227const TRANSIENT_IO_ERRORS: &[&str] = &[
228    "ConnectionRefused",
229    "ConnectionReset",
230    "ConnectionAborted",
231    "TimedOut",
232    "HostUnreachable",
233    "NetworkUnreachable",
234    "NotConnected",
235    "BrokenPipe",
236    "UnexpectedEof",
237    "failed to lookup address",
238];
239
240fn is_transient(error: &Error) -> bool {
241    match error.kind() {
242        ErrorKind::Timeout | ErrorKind::Canceled => true,
243        ErrorKind::IO => TRANSIENT_IO_ERRORS
244            .iter()
245            .any(|kind| error.details().contains(kind)),
246        _ => false,
247    }
248}
249
250pub async fn connect(config: &CacheConfig) -> anyhow::Result<CachePool> {
251    let sanitized_url = percent_encode_userinfo(&config.url);
252    let mut cfg =
253        Config::from_url(&sanitized_url).map_err(|e| anyhow::anyhow!("invalid VALKEY_URL: {e}"))?;
254
255    // `config.password` (typically from `VALKEY_PASSWORD`) is the robust
256    // path and takes priority over any credentials embedded in the URL —
257    // it's the only way to supply a password containing a raw `?`/`#`.
258    if let Some(password) = &config.password {
259        cfg.password = Some(password.clone());
260    }
261
262    let tls_enabled = config.url.starts_with("rediss://");
263    if tls_enabled {
264        if let Some(ca_cert_path) = &config.ca_cert_path {
265            let client_config = rustls_config_with_ca(ca_cert_path)?;
266            cfg.tls = Some(client_config.into());
267        }
268        // else: keep whatever `Config::from_url` derived (system roots
269        // via `TlsConnector::default_rustls()`), still with full verification.
270    }
271
272    let performance = PerformanceConfig {
273        default_command_timeout: COMMAND_TIMEOUT,
274        ..PerformanceConfig::default()
275    };
276    let reconnect =
277        ReconnectPolicy::new_exponential(0, RECONNECT_MIN_DELAY_MS, RECONNECT_MAX_DELAY_MS, 2);
278    let build = |cfg: Config| {
279        Pool::new(
280            cfg,
281            Some(performance.clone()),
282            None,
283            Some(reconnect.clone()),
284            config.pool_size,
285        )
286        .map_err(|e| anyhow::anyhow!("failed to build Valkey pool: {e}"))
287    };
288
289    let probe = build(cfg.clone())?;
290    let _handle = probe.connect();
291    match tokio::time::timeout(INITIAL_CONNECT_WAIT, probe.wait_for_connect()).await {
292        Ok(Ok(())) => {
293            tracing::info!(
294                pool_size = config.pool_size,
295                tls = tls_enabled,
296                "connected to Valkey"
297            );
298            return Ok(probe);
299        }
300        Ok(Err(e)) if !is_transient(&e) => {
301            let _ = probe.quit().await;
302            return Err(anyhow::anyhow!("Valkey connect failed: {e}"));
303        }
304        Ok(Err(e)) => tracing::warn!(
305            error = %e,
306            "Valkey unreachable at startup, reconnecting in the background"
307        ),
308        Err(_) => tracing::warn!(
309            wait_secs = INITIAL_CONNECT_WAIT.as_secs(),
310            "Valkey not connected yet, reconnecting in the background"
311        ),
312    }
313
314    let _ = probe.quit().await;
315    cfg.fail_fast = false;
316    let pool = build(cfg)?;
317    let _handle = pool.connect();
318    Ok(pool)
319}
320
321#[cfg(test)]
322mod tests {
323    use super::*;
324    use fred::interfaces::KeysInterface;
325
326    /// Gate: run only when a local TLS Valkey is available.
327    ///
328    /// `TEST_VALKEY_TLS_URL` — e.g. `<rediss://127.0.0.1:6380>`
329    /// `TEST_VALKEY_TLS_CA` — path to the CA PEM that signed the server cert
330    fn tls_env() -> Option<(String, String)> {
331        let url = std::env::var("TEST_VALKEY_TLS_URL").ok()?;
332        let ca = std::env::var("TEST_VALKEY_TLS_CA").ok()?;
333        Some((url, ca))
334    }
335
336    #[tokio::test]
337    async fn connects_over_tls_with_valid_ca() {
338        let Some((url, ca_cert_path)) = tls_env() else {
339            eprintln!("skipping: TEST_VALKEY_TLS_URL / TEST_VALKEY_TLS_CA not set");
340            return;
341        };
342
343        let pool = connect(&CacheConfig {
344            url,
345            pool_size: 2,
346            ca_cert_path: Some(ca_cert_path),
347            password: None,
348        })
349        .await
350        .expect("expected TLS connect with valid CA to succeed");
351
352        pool.set::<(), _, _>("ferrlabs-cache:tls-test", "ok", None, None, false)
353            .await
354            .expect("SET over TLS should succeed");
355        let value: String = pool
356            .get("ferrlabs-cache:tls-test")
357            .await
358            .expect("GET over TLS should succeed");
359        assert_eq!(value, "ok");
360    }
361
362    #[tokio::test]
363    async fn rejects_tls_connection_without_trusted_ca() {
364        let Some((url, _)) = tls_env() else {
365            eprintln!("skipping: TEST_VALKEY_TLS_URL / TEST_VALKEY_TLS_CA not set");
366            return;
367        };
368
369        // No `ca_cert_path` => falls back to system roots, which do not
370        // trust our self-signed test CA. The handshake must fail: this
371        // proves verification is real, not an accept-all connector.
372        let result = tokio::time::timeout(
373            std::time::Duration::from_secs(10),
374            connect(&CacheConfig {
375                url,
376                pool_size: 1,
377                ca_cert_path: None,
378                password: None,
379            }),
380        )
381        .await;
382
383        // Either an explicit connect error, or a timeout waiting for a
384        // handshake that never completes: both prove it never succeeded.
385        if let Ok(connect_result) = result {
386            assert!(
387                connect_result.is_err(),
388                "connecting over TLS without a trusted CA must fail"
389            );
390        }
391    }
392
393    #[tokio::test]
394    async fn rejects_wrong_explicit_ca() {
395        // Exercises the primary security path directly: an explicit
396        // `ca_cert_path` pointing at a CA (CA_B) that did NOT sign the
397        // server's certificate (signed by CA_A). The custom `RootCertStore`
398        // built in `rustls_config_with_ca` must reject the server cert —
399        // proving it verifies against the provided CA rather than accepting
400        // anything.
401        let Some((url, _)) = tls_env() else {
402            eprintln!("skipping: TEST_VALKEY_TLS_URL / TEST_VALKEY_TLS_CA not set");
403            return;
404        };
405        let Ok(wrong_ca) = std::env::var("TEST_VALKEY_TLS_WRONG_CA") else {
406            eprintln!("skipping: TEST_VALKEY_TLS_WRONG_CA not set");
407            return;
408        };
409
410        let result = tokio::time::timeout(
411            std::time::Duration::from_secs(10),
412            connect(&CacheConfig {
413                url,
414                pool_size: 1,
415                ca_cert_path: Some(wrong_ca),
416                password: None,
417            }),
418        )
419        .await;
420
421        // Explicit connect error, or a timeout on a handshake that never
422        // completes: both prove the wrong CA was not accepted.
423        if let Ok(connect_result) = result {
424            assert!(
425                connect_result.is_err(),
426                "connecting over TLS with a non-signing CA must fail"
427            );
428        }
429    }
430
431    // -- percent_encode_userinfo: pure unit tests, no network required --
432
433    #[test]
434    fn percent_encode_userinfo_splits_on_last_at_for_password_containing_at() {
435        // Password itself contains '@'; the host must not absorb it. Only
436        // the *last* '@' in the string is the userinfo/host separator.
437        let raw = "redis://:ab@cd@127.0.0.1:6379";
438        let sanitized = percent_encode_userinfo(raw);
439        assert_eq!(sanitized, "redis://:ab%40cd@127.0.0.1:6379");
440    }
441
442    #[test]
443    fn percent_encode_userinfo_splits_on_first_colon_for_password_containing_colon() {
444        // Password contains ':'; user/password must split on the *first*
445        // ':' in the userinfo so the rest of the password survives intact.
446        let raw = "redis://:ab:cd@127.0.0.1:6379";
447        let sanitized = percent_encode_userinfo(raw);
448        assert_eq!(sanitized, "redis://:ab%3Acd@127.0.0.1:6379");
449    }
450
451    #[test]
452    fn percent_encode_userinfo_encodes_percent_sign_itself() {
453        // A raw password already containing a literal '%' must have that
454        // '%' escaped too, otherwise `from_url` would misinterpret it as
455        // the start of a (possibly invalid) percent-escape and mangle the
456        // decoded password.
457        let raw = "redis://:ab%cd@127.0.0.1:6379";
458        let sanitized = percent_encode_userinfo(raw);
459        assert_eq!(sanitized, "redis://:ab%25cd@127.0.0.1:6379");
460    }
461
462    #[test]
463    fn percent_encode_userinfo_covers_slash_plus_equals() {
464        let raw = "redis://:ab/cd+ef=gh@127.0.0.1:6379";
465        let sanitized = percent_encode_userinfo(raw);
466        assert_eq!(sanitized, "redis://:ab%2Fcd%2Bef%3Dgh@127.0.0.1:6379");
467    }
468
469    #[test]
470    fn percent_encode_userinfo_leaves_url_without_userinfo_unchanged() {
471        let raw = "redis://127.0.0.1:6379";
472        assert_eq!(percent_encode_userinfo(raw), raw);
473    }
474
475    #[test]
476    fn percent_encode_userinfo_preserves_db_index_path() {
477        // fred accepts the DB index as a path (`/0`). The password must be
478        // encoded while the path is passed through verbatim.
479        let raw = "redis://:ab/cd@127.0.0.1:6379/0";
480        let sanitized = percent_encode_userinfo(raw);
481        assert_eq!(sanitized, "redis://:ab%2Fcd@127.0.0.1:6379/0");
482    }
483
484    #[test]
485    fn percent_encode_userinfo_ignores_at_sign_outside_the_authority() {
486        // A path/query may legitimately contain '@'. Searching the whole
487        // URL for the last '@' would treat `?note=a@b`'s '@' as the
488        // userinfo separator and silently drop the real host (producing
489        // host_part = "b"). The search must be bounded to the authority.
490        let raw = "redis://:pw@127.0.0.1:6379/0?note=a@b";
491        let sanitized = percent_encode_userinfo(raw);
492        assert_eq!(sanitized, "redis://:pw@127.0.0.1:6379/0?note=a@b");
493
494        // And the host actually survives a real parse.
495        let parsed = Config::from_url(&sanitized).expect("should parse");
496        let host = &parsed.server.hosts()[0];
497        assert_eq!(&*host.host, "127.0.0.1");
498        assert_eq!(host.port, 6379);
499    }
500
501    #[test]
502    fn percent_encode_userinfo_handles_slash_password_together_with_path_and_query() {
503        // The hard case, combining both hazards: the password contains '/'
504        // (so the authority cannot be bounded at the first '/') AND the
505        // query contains '@' (so the '@' search cannot be unbounded).
506        let raw = "redis://:ab/cd+ef=gh@127.0.0.1:6379/0?note=a@b";
507        let sanitized = percent_encode_userinfo(raw);
508        assert_eq!(
509            sanitized,
510            "redis://:ab%2Fcd%2Bef%3Dgh@127.0.0.1:6379/0?note=a@b"
511        );
512
513        let parsed = Config::from_url(&sanitized).expect("should parse");
514        let host = &parsed.server.hosts()[0];
515        assert_eq!(&*host.host, "127.0.0.1");
516        assert_eq!(host.port, 6379);
517    }
518
519    #[test]
520    fn percent_encode_userinfo_leaves_url_without_userinfo_but_with_path_query_unchanged() {
521        // No credentials at all: the '@' in the query must not be mistaken
522        // for a userinfo separator — URL returned verbatim.
523        let raw = "redis://127.0.0.1:6379/0?x=1@2";
524        assert_eq!(percent_encode_userinfo(raw), raw);
525    }
526
527    #[test]
528    fn percent_encode_userinfo_preserves_rediss_scheme() {
529        let raw = "rediss://:ab/cd@127.0.0.1:6380";
530        let sanitized = percent_encode_userinfo(raw);
531        assert_eq!(sanitized, "rediss://:ab%2Fcd@127.0.0.1:6380");
532    }
533
534    // -- end-to-end: a real Valkey instance with a URL-breaking password --
535
536    /// Gate: run only when a local Valkey with a URL-breaking password is
537    /// available.
538    ///
539    /// `TEST_VALKEY_URL_SAFE_PASSWORD_URL` — the RAW, non-percent-encoded
540    /// `redis://:<password>@host:port` URL, exactly as a Vault template
541    /// would render it (e.g. password `ab/cd+ef=gh` generated by
542    /// `openssl rand -base64 32`).
543    fn url_safe_password_env() -> Option<String> {
544        std::env::var("TEST_VALKEY_URL_SAFE_PASSWORD_URL").ok()
545    }
546
547    #[tokio::test]
548    async fn connects_with_raw_password_containing_url_breaking_characters() {
549        let Some(url) = url_safe_password_env() else {
550            eprintln!("skipping: TEST_VALKEY_URL_SAFE_PASSWORD_URL not set");
551            return;
552        };
553
554        // Before the fix this failed with `invalid VALKEY_URL: Url Error:
555        // EmptyHost`, because the raw '/' in the password terminated the
556        // authority early. The fix pre-encodes the userinfo before handing
557        // the URL to `Config::from_url`, and `fred`/`url` decode it
558        // back to the raw password for the actual AUTH handshake.
559        let pool = connect(&CacheConfig {
560            url,
561            pool_size: 2,
562            ca_cert_path: None,
563            password: None,
564        })
565        .await
566        .expect("connect with a raw URL-breaking password should succeed");
567
568        pool.set::<(), _, _>("ferrlabs-cache:url-safe-pw-test", "ok", None, None, false)
569            .await
570            .expect("SET should succeed once AUTH has decoded the real password");
571        let value: String = pool
572            .get("ferrlabs-cache:url-safe-pw-test")
573            .await
574            .expect("GET should succeed");
575        assert_eq!(value, "ok");
576    }
577
578    // -- VALKEY_PASSWORD: password supplied out-of-band, not in the URL --
579
580    /// Gate: run only when a local Valkey with a "normal" (URL-safe-once-
581    /// percent-encoded) password is available, reachable via a
582    /// credential-free URL.
583    ///
584    /// `TEST_VALKEY_PASSWORD_URL` — e.g. `redis://127.0.0.1:<port>` (NO
585    /// credentials in the URL).
586    /// `TEST_VALKEY_PASSWORD` — the AUTH password `requirepass` is set to on
587    /// that server.
588    fn password_env() -> Option<(String, String)> {
589        let url = std::env::var("TEST_VALKEY_PASSWORD_URL").ok()?;
590        let password = std::env::var("TEST_VALKEY_PASSWORD").ok()?;
591        Some((url, password))
592    }
593
594    #[tokio::test]
595    async fn connects_with_password_supplied_out_of_band() {
596        let Some((url, password)) = password_env() else {
597            eprintln!("skipping: TEST_VALKEY_PASSWORD_URL / TEST_VALKEY_PASSWORD not set");
598            return;
599        };
600
601        // The URL itself carries no credentials at all.
602        let pool = connect(&CacheConfig {
603            url,
604            pool_size: 2,
605            ca_cert_path: None,
606            password: Some(password),
607        })
608        .await
609        .expect("connect with password supplied via CacheConfig::password should succeed");
610
611        pool.set::<(), _, _>(
612            "ferrlabs-cache:password-field-test",
613            "ok",
614            None,
615            None,
616            false,
617        )
618        .await
619        .expect("SET should succeed once AUTH has used the out-of-band password");
620        let value: String = pool
621            .get("ferrlabs-cache:password-field-test")
622            .await
623            .expect("GET should succeed");
624        assert_eq!(value, "ok");
625    }
626
627    /// Gate: run only when a local Valkey whose password contains a raw `?`
628    /// and `#` is available — the case the URL-with-credentials form cannot
629    /// represent no matter how the userinfo is percent-encoded, because `?`
630    /// and `#` are the URL's own query/fragment delimiters and the ambiguity
631    /// is structural, not an encoding bug.
632    ///
633    /// `TEST_VALKEY_UNENCODABLE_PASSWORD_URL` — e.g. `redis://127.0.0.1:<port>`
634    /// (NO credentials in the URL).
635    /// `TEST_VALKEY_UNENCODABLE_PASSWORD` — the raw password, containing `?`
636    /// and `#` (e.g. `pa?ss#word/x+y=z`).
637    fn unencodable_password_env() -> Option<(String, String)> {
638        let url = std::env::var("TEST_VALKEY_UNENCODABLE_PASSWORD_URL").ok()?;
639        let password = std::env::var("TEST_VALKEY_UNENCODABLE_PASSWORD").ok()?;
640        Some((url, password))
641    }
642
643    #[tokio::test]
644    async fn url_with_credentials_cannot_represent_a_password_containing_question_mark_or_hash() {
645        // The negative half of the proof: the existing (and still supported)
646        // URL-with-credentials path cannot carry a raw '?'/'#' password, and
647        // percent-encoding the userinfo cannot rescue it.
648        //
649        // The failure happens at parse time, before any network I/O — there
650        // is no AUTH round-trip and no WRONGPASS here:
651        //   1. `percent_encode_userinfo` bounds its '@' search to the left of
652        //      the first '?'/'#'. In `redis://:pa?ss#word/x+y=z@host:port`
653        //      that '?' sits *inside* the still-unencoded password, so no '@'
654        //      is found within the bound and the URL is returned UNCHANGED
655        //      (no encoding applied at all).
656        //   2. `Config::from_url` then parses that raw URL, reads the
657        //      authority as ending at the '?', finds no host, and rejects it
658        //      with `Url Error: EmptyHost` — surfaced as `invalid VALKEY_URL`.
659        //
660        // Loosening the bound doesn't help either: the ambiguity is
661        // structural. A raw '?' in a password is indistinguishable from the
662        // URL's own query delimiter. Hence VALKEY_PASSWORD — this case is not
663        // redundant with the percent-encoding fix.
664        let Some((url, password)) = unencodable_password_env() else {
665            eprintln!(
666                "skipping: TEST_VALKEY_UNENCODABLE_PASSWORD_URL / TEST_VALKEY_UNENCODABLE_PASSWORD not set"
667            );
668            return;
669        };
670
671        // Build the raw URL-with-credentials form a naive caller might try,
672        // exactly like Vault template rendering would (no pre-encoding).
673        let scheme_end = url.find("://").expect("test URL must have a scheme");
674        let (scheme, authority) = url.split_at(scheme_end + 3);
675        let raw_url_with_creds = format!("{scheme}:{password}@{authority}");
676
677        let result = connect(&CacheConfig {
678            url: raw_url_with_creds,
679            pool_size: 1,
680            ca_cert_path: None,
681            password: None,
682        })
683        .await;
684        assert!(
685            result.is_err(),
686            "a raw '?'/'#'-containing password embedded in the URL must not \
687             produce a working connection — this is exactly why VALKEY_PASSWORD exists"
688        );
689    }
690
691    #[tokio::test]
692    async fn valkey_password_handles_a_password_containing_question_mark_or_hash() {
693        // The positive half: the same raw password, supplied out-of-band via
694        // `CacheConfig::password` against a credential-free URL, connects
695        // successfully. This is the feature's whole reason to exist.
696        let Some((url, password)) = unencodable_password_env() else {
697            eprintln!(
698                "skipping: TEST_VALKEY_UNENCODABLE_PASSWORD_URL / TEST_VALKEY_UNENCODABLE_PASSWORD not set"
699            );
700            return;
701        };
702
703        let pool = connect(&CacheConfig {
704            url,
705            pool_size: 2,
706            ca_cert_path: None,
707            password: Some(password),
708        })
709        .await
710        .expect("a password containing '?'/'#' supplied via VALKEY_PASSWORD should connect fine");
711
712        pool.set::<(), _, _>(
713            "ferrlabs-cache:unencodable-password-test",
714            "ok",
715            None,
716            None,
717            false,
718        )
719        .await
720        .expect("SET should succeed");
721        let value: String = pool
722            .get("ferrlabs-cache:unencodable-password-test")
723            .await
724            .expect("GET should succeed");
725        assert_eq!(value, "ok");
726    }
727
728    #[tokio::test]
729    async fn config_password_takes_priority_over_url_credentials() {
730        // If both are present, `password` wins: an intentionally wrong
731        // password in the URL must not prevent a successful connection when
732        // the correct password is supplied via `CacheConfig::password`.
733        let Some((url, password)) = password_env() else {
734            eprintln!("skipping: TEST_VALKEY_PASSWORD_URL / TEST_VALKEY_PASSWORD not set");
735            return;
736        };
737
738        let scheme_end = url.find("://").expect("test URL must have a scheme");
739        let (scheme, authority) = url.split_at(scheme_end + 3);
740        let url_with_wrong_creds = format!("{scheme}:not-the-real-password@{authority}");
741
742        let pool = connect(&CacheConfig {
743            url: url_with_wrong_creds,
744            pool_size: 2,
745            ca_cert_path: None,
746            password: Some(password),
747        })
748        .await
749        .expect("CacheConfig::password must take priority over URL credentials");
750
751        pool.set::<(), _, _>(
752            "ferrlabs-cache:password-priority-test",
753            "ok",
754            None,
755            None,
756            false,
757        )
758        .await
759        .expect("SET should succeed using the out-of-band password");
760        let value: String = pool
761            .get("ferrlabs-cache:password-priority-test")
762            .await
763            .expect("GET should succeed");
764        assert_eq!(value, "ok");
765    }
766
767    // -- Debug redaction: the secret must never reach a log line --
768
769    #[test]
770    fn debug_redacts_password_and_url_credentials() {
771        // A derived `Debug` would print both the `password` field and the
772        // credentials embedded in `url` in the clear, which would defeat the
773        // whole point of keeping the password out of the logs.
774        let config = CacheConfig {
775            url: "redis://:supersecret@host:6379".to_string(),
776            pool_size: 6,
777            ca_cert_path: None,
778            password: Some("supersecret".to_string()),
779        };
780
781        let rendered = format!("{config:?}");
782
783        assert!(
784            !rendered.contains("supersecret"),
785            "Debug must not leak the password (from the field or the URL), got: {rendered}"
786        );
787        assert!(
788            rendered.contains("<redacted>"),
789            "Debug should mark the password as redacted, got: {rendered}"
790        );
791        // The non-secret parts stay useful for debugging.
792        assert!(
793            rendered.contains("host:6379"),
794            "Debug should keep the host for debuggability, got: {rendered}"
795        );
796        assert!(rendered.contains("pool_size: 6"), "got: {rendered}");
797    }
798
799    #[test]
800    fn debug_renders_absent_password_as_none() {
801        let config = CacheConfig {
802            url: "redis://127.0.0.1:6379".to_string(),
803            pool_size: 2,
804            ca_cert_path: Some("/etc/ssl/ca.pem".to_string()),
805            password: None,
806        };
807
808        let rendered = format!("{config:?}");
809
810        assert!(
811            rendered.contains("password: None"),
812            "an absent password should render as None, got: {rendered}"
813        );
814        // A credential-free URL and the CA path are not secrets: keep them.
815        assert!(
816            rendered.contains("redis://127.0.0.1:6379"),
817            "got: {rendered}"
818        );
819        assert!(rendered.contains("/etc/ssl/ca.pem"), "got: {rendered}");
820    }
821
822    #[test]
823    fn debug_redacts_url_whose_password_contains_a_raw_question_mark() {
824        // The pathological form: the '?' inside the password precedes the
825        // real '@', so the userinfo boundary can't be located. `redact_url`
826        // must bail out to a fully redacted value rather than print a prefix
827        // of the password (e.g. "redis://:pa").
828        let config = CacheConfig {
829            url: "redis://:pa?ss#word/x+y=z@127.0.0.1:6379".to_string(),
830            pool_size: 1,
831            ca_cert_path: None,
832            password: None,
833        };
834
835        let rendered = format!("{config:?}");
836
837        // Note: assert on distinctive password substrings only — the field
838        // name "password" itself contains e.g. "pa".
839        for leak in ["pa?ss", "#word", "x+y=z", "pa?"] {
840            assert!(
841                !rendered.contains(leak),
842                "Debug must not leak any part of an unparseable password \
843                 (found {leak:?}), got: {rendered}"
844            );
845        }
846        assert!(rendered.contains("<redacted>"), "got: {rendered}");
847    }
848
849    fn unreachable_config() -> CacheConfig {
850        CacheConfig {
851            url: "redis://127.0.0.1:1".to_string(),
852            pool_size: 2,
853            ca_cert_path: None,
854            password: None,
855        }
856    }
857
858    #[tokio::test]
859    async fn connect_returns_a_pool_when_valkey_is_unreachable() {
860        let started = std::time::Instant::now();
861        let pool = connect(&unreachable_config()).await;
862        assert!(
863            pool.is_ok(),
864            "connect must not fail on an unreachable server"
865        );
866        assert!(
867            started.elapsed() <= INITIAL_CONNECT_WAIT + Duration::from_secs(2),
868            "connect waited {:?}",
869            started.elapsed()
870        );
871    }
872
873    #[tokio::test]
874    async fn pool_keeps_retrying_after_an_unreachable_startup() {
875        let pool = connect(&unreachable_config()).await.expect("pool");
876
877        let second = pool
878            .connect()
879            .await
880            .expect("the connection task must not panic")
881            .expect_err("a live router task refuses a second connect");
882
883        assert_eq!(
884            second.kind(),
885            &ErrorKind::Config,
886            "expected the router task to still hold the command channel, got: {second}"
887        );
888        assert!(
889            second.details().contains("already running"),
890            "expected the router task to still hold the command channel, got: {second}"
891        );
892    }
893
894    #[tokio::test]
895    async fn swr_loads_directly_within_the_command_timeout_when_valkey_is_down() {
896        let pool = connect(&unreachable_config()).await.expect("pool");
897        let swr = Swr {
898            pool: &pool,
899            key: "test:unreachable",
900            fresh_ttl: Duration::from_secs(30),
901            hard_ttl: Duration::from_secs(300),
902            lock_ttl: Duration::from_secs(30),
903            bypass: false,
904        };
905        let started = std::time::Instant::now();
906        let value: u32 = swr
907            .get_or_load(|| async { Ok(42) })
908            .await
909            .expect("loader value");
910        assert_eq!(value, 42);
911        assert!(
912            started.elapsed() <= COMMAND_TIMEOUT * 3,
913            "fallback took {:?}",
914            started.elapsed()
915        );
916    }
917
918    #[test]
919    fn network_failures_are_transient() {
920        for kind in [
921            std::io::ErrorKind::ConnectionRefused,
922            std::io::ErrorKind::TimedOut,
923            std::io::ErrorKind::ConnectionReset,
924        ] {
925            assert!(
926                is_transient(&Error::from(std::io::Error::from(kind))),
927                "{kind:?}"
928            );
929        }
930        assert!(is_transient(&Error::new(ErrorKind::Timeout, "timed out")));
931    }
932
933    #[test]
934    fn misconfiguration_is_not_transient() {
935        let bad_certificate = std::io::Error::new(
936            std::io::ErrorKind::InvalidData,
937            fred::rustls::Error::InvalidCertificate(fred::rustls::CertificateError::UnknownIssuer),
938        );
939        assert!(!is_transient(&Error::from(bad_certificate)));
940        assert!(!is_transient(&Error::new(ErrorKind::Auth, "WRONGPASS")));
941        assert!(!is_transient(&Error::new(
942            ErrorKind::Tls,
943            "invalid configuration"
944        )));
945        assert!(!is_transient(&Error::new(ErrorKind::Url, "invalid url")));
946    }
947}