Skip to main content

redis_tower/
pipeline.rs

1//! Redis command pipelining.
2//!
3//! [`Pipeline`] batches multiple commands into a single network roundtrip,
4//! reducing latency for bulk operations. Each command's typed response is
5//! preserved and can be extracted from [`PipelineResults`] by index.
6//!
7//! # Example
8//!
9//! ```no_run
10//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
11//! use redis_tower::{Pipeline, RedisConnection, commands::*};
12//!
13//! let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;
14//! let results = Pipeline::new()
15//!     .push(Set::new("a", "1"))
16//!     .push(Set::new("b", "2"))
17//!     .push(Get::new("a"))
18//!     .execute(&mut conn)
19//!     .await?;
20//!
21//! let val: &Option<bytes::Bytes> = results.get(2)?;
22//! # let _ = val;
23//! # Ok(())
24//! # }
25//! ```
26
27use std::any::Any;
28use std::future::Future;
29use std::sync::Arc;
30
31use redis_tower_core::{Command, Frame, RedisConnection, RedisError};
32use tokio::sync::Mutex;
33
34use crate::client::RedisClient;
35
36/// A connection type that can execute a batch of Redis frames in a single
37/// roundtrip (pipelining).
38///
39/// Implemented by [`RedisConnection`], [`RedisClient`], and the standard
40/// [`MultiplexedClient`](crate::MultiplexedClient). The `Arc<Mutex<C>>` blanket impl also allows
41/// pool-managed and shared executors to be passed directly to
42/// [`Pipeline::execute`].
43///
44/// # Note on transactions
45///
46/// Transactions require exclusive connection access for the duration of
47/// MULTI/EXEC. See [`TransactionExecutor`](crate::transaction::TransactionExecutor)
48/// for that variant.
49pub trait PipelineExecutor {
50    /// Send `frames` as a pipelined batch and return the responses in order.
51    fn execute_pipeline(
52        &mut self,
53        frames: Vec<Frame>,
54    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send;
55}
56
57impl PipelineExecutor for RedisConnection {
58    fn execute_pipeline(
59        &mut self,
60        frames: Vec<Frame>,
61    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
62        RedisConnection::execute_pipeline(self, frames)
63    }
64}
65
66impl<C: PipelineExecutor + Send> PipelineExecutor for Arc<Mutex<C>> {
67    fn execute_pipeline(
68        &mut self,
69        frames: Vec<Frame>,
70    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
71        let arc = Arc::clone(self);
72        async move { arc.lock().await.execute_pipeline(frames).await }
73    }
74}
75
76impl PipelineExecutor for RedisClient {
77    fn execute_pipeline(
78        &mut self,
79        frames: Vec<Frame>,
80    ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
81        let arc = Arc::clone(&self.inner);
82        async move { arc.lock().await.execute_pipeline(frames).await }
83    }
84}
85
86/// Type-erased response parser: takes a Frame, returns a boxed Any result.
87pub(crate) type ResponseParser =
88    Box<dyn FnOnce(Frame) -> Result<Box<dyn Any + Send>, RedisError> + Send>;
89
90/// A type-erased command entry for pipeline batching.
91struct PipelineEntry {
92    frame: Frame,
93    parser: ResponseParser,
94}
95
96/// Batches multiple commands into a single network roundtrip.
97///
98/// Each command's response type is preserved and can be extracted from
99/// the [`PipelineResults`] by index.
100///
101/// Accepts any type that implements [`PipelineExecutor`], including
102/// [`RedisConnection`], [`RedisClient`], the standard
103/// [`MultiplexedClient`](crate::MultiplexedClient), and `Arc<Mutex<C>>` for any
104/// `C: PipelineExecutor + Send`.
105///
106/// # Example
107///
108/// ```no_run
109/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
110/// use redis_tower::{Pipeline, RedisConnection};
111/// use redis_tower::commands::*;
112///
113/// let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;
114/// let results = Pipeline::new()
115///     .push(Set::new("a", "1"))
116///     .push(Set::new("b", "2"))
117///     .push(Get::new("a"))
118///     .execute(&mut conn)
119///     .await?;
120///
121/// let val: &Option<bytes::Bytes> = results.get(2)?;
122/// # let _ = val;
123/// # Ok(())
124/// # }
125/// ```
126pub struct Pipeline {
127    entries: Vec<PipelineEntry>,
128}
129
130impl Pipeline {
131    /// Create a new empty pipeline.
132    pub fn new() -> Self {
133        Self {
134            entries: Vec::new(),
135        }
136    }
137
138    /// Add a command to the pipeline. Returns `self` for chaining.
139    pub fn push<Cmd: Command + 'static>(mut self, cmd: Cmd) -> Self {
140        let frame = cmd.to_frame();
141        let parser = Box::new(
142            move |response: Frame| -> Result<Box<dyn Any + Send>, RedisError> {
143                let result = cmd.parse_response(response)?;
144                Ok(Box::new(result))
145            },
146        );
147        self.entries.push(PipelineEntry { frame, parser });
148        self
149    }
150
151    /// Execute all queued commands in a single roundtrip.
152    ///
153    /// Accepts any [`PipelineExecutor`]: [`RedisConnection`], [`RedisClient`],
154    /// the standard [`MultiplexedClient`](crate::MultiplexedClient),
155    /// `Arc<Mutex<RedisConnection>>`, etc.
156    pub async fn execute<E: PipelineExecutor>(
157        self,
158        conn: &mut E,
159    ) -> Result<PipelineResults, RedisError> {
160        let frames: Vec<Frame> = self.entries.iter().map(|e| e.frame.clone()).collect();
161        let responses = conn.execute_pipeline(frames).await?;
162
163        let mut results = Vec::with_capacity(responses.len());
164        for (entry, response) in self.entries.into_iter().zip(responses) {
165            // Surface Redis errors per-command.
166            if let Frame::Error(ref e) = response {
167                results.push(Err(RedisError::Redis(
168                    String::from_utf8_lossy(e).into_owned(),
169                )));
170            } else {
171                results.push((entry.parser)(response));
172            }
173        }
174
175        Ok(PipelineResults { results })
176    }
177
178    /// Returns the number of queued commands.
179    pub fn len(&self) -> usize {
180        self.entries.len()
181    }
182
183    /// Returns true if no commands are queued.
184    pub fn is_empty(&self) -> bool {
185        self.entries.is_empty()
186    }
187}
188
189impl Default for Pipeline {
190    fn default() -> Self {
191        Self::new()
192    }
193}
194
195/// Results from a pipeline execution.
196///
197/// Each result is accessed by index and downcast to the expected type.
198pub struct PipelineResults {
199    results: Vec<Result<Box<dyn Any + Send>, RedisError>>,
200}
201
202impl PipelineResults {
203    /// Create from raw type-erased results (used by Transaction).
204    pub(crate) fn from_raw(results: Vec<Result<Box<dyn Any + Send>, RedisError>>) -> Self {
205        Self { results }
206    }
207
208    /// Get the result at `index`, downcasting to the expected response type.
209    ///
210    /// Returns `Err` if the command at that index produced a Redis error,
211    /// or if the type `T` doesn't match the command's `Response` type.
212    pub fn get<T: Send + 'static>(&self, index: usize) -> Result<&T, RedisError> {
213        match self.results.get(index) {
214            Some(Ok(boxed)) => boxed.downcast_ref::<T>().ok_or(RedisError::TypeMismatch {
215                expected: std::any::type_name::<T>(),
216            }),
217            Some(Err(e)) => Err(RedisError::Redis(e.to_string())),
218            None => Err(RedisError::IndexOutOfBounds {
219                index,
220                len: self.results.len(),
221            }),
222        }
223    }
224
225    /// Take the result at `index`, consuming it.
226    pub fn take<T: Send + 'static>(&mut self, index: usize) -> Result<T, RedisError> {
227        match self.results.get_mut(index) {
228            Some(slot) => {
229                // Replace with a placeholder error so it can't be taken twice.
230                let result = std::mem::replace(
231                    slot,
232                    Err(RedisError::TypeMismatch {
233                        expected: "already taken",
234                    }),
235                );
236                match result {
237                    Ok(boxed) => {
238                        boxed
239                            .downcast::<T>()
240                            .map(|b| *b)
241                            .map_err(|_| RedisError::TypeMismatch {
242                                expected: std::any::type_name::<T>(),
243                            })
244                    }
245                    Err(e) => Err(e),
246                }
247            }
248            None => Err(RedisError::IndexOutOfBounds {
249                index,
250                len: self.results.len(),
251            }),
252        }
253    }
254
255    /// Returns the number of results.
256    pub fn len(&self) -> usize {
257        self.results.len()
258    }
259
260    /// Returns true if there are no results.
261    pub fn is_empty(&self) -> bool {
262        self.results.is_empty()
263    }
264
265    /// Returns `true` if any command in the pipeline produced an error.
266    pub fn has_errors(&self) -> bool {
267        self.results.iter().any(|r| r.is_err())
268    }
269
270    /// Collects all results into a `Vec<T>`, returning the first error if any
271    /// result is an error or if the type `T` doesn't match.
272    ///
273    /// Useful when all commands in the pipeline return the same type.
274    pub fn into_typed_vec<T: Send + 'static>(self) -> Result<Vec<T>, RedisError> {
275        self.results
276            .into_iter()
277            .map(|r| match r {
278                Ok(boxed) => {
279                    boxed
280                        .downcast::<T>()
281                        .map(|b| *b)
282                        .map_err(|_| RedisError::TypeMismatch {
283                            expected: std::any::type_name::<T>(),
284                        })
285                }
286                Err(e) => Err(e),
287            })
288            .collect()
289    }
290}
291
292#[cfg(test)]
293mod tests {
294    use super::*;
295
296    fn ok<T: Send + 'static>(value: T) -> Result<Box<dyn Any + Send>, RedisError> {
297        Ok(Box::new(value))
298    }
299
300    fn err() -> Result<Box<dyn Any + Send>, RedisError> {
301        Err(RedisError::Redis("boom".to_string()))
302    }
303
304    #[test]
305    fn has_errors_false_for_all_success() {
306        let results = PipelineResults::from_raw(vec![ok(1i64), ok(2i64)]);
307        assert!(!results.has_errors());
308    }
309
310    #[test]
311    fn has_errors_true_when_any_error() {
312        let results = PipelineResults::from_raw(vec![ok(1i64), err()]);
313        assert!(results.has_errors());
314    }
315
316    #[test]
317    fn into_typed_vec_homogeneous_succeeds() {
318        let results = PipelineResults::from_raw(vec![ok(1i64), ok(2i64), ok(3i64)]);
319        let vec = results.into_typed_vec::<i64>().unwrap();
320        assert_eq!(vec, vec![1, 2, 3]);
321    }
322
323    #[test]
324    fn into_typed_vec_errors_when_any_slot_errors() {
325        let results = PipelineResults::from_raw(vec![ok(1i64), err()]);
326        assert!(results.into_typed_vec::<i64>().is_err());
327    }
328
329    #[test]
330    fn get_out_of_bounds_returns_index_out_of_bounds() {
331        let results = PipelineResults::from_raw(vec![ok(1i64)]);
332        match results.get::<i64>(5) {
333            Err(RedisError::IndexOutOfBounds { index, len }) => {
334                assert_eq!(index, 5);
335                assert_eq!(len, 1);
336            }
337            other => panic!("expected IndexOutOfBounds, got {other:?}"),
338        }
339    }
340
341    #[test]
342    fn take_out_of_bounds_returns_index_out_of_bounds() {
343        let mut results = PipelineResults::from_raw(vec![ok(1i64)]);
344        match results.take::<i64>(5) {
345            Err(RedisError::IndexOutOfBounds { index, len }) => {
346                assert_eq!(index, 5);
347                assert_eq!(len, 1);
348            }
349            other => panic!("expected IndexOutOfBounds, got {other:?}"),
350        }
351    }
352
353    /// A mock pipeline executor for unit tests.
354    struct MockPipelineConn {
355        count: usize,
356    }
357
358    impl PipelineExecutor for MockPipelineConn {
359        fn execute_pipeline(
360            &mut self,
361            frames: Vec<Frame>,
362        ) -> impl Future<Output = Result<Vec<Frame>, RedisError>> + Send {
363            let responses: Vec<Frame> = frames
364                .iter()
365                .map(|_| Frame::SimpleString(bytes::Bytes::from("OK")))
366                .collect();
367            self.count += frames.len();
368            async move { Ok(responses) }
369        }
370    }
371
372    #[tokio::test]
373    async fn pipeline_execute_accepts_pipeline_executor() {
374        use redis_tower_commands::Set;
375
376        let mut conn = MockPipelineConn { count: 0 };
377        let results = Pipeline::new()
378            .push(Set::new("a", "1"))
379            .push(Set::new("b", "2"))
380            .execute(&mut conn)
381            .await
382            .unwrap();
383        assert_eq!(results.len(), 2);
384        assert_eq!(conn.count, 2);
385    }
386
387    #[tokio::test]
388    async fn pipeline_execute_accepts_arc_mutex_executor() {
389        use redis_tower_commands::Set;
390
391        let conn = Arc::new(Mutex::new(MockPipelineConn { count: 0 }));
392        let mut executor = Arc::clone(&conn);
393        let results = Pipeline::new()
394            .push(Set::new("a", "1"))
395            .execute(&mut executor)
396            .await
397            .unwrap();
398        assert_eq!(results.len(), 1);
399        assert_eq!(conn.lock().await.count, 1);
400    }
401}