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.

15.5 KB
Raw Blame
//! Redis pipeline support for batching multiple commands into a single round-trip.
//!
//! # Example
//!
//! ```rust,ignore
//! use common_redis::{Client, Pipeline, PipelineResult};
//!
//! async fn example(client: &impl Client) -> Result<(), CustomRedisError> {
//!     let results = client.pipeline()
//!         .set("key1", "value1")
//!         .set("key2", "value2")
//!         .get("key3")
//!         .execute()
//!         .await?;
//!
//!     // results[0] = Ok(PipelineResult::Ok)
//!     // results[1] = Ok(PipelineResult::Ok)
//!     // results[2] = Ok(PipelineResult::String("...")) or Err(NotFound)
//!     Ok(())
//! }
//! ```

use crate::{Client, CustomRedisError, RedisValueFormat};

/// Result type for individual pipeline operations.
///
/// Each variant corresponds to the return type of a Redis command.
#[derive(Debug, Clone, PartialEq)]
pub enum PipelineResult {
    /// Success — return value intentionally discarded (SET, DEL, HINCRBY, ZADD, etc.)
    Ok,
    /// String value (GET)
    String(String),
    /// Raw bytes (GET raw bytes)
    Bytes(Vec<u8>),
    /// Boolean result (SET NX EX, EXPIRE)
    Bool(bool),
    /// Count result (SCARD, SADD)
    Count(u64),
    /// List of strings (ZRANGEBYSCORE)
    Strings(Vec<String>),
}

/// Internal representation of a pipeline command.
#[derive(Debug, Clone)]
pub enum PipelineCommand {
    Get {
        key: String,
        format: RedisValueFormat,
    },
    GetRawBytes {
        key: String,
    },
    Set {
        key: String,
        value: String,
        format: RedisValueFormat,
    },
    SetEx {
        key: String,
        value: String,
        seconds: u64,
        format: RedisValueFormat,
    },
    SetNxEx {
        key: String,
        value: String,
        seconds: u64,
        format: RedisValueFormat,
    },
    Del {
        key: String,
    },
    HGet {
        key: String,
        field: String,
    },
    HIncrBy {
        key: String,
        field: String,
        count: i64,
    },
    Scard {
        key: String,
    },
    SAdd {
        key: String,
        member: String,
    },
    /// One ZADD with every `(score, member)` pair, so a batch is a single command.
    ZAdd {
        key: String,
        members: Vec<(i64, String)>,
    },
    Expire {
        key: String,
        seconds: u64,
    },
    ZRangeByScore {
        key: String,
        min: String,
        max: String,
    },
}

/// A Redis pipeline that batches multiple commands into a single round-trip.
///
/// Create a pipeline using [`ClientPipelineExt::pipeline()`], add commands using the builder
/// methods, then call [`execute()`](Pipeline::execute) to send all commands at once.
///
/// # Example
///
/// ```rust,ignore
/// let results = client.pipeline()
///     .set("key1", "value1")
///     .set("key2", "value2")
///     .get("key3")
///     .execute()
///     .await?;
/// ```
pub struct Pipeline<C> {
    client: C,
    commands: Vec<PipelineCommand>,
}

impl<C> Pipeline<C> {
    /// Create a new pipeline for the given client.
    pub fn new(client: C) -> Self {
        Self {
            client,
            commands: Vec::new(),
        }
    }

    /// Add a GET command to the pipeline.
    pub fn get(self, key: impl Into<String>) -> Self {
        self.get_with_format(key, RedisValueFormat::default())
    }

    /// Add a GET command with a specific format to the pipeline.
    pub fn get_with_format(mut self, key: impl Into<String>, format: RedisValueFormat) -> Self {
        self.commands.push(PipelineCommand::Get {
            key: key.into(),
            format,
        });
        self
    }

    /// Add a GET command for raw bytes to the pipeline.
    pub fn get_raw_bytes(mut self, key: impl Into<String>) -> Self {
        self.commands
            .push(PipelineCommand::GetRawBytes { key: key.into() });
        self
    }

