Skip to main content

redis_tower_protocol/
codec.rs

1use bytes::{Buf, Bytes, BytesMut};
2use resp_rs::resp3;
3use tokio_util::codec::{Decoder, Encoder};
4
5use crate::Frame;
6use crate::error::ProtocolError;
7
8#[cfg(test)]
9thread_local! {
10    static TEST_MATERIALIZATIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
11    static TEST_MATERIALIZED_BYTES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
12}
13
14/// Default maximum wire size, in bytes, of a single decoded frame.
15///
16/// The 512 MiB limit includes headers, payloads, and aggregate children. It is
17/// not a bulk-payload limit: a reply containing a 512 MiB value, or a larger
18/// aggregate, requires a higher limit. Lower it for untrusted servers.
19pub const DEFAULT_MAX_FRAME_SIZE: usize = 512 * 1024 * 1024;
20
21/// Default maximum nesting depth of a decoded frame.
22///
23/// Redis replies nest a handful of levels at most (`CLUSTER SLOTS` and
24/// `XINFO STREAM` are the deepest in common use), so 128 leaves a wide margin
25/// over real traffic while still bounding a hostile server's reply.
26pub const DEFAULT_MAX_DEPTH: usize = 128;
27
28/// Resource limits [`RespCodec`] applies while decoding.
29///
30/// Frames are structurally scanned before the allocating parser runs. The
31/// size limit bounds wire bytes, not exact heap usage: decoded aggregate
32/// elements have their own representation overhead. Incomplete frames never
33/// reserve storage for their declared element counts. Set either field to
34/// [`usize::MAX`] to disable that codec limit; dependency parsing limits remain.
35///
36/// ```
37/// use redis_tower_protocol::{RespCodec, RespLimits};
38///
39/// let codec = RespCodec::with_limits(RespLimits {
40///     max_frame_size: 8 * 1024 * 1024,
41///     max_depth: 16,
42/// });
43/// assert_eq!(codec.limits().max_depth, 16);
44/// ```
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub struct RespLimits {
47    /// Largest single frame's wire encoding, including headers and terminators.
48    ///
49    /// Enforced for complete and incomplete input before materialization. A
50    /// declared length or element count that cannot fit is rejected early.
51    /// This is not a total receive-buffer or exact decoded-heap limit: a burst
52    /// of individually small pipelined replies is accepted.
53    pub max_frame_size: usize,
54    /// Deepest nesting of arrays, sets, pushes, and maps, outermost first.
55    ///
56    /// Empty aggregates count as a level; RESP2 null arrays are nil leaves.
57    /// Attributes and streamed encodings are unsupported independently of depth.
58    pub max_depth: usize,
59}
60
61impl Default for RespLimits {
62    fn default() -> Self {
63        Self {
64            max_frame_size: DEFAULT_MAX_FRAME_SIZE,
65            max_depth: DEFAULT_MAX_DEPTH,
66        }
67    }
68}
69
70/// Tokio codec for RESP3 frame encoding/decoding, backed by resp-rs.
71///
72/// Decoding enforces the [`RespLimits`] the codec was built with; encoding is
73/// unaffected, since outbound frames are ones this client built itself.
74/// Attributes and streamed RESP3 encodings fail closed with an unsupported-
75/// operation error until their metadata/sequence can be attached to one reply.
76/// Errors and incomplete input leave the receive buffer unchanged.
77#[derive(Debug, Default, Clone, Copy)]
78pub struct RespCodec {
79    limits: RespLimits,
80}
81
82impl RespCodec {
83    /// A codec with the default limits.
84    pub fn new() -> Self {
85        Self::default()
86    }
87
88    /// A codec with explicit decode limits.
89    pub fn with_limits(limits: RespLimits) -> Self {
90        Self { limits }
91    }
92
93    /// The limits this codec enforces while decoding.
94    pub fn limits(&self) -> RespLimits {
95        self.limits
96    }
97}
98
99impl Decoder for RespCodec {
100    type Item = Frame;
101    type Error = ProtocolError;
102
103    fn decode(&mut self, src: &mut BytesMut) -> Result<Option<Frame>, ProtocolError> {
104        let Some(frame_len) = crate::preflight::frame_len(src, self.limits)? else {
105            return Ok(None);
106        };
107
108        #[cfg(test)]
109        {
110            TEST_MATERIALIZATIONS.with(|count| count.set(count.get() + 1));
111            TEST_MATERIALIZED_BYTES.with(|bytes| bytes.set(bytes.get() + frame_len));
112        }
113
114        // Materialize only a complete, bounded first frame. BytesMut::clone()
115        // copies, so cloning the entire unread pipeline here would repeatedly
116        // copy its shrinking remainder. Copying just this frame also preserves
117        // the original buffer if the parser rejects scalar semantics.
118        let input = Bytes::copy_from_slice(&src[..frame_len]);
119        let (frame, remaining) = resp3::parse_frame(input)?;
120        if !remaining.is_empty() {
121            return Err(resp_rs::ParseError::InvalidFormat.into());
122        }
123        src.advance(frame_len);
124        Ok(Some(frame))
125    }
126}
127
128impl Encoder<Frame> for RespCodec {
129    type Error = ProtocolError;
130
131    fn encode(&mut self, item: Frame, dst: &mut BytesMut) -> Result<(), ProtocolError> {
132        let serialized = resp3::frame_to_bytes(&item);
133        dst.extend_from_slice(&serialized);
134        Ok(())
135    }
136}
137
138#[cfg(test)]
139mod tests {
140    use super::*;
141    use bytes::Bytes;
142
143    #[test]
144    fn attributed_replies_fail_closed_before_consuming_pipeline_bytes() {
145        for wire in [
146            b"|1\r\n+ttl\r\n:1\r\n+first\r\n+second\r\n".as_slice(),
147            b"*1\r\n|1\r\n+ttl\r\n:1\r\n+first\r\n+second\r\n".as_slice(),
148        ] {
149            let mut codec = RespCodec::new();
150            let mut bytes = BytesMut::from(wire);
151            assert!(matches!(
152                codec.decode(&mut bytes),
153                Err(ProtocolError::Io(error)) if error.kind() == std::io::ErrorKind::Unsupported
154            ));
155            assert_eq!(
156                bytes.as_ref(),
157                wire,
158                "no reply may be mistaken for the next request's result"
159            );
160        }
161    }
162
163    #[test]
164    fn decode_simple_string() {
165        let mut buf = BytesMut::from("+OK\r\n");
166        let mut codec = RespCodec::new();
167        let frame = codec.decode(&mut buf).unwrap().unwrap();
168        assert_eq!(frame, Frame::SimpleString(Bytes::from("OK")));
169    }
170
171    #[test]
172    fn decode_error() {
173        let mut buf = BytesMut::from("-ERR unknown\r\n");
174        let mut codec = RespCodec::new();
175        let frame = codec.decode(&mut buf).unwrap().unwrap();
176        assert_eq!(frame, Frame::Error(Bytes::from("ERR unknown")));
177    }
178
179    #[test]
180    fn decode_integer() {
181        let mut buf = BytesMut::from(":42\r\n");
182        let mut codec = RespCodec::new();
183        let frame = codec.decode(&mut buf).unwrap().unwrap();
184        assert_eq!(frame, Frame::Integer(42));
185    }
186
187    #[test]
188    fn decode_bulk_string() {
189        let mut buf = BytesMut::from("$5\r\nhello\r\n");
190        let mut codec = RespCodec::new();
191        let frame = codec.decode(&mut buf).unwrap().unwrap();
192        assert_eq!(frame, Frame::BulkString(Some(Bytes::from("hello"))));
193    }
194
195    #[test]
196    fn decode_null_bulk_string() {
197        let mut buf = BytesMut::from("$-1\r\n");
198        let mut codec = RespCodec::new();
199        let frame = codec.decode(&mut buf).unwrap().unwrap();
200        assert_eq!(frame, Frame::BulkString(None));
201    }
202
203    #[test]
204    fn decode_array() {
205        let mut buf = BytesMut::from("*2\r\n$3\r\nGET\r\n$3\r\nkey\r\n");
206        let mut codec = RespCodec::new();
207        let frame = codec.decode(&mut buf).unwrap().unwrap();
208        assert_eq!(
209            frame,
210            Frame::Array(Some(vec![
211                Frame::BulkString(Some(Bytes::from("GET"))),
212                Frame::BulkString(Some(Bytes::from("key"))),
213            ]))
214        );
215    }
216
217    #[test]
218    fn decode_incomplete() {
219        let mut buf = BytesMut::from("$5\r\nhel");
220        let mut codec = RespCodec::new();
221        assert!(codec.decode(&mut buf).unwrap().is_none());
222    }
223
224    #[test]
225    fn encode_frame() {
226        let mut buf = BytesMut::new();
227        let mut codec = RespCodec::new();
228        let frame = Frame::Array(Some(vec![
229            Frame::BulkString(Some(Bytes::from("SET"))),
230            Frame::BulkString(Some(Bytes::from("key"))),
231            Frame::BulkString(Some(Bytes::from("value"))),
232        ]));
233        codec.encode(frame, &mut buf).unwrap();
234        assert_eq!(&buf[..], b"*3\r\n$3\r\nSET\r\n$3\r\nkey\r\n$5\r\nvalue\r\n");
235    }
236
237    // -- RESP3 types --
238
239    #[test]
240    fn decode_double() {
241        let mut buf = BytesMut::from(",2.72\r\n");
242        let mut codec = RespCodec::new();
243        let frame = codec.decode(&mut buf).unwrap().unwrap();
244        assert_eq!(frame, Frame::Double(2.72));
245    }
246
247    #[test]
248    fn decode_boolean_true() {
249        let mut buf = BytesMut::from("#t\r\n");
250        let mut codec = RespCodec::new();
251        let frame = codec.decode(&mut buf).unwrap().unwrap();
252        assert_eq!(frame, Frame::Boolean(true));
253    }
254
255    #[test]
256    fn decode_boolean_false() {
257        let mut buf = BytesMut::from("#f\r\n");
258        let mut codec = RespCodec::new();
259        let frame = codec.decode(&mut buf).unwrap().unwrap();
260        assert_eq!(frame, Frame::Boolean(false));
261    }
262
263    #[test]
264    fn decode_null() {
265        let mut buf = BytesMut::from("_\r\n");
266        let mut codec = RespCodec::new();
267        let frame = codec.decode(&mut buf).unwrap().unwrap();
268        assert_eq!(frame, Frame::Null);
269    }
270
271    #[test]
272    fn decode_map() {
273        let mut buf = BytesMut::from("%2\r\n+key1\r\n:1\r\n+key2\r\n:2\r\n");
274        let mut codec = RespCodec::new();
275        let frame = codec.decode(&mut buf).unwrap().unwrap();
276        assert_eq!(
277            frame,
278            Frame::Map(vec![
279                (Frame::SimpleString(Bytes::from("key1")), Frame::Integer(1)),
280                (Frame::SimpleString(Bytes::from("key2")), Frame::Integer(2)),
281            ])
282        );
283    }
284
285    #[test]
286    fn decode_set() {
287        let mut buf = BytesMut::from("~2\r\n+a\r\n+b\r\n");
288        let mut codec = RespCodec::new();
289        let frame = codec.decode(&mut buf).unwrap().unwrap();
290        assert_eq!(
291            frame,
292            Frame::Set(vec![
293                Frame::SimpleString(Bytes::from("a")),
294                Frame::SimpleString(Bytes::from("b")),
295            ])
296        );
297    }
298
299    #[test]
300    fn decode_push() {
301        let mut buf = BytesMut::from(">2\r\n+invalidate\r\n*1\r\n+key\r\n");
302        let mut codec = RespCodec::new();
303        let frame = codec.decode(&mut buf).unwrap().unwrap();
304        assert_eq!(
305            frame,
306            Frame::Push(vec![
307                Frame::SimpleString(Bytes::from("invalidate")),
308                Frame::Array(Some(vec![Frame::SimpleString(Bytes::from("key"))])),
309            ])
310        );
311    }
312
313    #[test]
314    fn decode_blob_error() {
315        let mut buf = BytesMut::from("!12\r\nSYNTAX error\r\n");
316        let mut codec = RespCodec::new();
317        let frame = codec.decode(&mut buf).unwrap().unwrap();
318        assert_eq!(frame, Frame::BlobError(Bytes::from("SYNTAX error")));
319    }
320
321    #[test]
322    fn decode_big_number() {
323        let mut buf = BytesMut::from("(12345678901234567890\r\n");
324        let mut codec = RespCodec::new();
325        let frame = codec.decode(&mut buf).unwrap().unwrap();
326        assert_eq!(frame, Frame::BigNumber(Bytes::from("12345678901234567890")));
327    }
328
329    #[test]
330    fn decode_verbatim_string() {
331        let mut buf = BytesMut::from("=15\r\ntxt:hello world\r\n");
332        let mut codec = RespCodec::new();
333        let frame = codec.decode(&mut buf).unwrap().unwrap();
334        assert_eq!(
335            frame,
336            Frame::VerbatimString(Bytes::from("txt"), Bytes::from("hello world"))
337        );
338    }
339
340    #[test]
341    fn roundtrip() {
342        let original = Frame::Array(Some(vec![
343            Frame::SimpleString(Bytes::from("OK")),
344            Frame::Integer(42),
345            Frame::BulkString(Some(Bytes::from("hello"))),
346            Frame::BulkString(None),
347        ]));
348        let serialized = resp3::frame_to_bytes(&original);
349        let mut buf = BytesMut::from(&serialized[..]);
350        let mut codec = RespCodec::new();
351        let decoded = codec.decode(&mut buf).unwrap().unwrap();
352        assert_eq!(original, decoded);
353    }
354
355    // -- Edge-case tests --
356
357    #[test]
358    fn decode_large_bulk_string() {
359        let payload = vec![b'x'; 1024 * 1024];
360        let header = format!("${}\r\n", payload.len());
361        let mut wire = BytesMut::from(header.as_bytes());
362        wire.extend_from_slice(&payload);
363        wire.extend_from_slice(b"\r\n");
364        let mut codec = RespCodec::new();
365        let frame = codec.decode(&mut wire).unwrap().unwrap();
366        assert_eq!(frame, Frame::BulkString(Some(Bytes::from(payload))));
367    }
368
369    #[test]
370    fn decode_fragmented() {
371        let wire = b"$5\r\nhello\r\n";
372        let mut codec = RespCodec::new();
373        let mut buf = BytesMut::new();
374        let mut result = None;
375        for &byte in wire.iter() {
376            buf.extend_from_slice(&[byte]);
377            if let Some(frame) = codec.decode(&mut buf).unwrap() {
378                result = Some(frame);
379                break;
380            }
381        }
382        assert_eq!(
383            result.unwrap(),
384            Frame::BulkString(Some(Bytes::from("hello")))
385        );
386    }
387
388    #[test]
389    fn decode_zero_length_bulk_string() {
390        let mut buf = BytesMut::from("$0\r\n\r\n");
391        let mut codec = RespCodec::new();
392        let frame = codec.decode(&mut buf).unwrap().unwrap();
393        assert_eq!(frame, Frame::BulkString(Some(Bytes::new())));
394    }
395
396    #[test]
397    fn decode_null_array() {
398        let mut buf = BytesMut::from("*-1\r\n");
399        let mut codec = RespCodec::new();
400        let frame = codec.decode(&mut buf).unwrap().unwrap();
401        assert_eq!(frame, Frame::Array(None));
402    }
403
404    #[test]
405    fn decode_empty_array() {
406        let mut buf = BytesMut::from("*0\r\n");
407        let mut codec = RespCodec::new();
408        let frame = codec.decode(&mut buf).unwrap().unwrap();
409        assert_eq!(frame, Frame::Array(Some(vec![])));
410    }
411
412    #[test]
413    fn decode_nested_array() {
414        let mut buf = BytesMut::from("*2\r\n*2\r\n$3\r\nfoo\r\n$3\r\nbar\r\n$3\r\nbaz\r\n");
415        let mut codec = RespCodec::new();
416        let frame = codec.decode(&mut buf).unwrap().unwrap();
417        assert_eq!(
418            frame,
419            Frame::Array(Some(vec![
420                Frame::Array(Some(vec![
421                    Frame::BulkString(Some(Bytes::from("foo"))),
422                    Frame::BulkString(Some(Bytes::from("bar"))),
423                ])),
424                Frame::BulkString(Some(Bytes::from("baz"))),
425            ]))
426        );
427    }
428
429    #[test]
430    fn decode_incomplete_no_crlf() {
431        // Missing trailing \r\n — should return Ok(None), not an error.
432        let mut buf = BytesMut::from("$5\r\nhello");
433        let mut codec = RespCodec::new();
434        assert!(codec.decode(&mut buf).unwrap().is_none());
435    }
436
437    #[test]
438    fn encode_null_bulk_string() {
439        let mut buf = BytesMut::new();
440        let mut codec = RespCodec::new();
441        codec.encode(Frame::BulkString(None), &mut buf).unwrap();
442        assert_eq!(&buf[..], b"$-1\r\n");
443    }
444
445    #[test]
446    fn encode_empty_array() {
447        let mut buf = BytesMut::new();
448        let mut codec = RespCodec::new();
449        codec.encode(Frame::Array(Some(vec![])), &mut buf).unwrap();
450        assert_eq!(&buf[..], b"*0\r\n");
451    }
452
453    #[test]
454    fn encode_nested_array() {
455        let mut buf = BytesMut::new();
456        let mut codec = RespCodec::new();
457        codec
458            .encode(
459                Frame::Array(Some(vec![
460                    Frame::Array(Some(vec![Frame::BulkString(Some(Bytes::from("a")))])),
461                    Frame::Integer(1),
462                ])),
463                &mut buf,
464            )
465            .unwrap();
466        assert_eq!(&buf[..], b"*2\r\n*1\r\n$1\r\na\r\n:1\r\n");
467    }
468
469    // -- Property-based tests --
470
471    #[cfg(test)]
472    mod prop_tests {
473        use super::*;
474        use proptest::prelude::*;
475
476        fn arb_leaf_frame() -> impl Strategy<Value = Frame> {
477            prop_oneof![
478                "[a-zA-Z0-9 ._:/-]{0,24}".prop_map(|s| Frame::SimpleString(Bytes::from(s))),
479                "[A-Z][A-Z0-9 ]{0,23}".prop_map(|s| Frame::Error(Bytes::from(s))),
480                any::<i64>().prop_map(Frame::Integer),
481                prop::collection::vec(any::<u8>(), 0..=64)
482                    .prop_map(|v| Frame::BulkString(Some(Bytes::from(v)))),
483                Just(Frame::BulkString(None)),
484                prop::collection::vec(any::<u8>(), 0..=64)
485                    .prop_map(|v| Frame::BlobError(Bytes::from(v))),
486                any::<f64>()
487                    .prop_filter("finite doubles have a stable Frame variant", |value| {
488                        value.is_finite()
489                    })
490                    .prop_map(Frame::Double),
491                prop_oneof![
492                    Just(Frame::SpecialFloat(Bytes::from_static(b"inf"))),
493                    Just(Frame::SpecialFloat(Bytes::from_static(b"-inf"))),
494                    Just(Frame::SpecialFloat(Bytes::from_static(b"nan"))),
495                ],
496                any::<bool>().prop_map(Frame::Boolean),
497                "-?[0-9]{1,48}".prop_map(|value| Frame::BigNumber(Bytes::from(value))),
498                prop::collection::vec(any::<u8>(), 0..=64).prop_map(|content| {
499                    Frame::VerbatimString(Bytes::from_static(b"txt"), Bytes::from(content))
500                }),
501                Just(Frame::Null),
502                Just(Frame::Array(None)),
503            ]
504        }
505
506        fn arb_frame() -> impl Strategy<Value = Frame> {
507            arb_leaf_frame().prop_recursive(4, 32, 6, |inner| {
508                prop_oneof![
509                    prop::collection::vec(inner.clone(), 0..=5)
510                        .prop_map(|items| Frame::Array(Some(items))),
511                    prop::collection::vec(inner.clone(), 0..=5).prop_map(Frame::Set),
512                    prop::collection::vec(inner.clone(), 0..=5).prop_map(Frame::Push),
513                    prop::collection::vec((inner.clone(), inner), 0..=4).prop_map(Frame::Map),
514                ]
515            })
516        }
517
518        fn encode_frames(frames: &[Frame]) -> Vec<u8> {
519            frames
520                .iter()
521                .flat_map(|frame| resp3::frame_to_bytes(frame).to_vec())
522                .collect()
523        }
524
525        fn decode_whole(wire: &[u8]) -> (Vec<Frame>, Vec<u8>) {
526            let mut codec = RespCodec::new();
527            let mut buffer = BytesMut::from(wire);
528            let mut frames = Vec::new();
529            while let Some(frame) = codec.decode(&mut buffer).unwrap() {
530                frames.push(frame);
531            }
532            (frames, buffer.to_vec())
533        }
534
535        fn decode_fragmented(wire: &[u8], plan: &[usize]) -> (Vec<Frame>, Vec<u8>) {
536            let mut codec = RespCodec::new();
537            let mut buffer = BytesMut::new();
538            let mut frames = Vec::new();
539            let mut offset = 0;
540            let mut plan_index = 0;
541            while offset < wire.len() {
542                let chunk_size = plan[plan_index % plan.len()];
543                plan_index += 1;
544                let end = offset.saturating_add(chunk_size).min(wire.len());
545                buffer.extend_from_slice(&wire[offset..end]);
546                offset = end;
547                while let Some(frame) = codec.decode(&mut buffer).unwrap() {
548                    frames.push(frame);
549                }
550            }
551            (frames, buffer.to_vec())
552        }
553
554        proptest! {
555            #![proptest_config(ProptestConfig::with_cases(192))]
556
557            #[test]
558            fn codec_roundtrip(frame in arb_frame()) {
559                let mut codec = RespCodec::new();
560                let mut buf = BytesMut::new();
561                codec.encode(frame.clone(), &mut buf).unwrap();
562                let decoded = codec.decode(&mut buf).unwrap().unwrap();
563                prop_assert_eq!(frame, decoded);
564            }
565
566            #[test]
567            fn pipelines_are_partition_invariant(
568                frames in prop::collection::vec(arb_frame(), 0..=16),
569                plan in prop::collection::vec(1usize..=64, 1..=16),
570            ) {
571                let wire = encode_frames(&frames);
572                let whole = decode_whole(&wire);
573                let fragmented = decode_fragmented(&wire, &plan);
574                prop_assert_eq!(&fragmented, &whole);
575                prop_assert_eq!(whole.0, frames);
576                prop_assert!(whole.1.is_empty());
577            }
578
579            #[test]
580            fn truncated_pipelines_have_partition_invariant_prefixes(
581                frames in prop::collection::vec(arb_frame(), 1..=12),
582                plan in prop::collection::vec(1usize..=32, 1..=12),
583                cutoff_seed in any::<usize>(),
584            ) {
585                let wire = encode_frames(&frames);
586                let cutoff = cutoff_seed % (wire.len() + 1);
587                let prefix = &wire[..cutoff];
588                prop_assert_eq!(decode_fragmented(prefix, &plan), decode_whole(prefix));
589            }
590        }
591    }
592}
593
594#[cfg(test)]
595mod limit_tests {
596    use super::*;
597    use bytes::Bytes;
598
599    /// `*1\r\n` repeated `depth` times around a single integer: the cheapest
600    /// wire encoding of a deeply nested reply, and the shape a hostile server
601    /// would use to drive `parse_frame`'s recursion.
602    fn nested(depth: usize) -> BytesMut {
603        let mut buf = BytesMut::new();
604        for _ in 0..depth {
605            buf.extend_from_slice(b"*1\r\n");
606        }
607        buf.extend_from_slice(b":1\r\n");
608        buf
609    }
610
611    #[test]
612    fn default_limits_are_the_documented_constants() {
613        let limits = RespCodec::new().limits();
614        assert_eq!(limits.max_frame_size, DEFAULT_MAX_FRAME_SIZE);
615        assert_eq!(limits.max_depth, DEFAULT_MAX_DEPTH);
616    }
617
618    #[test]
619    fn nesting_beyond_the_default_cap_is_rejected() {
620        let mut codec = RespCodec::new();
621        // Without the pre-scan this input recurses 100_000 frames deep inside
622        // resp-rs and aborts the process with a stack overflow.
623        let mut buf = nested(100_000);
624        let err = codec.decode(&mut buf).unwrap_err();
625        assert!(
626            matches!(err, ProtocolError::NestingTooDeep { max } if max == DEFAULT_MAX_DEPTH),
627            "unexpected error: {err:?}"
628        );
629    }
630
631    #[test]
632    fn nesting_within_the_cap_still_decodes() {
633        let mut codec = RespCodec::new();
634        // The complete frame is scanned before recursive parsing.
635        let mut buf = nested(DEFAULT_MAX_DEPTH);
636        let frame = codec.decode(&mut buf).unwrap().unwrap();
637        assert!(matches!(frame, Frame::Array(Some(_))));
638        assert!(buf.is_empty());
639    }
640
641    #[test]
642    fn a_custom_depth_cap_is_honored_in_both_directions() {
643        let limits = RespLimits {
644            max_depth: 3,
645            ..RespLimits::default()
646        };
647
648        let mut codec = RespCodec::with_limits(limits);
649        let mut ok = nested(3);
650        assert!(codec.decode(&mut ok).unwrap().is_some());
651
652        let mut too_deep = nested(4);
653        let err = codec.decode(&mut too_deep).unwrap_err();
654        assert!(matches!(err, ProtocolError::NestingTooDeep { max: 3 }));
655    }
656
657    #[test]
658    fn map_pairs_count_as_one_level_not_two() {
659        // %1\r\n +k\r\n +v\r\n is depth 1: the pair is two children of one map,
660        // not a level each. A scanner that counted pairs as nesting would
661        // reject this.
662        let limits = RespLimits {
663            max_depth: 1,
664            ..RespLimits::default()
665        };
666        let mut codec = RespCodec::with_limits(limits);
667        let mut buf = BytesMut::from(&b"%1\r\n+k\r\n+v\r\n"[..]);
668        let frame = codec.decode(&mut buf).unwrap().unwrap();
669        assert_eq!(
670            frame,
671            Frame::Map(vec![(
672                Frame::SimpleString(Bytes::from("k")),
673                Frame::SimpleString(Bytes::from("v"))
674            )])
675        );
676    }
677
678    #[test]
679    fn aggregate_markers_inside_a_bulk_payload_are_not_nesting() {
680        // The scanner skips blob payloads whole. If it did not, this value
681        // would read as 5_000 levels of array and be rejected, breaking a
682        // client that stores RESP-looking bytes in Redis.
683        let payload = b"*1\r\n".repeat(5_000);
684        let mut buf = BytesMut::new();
685        buf.extend_from_slice(format!("${}\r\n", payload.len()).as_bytes());
686        buf.extend_from_slice(&payload);
687        buf.extend_from_slice(b"\r\n");
688
689        let mut codec = RespCodec::new();
690        let frame = codec.decode(&mut buf).unwrap().unwrap();
691        assert_eq!(frame, Frame::BulkString(Some(Bytes::from(payload))));
692    }
693
694    #[test]
695    fn an_oversized_declared_frame_is_rejected_before_payload_arrives() {
696        let limits = RespLimits {
697            max_frame_size: 64,
698            ..RespLimits::default()
699        };
700        let mut codec = RespCodec::with_limits(limits);
701
702        // The declaration already establishes an impossible-to-fit extent.
703        let mut buf = BytesMut::from(&b"$1000000\r\n"[..]);
704        let err = codec.decode(&mut buf).unwrap_err();
705        assert!(
706            matches!(err, ProtocolError::FrameTooLarge { size, max } if size == 1_000_012 && max == 64),
707            "unexpected error: {err:?}"
708        );
709        assert_eq!(buf.as_ref(), b"$1000000\r\n");
710    }
711
712    #[test]
713    fn incomplete_aggregate_cardinality_never_reaches_materialization() {
714        TEST_MATERIALIZATIONS.with(|count| count.set(0));
715        TEST_MATERIALIZED_BYTES.with(|bytes| bytes.set(0));
716        let mut codec = RespCodec::new();
717        for header in [b"*4096\r\n".as_slice(), b"%4096\r\n"] {
718            let mut input = BytesMut::from(header);
719            assert!(codec.decode(&mut input).unwrap().is_none());
720            assert_eq!(&input[..], header);
721        }
722        TEST_MATERIALIZATIONS.with(|count| assert_eq!(count.get(), 0));
723        TEST_MATERIALIZED_BYTES.with(|bytes| assert_eq!(bytes.get(), 0));
724
725        let mut complete = BytesMut::from(&b"*1\r\n+OK\r\n"[..]);
726        assert!(codec.decode(&mut complete).unwrap().is_some());
727        TEST_MATERIALIZATIONS.with(|count| assert_eq!(count.get(), 1));
728        TEST_MATERIALIZED_BYTES.with(|bytes| assert_eq!(bytes.get(), 9));
729    }
730
731    #[test]
732    fn pipelined_decode_materializes_each_completed_frame_exactly_once() {
733        let wires: [&[u8]; 5] = [
734            b"+OK\r\n",
735            b"$6\r\na\0\xff\r\nz\r\n",
736            b":42\r\n",
737            b">2\r\n+invalidate\r\n$3\r\nkey\r\n",
738            b"*2\r\n$3\r\nGET\r\n$3\r\nkey\r\n",
739        ];
740        let mut pipeline = Vec::new();
741        for _ in 0..32 {
742            for wire in wires {
743                pipeline.extend_from_slice(wire);
744            }
745        }
746        let expected_frames = wires.len() * 32;
747        let expected_bytes = pipeline.len();
748        let historical_whole_buffer_copy_bytes = (0..32)
749            .flat_map(|_| wires)
750            .scan(expected_bytes, |remaining, wire| {
751                let copied = *remaining;
752                *remaining -= wire.len();
753                Some(copied)
754            })
755            .sum::<usize>();
756
757        TEST_MATERIALIZATIONS.with(|count| count.set(0));
758        TEST_MATERIALIZED_BYTES.with(|bytes| bytes.set(0));
759        let mut codec = RespCodec::new();
760        let mut input = BytesMut::from(pipeline.as_slice());
761        let mut frames = Vec::with_capacity(expected_frames);
762        while let Some(frame) = codec.decode(&mut input).unwrap() {
763            frames.push(frame);
764        }
765
766        assert_eq!(frames.len(), expected_frames);
767        assert!(input.is_empty());
768        assert!(
769            matches!(frames[1], Frame::BulkString(Some(ref value)) if value.as_ref() == b"a\0\xff\r\nz")
770        );
771        assert!(matches!(frames[3], Frame::Push(ref values) if values.len() == 2));
772        TEST_MATERIALIZATIONS.with(|count| assert_eq!(count.get(), expected_frames));
773        TEST_MATERIALIZED_BYTES.with(|bytes| assert_eq!(bytes.get(), expected_bytes));
774        assert!(
775            historical_whole_buffer_copy_bytes > expected_bytes * 50,
776            "the regression fixture must distinguish first-frame from whole-buffer copying"
777        );
778    }
779
780    #[test]
781    fn fragmented_input_is_not_materialized_until_the_frame_is_complete() {
782        let wire = b"$8\r\na\0\xff\r\nxyz\r\n";
783        TEST_MATERIALIZATIONS.with(|count| count.set(0));
784        TEST_MATERIALIZED_BYTES.with(|bytes| bytes.set(0));
785        let mut codec = RespCodec::new();
786        let mut input = BytesMut::new();
787
788        for (index, byte) in wire.iter().enumerate() {
789            input.extend_from_slice(std::slice::from_ref(byte));
790            let decoded = codec.decode(&mut input).unwrap();
791            if index + 1 == wire.len() {
792                assert!(decoded.is_some());
793            } else {
794                assert!(decoded.is_none());
795                TEST_MATERIALIZATIONS.with(|count| assert_eq!(count.get(), 0));
796                TEST_MATERIALIZED_BYTES.with(|bytes| assert_eq!(bytes.get(), 0));
797            }
798        }
799
800        assert!(input.is_empty());
801        TEST_MATERIALIZATIONS.with(|count| assert_eq!(count.get(), 1));
802        TEST_MATERIALIZED_BYTES.with(|bytes| assert_eq!(bytes.get(), wire.len()));
803    }
804
805    #[test]
806    fn the_size_cap_applies_per_frame_not_to_pipelined_bytes() {
807        // Three complete replies buffered together exceed a 6-byte cap in
808        // total, but each is parsed and drained on its own, so none is
809        // rejected. The cap bounds each frame, not the total receive buffer.
810        let limits = RespLimits {
811            max_frame_size: 6,
812            ..RespLimits::default()
813        };
814        let mut codec = RespCodec::with_limits(limits);
815        let mut buf = BytesMut::from(&b"+OK\r\n+OK\r\n+OK\r\n"[..]);
816
817        for _ in 0..3 {
818            let frame = codec.decode(&mut buf).unwrap().unwrap();
819            assert_eq!(frame, Frame::SimpleString(Bytes::from("OK")));
820        }
821        assert!(buf.is_empty());
822    }
823
824    #[test]
825    fn limits_can_be_disabled() {
826        let limits = RespLimits {
827            max_frame_size: usize::MAX,
828            max_depth: usize::MAX,
829        };
830        let mut codec = RespCodec::with_limits(limits);
831        let mut buf = nested(64);
832        assert!(codec.decode(&mut buf).unwrap().is_some());
833    }
834
835    #[test]
836    fn every_wire_type_survives_a_tight_depth_cap() {
837        // The scanner has to recognize each RESP3 type byte to skip it
838        // correctly; a tag it mishandles would either miscount nesting or
839        // desynchronize. Each of these is depth 1 under a cap of 1.
840        let limits = RespLimits {
841            max_depth: 1,
842            ..RespLimits::default()
843        };
844        let mut codec = RespCodec::with_limits(limits);
845
846        let cases: [&[u8]; 8] = [
847            b"*8\r\n+s\r\n-e\r\n:1\r\n#t\r\n(12345678901234567890\r\n,1.5\r\n_\r\n$3\r\nabc\r\n",
848            b"*2\r\n=9\r\ntxt:hello\r\n!5\r\nerror\r\n",
849            b"~2\r\n+a\r\n+b\r\n",
850            b">2\r\n+invalidate\r\n$1\r\nk\r\n",
851            b"%2\r\n+k1\r\n:1\r\n+k2\r\n:2\r\n",
852            b"*1\r\n$-1\r\n",
853            b"*-1\r\n",
854            b"*0\r\n",
855        ];
856
857        for case in cases {
858            let mut buf = BytesMut::from(case);
859            let decoded = codec.decode(&mut buf);
860            assert!(
861                decoded.is_ok(),
862                "{:?} was rejected: {:?}",
863                String::from_utf8_lossy(case),
864                decoded.unwrap_err()
865            );
866            assert!(
867                decoded.unwrap().is_some(),
868                "{:?} decoded to nothing",
869                String::from_utf8_lossy(case)
870            );
871        }
872    }
873
874    #[test]
875    fn a_malformed_frame_is_still_the_parsers_verdict() {
876        // Scalar semantics remain the parser's verdict after framing checks.
877        let mut codec = RespCodec::with_limits(RespLimits {
878            max_depth: 1,
879            ..RespLimits::default()
880        });
881        let mut buf = BytesMut::from(&b"#maybe\r\n"[..]);
882        assert!(matches!(
883            codec.decode(&mut buf).unwrap_err(),
884            ProtocolError::Parse(_)
885        ));
886    }
887}