Skip to main content

kevy_resp/
reply.rs

1//! The parsed-reply type returned by [`crate::parse_reply`].
2
3/// A parsed RESP reply (server → client) — the client-side counterpart of
4/// the crate's `encode_*` functions (server-side encoders).
5///
6/// Variants prefixed with `Resp3:` in their doc are only ever produced by
7/// a server speaking RESP3; an `HELLO 2` (or no `HELLO`) session sees the
8/// RESP2 subset (`Simple` / `Error` / `Int` / `Bulk` / `Nil` / `Array`)
9/// exclusively. The variant set is RESP3's type set and deliberately
10/// exhaustive: a `match` on `Reply` lists every wire type, so a decoder
11/// cannot silently drop one.
12///
13/// ```
14/// use kevy_resp::{Reply, parse_reply};
15///
16/// let (reply, used) = parse_reply(b"*2\r\n$3\r\nfoo\r\n:7\r\n")?.expect("complete frame");
17/// assert_eq!(used, 17);
18/// match reply {
19///     Reply::Array(items) => assert_eq!(items, [Reply::Bulk(b"foo".to_vec()), Reply::Int(7)]),
20///     other => panic!("unexpected {other:?}"),
21/// }
22/// # Ok::<(), kevy_resp::ProtocolError>(())
23/// ```
24#[derive(Debug, Clone, PartialEq)]
25pub enum Reply {
26    /// `+OK`
27    ///
28    /// ```
29    /// use kevy_resp::{Reply, parse_reply};
30    /// assert_eq!(parse_reply(b"+OK\r\n")?, Some((Reply::Simple(b"OK".to_vec()), 5)));
31    /// # Ok::<(), kevy_resp::ProtocolError>(())
32    /// ```
33    Simple(Vec<u8>),
34    /// `-ERR ...`
35    ///
36    /// ```
37    /// use kevy_resp::{Reply, parse_reply};
38    /// let (reply, _) = parse_reply(b"-ERR no such key\r\n")?.expect("complete frame");
39    /// assert_eq!(reply, Reply::Error(b"ERR no such key".to_vec()));
40    /// # Ok::<(), kevy_resp::ProtocolError>(())
41    /// ```
42    Error(Vec<u8>),
43    /// `:42`
44    ///
45    /// ```
46    /// use kevy_resp::{Reply, parse_reply};
47    /// assert_eq!(parse_reply(b":-3\r\n")?, Some((Reply::Int(-3), 5)));
48    /// # Ok::<(), kevy_resp::ProtocolError>(())
49    /// ```
50    Int(i64),
51    /// `$5\r\nhello\r\n`
52    ///
53    /// ```
54    /// use kevy_resp::{Reply, parse_reply};
55    /// let (reply, _) = parse_reply(b"$5\r\nhello\r\n")?.expect("complete frame");
56    /// assert_eq!(reply, Reply::Bulk(b"hello".to_vec()));
57    /// # Ok::<(), kevy_resp::ProtocolError>(())
58    /// ```
59    Bulk(Vec<u8>),
60    /// `$-1` or `*-1` — the RESP2 null sentinel; in RESP3 the dedicated
61    /// [`Reply::Null`] (`_\r\n`) is used instead. Both round-trip here.
62    ///
63    /// ```
64    /// use kevy_resp::{Reply, parse_reply};
65    /// assert_eq!(parse_reply(b"$-1\r\n")?, Some((Reply::Nil, 5)));
66    /// assert_eq!(parse_reply(b"*-1\r\n")?, Some((Reply::Nil, 5)));
67    /// # Ok::<(), kevy_resp::ProtocolError>(())
68    /// ```
69    Nil,
70    /// `*N ...`
71    ///
72    /// ```
73    /// use kevy_resp::{Reply, parse_reply};
74    /// let (reply, _) = parse_reply(b"*2\r\n:1\r\n+x\r\n")?.expect("complete frame");
75    /// assert_eq!(reply, Reply::Array(vec![Reply::Int(1), Reply::Simple(b"x".to_vec())]));
76    /// # Ok::<(), kevy_resp::ProtocolError>(())
77    /// ```
78    Array(Vec<Reply>),
79    /// **Resp3:** `%N\r\n<key1><value1>...<keyN><valueN>` — N pairs (the
80    /// header count is the pair count, NOT the element count, so a map of
81    /// 3 pairs is `%3` plus 6 sub-replies). Parsed/exposed as a Vec of
82    /// pairs so duplicate keys + insertion order are preserved.
83    ///
84    /// ```
85    /// use kevy_resp::{Reply, parse_reply};
86    /// let (reply, _) = parse_reply(b"%1\r\n+f\r\n:1\r\n")?.expect("complete frame");
87    /// assert_eq!(reply, Reply::Map(vec![(Reply::Simple(b"f".to_vec()), Reply::Int(1))]));
88    /// # Ok::<(), kevy_resp::ProtocolError>(())
89    /// ```
90    Map(Vec<(Reply, Reply)>),
91    /// **Resp3:** `~N\r\n<item1>...<itemN>` — set semantics on the wire;
92    /// dedup is the application's job (RESP3 doesn't require it).
93    ///
94    /// ```
95    /// use kevy_resp::{Reply, parse_reply};
96    /// let (reply, _) = parse_reply(b"~2\r\n:1\r\n:1\r\n")?.expect("complete frame");
97    /// // duplicates reach the caller as sent
98    /// assert_eq!(reply, Reply::Set(vec![Reply::Int(1), Reply::Int(1)]));
99    /// # Ok::<(), kevy_resp::ProtocolError>(())
100    /// ```
101    Set(Vec<Reply>),
102    /// **Resp3:** `,1.5\r\n` — double. `inf` / `-inf` / `nan` are valid
103    /// payloads per the RESP3 spec and survive the round-trip.
104    ///
105    /// ```
106    /// use kevy_resp::{Reply, parse_reply};
107    /// assert_eq!(parse_reply(b",1.5\r\n")?, Some((Reply::Double(1.5), 6)));
108    /// let (inf, _) = parse_reply(b",inf\r\n")?.expect("complete frame");
109    /// assert_eq!(inf, Reply::Double(f64::INFINITY));
110    /// # Ok::<(), kevy_resp::ProtocolError>(())
111    /// ```
112    Double(f64),
113    /// **Resp3:** `#t\r\n` / `#f\r\n` — boolean.
114    ///
115    /// ```
116    /// use kevy_resp::{Reply, parse_reply};
117    /// assert_eq!(parse_reply(b"#t\r\n")?, Some((Reply::Boolean(true), 4)));
118    /// # Ok::<(), kevy_resp::ProtocolError>(())
119    /// ```
120    Boolean(bool),
121    /// **Resp3:** `=15\r\ntxt:Some bytes\r\n` — verbatim string carrying
122    /// a 3-char format tag (`txt` / `mkd` / etc.) + raw bytes. The colon
123    /// separator is part of the wire encoding but not part of `data`.
124    ///
125    /// ```
126    /// use kevy_resp::{Reply, parse_reply};
127    /// let (reply, _) = parse_reply(b"=9\r\ntxt:hello\r\n")?.expect("complete frame");
128    /// assert_eq!(reply, Reply::Verbatim { fmt: *b"txt", data: b"hello".to_vec() });
129    /// # Ok::<(), kevy_resp::ProtocolError>(())
130    /// ```
131    Verbatim {
132        /// 3-char format tag (e.g. `b"txt"` for plain text, `b"mkd"` for markdown).
133        ///
134        /// ```
135        /// use kevy_resp::{Reply, parse_reply};
136        /// let (reply, _) = parse_reply(b"=8\r\nmkd:# hi\r\n")?.expect("complete frame");
137        /// let Reply::Verbatim { fmt, .. } = reply else { panic!("not verbatim") };
138        /// assert_eq!(&fmt, b"mkd");
139        /// # Ok::<(), kevy_resp::ProtocolError>(())
140        /// ```
141        fmt: [u8; 3],
142        /// Payload bytes following the `:` separator.
143        ///
144        /// ```
145        /// use kevy_resp::{Reply, parse_reply};
146        /// let (reply, _) = parse_reply(b"=6\r\ntxt:ab\r\n")?.expect("complete frame");
147        /// let Reply::Verbatim { data, .. } = reply else { panic!("not verbatim") };
148        /// assert_eq!(data, b"ab");
149        /// # Ok::<(), kevy_resp::ProtocolError>(())
150        /// ```
151        data: Vec<u8>,
152    },
153    /// **Resp3:** `(170141183460469231731687303715884105727\r\n` — arbitrary-
154    /// precision integer; carried as the raw digit bytes since we don't
155    /// pull in a bignum crate (charter: zero deps).
156    ///
157    /// ```
158    /// use kevy_resp::{Reply, parse_reply};
159    /// let (reply, _) = parse_reply(b"(12345678901234567890123\r\n")?.expect("complete frame");
160    /// assert_eq!(reply, Reply::BigNumber(b"12345678901234567890123".to_vec()));
161    /// # Ok::<(), kevy_resp::ProtocolError>(())
162    /// ```
163    BigNumber(Vec<u8>),
164    /// **Resp3:** `_\r\n` — true null. RESP2 falls back to [`Reply::Nil`].
165    ///
166    /// ```
167    /// use kevy_resp::{Reply, parse_reply};
168    /// assert_eq!(parse_reply(b"_\r\n")?, Some((Reply::Null, 3)));
169    /// # Ok::<(), kevy_resp::ProtocolError>(())
170    /// ```
171    Null,
172    /// **Resp3:** `>N\r\n...` — like [`Reply::Array`] but tagged as an
173    /// out-of-band server-push frame (pub/sub messages in RESP3). The
174    /// client must dispatch these separately from regular replies.
175    ///
176    /// ```
177    /// use kevy_resp::{Reply, parse_reply};
178    /// let (reply, _) = parse_reply(b">2\r\n+message\r\n+hi\r\n")?.expect("complete frame");
179    /// assert!(matches!(reply, Reply::Push(ref parts) if parts.len() == 2));
180    /// # Ok::<(), kevy_resp::ProtocolError>(())
181    /// ```
182    Push(Vec<Reply>),
183    /// **Resp3:** `!8\r\nERR ohno\r\n` — error carried as a length-prefixed
184    /// bulk (handles errors containing CRLF that the simple-string `-`
185    /// shape can't encode).
186    ///
187    /// ```
188    /// use kevy_resp::{Reply, parse_reply};
189    /// let (reply, _) = parse_reply(b"!8\r\nERR ohno\r\n")?.expect("complete frame");
190    /// assert_eq!(reply, Reply::BlobError(b"ERR ohno".to_vec()));
191    /// # Ok::<(), kevy_resp::ProtocolError>(())
192    /// ```
193    BlobError(Vec<u8>),
194}