Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

18.8 KB
Raw Blame
use async_trait::async_trait;
use std::sync::Arc;
use thiserror::Error;

// Re-export ErrorKind and RetryMethod so consumers can construct CustomRedisError in tests
// and understand retry behavior
pub use redis::ErrorKind as RedisErrorKind;
pub use redis::RetryMethod;

// Re-export pipeline types
pub use pipeline::{Pipeline, PipelineCommand, PipelineResult};

// ClientPipelineExt is defined later in this file after the Client trait

#[derive(Error, Debug, Clone)]
pub enum CustomRedisError {
    #[error("Not found in redis")]
    NotFound,
    #[error("Invalid configuration: {0}")]
    InvalidConfiguration(String),
    #[error("Parse error: {0}")]
    ParseError(String),
    #[error("Timeout error")]
    Timeout,
    #[error(transparent)]
    Redis(#[from] Arc<redis::RedisError>),
}

impl From<serde_pickle::Error> for CustomRedisError {
    fn from(err: serde_pickle::Error) -> Self {
        CustomRedisError::ParseError(err.to_string())
    }
}

impl From<redis::RedisError> for CustomRedisError {
    fn from(err: redis::RedisError) -> Self {
        if err.is_timeout() {
            CustomRedisError::Timeout
        } else {
            CustomRedisError::Redis(Arc::new(err))
        }
    }
}

impl From<std::string::FromUtf8Error> for CustomRedisError {
    fn from(err: std::string::FromUtf8Error) -> Self {
        CustomRedisError::ParseError(err.to_string())
    }
}

impl CustomRedisError {
    /// Create a Redis error from an ErrorKind (primarily for testing)
    pub fn from_redis_kind(kind: redis::ErrorKind, description: &'static str) -> Self {
        CustomRedisError::Redis(Arc::new(redis::RedisError::from((kind, description))))
    }

    /// Determine if this error is unrecoverable and should not be retried
    ///
    /// Returns `true` for configuration errors and permanent failures.
    /// Returns `false` for transient network/connection issues that may resolve on retry.
    ///
    /// Delegates to redis crate's `is_unrecoverable_error()` for Redis errors.
    pub fn is_unrecoverable_error(&self) -> bool {
        match self {
            // Timeouts are transient - not unrecoverable
            CustomRedisError::Timeout => false,

            // Configuration errors are permanent - unrecoverable
            CustomRedisError::InvalidConfiguration(_) => true,

            // Parse errors are permanent bugs - unrecoverable
            CustomRedisError::ParseError(_) => true,

            // NotFound is permanent - caller should handle this
            CustomRedisError::NotFound => true,

            // For Redis errors, check for specific unrecoverable kinds first
            CustomRedisError::Redis(err) => {
                Self::is_config_error(err) || err.is_unrecoverable_error()
            }
        }
    }

    /// Check if a Redis error is a configuration error that should never be retried
    fn is_config_error(err: &redis::RedisError) -> bool {
        matches!(
            err.kind(),
            redis::ErrorKind::InvalidClientConfig | redis::ErrorKind::AuthenticationFailed
        )
    }

    /// Determine the appropriate retry strategy for this error
    ///
    /// Returns a `RetryMethod` indicating how (if at all) this request should be retried.
    /// Delegates to redis crate's `retry_method()` for Redis errors.
    ///
    /// # Retry Methods
    /// - `NoRetry` - Permanent error, don't retry
    /// - `RetryImmediately` - Temporary issue, retry right away
    /// - `WaitAndRetry` - Sleep first to avoid overload
    /// - `Reconnect` - Create fresh connection (current is broken)
    /// - `MovedRedirect` / `AskRedirect` - Cluster-specific redirections
    pub fn retry_method(&self) -> RetryMethod {
        match self {
            // Timeouts: wait before retrying to avoid hammering the service
            CustomRedisError::Timeout => RetryMethod::WaitAndRetry,

            // Configuration errors are permanent - don't retry
            CustomRedisError::InvalidConfiguration(_) => RetryMethod::NoRetry,

            // Parse errors are permanent bugs - don't retry
            CustomRedisError::ParseError(_) => RetryMethod::NoRetry,

            // NotFound is permanent - caller should handle this
            CustomRedisError::NotFound => RetryMethod::NoRetry,

            // For Redis errors, check for specific non-retryable kinds first
            CustomRedisError::Redis(err) => {
                if Self::is_config_error(err) {
                    RetryMethod::NoRetry
                } else {
                    err.retry_method()
                }
            }
        }
    }
}

impl From<std::io::Error> for CustomRedisError {
    fn from(err: std::io::Error) -> Self {
        CustomRedisError::ParseError(format!("Compression error: {err}"))
    }
}

/// Configuration for zstd compression behavior
///
/// Mimics Django's ZstdCompressor configuration:
/// - Compresses values larger than threshold (default 512 bytes)
/// - Uses zstd compression level 0 (default preset, equivalent to level 3)
/// - Gracefully handles both compressed and uncompressed data on read
#[derive(Debug, Clone)]
pub struct CompressionConfig {
    /// Whether compression is enabled
    pub enabled: bool,
    /// Minimum size in bytes before compression is applied
    /// Django default: 512 bytes (ZstdCompressor.min_length)
    pub threshold: usize,
    /// Zstd compression level (1-22, or 0 for default)
    /// - Level 0: Use default preset (typically level 3) - Django default
    /// - Level 1-3: Fast compression, lower ratio
    /// - Level 4-9: Balanced compression
    /// - Level 10-15: High compression, slower
    /// - Level 16-22: Maximum compression, very slow
    pub level: i32,
}

impl Default for CompressionConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            threshold: 512, // Match Django's ZstdCompressor.min_length
            level: 0,       // Match Django's zstd_preset (default)
        }
    }
}

