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}