redis-tower 0.1.2

A Tower-based Redis client with strong typing, composable middleware, and resilience
Documentation
//! Redis command pipelining.
//!
//! [`Pipeline`] batches multiple commands into a single network roundtrip,
//! reducing latency for bulk operations. Each command's typed response is
//! preserved and can be extracted from [`PipelineResults`] by index.
//!
//! # Example
//!
//! ```no_run
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! use redis_tower::{Pipeline, RedisConnection, commands::*};
//!
//! let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;
//! let results = Pipeline::new()
//!     .push(Set::new("a", "1"))
//!     .push(Set::new("b", "2"))
//!     .push(Get::new("a"))
//!     .execute(&mut conn)
//!     .await?;
//!
//! let val: &Option<bytes::Bytes> = results.get(2)?;
//! # let _ = val;
//! # Ok(())
//! # }
//! ```

use std::any::Any;
use std::future::Future;
use std::sync::Arc;

use redis_tower_core::{Command, Frame, RedisConnection, RedisError};
use tokio::sync::Mutex;

use crate::client::RedisClient;

/// A connection type that can execute a batch of Redis frames in a single
/// roundtrip (pipelining).
///
/// Implemented by [`RedisConnection`], [`RedisClient`], and the standard
/// [`MultiplexedClient`](crate::MultiplexedClient). The `Arc<Mutex<C>>` blanket impl also allows
/// pool-managed and shared executors to be passed directly to
/// [`Pipeline::execute`].
///
/// # Note on transactions
///
/// Transactions require exclusive connection access for the duration of
/// MULTI/EXEC. See [`TransactionExecutor`](crate::transaction::TransactionExecutor)
/// for that variant.
pub trait PipelineExecutor {
    /// Send `frames` as a pipelined batch and return the responses in order.
    fn execute_pipeline(
        &mut self,
        frames: Vec<Frame>,
    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send;
}

impl PipelineExecutor for RedisConnection {
    fn execute_pipeline(
        &mut self,
        frames: Vec<Frame>,
    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
        RedisConnection::execute_pipeline(self, frames)
    }
}

impl<C: PipelineExecutor + Send> PipelineExecutor for Arc<Mutex<C>> {
    fn execute_pipeline(
        &mut self,
        frames: Vec<Frame>,
    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
        let arc = Arc::clone(self);
        async move { arc.lock().await.execute_pipeline(frames).await }
    }
}

impl PipelineExecutor for RedisClient {
    fn execute_pipeline(
        &mut self,
        frames: Vec<Frame>,
    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
        let arc = Arc::clone(&self.inner);
        async move { arc.lock().await.execute_pipeline(frames).await }
    }
}

/// Type-erased response parser: takes a Frame, returns a boxed Any result.
pub(crate) type ResponseParser =
    Box<dyn FnOnce(Frame) -> Result<Box<dyn Any + Send>, RedisError> + Send>;

/// A type-erased command entry for pipeline batching.
struct PipelineEntry {
    frame: Frame,
    parser: ResponseParser,
}

/// Batches multiple commands into a single network roundtrip.
///
/// Each command's response type is preserved and can be extracted from
/// the [`PipelineResults`] by index.
///
/// Accepts any type that implements [`PipelineExecutor`], including
/// [`RedisConnection`], [`RedisClient`], the standard
/// [`MultiplexedClient`](crate::MultiplexedClient), and `Arc<Mutex<C>>` for any
/// `C: PipelineExecutor + Send`.
///
/// # Example
///
/// ```no_run
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// use redis_tower::{Pipeline, RedisConnection};
/// use redis_tower::commands::*;
///
/// let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;
/// let results = Pipeline::new()
///     .push(Set::new("a", "1"))
///     .push(Set::new("b", "2"))
///     .push(Get::new("a"))
///     .execute(&mut conn)
///     .await?;
///
/// let val: &Option<bytes::Bytes> = results.get(2)?;
/// # let _ = val;
/// # Ok(())
/// # }
/// ```
pub struct Pipeline {
    entries: Vec<PipelineEntry>,
}

impl Pipeline {
    /// Create a new empty pipeline.
    pub fn new() -> Self {
        Self {
            entries: Vec::new(),
        }
    }