    /// Add a SET command to the pipeline.
    pub fn set(self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.set_with_format(key, value, RedisValueFormat::default())
    }

    /// Add a SET command with a specific format to the pipeline.
    pub fn set_with_format(
        mut self,
        key: impl Into<String>,
        value: impl Into<String>,
        format: RedisValueFormat,
    ) -> Self {
        self.commands.push(PipelineCommand::Set {
            key: key.into(),
            value: value.into(),
            format,
        });
        self
    }

    /// Add a SETEX command (SET with expiration) to the pipeline.
    pub fn setex(self, key: impl Into<String>, value: impl Into<String>, seconds: u64) -> Self {
        self.setex_with_format(key, value, seconds, RedisValueFormat::default())
    }

    /// Add a SETEX command with a specific format to the pipeline.
    pub fn setex_with_format(
        mut self,
        key: impl Into<String>,
        value: impl Into<String>,
        seconds: u64,
        format: RedisValueFormat,
    ) -> Self {
        self.commands.push(PipelineCommand::SetEx {
            key: key.into(),
            value: value.into(),
            seconds,
            format,
        });
        self
    }

    /// Add a SET NX EX command (SET if not exists with expiration) to the pipeline.
    pub fn set_nx_ex(self, key: impl Into<String>, value: impl Into<String>, seconds: u64) -> Self {
        self.set_nx_ex_with_format(key, value, seconds, RedisValueFormat::default())
    }

    /// Add a SET NX EX command with a specific format to the pipeline.
    pub fn set_nx_ex_with_format(
        mut self,
        key: impl Into<String>,
        value: impl Into<String>,
        seconds: u64,
        format: RedisValueFormat,
    ) -> Self {
        self.commands.push(PipelineCommand::SetNxEx {
            key: key.into(),
            value: value.into(),
            seconds,
            format,
        });
        self
    }

    /// Add a DEL command to the pipeline.
    pub fn del(mut self, key: impl Into<String>) -> Self {
        self.commands.push(PipelineCommand::Del { key: key.into() });
        self
    }

    /// Add an HGET command to the pipeline.
    pub fn hget(mut self, key: impl Into<String>, field: impl Into<String>) -> Self {
        self.commands.push(PipelineCommand::HGet {
            key: key.into(),
            field: field.into(),
        });
        self
    }

    /// Add an HINCRBY command to the pipeline.
    pub fn hincrby(mut self, key: impl Into<String>, field: impl Into<String>, count: i64) -> Self {
        self.commands.push(PipelineCommand::HIncrBy {
            key: key.into(),
            field: field.into(),
            count,
        });
        self
    }

    /// Add an SCARD command to the pipeline.
    pub fn scard(mut self, key: impl Into<String>) -> Self {
        self.commands
            .push(PipelineCommand::Scard { key: key.into() });
        self
    }

    /// Add an SADD command to the pipeline.
    pub fn sadd(mut self, key: impl Into<String>, member: impl Into<String>) -> Self {
        self.commands.push(PipelineCommand::SAdd {
            key: key.into(),
            member: member.into(),
        });
        self
    }

    /// Add a ZADD command to the pipeline.
    pub fn zadd(mut self, key: impl Into<String>, members: Vec<(i64, String)>) -> Self {
        self.commands.push(PipelineCommand::ZAdd {
            key: key.into(),
            members,
        });
        self
    }

    /// Add an EXPIRE command to the pipeline.
    pub fn expire(mut self, key: impl Into<String>, seconds: u64) -> Self {
        self.commands.push(PipelineCommand::Expire {
            key: key.into(),
            seconds,
        });
        self
    }

    /// Add a ZRANGEBYSCORE command to the pipeline.
    pub fn zrangebyscore(
        mut self,
        key: impl Into<String>,
        min: impl Into<String>,
        max: impl Into<String>,
    ) -> Self {
        self.commands.push(PipelineCommand::ZRangeByScore {
            key: key.into(),
            min: min.into(),
            max: max.into(),
        });
        self
    }