impl CompressionConfig {
    /// Create a new compression configuration
    pub fn new(enabled: bool, threshold: usize, level: i32) -> Self {
        Self {
            enabled,
            threshold,
            level,
        }
    }

    /// Create a configuration with compression disabled
    pub fn disabled() -> Self {
        Self {
            enabled: false,
            threshold: 0,
            level: 0,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum RedisValueFormat {
    #[default]
    Pickle,
    Utf8,
    RawBytes,
}

#[async_trait]
pub trait Client: Send + Sync {
    async fn zrangebyscore(
        &self,
        k: String,
        min: String,
        max: String,
    ) -> Result<Vec<String>, CustomRedisError>;

    /// `ZRANGEBYSCORE ... LIMIT offset count`: one page of a sorted set, so a
    /// large set can be read without one reply that holds every member.
    async fn zrangebyscore_limit(
        &self,
        k: String,
        min: String,
        max: String,
        offset: isize,
        count: isize,
    ) -> Result<Vec<String>, CustomRedisError>;

    /// Add a single (member, score) pair to a sorted set.
    async fn zadd(&self, k: String, member: String, score: i64) -> Result<(), CustomRedisError>;

    /// Add a (member, score) pair only when the member is absent, so repeated writes keep
    /// the first score. `zadd` overwrites it.
    async fn zadd_nx(&self, k: String, member: String, score: i64) -> Result<(), CustomRedisError>;

    async fn zrem(&self, k: String, member: String) -> Result<(), CustomRedisError>;

    async fn hincrby(&self, k: String, v: String, count: i64) -> Result<(), CustomRedisError>;

    async fn get(&self, k: String) -> Result<String, CustomRedisError>;
    async fn get_with_format(
        &self,
        k: String,
        format: RedisValueFormat,
    ) -> Result<String, CustomRedisError>;
    async fn get_raw_bytes(&self, k: String) -> Result<Vec<u8>, CustomRedisError>;
    /// Set raw bytes directly without any serialization or compression.
    /// Used primarily for tests that need to write pickle-formatted data.
    async fn set_bytes(
        &self,
        k: String,
        v: Vec<u8>,
        ttl_seconds: Option<u64>,
    ) -> Result<(), CustomRedisError>;
    async fn set(&self, k: String, v: String) -> Result<(), CustomRedisError>;
    async fn set_with_format(
        &self,
        k: String,
        v: String,
        format: RedisValueFormat,
    ) -> Result<(), CustomRedisError>;
    async fn setex(&self, k: String, v: String, seconds: u64) -> Result<(), CustomRedisError>;
    async fn setex_with_format(
        &self,
        k: String,
        v: String,
        seconds: u64,
        format: RedisValueFormat,
    ) -> Result<(), CustomRedisError>;
    async fn set_nx_ex(&self, k: String, v: String, seconds: u64)
        -> Result<bool, CustomRedisError>;
    async fn set_nx_ex_with_format(
        &self,
        k: String,
        v: String,
        seconds: u64,
        format: RedisValueFormat,
    ) -> Result<bool, CustomRedisError>;
    async fn batch_incr_by_expire_nx(
        &self,
        items: Vec<(String, i64)>,
        ttl_seconds: usize,
    ) -> Result<(), CustomRedisError>;

    /// Like batch_incr_by_expire_nx but always sets the TTL (no NX flag).
    /// Compatible with Redis 6.x which doesn't support EXPIRE ... NX.
    async fn batch_incr_by_expire(
        &self,
        items: Vec<(String, i64)>,
        ttl_seconds: usize,
    ) -> Result<(), CustomRedisError>;

    /// Increment each key and set its expiry to an absolute unix second, as
    /// `(key, increment, expire_at)`.
    ///
    /// Prefer this over `batch_incr_by_expire` when the key fixes its own
    /// deadline; do not add `NX`, which needs Redis 7 and buys nothing here.
    async fn batch_incr_by_expire_at(
        &self,
        items: Vec<(String, i64, i64)>,
    ) -> Result<(), CustomRedisError>;

    async fn del(&self, k: String) -> Result<(), CustomRedisError>;
    async fn hget(&self, k: String, field: String) -> Result<String, CustomRedisError>;
    async fn scard(&self, k: String) -> Result<u64, CustomRedisError>;
    async fn mget(&self, keys: Vec<String>) -> Result<Vec<Option<Vec<u8>>>, CustomRedisError>;
    async fn scard_multiple(&self, keys: Vec<String>) -> Result<Vec<u64>, CustomRedisError>;
    async fn batch_sadd_expire(
        &self,
        items: Vec<(String, String)>,
        ttl_seconds: usize,
    ) -> Result<(), CustomRedisError>;
    async fn batch_set_nx_ex(
        &self,
        items: Vec<(String, String, usize)>, // (key, value, ttl_seconds)
    ) -> Result<Vec<bool>, CustomRedisError>;
    async fn batch_del(&self, keys: Vec<String>) -> Result<(), CustomRedisError>;
    /// Execute a batch of pipeline commands atomically in a single round-trip.
    ///
    /// Commands are wrapped in `MULTI`/`EXEC`, so either every command commits
    /// or none do. A connection drop, server hangup, or read timeout after the
    /// pipeline is sent leaves Redis in its prior state — there is no
    /// partial-commit window that would surface as `Err` here while some
    /// commands had already taken effect server-side. This matters for
    /// non-idempotent operations (e.g. `HINCRBY`) where a retry on `Err`
    /// would otherwise risk double-counting.
    ///
    /// Returns a vector of results, one for each command in the same order.
    /// The outer Result is for connection-level errors, inner Results are per-command.
    async fn execute_pipeline(
        &self,
        commands: Vec<PipelineCommand>,
    ) -> Result<Vec<Result<PipelineResult, CustomRedisError>>, CustomRedisError>;

    /// Attempt to repair a dead underlying connection.
    ///
    /// Callers that see `CustomRedisError::is_unrecoverable_error()` may call
    /// this; implementations that self-heal (or have nothing to heal) keep the
    /// default no-op. Must be cheap to call repeatedly -- implementations own
    /// their own cooldown.
    async fn heal(&self) {}

    /// Return whether a fresh connection replaced the old one. Test clients do not reconnect.
    async fn reconnect(&self) -> bool {
        false
    }
}

/// Extension trait providing the `.pipeline()` builder method.
///
/// Requires `Clone` because the client is cloned into the Pipeline builder.
/// For trait objects (`dyn Client`), call `execute_pipeline()` directly instead.
pub trait ClientPipelineExt: Client + Clone {
    /// Create a new pipeline for batching multiple Redis commands.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use common_redis::{Client, ClientPipelineExt, PipelineResult};
    ///
    /// async fn example(client: &impl ClientPipelineExt) {
    ///     let results = client.pipeline()
    ///         .set("key1", "value1")
    ///         .set("key2", "value2")
    ///         .get("key3")
    ///         .execute()
    ///         .await
    ///         .unwrap();
    /// }
    /// ```
    fn pipeline(&self) -> Pipeline<Self> {
        Pipeline::new(self.clone())
    }
}

// Blanket implementation for all types that implement Client and Clone
impl<T: Client + Clone> ClientPipelineExt for T {}

// Module declarations
mod client;
mod mock;
mod pipeline;
mod read_write;

// Re-export public APIs
pub use client::{RedisClient, ScriptRunner};
pub use mock::{MockRedisCall, MockRedisClient, MockRedisValue};
pub use read_write::{ReadWriteClient, ReadWriteClientConfig};

#[cfg(test)]
mod tests {
    use super::*;

    mod error_transience {
        use super::*;

        // Tests for our custom error variants
        #[test]
        fn test_timeout_is_recoverable() {
            let err = CustomRedisError::Timeout;
            assert!(!err.is_unrecoverable_error());
        }

        #[test]
        fn test_parse_error_is_unrecoverable() {
            let err = CustomRedisError::ParseError("invalid data".to_string());
            assert!(err.is_unrecoverable_error());
        }

        #[test]
        fn test_not_found_is_unrecoverable() {
            let err = CustomRedisError::NotFound;
            assert!(err.is_unrecoverable_error());
        }

        #[test]
        fn test_invalid_configuration_is_unrecoverable() {
            let err = CustomRedisError::InvalidConfiguration("test config error".to_string());
            assert!(err.is_unrecoverable_error());
        }

        // Smoke test: verify we delegate to redis::RedisError instead of reimplementing
        #[test]
        fn test_redis_error_delegation() {
            let custom_err = CustomRedisError::Redis(Arc::new(redis::RedisError::from((
                redis::ErrorKind::IoError,
                "test error",
            ))));
            let redis_err = redis::RedisError::from((redis::ErrorKind::IoError, "test error"));

            // Verify delegation works by comparing with direct redis::RedisError behavior
            assert_eq!(
                custom_err.is_unrecoverable_error(),
                redis_err.is_unrecoverable_error()
            );
        }
    }

    mod retry_methods {
        use super::*;

        // Tests for our custom error variants
        #[test]
        fn test_timeout_wait_and_retry() {
            let err = CustomRedisError::Timeout;
            assert!(matches!(err.retry_method(), RetryMethod::WaitAndRetry));
        }

        #[test]
        fn test_parse_error_no_retry() {
            let err = CustomRedisError::ParseError("invalid data".to_string());
            assert!(matches!(err.retry_method(), RetryMethod::NoRetry));
        }

        #[test]
        fn test_not_found_no_retry() {
            let err = CustomRedisError::NotFound;
            assert!(matches!(err.retry_method(), RetryMethod::NoRetry));
        }

        #[test]
        fn test_invalid_configuration_no_retry() {
            let err = CustomRedisError::InvalidConfiguration("test config error".to_string());
            assert!(matches!(err.retry_method(), RetryMethod::NoRetry));
        }

        // Smoke test: verify we delegate to redis::RedisError instead of reimplementing
        #[test]
        fn test_redis_error_delegation() {
            let custom_err = CustomRedisError::Redis(Arc::new(redis::RedisError::from((
                redis::ErrorKind::IoError,
                "test error",
            ))));
            let redis_err = redis::RedisError::from((redis::ErrorKind::IoError, "test error"));

            // Verify delegation works by comparing with direct redis::RedisError behavior
            let custom_retry = custom_err.retry_method();
            let redis_retry = redis_err.retry_method();

            // Compare by matching both - they should be the same variant
            match (custom_retry, redis_retry) {
                (RetryMethod::NoRetry, RetryMethod::NoRetry) => {}
                (RetryMethod::Reconnect, RetryMethod::Reconnect) => {}
                (RetryMethod::WaitAndRetry, RetryMethod::WaitAndRetry) => {}
                (RetryMethod::RetryImmediately, RetryMethod::RetryImmediately) => {}
                (RetryMethod::MovedRedirect, RetryMethod::MovedRedirect) => {}
                (RetryMethod::AskRedirect, RetryMethod::AskRedirect) => {}
                _ => panic!("Delegation failed: retry methods don't match"),
            }
        }

        #[test]
        fn test_invalid_client_config_is_unrecoverable() {
            let err = CustomRedisError::Redis(Arc::new(redis::RedisError::from((
                redis::ErrorKind::InvalidClientConfig,
                "Redis URL did not parse",
            ))));

            assert!(
                err.is_unrecoverable_error(),
                "InvalidClientConfig should be unrecoverable"
            );
            assert!(
                matches!(err.retry_method(), RetryMethod::NoRetry),
                "InvalidClientConfig should not be retried"
            );
        }

        #[test]
        fn test_authentication_failed_is_unrecoverable() {
            let err = CustomRedisError::Redis(Arc::new(redis::RedisError::from((
                redis::ErrorKind::AuthenticationFailed,
                "WRONGPASS invalid username-password pair",
            ))));

            assert!(
                err.is_unrecoverable_error(),
                "AuthenticationFailed should be unrecoverable"
            );
            assert!(
                matches!(err.retry_method(), RetryMethod::NoRetry),
                "AuthenticationFailed should not be retried"
            );
        }

        #[test]
        fn test_io_error_is_retryable() {
            let err = CustomRedisError::Redis(Arc::new(redis::RedisError::from((
                redis::ErrorKind::IoError,
                "Connection refused",
            ))));

            // IoError is retryable (transient network issue)
            assert!(
                !err.is_unrecoverable_error(),
                "IoError should be recoverable"
            );
            // The exact retry method depends on redis crate implementation,
            // but it should not be NoRetry
            assert!(
                !matches!(err.retry_method(), RetryMethod::NoRetry),
                "IoError should be retried"
            );
        }
    }
}