Skip to main content

redis_tower_core/
from_frame.rs

1//! Typed decoding of raw RESP frames into Rust types.
2//!
3//! [`RedisConvert`](crate::RedisConvert) converts the *already-typed* response a
4//! command produces (`Option<Bytes>`, `i64`, ...). [`FromFrame`] works one level
5//! lower: it decodes a raw [`Frame`] straight into a Rust type, which is what
6//! dynamic callers need when they run an arbitrary command via
7//! [`RawCommand`](https://docs.rs/redis-tower-commands) and get back a `Frame`
8//! with no typed response shape attached.
9//!
10//! Impls are provided for the common scalar types, `Bytes`, `Option<T>`,
11//! `Vec<T>`, fixed-size tuples, and `HashMap<K, V>`, covering the bulk of the
12//! reply shapes a CLI or tooling layer decodes. `Frame` implements `FromFrame`
13//! as an identity, so `query::<Frame>()` is the raw passthrough.
14//!
15//! # Example
16//!
17//! Decoding the frames a dynamic command would return. `RawCommand::query::<T>()`
18//! calls `T::from_frame` on the reply, so these are the shapes it handles.
19//!
20//! ```no_run
21//! use std::collections::HashMap;
22//!
23//! use redis_tower_core::FromFrame;
24//! use redis_tower_protocol::Frame;
25//! use redis_tower_protocol::helpers::{array, bulk};
26//!
27//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
28//! // Scalar -- the INCR reply
29//! let n = i64::from_frame(Frame::Integer(1))?;
30//!
31//! // Array -- the SMEMBERS reply
32//! let members = Vec::<String>::from_frame(array(vec![bulk("a"), bulk("b")]))?;
33//!
34//! // Map (RESP3 map or RESP2 flat array) -- the HGETALL reply
35//! let fields = HashMap::<String, String>::from_frame(array(vec![bulk("f"), bulk("v")]))?;
36//! # let _ = (n, members, fields);
37//! # Ok(())
38//! # }
39//! ```
40
41use std::collections::HashMap;
42use std::hash::Hash;
43
44use bytes::Bytes;
45
46use crate::Frame;
47use crate::error::RedisError;
48
49/// Decode a raw RESP [`Frame`] into a Rust type.
50///
51/// Implement this trait for custom types to enable
52/// [`RawCommand::query::<T>()`](https://docs.rs/redis-tower-commands) typed
53/// decoding of dynamic commands.
54pub trait FromFrame: Sized {
55    /// Decode a response frame into this type.
56    ///
57    /// Error frames (`-ERR ...` / blob errors) are surfaced as
58    /// [`RedisError::Redis`] before any type matching, so every impl can assume
59    /// a non-error frame.
60    fn from_frame(frame: Frame) -> Result<Self, RedisError>;
61}
62
63/// Reject error frames up front so each impl only handles value frames.
64fn check_error(frame: Frame) -> Result<Frame, RedisError> {
65    match frame {
66        Frame::Error(b) | Frame::BlobError(b) => {
67            Err(RedisError::Redis(String::from_utf8_lossy(&b).into_owned()))
68        }
69        other => Ok(other),
70    }
71}
72
73fn unexpected(expected: &'static str, frame: &Frame) -> RedisError {
74    RedisError::UnexpectedResponse {
75        expected,
76        actual: format!("{frame:?}"),
77    }
78}
79
80/// Extract the bytes from a string-like frame (simple/bulk/verbatim/big-number).
81fn frame_to_bytes(frame: Frame) -> Result<Bytes, RedisError> {
82    match frame {
83        Frame::SimpleString(b) | Frame::BigNumber(b) => Ok(b),
84        Frame::BulkString(Some(b)) => Ok(b),
85        Frame::VerbatimString(_, b) => Ok(b),
86        other => Err(unexpected("string-like frame", &other)),
87    }
88}
89
90/// Extract the element vector from an array-like frame.
91fn frame_to_vec(frame: Frame) -> Result<Vec<Frame>, RedisError> {
92    match frame {
93        Frame::Array(Some(v)) => Ok(v),
94        Frame::Array(None) => Ok(Vec::new()),
95        Frame::Set(v)
96        | Frame::Push(v)
97        | Frame::StreamedArray(v)
98        | Frame::StreamedSet(v)
99        | Frame::StreamedPush(v) => Ok(v),
100        other => Err(unexpected("array-like frame", &other)),
101    }
102}
103
104// -- Identity --
105
106impl FromFrame for Frame {
107    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
108        Ok(frame)
109    }
110}
111
112// -- String-like scalars --
113
114impl FromFrame for Bytes {
115    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
116        frame_to_bytes(check_error(frame)?)
117    }
118}
119
120// Note: there is intentionally no dedicated `Vec<u8>` impl. Raw bulk-string
121// bytes decode to `Bytes` (use `.to_vec()` for an owned `Vec<u8>`); `Vec<u8>`
122// itself is handled by the generic `Vec<T>` impl as an array of `u8` elements.
123
124impl FromFrame for String {
125    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
126        let b = frame_to_bytes(check_error(frame)?)?;
127        String::from_utf8(b.to_vec()).map_err(|_| RedisError::TypeMismatch {
128            expected: "valid UTF-8 string",
129        })
130    }
131}
132
133// -- Integer scalars --
134
135macro_rules! impl_from_frame_int {
136    ($($t:ty),+) => {
137        $(
138            impl FromFrame for $t {
139                fn from_frame(frame: Frame) -> Result<Self, RedisError> {
140                    match check_error(frame)? {
141                        Frame::Integer(i) => <$t>::try_from(i).map_err(|_| {
142                            RedisError::TypeMismatch {
143                                expected: concat!(stringify!($t), " (value out of range)"),
144                            }
145                        }),
146                        other => {
147                            let b = frame_to_bytes(other)?;
148                            let s = std::str::from_utf8(&b).map_err(|_| {
149                                RedisError::TypeMismatch {
150                                    expected: concat!("parseable as ", stringify!($t)),
151                                }
152                            })?;
153                            s.trim().parse::<$t>().map_err(|_| RedisError::TypeMismatch {
154                                expected: concat!("parseable as ", stringify!($t)),
155                            })
156                        }
157                    }
158                }
159            }
160        )+
161    };
162}
163
164impl_from_frame_int!(
165    i8, i16, i32, i64, i128, u8, u16, u32, u64, u128, isize, usize
166);
167
168// -- Float scalars --
169
170fn parse_float<T: std::str::FromStr>(b: &[u8]) -> Result<T, RedisError> {
171    let s = std::str::from_utf8(b).map_err(|_| RedisError::TypeMismatch {
172        expected: "parseable as float",
173    })?;
174    s.trim().parse::<T>().map_err(|_| RedisError::TypeMismatch {
175        expected: "parseable as float",
176    })
177}
178
179impl FromFrame for f64 {
180    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
181        match check_error(frame)? {
182            Frame::Double(d) => Ok(d),
183            Frame::Integer(i) => Ok(i as f64),
184            Frame::SpecialFloat(b) => parse_float::<f64>(&b),
185            other => parse_float::<f64>(&frame_to_bytes(other)?),
186        }
187    }
188}
189
190impl FromFrame for f32 {
191    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
192        match check_error(frame)? {
193            Frame::Double(d) => Ok(d as f32),
194            Frame::Integer(i) => Ok(i as f32),
195            Frame::SpecialFloat(b) => parse_float::<f32>(&b),
196            other => parse_float::<f32>(&frame_to_bytes(other)?),
197        }
198    }
199}
200
201// -- Boolean --
202
203impl FromFrame for bool {
204    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
205        match check_error(frame)? {
206            Frame::Boolean(b) => Ok(b),
207            Frame::Integer(i) => Ok(i != 0),
208            other => match frame_to_bytes(other)?.as_ref() {
209                b"1" | b"true" | b"TRUE" => Ok(true),
210                b"0" | b"false" | b"FALSE" => Ok(false),
211                _ => Err(RedisError::TypeMismatch {
212                    expected: "boolean (1/0 or true/false)",
213                }),
214            },
215        }
216    }
217}
218
219// -- Option --
220
221impl<T: FromFrame> FromFrame for Option<T> {
222    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
223        match check_error(frame)? {
224            Frame::Null | Frame::BulkString(None) | Frame::Array(None) => Ok(None),
225            other => T::from_frame(other).map(Some),
226        }
227    }
228}
229
230// -- Vec --
231
232impl<T: FromFrame> FromFrame for Vec<T> {
233    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
234        frame_to_vec(check_error(frame)?)?
235            .into_iter()
236            .map(T::from_frame)
237            .collect()
238    }
239}
240
241// -- HashMap --
242
243impl<K, V> FromFrame for HashMap<K, V>
244where
245    K: FromFrame + Eq + Hash,
246    V: FromFrame,
247{
248    fn from_frame(frame: Frame) -> Result<Self, RedisError> {
249        let pairs = match check_error(frame)? {
250            Frame::Map(pairs) | Frame::StreamedMap(pairs) | Frame::Attribute(pairs) => pairs,
251            Frame::Array(None) => Vec::new(),
252            // RESP2 returns maps as a flat array [k, v, k, v, ...].
253            Frame::Array(Some(flat)) => {
254                if flat.len() % 2 != 0 {
255                    return Err(RedisError::UnexpectedResponse {
256                        expected: "flat array with an even number of elements",
257                        actual: format!("array of {} elements", flat.len()),
258                    });
259                }
260                let mut it = flat.into_iter();
261                let mut pairs = Vec::with_capacity(it.len() / 2);
262                while let (Some(k), Some(v)) = (it.next(), it.next()) {
263                    pairs.push((k, v));
264                }
265                pairs
266            }
267            other => return Err(unexpected("map or flat array", &other)),
268        };
269        pairs
270            .into_iter()
271            .map(|(k, v)| Ok((K::from_frame(k)?, V::from_frame(v)?)))
272            .collect()
273    }
274}
275
276// -- Tuples --
277
278macro_rules! impl_from_frame_tuple {
279    ($len:expr; $($name:ident),+) => {
280        impl<$($name: FromFrame),+> FromFrame for ($($name,)+) {
281            fn from_frame(frame: Frame) -> Result<Self, RedisError> {
282                let items = frame_to_vec(check_error(frame)?)?;
283                if items.len() != $len {
284                    return Err(RedisError::UnexpectedResponse {
285                        expected: concat!("array of ", stringify!($len), " elements"),
286                        actual: format!("array of {} elements", items.len()),
287                    });
288                }
289                let mut it = items.into_iter();
290                Ok((
291                    $( $name::from_frame(it.next().expect("length checked above"))?, )+
292                ))
293            }
294        }
295    };
296}
297
298impl_from_frame_tuple!(1; A);
299impl_from_frame_tuple!(2; A, B);
300impl_from_frame_tuple!(3; A, B, C);
301impl_from_frame_tuple!(4; A, B, C, D);
302impl_from_frame_tuple!(5; A, B, C, D, E);
303impl_from_frame_tuple!(6; A, B, C, D, E, F);
304
305#[cfg(test)]
306mod tests {
307    use super::*;
308
309    // -- Identity --
310
311    #[test]
312    fn frame_identity() {
313        let f = Frame::Integer(7);
314        let out: Frame = FromFrame::from_frame(f.clone()).unwrap();
315        assert_eq!(out, f);
316    }
317
318    #[test]
319    fn frame_identity_preserves_errors() {
320        // The identity impl is a raw passthrough and does not reject errors.
321        let f = Frame::Error(Bytes::from("ERR boom"));
322        let out: Frame = FromFrame::from_frame(f.clone()).unwrap();
323        assert_eq!(out, f);
324    }
325
326    // -- Error frames --
327
328    #[test]
329    fn error_frame_maps_to_redis_error() {
330        let f = Frame::Error(Bytes::from("ERR wrong type"));
331        let r: Result<String, _> = FromFrame::from_frame(f);
332        match r {
333            Err(RedisError::Redis(m)) => assert_eq!(m, "ERR wrong type"),
334            other => panic!("expected Redis error, got {other:?}"),
335        }
336    }
337
338    #[test]
339    fn blob_error_maps_to_redis_error() {
340        let f = Frame::BlobError(Bytes::from("SYNTAX bad"));
341        let r: Result<i64, _> = FromFrame::from_frame(f);
342        assert!(matches!(r, Err(RedisError::Redis(_))));
343    }
344
345    // -- String-like scalars --
346
347    #[test]
348    fn string_from_bulk() {
349        let s: String = FromFrame::from_frame(Frame::BulkString(Some(Bytes::from("hi")))).unwrap();
350        assert_eq!(s, "hi");
351    }
352
353    #[test]
354    fn string_from_simple() {
355        let s: String = FromFrame::from_frame(Frame::SimpleString(Bytes::from("OK"))).unwrap();
356        assert_eq!(s, "OK");
357    }
358
359    #[test]
360    fn string_from_verbatim() {
361        let f = Frame::VerbatimString(Bytes::from("txt"), Bytes::from("hello"));
362        let s: String = FromFrame::from_frame(f).unwrap();
363        assert_eq!(s, "hello");
364    }
365
366    #[test]
367    fn bytes_from_bulk() {
368        let b: Bytes = FromFrame::from_frame(Frame::BulkString(Some(Bytes::from("raw")))).unwrap();
369        assert_eq!(b, Bytes::from("raw"));
370    }
371
372    #[test]
373    fn vec_u8_from_integer_array() {
374        // Vec<u8> is an array of u8 elements (the generic Vec<T> impl), not raw
375        // bulk-string bytes -- use Bytes for that.
376        let f = Frame::Array(Some(vec![Frame::Integer(1), Frame::Integer(2)]));
377        let v: Vec<u8> = FromFrame::from_frame(f).unwrap();
378        assert_eq!(v, vec![1u8, 2]);
379    }
380
381    #[test]
382    fn string_invalid_utf8_fails() {
383        let f = Frame::BulkString(Some(Bytes::from(vec![0xff, 0xfe])));
384        let r: Result<String, _> = FromFrame::from_frame(f);
385        assert!(matches!(r, Err(RedisError::TypeMismatch { .. })));
386    }
387
388    #[test]
389    fn string_from_integer_fails() {
390        let r: Result<String, _> = FromFrame::from_frame(Frame::Integer(1));
391        assert!(matches!(r, Err(RedisError::UnexpectedResponse { .. })));
392    }
393
394    // -- Integer scalars --
395
396    #[test]
397    fn i64_from_integer() {
398        let n: i64 = FromFrame::from_frame(Frame::Integer(42)).unwrap();
399        assert_eq!(n, 42);
400    }
401
402    #[test]
403    fn u32_from_integer() {
404        let n: u32 = FromFrame::from_frame(Frame::Integer(7)).unwrap();
405        assert_eq!(n, 7);
406    }
407
408    #[test]
409    fn u32_from_negative_integer_fails() {
410        let r: Result<u32, _> = FromFrame::from_frame(Frame::Integer(-1));
411        assert!(matches!(r, Err(RedisError::TypeMismatch { .. })));
412    }
413
414    #[test]
415    fn i64_from_bulk_string() {
416        // Redis often returns numbers as bulk strings.
417        let n: i64 = FromFrame::from_frame(Frame::BulkString(Some(Bytes::from("123")))).unwrap();
418        assert_eq!(n, 123);
419    }
420
421    #[test]
422    fn i64_from_unparseable_string_fails() {
423        let f = Frame::BulkString(Some(Bytes::from("nope")));
424        let r: Result<i64, _> = FromFrame::from_frame(f);
425        assert!(matches!(r, Err(RedisError::TypeMismatch { .. })));
426    }
427
428    // -- Float scalars --
429
430    #[test]
431    fn f64_from_double() {
432        let n: f64 = FromFrame::from_frame(Frame::Double(2.5)).unwrap();
433        assert!((n - 2.5).abs() < f64::EPSILON);
434    }
435
436    #[test]
437    fn f64_from_integer() {
438        let n: f64 = FromFrame::from_frame(Frame::Integer(3)).unwrap();
439        assert!((n - 3.0).abs() < f64::EPSILON);
440    }
441
442    #[test]
443    fn f64_from_bulk_string() {
444        let n: f64 = FromFrame::from_frame(Frame::BulkString(Some(Bytes::from("1.25")))).unwrap();
445        assert!((n - 1.25).abs() < 1e-9);
446    }
447
448    #[test]
449    fn f64_from_special_float_inf() {
450        let n: f64 = FromFrame::from_frame(Frame::SpecialFloat(Bytes::from("inf"))).unwrap();
451        assert!(n.is_infinite() && n.is_sign_positive());
452    }
453
454    #[test]
455    fn f32_from_double() {
456        let n: f32 = FromFrame::from_frame(Frame::Double(1.5)).unwrap();
457        assert!((n - 1.5).abs() < f32::EPSILON);
458    }
459
460    // -- Boolean --
461
462    #[test]
463    fn bool_from_boolean() {
464        let b: bool = FromFrame::from_frame(Frame::Boolean(true)).unwrap();
465        assert!(b);
466    }
467
468    #[test]
469    fn bool_from_integer() {
470        assert!(<bool as FromFrame>::from_frame(Frame::Integer(1)).unwrap());
471        assert!(!<bool as FromFrame>::from_frame(Frame::Integer(0)).unwrap());
472    }
473
474    #[test]
475    fn bool_from_string() {
476        let f = Frame::BulkString(Some(Bytes::from("true")));
477        assert!(<bool as FromFrame>::from_frame(f).unwrap());
478    }
479
480    #[test]
481    fn bool_from_invalid_string_fails() {
482        let f = Frame::BulkString(Some(Bytes::from("maybe")));
483        let r: Result<bool, _> = FromFrame::from_frame(f);
484        assert!(matches!(r, Err(RedisError::TypeMismatch { .. })));
485    }
486
487    // -- Option --
488
489    #[test]
490    fn option_from_null() {
491        let v: Option<String> = FromFrame::from_frame(Frame::Null).unwrap();
492        assert_eq!(v, None);
493    }
494
495    #[test]
496    fn option_from_nil_bulk() {
497        let v: Option<String> = FromFrame::from_frame(Frame::BulkString(None)).unwrap();
498        assert_eq!(v, None);
499    }
500
501    #[test]
502    fn option_from_nil_array() {
503        let v: Option<Vec<String>> = FromFrame::from_frame(Frame::Array(None)).unwrap();
504        assert_eq!(v, None);
505    }
506
507    #[test]
508    fn option_some() {
509        let f = Frame::BulkString(Some(Bytes::from("x")));
510        let v: Option<String> = FromFrame::from_frame(f).unwrap();
511        assert_eq!(v, Some("x".to_string()));
512    }
513
514    // -- Vec --
515
516    #[test]
517    fn vec_string_from_array() {
518        let f = Frame::Array(Some(vec![
519            Frame::BulkString(Some(Bytes::from("a"))),
520            Frame::BulkString(Some(Bytes::from("b"))),
521        ]));
522        let v: Vec<String> = FromFrame::from_frame(f).unwrap();
523        assert_eq!(v, vec!["a", "b"]);
524    }
525
526    #[test]
527    fn vec_from_set() {
528        let f = Frame::Set(vec![Frame::Integer(1), Frame::Integer(2)]);
529        let v: Vec<i64> = FromFrame::from_frame(f).unwrap();
530        assert_eq!(v, vec![1, 2]);
531    }
532
533    #[test]
534    fn vec_from_empty_array() {
535        let v: Vec<String> = FromFrame::from_frame(Frame::Array(None)).unwrap();
536        assert!(v.is_empty());
537    }
538
539    #[test]
540    fn vec_of_options_mixed() {
541        let f = Frame::Array(Some(vec![
542            Frame::BulkString(Some(Bytes::from("a"))),
543            Frame::Null,
544        ]));
545        let v: Vec<Option<String>> = FromFrame::from_frame(f).unwrap();
546        assert_eq!(v, vec![Some("a".to_string()), None]);
547    }
548
549    #[test]
550    fn vec_from_non_array_fails() {
551        let r: Result<Vec<String>, _> = FromFrame::from_frame(Frame::Integer(1));
552        assert!(matches!(r, Err(RedisError::UnexpectedResponse { .. })));
553    }
554
555    // -- HashMap --
556
557    #[test]
558    fn hashmap_from_map() {
559        let f = Frame::Map(vec![
560            (
561                Frame::BulkString(Some(Bytes::from("k1"))),
562                Frame::BulkString(Some(Bytes::from("v1"))),
563            ),
564            (
565                Frame::BulkString(Some(Bytes::from("k2"))),
566                Frame::BulkString(Some(Bytes::from("v2"))),
567            ),
568        ]);
569        let m: HashMap<String, String> = FromFrame::from_frame(f).unwrap();
570        assert_eq!(m.get("k1").unwrap(), "v1");
571        assert_eq!(m.get("k2").unwrap(), "v2");
572    }
573
574    #[test]
575    fn hashmap_from_flat_array() {
576        // RESP2 shape: HGETALL returns a flat array.
577        let f = Frame::Array(Some(vec![
578            Frame::BulkString(Some(Bytes::from("field"))),
579            Frame::BulkString(Some(Bytes::from("42"))),
580        ]));
581        let m: HashMap<String, i64> = FromFrame::from_frame(f).unwrap();
582        assert_eq!(m.get("field").copied(), Some(42));
583    }
584
585    #[test]
586    fn hashmap_from_odd_flat_array_fails() {
587        let f = Frame::Array(Some(vec![Frame::BulkString(Some(Bytes::from("lonely")))]));
588        let r: Result<HashMap<String, String>, _> = FromFrame::from_frame(f);
589        assert!(matches!(r, Err(RedisError::UnexpectedResponse { .. })));
590    }
591
592    #[test]
593    fn hashmap_from_empty_array() {
594        let m: HashMap<String, String> = FromFrame::from_frame(Frame::Array(None)).unwrap();
595        assert!(m.is_empty());
596    }
597
598    // -- Tuples --
599
600    #[test]
601    fn tuple_pair() {
602        let f = Frame::Array(Some(vec![
603            Frame::BulkString(Some(Bytes::from("name"))),
604            Frame::Integer(30),
605        ]));
606        let (name, age): (String, i64) = FromFrame::from_frame(f).unwrap();
607        assert_eq!(name, "name");
608        assert_eq!(age, 30);
609    }
610
611    #[test]
612    fn tuple_triple_mixed() {
613        let f = Frame::Array(Some(vec![
614            Frame::BulkString(Some(Bytes::from("a"))),
615            Frame::Integer(1),
616            Frame::Double(2.5),
617        ]));
618        let (a, b, c): (String, i64, f64) = FromFrame::from_frame(f).unwrap();
619        assert_eq!(a, "a");
620        assert_eq!(b, 1);
621        assert!((c - 2.5).abs() < f64::EPSILON);
622    }
623
624    #[test]
625    fn tuple_wrong_arity_fails() {
626        let f = Frame::Array(Some(vec![Frame::Integer(1)]));
627        let r: Result<(i64, i64), _> = FromFrame::from_frame(f);
628        assert!(matches!(r, Err(RedisError::UnexpectedResponse { .. })));
629    }
630
631    // -- Nested --
632
633    #[test]
634    fn nested_vec_of_pairs() {
635        let f = Frame::Array(Some(vec![
636            Frame::Array(Some(vec![
637                Frame::BulkString(Some(Bytes::from("a"))),
638                Frame::Integer(1),
639            ])),
640            Frame::Array(Some(vec![
641                Frame::BulkString(Some(Bytes::from("b"))),
642                Frame::Integer(2),
643            ])),
644        ]));
645        let v: Vec<(String, i64)> = FromFrame::from_frame(f).unwrap();
646        assert_eq!(v, vec![("a".to_string(), 1), ("b".to_string(), 2)]);
647    }
648}