    /// Get the commands in this pipeline.
    pub fn into_commands(self) -> (C, Vec<PipelineCommand>) {
        (self.client, self.commands)
    }

    /// Check if the pipeline is empty.
    pub fn is_empty(&self) -> bool {
        self.commands.is_empty()
    }

    /// Get the number of commands in the pipeline.
    pub fn len(&self) -> usize {
        self.commands.len()
    }
}

impl<C: Client> Pipeline<C> {
    /// Execute all commands in the pipeline as a single batch.
    ///
    /// Returns a vector of results in the same order as commands were added.
    /// Each result is either `Ok(PipelineResult)` or `Err(CustomRedisError)`.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection fails. Individual command failures
    /// are returned as `Err` in the result vector.
    pub async fn execute(
        self,
    ) -> Result<Vec<Result<PipelineResult, CustomRedisError>>, CustomRedisError> {
        let (client, commands) = self.into_commands();
        // Handle empty pipelines here to avoid unnecessary round-trips.
        // This is the single check point - implementations can assume non-empty.
        if commands.is_empty() {
            return Ok(Vec::new());
        }
        client.execute_pipeline(commands).await
    }
}

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

    #[test]
    fn test_pipeline_builder_commands() {
        // Create a dummy pipeline to test the builder
        struct DummyClient;

        let pipeline = Pipeline::new(DummyClient)
            .set("key1", "value1")
            .set("key2", "value2")
            .get("key3");

        assert_eq!(pipeline.len(), 3);
        assert!(!pipeline.is_empty());

        let (_, commands) = pipeline.into_commands();
        assert_eq!(commands.len(), 3);

        assert!(
            matches!(&commands[0], PipelineCommand::Set { key, value, .. } if key == "key1" && value == "value1")
        );
        assert!(
            matches!(&commands[1], PipelineCommand::Set { key, value, .. } if key == "key2" && value == "value2")
        );
        assert!(matches!(&commands[2], PipelineCommand::Get { key, .. } if key == "key3"));
    }

    #[test]
    fn test_pipeline_empty() {
        struct DummyClient;
        let pipeline = Pipeline::new(DummyClient);
        assert!(pipeline.is_empty());
        assert_eq!(pipeline.len(), 0);
    }

    #[test]
    fn test_pipeline_all_commands() {
        struct DummyClient;

        let pipeline = Pipeline::new(DummyClient)
            .get("k1")
            .get_with_format("k2", RedisValueFormat::Utf8)
            .get_raw_bytes("k3")
            .set("k4", "v4")
            .set_with_format("k5", "v5", RedisValueFormat::Utf8)
            .setex("k6", "v6", 60)
            .setex_with_format("k7", "v7", 60, RedisValueFormat::Utf8)
            .set_nx_ex("k8", "v8", 60)
            .set_nx_ex_with_format("k9", "v9", 60, RedisValueFormat::Utf8)
            .del("k10")
            .hget("k11", "f11")
            .hincrby("k12", "f12", 5)
            .scard("k13")
            .sadd("k14", "m14")
            .expire("k15", 300)
            .zrangebyscore("k16", "0", "100");

        let (_, commands) = pipeline.into_commands();
        assert_eq!(commands.len(), 16);
        assert!(
            matches!(&commands[14], PipelineCommand::Expire { key, seconds } if key == "k15" && *seconds == 300)
        );
    }

    #[test]
    fn test_pipeline_result_equality() {
        assert_eq!(PipelineResult::Ok, PipelineResult::Ok);
        assert_eq!(
            PipelineResult::String("test".to_string()),
            PipelineResult::String("test".to_string())
        );
        assert_ne!(
            PipelineResult::String("test1".to_string()),
            PipelineResult::String("test2".to_string())
        );
    }
}

#[cfg(test)]
mod integration_tests {
    use super::*;
    use crate::{ClientPipelineExt, CustomRedisError, MockRedisClient};