    /// Add a command to the pipeline. Returns `self` for chaining.
    pub fn push<Cmd: Command + 'static>(mut self, cmd: Cmd) -> Self {
        let frame = cmd.to_frame();
        let parser = Box::new(
            move |response: Frame| -> Result<Box<dyn Any + Send>, RedisError> {
                let result = cmd.parse_response(response)?;
                Ok(Box::new(result))
            },
        );
        self.entries.push(PipelineEntry { frame, parser });
        self
    }

    /// Execute all queued commands in a single roundtrip.
    ///
    /// Accepts any [`PipelineExecutor`]: [`RedisConnection`], [`RedisClient`],
    /// the standard [`MultiplexedClient`](crate::MultiplexedClient),
    /// `Arc<Mutex<RedisConnection>>`, etc.
    pub async fn execute<E: PipelineExecutor>(
        self,
        conn: &mut E,
    ) -> Result<PipelineResults, RedisError> {
        let frames: Vec<Frame> = self.entries.iter().map(|e| e.frame.clone()).collect();
        let responses = conn.execute_pipeline(frames).await?;

        let mut results = Vec::with_capacity(responses.len());
        for (entry, response) in self.entries.into_iter().zip(responses) {
            // Surface Redis errors per-command.
            if let Frame::Error(ref e) = response {
                results.push(Err(RedisError::Redis(
                    String::from_utf8_lossy(e).into_owned(),
                )));
            } else {
                results.push((entry.parser)(response));
            }
        }

        Ok(PipelineResults { results })
    }

    /// Returns the number of queued commands.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Returns true if no commands are queued.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

impl Default for Pipeline {
    fn default() -> Self {
        Self::new()
    }
}

/// Results from a pipeline execution.
///
/// Each result is accessed by index and downcast to the expected type.
pub struct PipelineResults {
    results: Vec<Result<Box<dyn Any + Send>, RedisError>>,
}

impl PipelineResults {
    /// Create from raw type-erased results (used by Transaction).
    pub(crate) fn from_raw(results: Vec<Result<Box<dyn Any + Send>, RedisError>>) -> Self {
        Self { results }
    }

    /// Get the result at `index`, downcasting to the expected response type.
    ///
    /// Returns `Err` if the command at that index produced a Redis error,
    /// or if the type `T` doesn't match the command's `Response` type.
    pub fn get<T: Send + 'static>(&self, index: usize) -> Result<&T, RedisError> {
        match self.results.get(index) {
            Some(Ok(boxed)) => boxed.downcast_ref::<T>().ok_or(RedisError::TypeMismatch {
                expected: std::any::type_name::<T>(),
            }),
            Some(Err(e)) => Err(RedisError::Redis(e.to_string())),
            None => Err(RedisError::IndexOutOfBounds {
                index,
                len: self.results.len(),
            }),
        }
    }

