use std::time::Duration;
use fred::prelude::*;
pub use fred;
mod swr;
pub use swr::Swr;
#[derive(Clone)]
pub struct CacheConfig {
pub url: String,
pub pool_size: usize,
pub ca_cert_path: Option<String>,
pub password: Option<String>,
}
fn redact_url(url: &str) -> String {
let Some(scheme_end) = url.find("://") else {
return "<redacted>".to_string();
};
let (scheme, rest) = url.split_at(scheme_end + 3);
let search_end = rest.find(['?', '#']).unwrap_or(rest.len());
let after_userinfo = match rest[..search_end].rfind('@') {
Some(at_pos) => &rest[at_pos + 1..],
None if rest.contains('@') => {
return format!("{scheme}<redacted>");
}
None => rest,
};
let host_end = after_userinfo
.find(['/', '?', '#'])
.unwrap_or(after_userinfo.len());
format!("{scheme}{}", &after_userinfo[..host_end])
}
impl std::fmt::Debug for CacheConfig {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("CacheConfig")
.field("url", &redact_url(&self.url))
.field("pool_size", &self.pool_size)
.field("ca_cert_path", &self.ca_cert_path)
.field("password", &self.password.as_ref().map(|_| "<redacted>"))
.finish()
}
}
impl CacheConfig {
pub fn from_env() -> anyhow::Result<Self> {
let url = std::env::var("VALKEY_URL")
.or_else(|_| std::env::var("REDIS_URL"))
.map_err(|_| anyhow::anyhow!("VALKEY_URL (or REDIS_URL) not set"))?;
let pool_size = std::env::var("VALKEY_POOL_SIZE")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(6);
let ca_cert_path = std::env::var("VALKEY_CA_CERT").ok();
let password = std::env::var("VALKEY_PASSWORD")
.ok()
.filter(|v| !v.is_empty());
Ok(Self {
url,
pool_size,
ca_cert_path,
password,
})
}
}
pub type CachePool = Pool;
const RECONNECT_MIN_DELAY_MS: u32 = 100;
const RECONNECT_MAX_DELAY_MS: u32 = 30_000;
const COMMAND_TIMEOUT: Duration = Duration::from_secs(1);
const INITIAL_CONNECT_WAIT: Duration = Duration::from_secs(5);
fn percent_encode_userinfo(url: &str) -> String {
let Some(scheme_end) = url.find("://") else {
return url.to_string();
};
let (scheme, rest) = url.split_at(scheme_end + 3);
let search_end = rest.find(['?', '#']).unwrap_or(rest.len());
let Some(at_pos) = rest[..search_end].rfind('@') else {
return url.to_string();
};
let (userinfo, after_at) = rest.split_at(at_pos);
let after_at = &after_at[1..];
let host_end = after_at.find(['/', '?', '#']).unwrap_or(after_at.len());
let (host_part, tail) = after_at.split_at(host_end);
let encode_set: &percent_encoding::AsciiSet = percent_encoding::NON_ALPHANUMERIC;
if let Some((user, pass)) = userinfo.split_once(':') {
let enc_user = percent_encoding::utf8_percent_encode(user, encode_set);
let enc_pass = percent_encoding::utf8_percent_encode(pass, encode_set);
format!("{scheme}{enc_user}:{enc_pass}@{host_part}{tail}")
} else {
let enc_user = percent_encoding::utf8_percent_encode(userinfo, encode_set);
format!("{scheme}{enc_user}@{host_part}{tail}")
}
}
fn rustls_config_with_ca(ca_cert_path: &str) -> anyhow::Result<fred::rustls::ClientConfig> {
let pem_bytes = std::fs::read(ca_cert_path)
.map_err(|e| anyhow::anyhow!("failed to read VALKEY_CA_CERT ({ca_cert_path}): {e}"))?;
let mut reader = std::io::BufReader::new(pem_bytes.as_slice());
let certs: Vec<_> = rustls_pemfile::certs(&mut reader)
.collect::<Result<_, _>>()
.map_err(|e| anyhow::anyhow!("failed to parse VALKEY_CA_CERT PEM: {e}"))?;
if certs.is_empty() {
anyhow::bail!("VALKEY_CA_CERT ({ca_cert_path}) contains no certificates");
}
let mut roots = fred::rustls::RootCertStore::empty();
for cert in certs {
roots
.add(cert)
.map_err(|e| anyhow::anyhow!("invalid CA certificate in VALKEY_CA_CERT: {e}"))?;
}
Ok(fred::rustls::ClientConfig::builder()
.with_root_certificates(roots)
.with_no_client_auth())
}
const TRANSIENT_IO_ERRORS: &[&str] = &[
"ConnectionRefused",
"ConnectionReset",
"ConnectionAborted",
"TimedOut",
"HostUnreachable",
"NetworkUnreachable",
"NotConnected",
"BrokenPipe",
"UnexpectedEof",
"failed to lookup address",
];
fn is_transient(error: &Error) -> bool {
match error.kind() {
ErrorKind::Timeout | ErrorKind::Canceled => true,
ErrorKind::IO => TRANSIENT_IO_ERRORS
.iter()
.any(|kind| error.details().contains(kind)),
_ => false,
}
}
pub async fn connect(config: &CacheConfig) -> anyhow::Result<CachePool> {
let sanitized_url = percent_encode_userinfo(&config.url);
let mut cfg =
Config::from_url(&sanitized_url).map_err(|e| anyhow::anyhow!("invalid VALKEY_URL: {e}"))?;
if let Some(password) = &config.password {
cfg.password = Some(password.clone());
}
let tls_enabled = config.url.starts_with("rediss://");
if tls_enabled {
if let Some(ca_cert_path) = &config.ca_cert_path {
let client_config = rustls_config_with_ca(ca_cert_path)?;
cfg.tls = Some(client_config.into());
}
}
let performance = PerformanceConfig {
default_command_timeout: COMMAND_TIMEOUT,
..PerformanceConfig::default()
};
let reconnect =
ReconnectPolicy::new_exponential(0, RECONNECT_MIN_DELAY_MS, RECONNECT_MAX_DELAY_MS, 2);
let build = |cfg: Config| {
Pool::new(
cfg,
Some(performance.clone()),
None,
Some(reconnect.clone()),
config.pool_size,
)
.map_err(|e| anyhow::anyhow!("failed to build Valkey pool: {e}"))
};
let probe = build(cfg.clone())?;
let _handle = probe.connect();
match tokio::time::timeout(INITIAL_CONNECT_WAIT, probe.wait_for_connect()).await {
Ok(Ok(())) => {
tracing::info!(
pool_size = config.pool_size,
tls = tls_enabled,
"connected to Valkey"
);
return Ok(probe);
}
Ok(Err(e)) if !is_transient(&e) => {
let _ = probe.quit().await;
return Err(anyhow::anyhow!("Valkey connect failed: {e}"));
}
Ok(Err(e)) => tracing::warn!(
error = %e,
"Valkey unreachable at startup, reconnecting in the background"
),
Err(_) => tracing::warn!(
wait_secs = INITIAL_CONNECT_WAIT.as_secs(),
"Valkey not connected yet, reconnecting in the background"
),
}
let _ = probe.quit().await;
cfg.fail_fast = false;
let pool = build(cfg)?;
let _handle = pool.connect();
Ok(pool)
}
#[cfg(test)]
mod tests {
use super::*;
use fred::interfaces::KeysInterface;
fn tls_env() -> Option<(String, String)> {
let url = std::env::var("TEST_VALKEY_TLS_URL").ok()?;
let ca = std::env::var("TEST_VALKEY_TLS_CA").ok()?;
Some((url, ca))
}
#[tokio::test]
async fn connects_over_tls_with_valid_ca() {
let Some((url, ca_cert_path)) = tls_env() else {
eprintln!("skipping: TEST_VALKEY_TLS_URL / TEST_VALKEY_TLS_CA not set");
return;
};
let pool = connect(&CacheConfig {
url,
pool_size: 2,
ca_cert_path: Some(ca_cert_path),
password: None,
})
.await
.expect("expected TLS connect with valid CA to succeed");
pool.set::<(), _, _>("ferrlabs-cache:tls-test", "ok", None, None, false)
.await
.expect("SET over TLS should succeed");
let value: String = pool
.get("ferrlabs-cache:tls-test")
.await
.expect("GET over TLS should succeed");
assert_eq!(value, "ok");
}
#[tokio::test]
async fn rejects_tls_connection_without_trusted_ca() {
let Some((url, _)) = tls_env() else {
eprintln!("skipping: TEST_VALKEY_TLS_URL / TEST_VALKEY_TLS_CA not set");
return;
};
let result = tokio::time::timeout(
std::time::Duration::from_secs(10),
connect(&CacheConfig {
url,
pool_size: 1,
ca_cert_path: None,
password: None,
}),
)
.await;
if let Ok(connect_result) = result {
assert!(
connect_result.is_err(),
"connecting over TLS without a trusted CA must fail"
);
}
}
#[tokio::test]
async fn rejects_wrong_explicit_ca() {
let Some((url, _)) = tls_env() else {
eprintln!("skipping: TEST_VALKEY_TLS_URL / TEST_VALKEY_TLS_CA not set");
return;
};
let Ok(wrong_ca) = std::env::var("TEST_VALKEY_TLS_WRONG_CA") else {
eprintln!("skipping: TEST_VALKEY_TLS_WRONG_CA not set");
return;
};
let result = tokio::time::timeout(
std::time::Duration::from_secs(10),
connect(&CacheConfig {
url,
pool_size: 1,
ca_cert_path: Some(wrong_ca),
password: None,
}),
)
.await;
if let Ok(connect_result) = result {
assert!(
connect_result.is_err(),
"connecting over TLS with a non-signing CA must fail"
);
}
}
#[test]
fn percent_encode_userinfo_splits_on_last_at_for_password_containing_at() {
let raw = "redis://:ab@cd@127.0.0.1:6379";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "redis://:ab%40cd@127.0.0.1:6379");
}
#[test]
fn percent_encode_userinfo_splits_on_first_colon_for_password_containing_colon() {
let raw = "redis://:ab:cd@127.0.0.1:6379";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "redis://:ab%3Acd@127.0.0.1:6379");
}
#[test]
fn percent_encode_userinfo_encodes_percent_sign_itself() {
let raw = "redis://:ab%cd@127.0.0.1:6379";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "redis://:ab%25cd@127.0.0.1:6379");
}
#[test]
fn percent_encode_userinfo_covers_slash_plus_equals() {
let raw = "redis://:ab/cd+ef=gh@127.0.0.1:6379";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "redis://:ab%2Fcd%2Bef%3Dgh@127.0.0.1:6379");
}
#[test]
fn percent_encode_userinfo_leaves_url_without_userinfo_unchanged() {
let raw = "redis://127.0.0.1:6379";
assert_eq!(percent_encode_userinfo(raw), raw);
}
#[test]
fn percent_encode_userinfo_preserves_db_index_path() {
let raw = "redis://:ab/cd@127.0.0.1:6379/0";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "redis://:ab%2Fcd@127.0.0.1:6379/0");
}
#[test]
fn percent_encode_userinfo_ignores_at_sign_outside_the_authority() {
let raw = "redis://:pw@127.0.0.1:6379/0?note=a@b";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "redis://:pw@127.0.0.1:6379/0?note=a@b");
let parsed = Config::from_url(&sanitized).expect("should parse");
let host = &parsed.server.hosts()[0];
assert_eq!(&*host.host, "127.0.0.1");
assert_eq!(host.port, 6379);
}
#[test]
fn percent_encode_userinfo_handles_slash_password_together_with_path_and_query() {
let raw = "redis://:ab/cd+ef=gh@127.0.0.1:6379/0?note=a@b";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(
sanitized,
"redis://:ab%2Fcd%2Bef%3Dgh@127.0.0.1:6379/0?note=a@b"
);
let parsed = Config::from_url(&sanitized).expect("should parse");
let host = &parsed.server.hosts()[0];
assert_eq!(&*host.host, "127.0.0.1");
assert_eq!(host.port, 6379);
}
#[test]
fn percent_encode_userinfo_leaves_url_without_userinfo_but_with_path_query_unchanged() {
let raw = "redis://127.0.0.1:6379/0?x=1@2";
assert_eq!(percent_encode_userinfo(raw), raw);
}
#[test]
fn percent_encode_userinfo_preserves_rediss_scheme() {
let raw = "rediss://:ab/cd@127.0.0.1:6380";
let sanitized = percent_encode_userinfo(raw);
assert_eq!(sanitized, "rediss://:ab%2Fcd@127.0.0.1:6380");
}
fn url_safe_password_env() -> Option<String> {
std::env::var("TEST_VALKEY_URL_SAFE_PASSWORD_URL").ok()
}
#[tokio::test]
async fn connects_with_raw_password_containing_url_breaking_characters() {
let Some(url) = url_safe_password_env() else {
eprintln!("skipping: TEST_VALKEY_URL_SAFE_PASSWORD_URL not set");
return;
};
let pool = connect(&CacheConfig {
url,
pool_size: 2,
ca_cert_path: None,
password: None,
})
.await
.expect("connect with a raw URL-breaking password should succeed");
pool.set::<(), _, _>("ferrlabs-cache:url-safe-pw-test", "ok", None, None, false)
.await
.expect("SET should succeed once AUTH has decoded the real password");
let value: String = pool
.get("ferrlabs-cache:url-safe-pw-test")
.await
.expect("GET should succeed");
assert_eq!(value, "ok");
}
fn password_env() -> Option<(String, String)> {
let url = std::env::var("TEST_VALKEY_PASSWORD_URL").ok()?;
let password = std::env::var("TEST_VALKEY_PASSWORD").ok()?;
Some((url, password))
}
#[tokio::test]
async fn connects_with_password_supplied_out_of_band() {
let Some((url, password)) = password_env() else {
eprintln!("skipping: TEST_VALKEY_PASSWORD_URL / TEST_VALKEY_PASSWORD not set");
return;
};
let pool = connect(&CacheConfig {
url,
pool_size: 2,
ca_cert_path: None,
password: Some(password),
})
.await
.expect("connect with password supplied via CacheConfig::password should succeed");
pool.set::<(), _, _>(
"ferrlabs-cache:password-field-test",
"ok",
None,
None,
false,
)
.await
.expect("SET should succeed once AUTH has used the out-of-band password");
let value: String = pool
.get("ferrlabs-cache:password-field-test")
.await
.expect("GET should succeed");
assert_eq!(value, "ok");
}
fn unencodable_password_env() -> Option<(String, String)> {
let url = std::env::var("TEST_VALKEY_UNENCODABLE_PASSWORD_URL").ok()?;
let password = std::env::var("TEST_VALKEY_UNENCODABLE_PASSWORD").ok()?;
Some((url, password))
}
#[tokio::test]
async fn url_with_credentials_cannot_represent_a_password_containing_question_mark_or_hash() {
let Some((url, password)) = unencodable_password_env() else {
eprintln!(
"skipping: TEST_VALKEY_UNENCODABLE_PASSWORD_URL / TEST_VALKEY_UNENCODABLE_PASSWORD not set"
);
return;
};
let scheme_end = url.find("://").expect("test URL must have a scheme");
let (scheme, authority) = url.split_at(scheme_end + 3);
let raw_url_with_creds = format!("{scheme}:{password}@{authority}");
let result = connect(&CacheConfig {
url: raw_url_with_creds,
pool_size: 1,
ca_cert_path: None,
password: None,
})
.await;
assert!(
result.is_err(),
"a raw '?'/'#'-containing password embedded in the URL must not \
produce a working connection — this is exactly why VALKEY_PASSWORD exists"
);
}
#[tokio::test]
async fn valkey_password_handles_a_password_containing_question_mark_or_hash() {
let Some((url, password)) = unencodable_password_env() else {
eprintln!(
"skipping: TEST_VALKEY_UNENCODABLE_PASSWORD_URL / TEST_VALKEY_UNENCODABLE_PASSWORD not set"
);
return;
};
let pool = connect(&CacheConfig {
url,
pool_size: 2,
ca_cert_path: None,
password: Some(password),
})
.await
.expect("a password containing '?'/'#' supplied via VALKEY_PASSWORD should connect fine");
pool.set::<(), _, _>(
"ferrlabs-cache:unencodable-password-test",
"ok",
None,
None,
false,
)
.await
.expect("SET should succeed");
let value: String = pool
.get("ferrlabs-cache:unencodable-password-test")
.await
.expect("GET should succeed");
assert_eq!(value, "ok");
}
#[tokio::test]
async fn config_password_takes_priority_over_url_credentials() {
let Some((url, password)) = password_env() else {
eprintln!("skipping: TEST_VALKEY_PASSWORD_URL / TEST_VALKEY_PASSWORD not set");
return;
};
let scheme_end = url.find("://").expect("test URL must have a scheme");
let (scheme, authority) = url.split_at(scheme_end + 3);
let url_with_wrong_creds = format!("{scheme}:not-the-real-password@{authority}");
let pool = connect(&CacheConfig {
url: url_with_wrong_creds,
pool_size: 2,
ca_cert_path: None,
password: Some(password),
})
.await
.expect("CacheConfig::password must take priority over URL credentials");
pool.set::<(), _, _>(
"ferrlabs-cache:password-priority-test",
"ok",
None,
None,
false,
)
.await
.expect("SET should succeed using the out-of-band password");
let value: String = pool
.get("ferrlabs-cache:password-priority-test")
.await
.expect("GET should succeed");
assert_eq!(value, "ok");
}
#[test]
fn debug_redacts_password_and_url_credentials() {
let config = CacheConfig {
url: "redis://:supersecret@host:6379".to_string(),
pool_size: 6,
ca_cert_path: None,
password: Some("supersecret".to_string()),
};
let rendered = format!("{config:?}");
assert!(
!rendered.contains("supersecret"),
"Debug must not leak the password (from the field or the URL), got: {rendered}"
);
assert!(
rendered.contains("<redacted>"),
"Debug should mark the password as redacted, got: {rendered}"
);
assert!(
rendered.contains("host:6379"),
"Debug should keep the host for debuggability, got: {rendered}"
);
assert!(rendered.contains("pool_size: 6"), "got: {rendered}");
}
#[test]
fn debug_renders_absent_password_as_none() {
let config = CacheConfig {
url: "redis://127.0.0.1:6379".to_string(),
pool_size: 2,
ca_cert_path: Some("/etc/ssl/ca.pem".to_string()),
password: None,
};
let rendered = format!("{config:?}");
assert!(
rendered.contains("password: None"),
"an absent password should render as None, got: {rendered}"
);
assert!(
rendered.contains("redis://127.0.0.1:6379"),
"got: {rendered}"
);
assert!(rendered.contains("/etc/ssl/ca.pem"), "got: {rendered}");
}
#[test]
fn debug_redacts_url_whose_password_contains_a_raw_question_mark() {
let config = CacheConfig {
url: "redis://:pa?ss#word/x+y=z@127.0.0.1:6379".to_string(),
pool_size: 1,
ca_cert_path: None,
password: None,
};
let rendered = format!("{config:?}");
for leak in ["pa?ss", "#word", "x+y=z", "pa?"] {
assert!(
!rendered.contains(leak),
"Debug must not leak any part of an unparseable password \
(found {leak:?}), got: {rendered}"
);
}
assert!(rendered.contains("<redacted>"), "got: {rendered}");
}
fn unreachable_config() -> CacheConfig {
CacheConfig {
url: "redis://127.0.0.1:1".to_string(),
pool_size: 2,
ca_cert_path: None,
password: None,
}
}
#[tokio::test]
async fn connect_returns_a_pool_when_valkey_is_unreachable() {
let started = std::time::Instant::now();
let pool = connect(&unreachable_config()).await;
assert!(
pool.is_ok(),
"connect must not fail on an unreachable server"
);
assert!(
started.elapsed() <= INITIAL_CONNECT_WAIT + Duration::from_secs(2),
"connect waited {:?}",
started.elapsed()
);
}
#[tokio::test]
async fn pool_keeps_retrying_after_an_unreachable_startup() {
let pool = connect(&unreachable_config()).await.expect("pool");
let second = pool
.connect()
.await
.expect("the connection task must not panic")
.expect_err("a live router task refuses a second connect");
assert_eq!(
second.kind(),
&ErrorKind::Config,
"expected the router task to still hold the command channel, got: {second}"
);
assert!(
second.details().contains("already running"),
"expected the router task to still hold the command channel, got: {second}"
);
}
#[tokio::test]
async fn swr_loads_directly_within_the_command_timeout_when_valkey_is_down() {
let pool = connect(&unreachable_config()).await.expect("pool");
let swr = Swr {
pool: &pool,
key: "test:unreachable",
fresh_ttl: Duration::from_secs(30),
hard_ttl: Duration::from_secs(300),
lock_ttl: Duration::from_secs(30),
bypass: false,
};
let started = std::time::Instant::now();
let value: u32 = swr
.get_or_load(|| async { Ok(42) })
.await
.expect("loader value");
assert_eq!(value, 42);
assert!(
started.elapsed() <= COMMAND_TIMEOUT * 3,
"fallback took {:?}",
started.elapsed()
);
}
#[test]
fn network_failures_are_transient() {
for kind in [
std::io::ErrorKind::ConnectionRefused,
std::io::ErrorKind::TimedOut,
std::io::ErrorKind::ConnectionReset,
] {
assert!(
is_transient(&Error::from(std::io::Error::from(kind))),
"{kind:?}"
);
}
assert!(is_transient(&Error::new(ErrorKind::Timeout, "timed out")));
}
#[test]
fn misconfiguration_is_not_transient() {
let bad_certificate = std::io::Error::new(
std::io::ErrorKind::InvalidData,
fred::rustls::Error::InvalidCertificate(fred::rustls::CertificateError::UnknownIssuer),
);
assert!(!is_transient(&Error::from(bad_certificate)));
assert!(!is_transient(&Error::new(ErrorKind::Auth, "WRONGPASS")));
assert!(!is_transient(&Error::new(
ErrorKind::Tls,
"invalid configuration"
)));
assert!(!is_transient(&Error::new(ErrorKind::Url, "invalid url")));
}
}