    #[tokio::test]
    async fn test_mock_pipeline_set_and_get() {
        let mut client = MockRedisClient::new();
        client.set_ret("key1", Ok(()));
        client.set_ret("key2", Ok(()));
        client.get_ret("key3", Ok("value3".to_string()));

        let results = client
            .pipeline()
            .set("key1", "value1")
            .set("key2", "value2")
            .get("key3")
            .execute()
            .await
            .unwrap();

        assert_eq!(results.len(), 3);
        assert!(matches!(results[0], Ok(PipelineResult::Ok)));
        assert!(matches!(results[1], Ok(PipelineResult::Ok)));
        assert!(matches!(&results[2], Ok(PipelineResult::String(s)) if s == "value3"));
    }

    #[tokio::test]
    async fn test_mock_pipeline_partial_failure() {
        let mut client = MockRedisClient::new();
        client.set_ret("key1", Ok(()));
        // key2 not configured, will return NotFound
        client.get_ret("key3", Ok("value3".to_string()));

        let results = client
            .pipeline()
            .set("key1", "value1")
            .get("key2") // This will fail
            .get("key3")
            .execute()
            .await
            .unwrap();

        assert_eq!(results.len(), 3);
        assert!(matches!(results[0], Ok(PipelineResult::Ok)));
        assert!(matches!(results[1], Err(CustomRedisError::NotFound)));
        assert!(matches!(&results[2], Ok(PipelineResult::String(s)) if s == "value3"));
    }

    #[tokio::test]
    async fn test_mock_pipeline_empty() {
        let client = MockRedisClient::new();

        let results = client.pipeline().execute().await.unwrap();

        assert!(results.is_empty());
    }

    #[tokio::test]
    async fn test_mock_pipeline_records_calls() {
        let mut client = MockRedisClient::new();
        client.set_ret("key1", Ok(()));
        client.get_ret("key2", Ok("value2".to_string()));

        let _results = client
            .pipeline()
            .set("key1", "value1")
            .get("key2")
            .execute()
            .await
            .unwrap();

        let calls = client.get_calls();
        assert_eq!(calls.len(), 2);
        assert_eq!(calls[0].op, "pipeline_set");
        assert_eq!(calls[0].key, "key1");
        assert_eq!(calls[1].op, "pipeline_get");
        assert_eq!(calls[1].key, "key2");
    }

    #[tokio::test]
    async fn test_mock_pipeline_all_result_types() {
        let mut client = MockRedisClient::new();
        client.get_ret("get_key", Ok("string_value".to_string()));
        client.set_ret("set_key", Ok(()));
        client.del_ret("del_key", Ok(()));
        client.set_nx_ex_ret("nx_key", Ok(true));
        client.scard_ret("scard_key", Ok(42));
        client.zrangebyscore_ret("zset_key", vec!["a".to_string(), "b".to_string()]);

        let results = client
            .pipeline()
            .get("get_key")
            .set("set_key", "value")
            .del("del_key")
            .set_nx_ex("nx_key", "value", 60)
            .scard("scard_key")
            .sadd("sadd_key", "member1")
            .zrangebyscore("zset_key", "0", "100")
            .execute()
            .await
            .unwrap();

        assert_eq!(results.len(), 7);
        assert!(matches!(&results[0], Ok(PipelineResult::String(s)) if s == "string_value"));
        assert!(matches!(results[1], Ok(PipelineResult::Ok)));
        assert!(matches!(results[2], Ok(PipelineResult::Ok)));
        assert!(matches!(results[3], Ok(PipelineResult::Bool(true))));
        assert!(matches!(results[4], Ok(PipelineResult::Count(42))));
        assert!(matches!(results[5], Ok(PipelineResult::Count(_)))); // SADD
        assert!(
            matches!(&results[6], Ok(PipelineResult::Strings(v)) if v == &vec!["a".to_string(), "b".to_string()])
        );
    }
}