    /// Take the result at `index`, consuming it.
    pub fn take<T: Send + 'static>(&mut self, index: usize) -> Result<T, RedisError> {
        match self.results.get_mut(index) {
            Some(slot) => {
                // Replace with a placeholder error so it can't be taken twice.
                let result = std::mem::replace(
                    slot,
                    Err(RedisError::TypeMismatch {
                        expected: "already taken",
                    }),
                );
                match result {
                    Ok(boxed) => {
                        boxed
                            .downcast::<T>()
                            .map(|b| *b)
                            .map_err(|_| RedisError::TypeMismatch {
                                expected: std::any::type_name::<T>(),
                            })
                    }
                    Err(e) => Err(e),
                }
            }
            None => Err(RedisError::IndexOutOfBounds {
                index,
                len: self.results.len(),
            }),
        }
    }

    /// Returns the number of results.
    pub fn len(&self) -> usize {
        self.results.len()
    }

    /// Returns true if there are no results.
    pub fn is_empty(&self) -> bool {
        self.results.is_empty()
    }

    /// Returns `true` if any command in the pipeline produced an error.
    pub fn has_errors(&self) -> bool {
        self.results.iter().any(|r| r.is_err())
    }

    /// Collects all results into a `Vec<T>`, returning the first error if any
    /// result is an error or if the type `T` doesn't match.
    ///
    /// Useful when all commands in the pipeline return the same type.
    pub fn into_typed_vec<T: Send + 'static>(self) -> Result<Vec<T>, RedisError> {
        self.results
            .into_iter()
            .map(|r| match r {
                Ok(boxed) => {
                    boxed
                        .downcast::<T>()
                        .map(|b| *b)
                        .map_err(|_| RedisError::TypeMismatch {
                            expected: std::any::type_name::<T>(),
                        })
                }
                Err(e) => Err(e),
            })
            .collect()
    }
}

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

    fn ok<T: Send + 'static>(value: T) -> Result<Box<dyn Any + Send>, RedisError> {
        Ok(Box::new(value))
    }

    fn err() -> Result<Box<dyn Any + Send>, RedisError> {
        Err(RedisError::Redis("boom".to_string()))
    }

    #[test]
    fn has_errors_false_for_all_success() {
        let results = PipelineResults::from_raw(vec![ok(1i64), ok(2i64)]);
        assert!(!results.has_errors());
    }

    #[test]
    fn has_errors_true_when_any_error() {
        let results = PipelineResults::from_raw(vec![ok(1i64), err()]);
        assert!(results.has_errors());
    }

    #[test]
    fn into_typed_vec_homogeneous_succeeds() {
        let results = PipelineResults::from_raw(vec![ok(1i64), ok(2i64), ok(3i64)]);
        let vec = results.into_typed_vec::<i64>().unwrap();
        assert_eq!(vec, vec![1, 2, 3]);
    }

    #[test]
    fn into_typed_vec_errors_when_any_slot_errors() {
        let results = PipelineResults::from_raw(vec![ok(1i64), err()]);
        assert!(results.into_typed_vec::<i64>().is_err());
    }

    #[test]
    fn get_out_of_bounds_returns_index_out_of_bounds() {
        let results = PipelineResults::from_raw(vec![ok(1i64)]);
        match results.get::<i64>(5) {
            Err(RedisError::IndexOutOfBounds { index, len }) => {
                assert_eq!(index, 5);
                assert_eq!(len, 1);
            }
            other => panic!("expected IndexOutOfBounds, got {other:?}"),
        }
    }

    #[test]
    fn take_out_of_bounds_returns_index_out_of_bounds() {
        let mut results = PipelineResults::from_raw(vec![ok(1i64)]);
        match results.take::<i64>(5) {
            Err(RedisError::IndexOutOfBounds { index, len }) => {
                assert_eq!(index, 5);
                assert_eq!(len, 1);
            }
            other => panic!("expected IndexOutOfBounds, got {other:?}"),
        }
    }

    /// A mock pipeline executor for unit tests.
    struct MockPipelineConn {
        count: usize,
    }

    impl PipelineExecutor for MockPipelineConn {
        fn execute_pipeline(
            &mut self,
            frames: Vec<Frame>,
        ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
            let responses: Vec<Frame> = frames
                .iter()
                .map(|_| Frame::SimpleString(bytes::Bytes::from("OK")))
                .collect();
            self.count += frames.len();
            async move { Ok(responses) }
        }
    }

    #[tokio::test]
    async fn pipeline_execute_accepts_pipeline_executor() {
        use redis_tower_commands::Set;

        let mut conn = MockPipelineConn { count: 0 };
        let results = Pipeline::new()
            .push(Set::new("a", "1"))
            .push(Set::new("b", "2"))
            .execute(&mut conn)
            .await
            .unwrap();
        assert_eq!(results.len(), 2);
        assert_eq!(conn.count, 2);
    }

    #[tokio::test]
    async fn pipeline_execute_accepts_arc_mutex_executor() {
        use redis_tower_commands::Set;

        let conn = Arc::new(Mutex::new(MockPipelineConn { count: 0 }));
        let mut executor = Arc::clone(&conn);
        let results = Pipeline::new()
            .push(Set::new("a", "1"))
            .execute(&mut executor)
            .await
            .unwrap();
        assert_eq!(results.len(), 1);
        assert_eq!(conn.lock().await.count, 1);
    }
}