Skip to main content

redis_tower_commands/
scan.rs

1//! Cursor-based iteration over keys and collection members.
2//!
3//! [`Scan`], [`HScan`], [`SScan`], and [`ZScan`] return a cursor plus one page
4//! of results. A complete traversal continues until Redis returns cursor zero;
5//! pages may be empty and elements may repeat while the data set changes.
6//! Avoid [`Keys`](crate::keys::Keys) for production-wide iteration.
7//!
8//! ```
9//! use redis_tower_commands::Scan;
10//! use redis_tower_core::Command;
11//!
12//! let command = Scan::new().match_pattern("user:*").count(100);
13//! assert_eq!(command.name(), "SCAN");
14//! ```
15//!
16//! See the [command cookbook] for a complete cursor loop.
17//!
18//! [command cookbook]: https://github.com/joshrotenberg/redis-tower/blob/main/docs/COMMAND-COOKBOOK.md#cursor-iteration
19
20use crate::CommandArg;
21use bytes::Bytes;
22use redis_tower_core::{Command, Frame, RedisError};
23use redis_tower_protocol::helpers::{array, bulk};
24
25/// Result of a SCAN command: cursor + batch of results.
26#[derive(Debug, Clone)]
27pub struct ScanResult<T> {
28    /// The cursor to use for the next iteration. "0" means iteration is complete.
29    pub cursor: String,
30    /// The batch of results from this iteration.
31    pub results: Vec<T>,
32}
33
34impl<T> ScanResult<T> {
35    /// Returns true if the scan is complete (cursor is "0").
36    pub fn is_finished(&self) -> bool {
37        self.cursor == "0"
38    }
39}
40
41/// SCAN cursor \[MATCH pattern\] \[COUNT count\] \[TYPE type\]
42///
43/// Iterates over all keys in the database.
44#[derive(Clone)]
45pub struct Scan {
46    cursor: String,
47    pattern: Option<CommandArg>,
48    count: Option<u64>,
49    key_type: Option<String>,
50}
51
52impl Scan {
53    /// Start a new scan from cursor "0".
54    pub fn new() -> Self {
55        Self {
56            cursor: "0".to_string(),
57            pattern: None,
58            count: None,
59            key_type: None,
60        }
61    }
62
63    /// Continue a scan from a specific cursor.
64    pub fn cursor(mut self, cursor: impl Into<String>) -> Self {
65        self.cursor = cursor.into();
66        self
67    }
68
69    /// Filter keys matching a glob pattern.
70    pub fn match_pattern(mut self, pattern: impl Into<CommandArg>) -> Self {
71        self.pattern = Some(pattern.into());
72        self
73    }
74
75    /// Hint for how many elements to return per iteration.
76    pub fn count(mut self, n: u64) -> Self {
77        self.count = Some(n);
78        self
79    }
80
81    /// Filter by key type (string, list, set, zset, hash, stream).
82    pub fn key_type(mut self, t: impl Into<String>) -> Self {
83        self.key_type = Some(t.into());
84        self
85    }
86}
87
88impl Default for Scan {
89    fn default() -> Self {
90        Self::new()
91    }
92}
93
94impl Command for Scan {
95    type Response = ScanResult<Bytes>;
96
97    fn to_frame(&self) -> Frame {
98        let mut args = vec![bulk("SCAN"), bulk(self.cursor.as_str())];
99        if let Some(ref pattern) = self.pattern {
100            args.push(bulk("MATCH"));
101            args.push(bulk(pattern));
102        }
103        if let Some(n) = self.count {
104            args.push(bulk("COUNT"));
105            args.push(bulk(n.to_string()));
106        }
107        if let Some(ref t) = self.key_type {
108            args.push(bulk("TYPE"));
109            args.push(bulk(t.as_str()));
110        }
111        array(args)
112    }
113
114    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
115        parse_scan_response(frame, extract_bulk_bytes)
116    }
117
118    fn name(&self) -> &str {
119        "SCAN"
120    }
121}
122
123/// SSCAN key cursor \[MATCH pattern\] \[COUNT count\]
124///
125/// Iterates over members of a set.
126#[derive(Clone)]
127pub struct SScan {
128    key: CommandArg,
129    cursor: String,
130    pattern: Option<CommandArg>,
131    count: Option<u64>,
132}
133
134impl SScan {
135    /// Create a new [`SScan`] command.
136    pub fn new(key: impl Into<CommandArg>) -> Self {
137        Self {
138            key: key.into(),
139            cursor: "0".to_string(),
140            pattern: None,
141            count: None,
142        }
143    }
144
145    /// Configure the `cursor` option.
146    pub fn cursor(mut self, cursor: impl Into<String>) -> Self {
147        self.cursor = cursor.into();
148        self
149    }
150
151    /// Configure the `match_pattern` option.
152    pub fn match_pattern(mut self, pattern: impl Into<CommandArg>) -> Self {
153        self.pattern = Some(pattern.into());
154        self
155    }
156
157    /// Configure the `count` option.
158    pub fn count(mut self, n: u64) -> Self {
159        self.count = Some(n);
160        self
161    }
162}
163
164impl Command for SScan {
165    type Response = ScanResult<Bytes>;
166
167    fn to_frame(&self) -> Frame {
168        let mut args = vec![bulk("SSCAN"), bulk(&self.key), bulk(self.cursor.as_str())];
169        if let Some(ref pattern) = self.pattern {
170            args.push(bulk("MATCH"));
171            args.push(bulk(pattern));
172        }
173        if let Some(n) = self.count {
174            args.push(bulk("COUNT"));
175            args.push(bulk(n.to_string()));
176        }
177        array(args)
178    }
179
180    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
181        parse_scan_response(frame, extract_bulk_bytes)
182    }
183
184    fn name(&self) -> &str {
185        "SSCAN"
186    }
187}
188
189/// HSCAN key cursor \[MATCH pattern\] \[COUNT count\]
190///
191/// Iterates over fields and values of a hash. Returns (field, value) pairs.
192#[derive(Clone)]
193pub struct HScan {
194    key: CommandArg,
195    cursor: String,
196    pattern: Option<CommandArg>,
197    count: Option<u64>,
198}
199
200impl HScan {
201    /// Create a new [`HScan`] command.
202    pub fn new(key: impl Into<CommandArg>) -> Self {
203        Self {
204            key: key.into(),
205            cursor: "0".to_string(),
206            pattern: None,
207            count: None,
208        }
209    }
210
211    /// Configure the `cursor` option.
212    pub fn cursor(mut self, cursor: impl Into<String>) -> Self {
213        self.cursor = cursor.into();
214        self
215    }
216
217    /// Configure the `match_pattern` option.
218    pub fn match_pattern(mut self, pattern: impl Into<CommandArg>) -> Self {
219        self.pattern = Some(pattern.into());
220        self
221    }
222
223    /// Configure the `count` option.
224    pub fn count(mut self, n: u64) -> Self {
225        self.count = Some(n);
226        self
227    }
228}
229
230impl Command for HScan {
231    type Response = ScanResult<(Bytes, Bytes)>;
232
233    fn to_frame(&self) -> Frame {
234        let mut args = vec![bulk("HSCAN"), bulk(&self.key), bulk(self.cursor.as_str())];
235        if let Some(ref pattern) = self.pattern {
236            args.push(bulk("MATCH"));
237            args.push(bulk(pattern));
238        }
239        if let Some(n) = self.count {
240            args.push(bulk("COUNT"));
241            args.push(bulk(n.to_string()));
242        }
243        array(args)
244    }
245
246    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
247        parse_scan_pair_response(frame)
248    }
249
250    fn name(&self) -> &str {
251        "HSCAN"
252    }
253}
254
255/// ZSCAN key cursor \[MATCH pattern\] \[COUNT count\]
256///
257/// Iterates over members and scores of a sorted set. Returns (member, score) pairs.
258#[derive(Clone)]
259pub struct ZScan {
260    key: CommandArg,
261    cursor: String,
262    pattern: Option<CommandArg>,
263    count: Option<u64>,
264}
265
266impl ZScan {
267    /// Create a new [`ZScan`] command.
268    pub fn new(key: impl Into<CommandArg>) -> Self {
269        Self {
270            key: key.into(),
271            cursor: "0".to_string(),
272            pattern: None,
273            count: None,
274        }
275    }
276
277    /// Configure the `cursor` option.
278    pub fn cursor(mut self, cursor: impl Into<String>) -> Self {
279        self.cursor = cursor.into();
280        self
281    }
282
283    /// Configure the `match_pattern` option.
284    pub fn match_pattern(mut self, pattern: impl Into<CommandArg>) -> Self {
285        self.pattern = Some(pattern.into());
286        self
287    }
288
289    /// Configure the `count` option.
290    pub fn count(mut self, n: u64) -> Self {
291        self.count = Some(n);
292        self
293    }
294}
295
296impl Command for ZScan {
297    type Response = ScanResult<(Bytes, f64)>;
298
299    fn to_frame(&self) -> Frame {
300        let mut args = vec![bulk("ZSCAN"), bulk(&self.key), bulk(self.cursor.as_str())];
301        if let Some(ref pattern) = self.pattern {
302            args.push(bulk("MATCH"));
303            args.push(bulk(pattern));
304        }
305        if let Some(n) = self.count {
306            args.push(bulk("COUNT"));
307            args.push(bulk(n.to_string()));
308        }
309        array(args)
310    }
311
312    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
313        parse_scan_score_response(frame)
314    }
315
316    fn name(&self) -> &str {
317        "ZSCAN"
318    }
319}
320
321// -- Response parsing helpers --
322
323/// Parse a SCAN response: [cursor, [results...]]
324fn parse_scan_response<T>(
325    frame: Frame,
326    parse_item: impl Fn(&Frame) -> Result<T, RedisError>,
327) -> Result<ScanResult<T>, RedisError> {
328    let items = match frame {
329        Frame::Array(Some(items)) if items.len() == 2 => items,
330        other => {
331            return Err(RedisError::UnexpectedResponse {
332                expected: "two-element array [cursor, results]",
333                actual: format!("{other:?}"),
334            });
335        }
336    };
337
338    let cursor = match &items[0] {
339        Frame::BulkString(Some(b)) => String::from_utf8_lossy(b).into_owned(),
340        other => {
341            return Err(RedisError::UnexpectedResponse {
342                expected: "bulk string cursor",
343                actual: format!("{other:?}"),
344            });
345        }
346    };
347
348    let result_items = match &items[1] {
349        Frame::Array(Some(items)) => items,
350        Frame::Array(None) => {
351            return Ok(ScanResult {
352                cursor,
353                results: Vec::new(),
354            });
355        }
356        // RESP3 may return Set for SSCAN
357        Frame::Set(items) => items,
358        other => {
359            return Err(RedisError::UnexpectedResponse {
360                expected: "array of results",
361                actual: format!("{other:?}"),
362            });
363        }
364    };
365
366    let mut results = Vec::with_capacity(result_items.len());
367    for item in result_items {
368        results.push(parse_item(item)?);
369    }
370
371    Ok(ScanResult { cursor, results })
372}
373
374/// Parse HSCAN response: [cursor, [field, value, field, value, ...]]
375fn parse_scan_pair_response(frame: Frame) -> Result<ScanResult<(Bytes, Bytes)>, RedisError> {
376    let items = match frame {
377        Frame::Array(Some(items)) if items.len() == 2 => items,
378        other => {
379            return Err(RedisError::UnexpectedResponse {
380                expected: "two-element array [cursor, results]",
381                actual: format!("{other:?}"),
382            });
383        }
384    };
385
386    let cursor = match &items[0] {
387        Frame::BulkString(Some(b)) => String::from_utf8_lossy(b).into_owned(),
388        other => {
389            return Err(RedisError::UnexpectedResponse {
390                expected: "bulk string cursor",
391                actual: format!("{other:?}"),
392            });
393        }
394    };
395
396    let result_items = match &items[1] {
397        Frame::Array(Some(items)) => items,
398        Frame::Array(None) => {
399            return Ok(ScanResult {
400                cursor,
401                results: Vec::new(),
402            });
403        }
404        other => {
405            return Err(RedisError::UnexpectedResponse {
406                expected: "array of field-value pairs",
407                actual: format!("{other:?}"),
408            });
409        }
410    };
411
412    if result_items.len() % 2 != 0 {
413        return Err(RedisError::UnexpectedResponse {
414            expected: "even number of elements",
415            actual: format!("{} elements", result_items.len()),
416        });
417    }
418
419    let mut results = Vec::with_capacity(result_items.len() / 2);
420    for chunk in result_items.chunks(2) {
421        let field = extract_bulk_bytes(&chunk[0])?;
422        let value = extract_bulk_bytes(&chunk[1])?;
423        results.push((field, value));
424    }
425
426    Ok(ScanResult { cursor, results })
427}
428
429/// Parse ZSCAN response: [cursor, [member, score, member, score, ...]]
430fn parse_scan_score_response(frame: Frame) -> Result<ScanResult<(Bytes, f64)>, RedisError> {
431    let items = match frame {
432        Frame::Array(Some(items)) if items.len() == 2 => items,
433        other => {
434            return Err(RedisError::UnexpectedResponse {
435                expected: "two-element array [cursor, results]",
436                actual: format!("{other:?}"),
437            });
438        }
439    };
440
441    let cursor = match &items[0] {
442        Frame::BulkString(Some(b)) => String::from_utf8_lossy(b).into_owned(),
443        other => {
444            return Err(RedisError::UnexpectedResponse {
445                expected: "bulk string cursor",
446                actual: format!("{other:?}"),
447            });
448        }
449    };
450
451    let result_items = match &items[1] {
452        Frame::Array(Some(items)) => items,
453        Frame::Array(None) => {
454            return Ok(ScanResult {
455                cursor,
456                results: Vec::new(),
457            });
458        }
459        other => {
460            return Err(RedisError::UnexpectedResponse {
461                expected: "array of member-score pairs",
462                actual: format!("{other:?}"),
463            });
464        }
465    };
466
467    if result_items.len() % 2 != 0 {
468        return Err(RedisError::UnexpectedResponse {
469            expected: "even number of elements",
470            actual: format!("{} elements", result_items.len()),
471        });
472    }
473
474    let mut results = Vec::with_capacity(result_items.len() / 2);
475    for chunk in result_items.chunks(2) {
476        let member = extract_bulk_bytes(&chunk[0])?;
477        let score = match &chunk[1] {
478            Frame::BulkString(Some(b)) => {
479                let s = std::str::from_utf8(b).map_err(|e| RedisError::UnexpectedResponse {
480                    expected: "valid UTF-8 score",
481                    actual: e.to_string(),
482                })?;
483                s.parse::<f64>()
484                    .map_err(|e| RedisError::UnexpectedResponse {
485                        expected: "valid f64 score",
486                        actual: e.to_string(),
487                    })?
488            }
489            Frame::Double(d) => *d,
490            other => {
491                return Err(RedisError::UnexpectedResponse {
492                    expected: "bulk string or double score",
493                    actual: format!("{other:?}"),
494                });
495            }
496        };
497        results.push((member, score));
498    }
499
500    Ok(ScanResult { cursor, results })
501}
502
503fn extract_bulk_bytes(frame: &Frame) -> Result<Bytes, RedisError> {
504    match frame {
505        Frame::BulkString(Some(b)) => Ok(b.clone()),
506        other => Err(RedisError::UnexpectedResponse {
507            expected: "bulk string",
508            actual: format!("{other:?}"),
509        }),
510    }
511}
512
513#[cfg(test)]
514mod tests {
515    use super::*;
516    use redis_tower_core::Command;
517    use redis_tower_protocol::Frame;
518    use redis_tower_protocol::helpers::{array, bulk};
519
520    // -- Scan --
521
522    #[test]
523    fn scan_default_to_frame() {
524        let cmd = Scan::new();
525        assert_eq!(cmd.to_frame(), array(vec![bulk("SCAN"), bulk("0")]));
526    }
527
528    #[test]
529    fn scan_with_options_to_frame() {
530        let cmd = Scan::new()
531            .cursor("42")
532            .match_pattern("user:*")
533            .count(100)
534            .key_type("string");
535        assert_eq!(
536            cmd.to_frame(),
537            array(vec![
538                bulk("SCAN"),
539                bulk("42"),
540                bulk("MATCH"),
541                bulk("user:*"),
542                bulk("COUNT"),
543                bulk("100"),
544                bulk("TYPE"),
545                bulk("string"),
546            ])
547        );
548    }
549
550    #[test]
551    fn scan_parse_response_with_results() {
552        let cmd = Scan::new();
553        let frame = Frame::Array(Some(vec![
554            Frame::BulkString(Some(Bytes::from("17"))),
555            Frame::Array(Some(vec![
556                Frame::BulkString(Some(Bytes::from("key1"))),
557                Frame::BulkString(Some(Bytes::from("key2"))),
558            ])),
559        ]));
560        let result = cmd.parse_response(frame).unwrap();
561        assert_eq!(result.cursor, "17");
562        assert!(!result.is_finished());
563        assert_eq!(
564            result.results,
565            vec![Bytes::from("key1"), Bytes::from("key2")]
566        );
567    }
568
569    #[test]
570    fn scan_parse_response_finished() {
571        let cmd = Scan::new();
572        let frame = Frame::Array(Some(vec![
573            Frame::BulkString(Some(Bytes::from("0"))),
574            Frame::Array(Some(vec![Frame::BulkString(Some(Bytes::from("last_key")))])),
575        ]));
576        let result = cmd.parse_response(frame).unwrap();
577        assert_eq!(result.cursor, "0");
578        assert!(result.is_finished());
579    }
580
581    #[test]
582    fn scan_parse_response_empty_results() {
583        let cmd = Scan::new();
584        let frame = Frame::Array(Some(vec![
585            Frame::BulkString(Some(Bytes::from("5"))),
586            Frame::Array(None),
587        ]));
588        let result = cmd.parse_response(frame).unwrap();
589        assert_eq!(result.cursor, "5");
590        assert!(result.results.is_empty());
591    }
592
593    #[test]
594    fn scan_parse_error_on_wrong_shape() {
595        let cmd = Scan::new();
596        assert!(cmd.parse_response(Frame::Integer(0)).is_err());
597    }
598
599    // -- SScan --
600
601    #[test]
602    fn sscan_to_frame() {
603        let cmd = SScan::new("myset").match_pattern("a*").count(10);
604        assert_eq!(
605            cmd.to_frame(),
606            array(vec![
607                bulk("SSCAN"),
608                bulk("myset"),
609                bulk("0"),
610                bulk("MATCH"),
611                bulk("a*"),
612                bulk("COUNT"),
613                bulk("10"),
614            ])
615        );
616    }
617
618    #[test]
619    fn sscan_parse_response() {
620        let cmd = SScan::new("myset");
621        let frame = Frame::Array(Some(vec![
622            Frame::BulkString(Some(Bytes::from("0"))),
623            Frame::Array(Some(vec![Frame::BulkString(Some(Bytes::from("member1")))])),
624        ]));
625        let result = cmd.parse_response(frame).unwrap();
626        assert!(result.is_finished());
627        assert_eq!(result.results, vec![Bytes::from("member1")]);
628    }
629
630    // -- HScan --
631
632    #[test]
633    fn hscan_to_frame() {
634        let cmd = HScan::new("myhash").cursor("10");
635        assert_eq!(
636            cmd.to_frame(),
637            array(vec![bulk("HSCAN"), bulk("myhash"), bulk("10")])
638        );
639    }
640
641    #[test]
642    fn hscan_parse_response_pairs() {
643        let cmd = HScan::new("myhash");
644        let frame = Frame::Array(Some(vec![
645            Frame::BulkString(Some(Bytes::from("0"))),
646            Frame::Array(Some(vec![
647                Frame::BulkString(Some(Bytes::from("field1"))),
648                Frame::BulkString(Some(Bytes::from("value1"))),
649                Frame::BulkString(Some(Bytes::from("field2"))),
650                Frame::BulkString(Some(Bytes::from("value2"))),
651            ])),
652        ]));
653        let result = cmd.parse_response(frame).unwrap();
654        assert_eq!(result.results.len(), 2);
655        assert_eq!(
656            result.results[0],
657            (Bytes::from("field1"), Bytes::from("value1"))
658        );
659        assert_eq!(
660            result.results[1],
661            (Bytes::from("field2"), Bytes::from("value2"))
662        );
663    }
664
665    #[test]
666    fn hscan_parse_error_on_odd_elements() {
667        let cmd = HScan::new("myhash");
668        let frame = Frame::Array(Some(vec![
669            Frame::BulkString(Some(Bytes::from("0"))),
670            Frame::Array(Some(vec![
671                Frame::BulkString(Some(Bytes::from("field1"))),
672                Frame::BulkString(Some(Bytes::from("value1"))),
673                Frame::BulkString(Some(Bytes::from("field2"))),
674            ])),
675        ]));
676        assert!(cmd.parse_response(frame).is_err());
677    }
678
679    // -- ZScan --
680
681    #[test]
682    fn zscan_to_frame() {
683        let cmd = ZScan::new("myzset").match_pattern("a*");
684        assert_eq!(
685            cmd.to_frame(),
686            array(vec![
687                bulk("ZSCAN"),
688                bulk("myzset"),
689                bulk("0"),
690                bulk("MATCH"),
691                bulk("a*"),
692            ])
693        );
694    }
695
696    #[test]
697    fn zscan_parse_response_member_score_pairs() {
698        let cmd = ZScan::new("myzset");
699        let frame = Frame::Array(Some(vec![
700            Frame::BulkString(Some(Bytes::from("0"))),
701            Frame::Array(Some(vec![
702                Frame::BulkString(Some(Bytes::from("member1"))),
703                Frame::BulkString(Some(Bytes::from("1.5"))),
704                Frame::BulkString(Some(Bytes::from("member2"))),
705                Frame::BulkString(Some(Bytes::from("3.0"))),
706            ])),
707        ]));
708        let result = cmd.parse_response(frame).unwrap();
709        assert_eq!(result.results.len(), 2);
710        assert_eq!(result.results[0].0, Bytes::from("member1"));
711        assert!((result.results[0].1 - 1.5).abs() < f64::EPSILON);
712        assert_eq!(result.results[1].0, Bytes::from("member2"));
713        assert!((result.results[1].1 - 3.0).abs() < f64::EPSILON);
714    }
715
716    #[test]
717    fn zscan_parse_double_score() {
718        let cmd = ZScan::new("myzset");
719        let frame = Frame::Array(Some(vec![
720            Frame::BulkString(Some(Bytes::from("0"))),
721            Frame::Array(Some(vec![
722                Frame::BulkString(Some(Bytes::from("member1"))),
723                Frame::Double(2.5),
724            ])),
725        ]));
726        let result = cmd.parse_response(frame).unwrap();
727        assert!((result.results[0].1 - 2.5).abs() < f64::EPSILON);
728    }
729}