packet/
serialize.rs

1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Serialization.
6
7use std::cmp;
8use std::convert::Infallible as Never;
9use std::fmt::{self, Debug, Formatter};
10use std::marker::PhantomData;
11use std::ops::{Range, RangeBounds};
12
13use arrayvec::ArrayVec;
14use zerocopy::SplitByteSlice;
15
16use crate::{
17    AsFragmentedByteSlice, Buffer, BufferView, BufferViewMut, ContiguousBuffer, EmptyBuf,
18    FragmentedBuffer, FragmentedBufferMut, FragmentedBytes, FragmentedBytesMut, GrowBuffer,
19    GrowBufferMut, ParsablePacket, ParseBuffer, ParseBufferMut, ReusableBuffer, ShrinkBuffer,
20    canonicalize_range, take_back, take_back_mut, take_front, take_front_mut,
21};
22
23/// Either of two buffers.
24///
25/// An `Either` wraps one of two different buffer types. It implements all of
26/// the relevant traits by calling the corresponding methods on the wrapped
27/// buffer.
28#[derive(Copy, Clone, Debug)]
29pub enum Either<A, B> {
30    A(A),
31    B(B),
32}
33
34impl<A, B> Either<A, B> {
35    /// Maps the `A` variant of an `Either`.
36    ///
37    /// Given an `Either<A, B>` and a function from `A` to `AA`, `map_a`
38    /// produces an `Either<AA, B>` by applying the function to the `A` variant
39    /// or passing on the `B` variant unmodified.
40    pub fn map_a<AA, F: FnOnce(A) -> AA>(self, f: F) -> Either<AA, B> {
41        match self {
42            Either::A(a) => Either::A(f(a)),
43            Either::B(b) => Either::B(b),
44        }
45    }
46
47    /// Maps the `B` variant of an `Either`.
48    ///
49    /// Given an `Either<A, B>` and a function from `B` to `BB`, `map_b`
50    /// produces an `Either<A, BB>` by applying the function to the `B` variant
51    /// or passing on the `A` variant unmodified.
52    pub fn map_b<BB, F: FnOnce(B) -> BB>(self, f: F) -> Either<A, BB> {
53        match self {
54            Either::A(a) => Either::A(a),
55            Either::B(b) => Either::B(f(b)),
56        }
57    }
58
59    /// Returns the `A` variant in an `Either<A, B>`.
60    ///
61    /// # Panics
62    ///
63    /// Panics if this `Either<A, B>` does not hold the `A` variant.
64    pub fn unwrap_a(self) -> A {
65        match self {
66            Either::A(x) => x,
67            Either::B(_) => panic!("This `Either<A, B>` does not hold the `A` variant"),
68        }
69    }
70
71    /// Returns the `B` variant in an `Either<A, B>`.
72    ///
73    /// # Panics
74    ///
75    /// Panics if this `Either<A, B>` does not hold the `B` variant.
76    pub fn unwrap_b(self) -> B {
77        match self {
78            Either::A(_) => panic!("This `Either<A, B>` does not hold the `B` variant"),
79            Either::B(x) => x,
80        }
81    }
82}
83
84impl<A> Either<A, A> {
85    /// Returns the inner value held by this `Either` when both possible values
86    /// `Either::A` and `Either::B` contain the same inner types.
87    pub fn into_inner(self) -> A {
88        match self {
89            Either::A(x) => x,
90            Either::B(x) => x,
91        }
92    }
93}
94
95impl<A> Either<A, Never> {
96    /// Returns the `A` value in an `Either<A, Never>`.
97    #[inline]
98    pub fn into_a(self) -> A {
99        match self {
100            Either::A(a) => a,
101        }
102    }
103}
104
105impl<B> Either<Never, B> {
106    /// Returns the `B` value in an `Either<Never, B>`.
107    #[inline]
108    pub fn into_b(self) -> B {
109        match self {
110            Either::B(b) => b,
111        }
112    }
113}
114
115macro_rules! call_method_on_either {
116    ($val:expr, $method:ident, $($args:expr),*) => {
117        match $val {
118            Either::A(a) => a.$method($($args),*),
119            Either::B(b) => b.$method($($args),*),
120        }
121    };
122    ($val:expr, $method:ident) => {
123        call_method_on_either!($val, $method,)
124    };
125}
126
127// NOTE(joshlf): We override the default implementations of all methods for
128// Either. Many of the default implementations make multiple calls to other
129// Buffer methods, each of which performs a match statement to figure out which
130// Either variant is present. We assume that doing this match once is more
131// performant than doing it multiple times.
132
133impl<A, B> FragmentedBuffer for Either<A, B>
134where
135    A: FragmentedBuffer,
136    B: FragmentedBuffer,
137{
138    fn len(&self) -> usize {
139        call_method_on_either!(self, len)
140    }
141
142    fn with_bytes<'a, R, F>(&'a self, f: F) -> R
143    where
144        F: for<'b> FnOnce(FragmentedBytes<'b, 'a>) -> R,
145    {
146        call_method_on_either!(self, with_bytes, f)
147    }
148}
149
150impl<A, B> ContiguousBuffer for Either<A, B>
151where
152    A: ContiguousBuffer,
153    B: ContiguousBuffer,
154{
155}
156
157impl<A, B> ShrinkBuffer for Either<A, B>
158where
159    A: ShrinkBuffer,
160    B: ShrinkBuffer,
161{
162    fn shrink<R: RangeBounds<usize>>(&mut self, range: R) {
163        call_method_on_either!(self, shrink, range)
164    }
165    fn shrink_front(&mut self, n: usize) {
166        call_method_on_either!(self, shrink_front, n)
167    }
168    fn shrink_back(&mut self, n: usize) {
169        call_method_on_either!(self, shrink_back, n)
170    }
171}
172
173impl<A, B> ParseBuffer for Either<A, B>
174where
175    A: ParseBuffer,
176    B: ParseBuffer,
177{
178    fn parse<'a, P: ParsablePacket<&'a [u8], ()>>(&'a mut self) -> Result<P, P::Error> {
179        call_method_on_either!(self, parse)
180    }
181    fn parse_with<'a, ParseArgs, P: ParsablePacket<&'a [u8], ParseArgs>>(
182        &'a mut self,
183        args: ParseArgs,
184    ) -> Result<P, P::Error> {
185        call_method_on_either!(self, parse_with, args)
186    }
187}
188
189impl<A, B> FragmentedBufferMut for Either<A, B>
190where
191    A: FragmentedBufferMut,
192    B: FragmentedBufferMut,
193{
194    fn with_bytes_mut<'a, R, F>(&'a mut self, f: F) -> R
195    where
196        F: for<'b> FnOnce(FragmentedBytesMut<'b, 'a>) -> R,
197    {
198        call_method_on_either!(self, with_bytes_mut, f)
199    }
200}
201
202impl<A, B> ParseBufferMut for Either<A, B>
203where
204    A: ParseBufferMut,
205    B: ParseBufferMut,
206{
207    fn parse_mut<'a, P: ParsablePacket<&'a mut [u8], ()>>(&'a mut self) -> Result<P, P::Error> {
208        call_method_on_either!(self, parse_mut)
209    }
210    fn parse_with_mut<'a, ParseArgs, P: ParsablePacket<&'a mut [u8], ParseArgs>>(
211        &'a mut self,
212        args: ParseArgs,
213    ) -> Result<P, P::Error> {
214        call_method_on_either!(self, parse_with_mut, args)
215    }
216}
217
218impl<A, B> GrowBuffer for Either<A, B>
219where
220    A: GrowBuffer,
221    B: GrowBuffer,
222{
223    #[inline]
224    fn with_parts<'a, O, F>(&'a self, f: F) -> O
225    where
226        F: for<'b> FnOnce(&'a [u8], FragmentedBytes<'b, 'a>, &'a [u8]) -> O,
227    {
228        call_method_on_either!(self, with_parts, f)
229    }
230    fn capacity(&self) -> usize {
231        call_method_on_either!(self, capacity)
232    }
233    fn prefix_len(&self) -> usize {
234        call_method_on_either!(self, prefix_len)
235    }
236    fn suffix_len(&self) -> usize {
237        call_method_on_either!(self, suffix_len)
238    }
239    fn grow_front(&mut self, n: usize) {
240        call_method_on_either!(self, grow_front, n)
241    }
242    fn grow_back(&mut self, n: usize) {
243        call_method_on_either!(self, grow_back, n)
244    }
245    fn reset(&mut self) {
246        call_method_on_either!(self, reset)
247    }
248}
249
250impl<A, B> GrowBufferMut for Either<A, B>
251where
252    A: GrowBufferMut,
253    B: GrowBufferMut,
254{
255    fn with_parts_mut<'a, O, F>(&'a mut self, f: F) -> O
256    where
257        F: for<'b> FnOnce(&'a mut [u8], FragmentedBytesMut<'b, 'a>, &'a mut [u8]) -> O,
258    {
259        call_method_on_either!(self, with_parts_mut, f)
260    }
261
262    fn with_all_contents_mut<'a, O, F>(&'a mut self, f: F) -> O
263    where
264        F: for<'b> FnOnce(FragmentedBytesMut<'b, 'a>) -> O,
265    {
266        call_method_on_either!(self, with_all_contents_mut, f)
267    }
268
269    fn serialize<BB: PacketBuilder>(&mut self, builder: BB) {
270        call_method_on_either!(self, serialize, builder)
271    }
272}
273
274impl<A, B> Buffer for Either<A, B>
275where
276    A: Buffer,
277    B: Buffer,
278{
279    fn parse_with_view<'a, ParseArgs, P: ParsablePacket<&'a [u8], ParseArgs>>(
280        &'a mut self,
281        args: ParseArgs,
282    ) -> Result<(P, &'a [u8]), P::Error> {
283        call_method_on_either!(self, parse_with_view, args)
284    }
285}
286
287impl<A: AsRef<[u8]>, B: AsRef<[u8]>> AsRef<[u8]> for Either<A, B> {
288    fn as_ref(&self) -> &[u8] {
289        call_method_on_either!(self, as_ref)
290    }
291}
292
293impl<A: AsMut<[u8]>, B: AsMut<[u8]>> AsMut<[u8]> for Either<A, B> {
294    fn as_mut(&mut self) -> &mut [u8] {
295        call_method_on_either!(self, as_mut)
296    }
297}
298
299/// A byte slice wrapper providing buffer functionality.
300///
301/// A `Buf` wraps a byte slice (a type which implements `AsRef<[u8]>` or
302/// `AsMut<[u8]>`) and implements various buffer traits by keeping track of
303/// prefix, body, and suffix offsets within the byte slice.
304#[derive(Clone, Debug)]
305pub struct Buf<B> {
306    buf: B,
307    body: Range<usize>,
308}
309
310impl<B: AsRef<[u8]>> PartialEq for Buf<B> {
311    fn eq(&self, other: &Self) -> bool {
312        let self_slice = AsRef::<[u8]>::as_ref(self);
313        let other_slice = AsRef::<[u8]>::as_ref(other);
314        PartialEq::eq(self_slice, other_slice)
315    }
316}
317
318impl<B: AsRef<[u8]>> Eq for Buf<B> {}
319
320impl Buf<Vec<u8>> {
321    /// Extracts the contained data trimmed to the buffer's range.
322    pub fn into_inner(self) -> Vec<u8> {
323        let Buf { mut buf, body } = self;
324        let len = body.end - body.start;
325        let _ = buf.drain(..body.start);
326        buf.truncate(len);
327        buf
328    }
329}
330
331impl<B: AsRef<[u8]>> Buf<B> {
332    /// Constructs a new `Buf`.
333    ///
334    /// `new` constructs a new `Buf` from a buffer and a body range. The bytes
335    /// within the range will be the body, the bytes before the range will be
336    /// the prefix, and the bytes after the range will be the suffix.
337    ///
338    /// # Panics
339    ///
340    /// Panics if `range` is out of bounds of `buf`, or if it is nonsensical
341    /// (the end precedes the start).
342    pub fn new<R: RangeBounds<usize>>(buf: B, body: R) -> Buf<B> {
343        let len = buf.as_ref().len();
344        Buf { buf, body: canonicalize_range(len, &body) }
345    }
346
347    /// Constructs a [`BufView`] which will be a [`BufferView`] into this `Buf`.
348    pub fn buffer_view(&mut self) -> BufView<'_> {
349        BufView { buf: &self.buf.as_ref()[self.body.clone()], body: &mut self.body }
350    }
351}
352
353impl<B: AsRef<[u8]> + AsMut<[u8]>> Buf<B> {
354    /// Constructs a [`BufViewMut`] which will be a [`BufferViewMut`] into this `Buf`.
355    pub fn buffer_view_mut(&mut self) -> BufViewMut<'_> {
356        BufViewMut { buf: &mut self.buf.as_mut()[self.body.clone()], body: &mut self.body }
357    }
358}
359
360impl<B: AsRef<[u8]>> FragmentedBuffer for Buf<B> {
361    fragmented_buffer_method_impls!();
362}
363impl<B: AsRef<[u8]>> ContiguousBuffer for Buf<B> {}
364impl<B: AsRef<[u8]>> ShrinkBuffer for Buf<B> {
365    fn shrink<R: RangeBounds<usize>>(&mut self, range: R) {
366        let len = self.len();
367        let mut range = canonicalize_range(len, &range);
368        range.start += self.body.start;
369        range.end += self.body.start;
370        self.body = range;
371    }
372
373    fn shrink_front(&mut self, n: usize) {
374        assert!(n <= self.len());
375        self.body.start += n;
376    }
377    fn shrink_back(&mut self, n: usize) {
378        assert!(n <= self.len());
379        self.body.end -= n;
380    }
381}
382impl<B: AsRef<[u8]>> ParseBuffer for Buf<B> {
383    fn parse_with<'a, ParseArgs, P: ParsablePacket<&'a [u8], ParseArgs>>(
384        &'a mut self,
385        args: ParseArgs,
386    ) -> Result<P, P::Error> {
387        P::parse(self.buffer_view(), args)
388    }
389}
390
391impl<B: AsRef<[u8]> + AsMut<[u8]>> FragmentedBufferMut for Buf<B> {
392    fragmented_buffer_mut_method_impls!();
393}
394
395impl<B: AsRef<[u8]> + AsMut<[u8]>> ParseBufferMut for Buf<B> {
396    fn parse_with_mut<'a, ParseArgs, P: ParsablePacket<&'a mut [u8], ParseArgs>>(
397        &'a mut self,
398        args: ParseArgs,
399    ) -> Result<P, P::Error> {
400        P::parse_mut(self.buffer_view_mut(), args)
401    }
402}
403
404impl<B: AsRef<[u8]>> GrowBuffer for Buf<B> {
405    fn with_parts<'a, O, F>(&'a self, f: F) -> O
406    where
407        F: for<'b> FnOnce(&'a [u8], FragmentedBytes<'b, 'a>, &'a [u8]) -> O,
408    {
409        let (prefix, buf) = self.buf.as_ref().split_at(self.body.start);
410        let (body, suffix) = buf.split_at(self.body.end - self.body.start);
411        let mut body = [&body[..]];
412        f(prefix, body.as_fragmented_byte_slice(), suffix)
413    }
414    fn capacity(&self) -> usize {
415        self.buf.as_ref().len()
416    }
417    fn prefix_len(&self) -> usize {
418        self.body.start
419    }
420    fn suffix_len(&self) -> usize {
421        self.buf.as_ref().len() - self.body.end
422    }
423    fn grow_front(&mut self, n: usize) {
424        assert!(n <= self.body.start);
425        self.body.start -= n;
426    }
427    fn grow_back(&mut self, n: usize) {
428        assert!(n <= self.buf.as_ref().len() - self.body.end);
429        self.body.end += n;
430    }
431}
432
433impl<B: AsRef<[u8]> + AsMut<[u8]>> GrowBufferMut for Buf<B> {
434    fn with_parts_mut<'a, O, F>(&'a mut self, f: F) -> O
435    where
436        F: for<'b> FnOnce(&'a mut [u8], FragmentedBytesMut<'b, 'a>, &'a mut [u8]) -> O,
437    {
438        let (prefix, buf) = self.buf.as_mut().split_at_mut(self.body.start);
439        let (body, suffix) = buf.split_at_mut(self.body.end - self.body.start);
440        let mut body = [&mut body[..]];
441        f(prefix, body.as_fragmented_byte_slice(), suffix)
442    }
443
444    fn with_all_contents_mut<'a, O, F>(&'a mut self, f: F) -> O
445    where
446        F: for<'b> FnOnce(FragmentedBytesMut<'b, 'a>) -> O,
447    {
448        let mut all = [self.buf.as_mut()];
449        f(all.as_fragmented_byte_slice())
450    }
451}
452
453impl<B: AsRef<[u8]>> AsRef<[u8]> for Buf<B> {
454    fn as_ref(&self) -> &[u8] {
455        &self.buf.as_ref()[self.body.clone()]
456    }
457}
458
459impl<B: AsMut<[u8]>> AsMut<[u8]> for Buf<B> {
460    fn as_mut(&mut self) -> &mut [u8] {
461        &mut self.buf.as_mut()[self.body.clone()]
462    }
463}
464
465impl<B: AsRef<[u8]>> Buffer for Buf<B> {
466    fn parse_with_view<'a, ParseArgs, P: ParsablePacket<&'a [u8], ParseArgs>>(
467        &'a mut self,
468        args: ParseArgs,
469    ) -> Result<(P, &'a [u8]), P::Error> {
470        let Self { body, ref buf } = self;
471        let body_before = body.clone();
472        let view = BufView { buf: &buf.as_ref()[body.clone()], body };
473        P::parse(view, args).map(|r| (r, &buf.as_ref()[body_before]))
474    }
475}
476
477/// A [`BufferView`] into a [`Buf`].
478///
479/// A `BufView` is constructed by [`Buf::buffer_view`], and implements
480/// `BufferView`, providing a view into the `Buf` from which it was constructed.
481pub struct BufView<'a> {
482    buf: &'a [u8],
483    body: &'a mut Range<usize>,
484}
485
486impl<'a> BufferView<&'a [u8]> for BufView<'a> {
487    fn take_front(&mut self, n: usize) -> Option<&'a [u8]> {
488        if self.len() < n {
489            return None;
490        }
491        self.body.start += n;
492        Some(take_front(&mut self.buf, n))
493    }
494
495    fn take_back(&mut self, n: usize) -> Option<&'a [u8]> {
496        if self.len() < n {
497            return None;
498        }
499        self.body.end -= n;
500        Some(take_back(&mut self.buf, n))
501    }
502
503    fn into_rest(self) -> &'a [u8] {
504        self.buf
505    }
506}
507
508impl<'a> AsRef<[u8]> for BufView<'a> {
509    fn as_ref(&self) -> &[u8] {
510        self.buf
511    }
512}
513
514/// A [`BufferViewMut`] into a [`Buf`].
515///
516/// A `BufViewMut` is constructed by [`Buf::buffer_view_mut`], and implements
517/// `BufferViewMut`, providing a mutable view into the `Buf` from which it was
518/// constructed.
519pub struct BufViewMut<'a> {
520    buf: &'a mut [u8],
521    body: &'a mut Range<usize>,
522}
523
524impl<'a> BufferView<&'a mut [u8]> for BufViewMut<'a> {
525    fn take_front(&mut self, n: usize) -> Option<&'a mut [u8]> {
526        if self.len() < n {
527            return None;
528        }
529        self.body.start += n;
530        Some(take_front_mut(&mut self.buf, n))
531    }
532
533    fn take_back(&mut self, n: usize) -> Option<&'a mut [u8]> {
534        if self.len() < n {
535            return None;
536        }
537        self.body.end -= n;
538        Some(take_back_mut(&mut self.buf, n))
539    }
540
541    fn into_rest(self) -> &'a mut [u8] {
542        self.buf
543    }
544}
545
546impl<'a> BufferViewMut<&'a mut [u8]> for BufViewMut<'a> {}
547
548impl<'a> AsRef<[u8]> for BufViewMut<'a> {
549    fn as_ref(&self) -> &[u8] {
550        self.buf
551    }
552}
553
554impl<'a> AsMut<[u8]> for BufViewMut<'a> {
555    fn as_mut(&mut self) -> &mut [u8] {
556        self.buf
557    }
558}
559
560/// The constraints required by a [`PacketBuilder`].
561///
562/// `PacketConstraints` represents the constraints that must be satisfied in
563/// order to serialize a `PacketBuilder`.
564///
565/// A `PacketConstraints`, `c`, guarantees two properties:
566/// - `c.max_body_len() >= c.min_body_len()`
567/// - `c.header_len() + c.min_body_len() + c.footer_len()` does not overflow
568///   `usize`
569///
570/// It is not possible (using safe code) to obtain a `PacketConstraints` which
571/// violates these properties, so code may rely for its correctness on the
572/// assumption that these properties hold.
573#[derive(Copy, Clone, Debug, Eq, PartialEq)]
574pub struct PacketConstraints {
575    header_len: usize,
576    footer_len: usize,
577    min_body_len: usize,
578    max_body_len: usize,
579}
580
581impl PacketConstraints {
582    /// A no-op `PacketConstraints` which does not add any constraints - there
583    /// is no header, footer, minimum body length requirement, or maximum body
584    /// length requirement.
585    pub const UNCONSTRAINED: Self =
586        Self { header_len: 0, footer_len: 0, min_body_len: 0, max_body_len: usize::MAX };
587
588    /// Constructs a new `PacketConstraints`.
589    ///
590    /// # Panics
591    ///
592    /// `new` panics if the arguments violate the validity properties of
593    /// `PacketConstraints` - if `max_body_len < min_body_len`, or if
594    /// `header_len + min_body_len + footer_len` overflows `usize`.
595    #[inline]
596    pub fn new(
597        header_len: usize,
598        footer_len: usize,
599        min_body_len: usize,
600        max_body_len: usize,
601    ) -> PacketConstraints {
602        PacketConstraints::try_new(header_len, footer_len, min_body_len, max_body_len).expect(
603            "max_body_len < min_body_len or header_len + min_body_len + footer_len overflows usize",
604        )
605    }
606
607    /// Tries to construct a new `PacketConstraints`.
608    ///
609    /// `new` returns `None` if the provided values violate the validity
610    /// properties of `PacketConstraints` - if `max_body_len < min_body_len`, or
611    /// if `header_len + min_body_len + footer_len` overflows `usize`.
612    #[inline]
613    pub fn try_new(
614        header_len: usize,
615        footer_len: usize,
616        min_body_len: usize,
617        max_body_len: usize,
618    ) -> Option<PacketConstraints> {
619        // Test case 3 in test_packet_constraints
620        let header_min_body_footer_overflows = header_len
621            .checked_add(min_body_len)
622            .and_then(|sum| sum.checked_add(footer_len))
623            .is_none();
624        // Test case 5 in test_packet_constraints
625        let max_less_than_min = max_body_len < min_body_len;
626        if max_less_than_min || header_min_body_footer_overflows {
627            return None;
628        }
629        Some(PacketConstraints { header_len, footer_len, min_body_len, max_body_len })
630    }
631
632    /// Constructs a new `PacketConstraints` with a given `max_body_len`.
633    ///
634    /// The `header_len`, `footer_len`, and `min_body_len` are all `0`.
635    #[inline]
636    pub fn with_max_body_len(max_body_len: usize) -> PacketConstraints {
637        // SAFETY:
638        // - `max_body_len >= min_body_len` by construction
639        // - `header_len + min_body_len + footer_len` is 0 and thus does not
640        //   overflow `usize`
641        PacketConstraints { header_len: 0, footer_len: 0, min_body_len: 0, max_body_len }
642    }
643
644    /// The number of bytes in this packet's header.
645    #[inline]
646    pub fn header_len(&self) -> usize {
647        self.header_len
648    }
649
650    /// The number of bytes in this packet's footer.
651    #[inline]
652    pub fn footer_len(&self) -> usize {
653        self.footer_len
654    }
655
656    /// The minimum body length (in bytes) required by this packet in order to
657    /// avoid adding padding.
658    ///
659    /// `min_body_len` returns the minimum number of body bytes required in
660    /// order to avoid adding padding. Note that, if padding bytes are required,
661    /// they may not necessarily belong immediately following the body,
662    /// depending on which packet layer imposes the minimum. In particular, in a
663    /// nested packet, padding goes after the body of the layer which imposes
664    /// the minimum. This means that, if the layer that imposes the minimum is
665    /// not the innermost one, then padding must be added not after the
666    /// innermost body, but instead in between footers.
667    /// [`NestedPacketBuilder::serialize_into`] is responsible for inserting
668    /// padding when serializing nested packets.
669    ///
670    /// If there is no minimum body length, this returns 0.
671    #[inline]
672    pub fn min_body_len(&self) -> usize {
673        self.min_body_len
674    }
675
676    /// The maximum length (in bytes) of a body allowed by this packet.
677    ///
678    /// If there is no maximum body length, this returns [`core::usize::MAX`].
679    #[inline]
680    pub fn max_body_len(&self) -> usize {
681        self.max_body_len
682    }
683
684    /// Attempts to encapsulate `self` in `outer`.
685    ///
686    /// Upon success, `try_encapsulate` returns a `PacketConstraints` which
687    /// represents the encapsulation of `self` in `outer`. Its header length,
688    /// footer length, minimum body length, and maximum body length are set
689    /// accordingly.
690    ///
691    /// This is probably not the method you want to use; consider
692    /// [`Serializer::encapsulate`] instead.
693    pub fn try_encapsulate(&self, outer: &Self) -> Option<PacketConstraints> {
694        let inner = self;
695        // Test case 1 in test_packet_constraints
696        let header_len = inner.header_len.checked_add(outer.header_len)?;
697        // Test case 2 in test_packet_constraints
698        let footer_len = inner.footer_len.checked_add(outer.footer_len)?;
699        // This is guaranteed not to overflow by the invariants on
700        // PacketConstraint.
701        let inner_header_footer_len = inner.header_len + inner.footer_len;
702        // Note the saturating_sub here - it's OK if the inner PacketBuilder
703        // more than satisfies the outer PacketBuilder's minimum body length
704        // requirement.
705        let min_body_len = cmp::max(
706            outer.min_body_len.saturating_sub(inner_header_footer_len),
707            inner.min_body_len,
708        );
709        // Note the checked_sub here - it's NOT OK if the inner PacketBuilder
710        // exceeds the outer PacketBuilder's maximum body length requirement.
711        //
712        // Test case 4 in test_packet_constraints
713        let max_body_len =
714            cmp::min(outer.max_body_len.checked_sub(inner_header_footer_len)?, inner.max_body_len);
715        // It's still possible that `min_body_len > max_body_len` or that
716        // `header_len + min_body_len + footer_len` overflows `usize`; `try_new`
717        // checks those constraints for us.
718        PacketConstraints::try_new(header_len, footer_len, min_body_len, max_body_len)
719    }
720}
721
722/// The target buffers into which [`PacketBuilder::serialize`] serializes its
723/// header and footer.
724pub struct SerializeTarget<'a> {
725    #[allow(missing_docs)]
726    pub header: &'a mut [u8],
727    #[allow(missing_docs)]
728    pub footer: &'a mut [u8],
729}
730
731/// A builder capable of serializing a packet's headers and footers.
732///
733/// A `PacketBuilder` describes a packet's headers and footers, and is capable
734/// of serializing the header and the footer into an existing buffer via the
735/// `serialize` method. A `PacketBuilder` never describes a body.
736/// [`PacketBuilder::wrap_body`] must be used to create a packet serializer
737/// for a whole packet.
738///
739/// `()` may be used as an "empty" `PacketBuilder` with no header, footer,
740/// minimum body length requirement, or maximum body length requirement.
741pub trait PacketBuilder: Sized {
742    /// Gets the constraints for this `PacketBuilder`.
743    fn constraints(&self) -> PacketConstraints;
744
745    /// Serializes this packet into an existing buffer.
746    ///
747    /// *This method is usually called by this crate during the serialization of
748    /// a [`Serializer`], not directly by the user.*
749    ///
750    /// # Preconditions
751    ///
752    /// The caller is responsible for initializing `body` with the body to be
753    /// encapsulated, and for ensuring that the body satisfies both the minimum
754    /// and maximum body length requirements, possibly by adding padding or by
755    /// truncating the body.
756    ///
757    /// # Postconditions
758    ///
759    /// `serialize` is responsible for serializing its header and footer into
760    /// `target.header` and `target.footer` respectively.
761    ///
762    /// # Security
763    ///
764    /// `serialize` must initialize the bytes of the header and footer, even if
765    /// only to zero, in order to avoid leaking the contents of packets
766    /// previously stored in the same buffer.
767    ///
768    /// # Panics
769    ///
770    /// May panic if the `target.header` or `target.footer` are not large enough
771    /// to fit the packet's header and footer respectively, or if the body does
772    /// not satisfy the minimum or maximum body length requirements.
773    fn serialize(&self, target: &mut SerializeTarget<'_>, body: FragmentedBytesMut<'_, '_>);
774
775    /// Wraps given packet `body` in this packet.
776    ///
777    /// Consumes the [`PacketBuilder`] and the `body`. If the `body` implements
778    /// `Serializer` then the result implement `Serializer` as well.
779    #[inline]
780    fn wrap_body<B>(self, body: B) -> Nested<B, Self> {
781        Nested { inner: body, outer: self }
782    }
783}
784
785impl<'a, B: PacketBuilder> PacketBuilder for &'a B {
786    #[inline]
787    fn constraints(&self) -> PacketConstraints {
788        B::constraints(self)
789    }
790    #[inline]
791    fn serialize(&self, target: &mut SerializeTarget<'_>, body: FragmentedBytesMut<'_, '_>) {
792        B::serialize(self, target, body)
793    }
794}
795
796impl<'a, B: PacketBuilder> PacketBuilder for &'a mut B {
797    #[inline]
798    fn constraints(&self) -> PacketConstraints {
799        B::constraints(self)
800    }
801    #[inline]
802    fn serialize(&self, target: &mut SerializeTarget<'_>, body: FragmentedBytesMut<'_, '_>) {
803        B::serialize(self, target, body)
804    }
805}
806
807impl PacketBuilder for () {
808    #[inline]
809    fn constraints(&self) -> PacketConstraints {
810        PacketConstraints::UNCONSTRAINED
811    }
812    #[inline]
813    fn serialize(&self, _target: &mut SerializeTarget<'_>, _body: FragmentedBytesMut<'_, '_>) {}
814}
815
816impl PacketBuilder for Never {
817    fn constraints(&self) -> PacketConstraints {
818        match *self {}
819    }
820    fn serialize(&self, _target: &mut SerializeTarget<'_>, _body: FragmentedBytesMut<'_, '_>) {}
821}
822
823/// One object encapsulated in another one.
824///
825/// `Nested`s are constructed using the [`PacketBuilder::wrap_body`] and
826/// [`Serializer::wrap_in`] methods.
827///
828/// When `I: Serializer` and `O: PacketBuilder`, `Nested<I, O>` implements
829/// [`Serializer`].
830#[derive(Copy, Clone, Debug, Eq, PartialEq)]
831pub struct Nested<I, O> {
832    inner: I,
833    outer: O,
834}
835
836impl<I, O> Nested<I, O> {
837    /// Consumes this `Nested` and returns the inner object, discarding the
838    /// outer one.
839    #[inline]
840    pub fn into_inner(self) -> I {
841        self.inner
842    }
843
844    /// Consumes this `Nested` and returns the outer object, discarding the
845    /// inner one.
846    #[inline]
847    pub fn into_outer(self) -> O {
848        self.outer
849    }
850
851    #[inline]
852    pub fn inner(&self) -> &I {
853        &self.inner
854    }
855
856    #[inline]
857    pub fn inner_mut(&mut self) -> &mut I {
858        &mut self.inner
859    }
860
861    #[inline]
862    pub fn outer(&self) -> &O {
863        &self.outer
864    }
865
866    #[inline]
867    pub fn outer_mut(&mut self) -> &mut O {
868        &mut self.outer
869    }
870}
871
872/// A [`PacketBuilder`] which has no header or footer, but which imposes a
873/// maximum body length constraint.
874///
875/// `LimitedSizePacketBuilder`s are constructed using the
876/// [`Serializer::with_size_limit`] method.
877#[derive(Copy, Clone, Debug)]
878#[cfg_attr(test, derive(Eq, PartialEq))]
879pub struct LimitedSizePacketBuilder {
880    /// The maximum body length.
881    pub limit: usize,
882}
883
884impl PacketBuilder for LimitedSizePacketBuilder {
885    fn constraints(&self) -> PacketConstraints {
886        PacketConstraints::with_max_body_len(self.limit)
887    }
888
889    fn serialize(&self, _target: &mut SerializeTarget<'_>, _body: FragmentedBytesMut<'_, '_>) {}
890}
891
892/// A builder capable of serializing packets - which do not encapsulate other
893/// packets - into an existing buffer.
894///
895/// An `InnerPacketBuilder` describes a packet, and is capable of serializing
896/// that packet into an existing buffer via the `serialize` method. Unlike the
897/// [`PacketBuilder`] trait, it describes a packet which does not encapsulate
898/// other packets.
899///
900/// # Notable implementations
901///
902/// `InnerPacketBuilder` is implemented for `&[u8]`, `&mut [u8]`, and `Vec<u8>`
903/// by treating the contents of the slice/`Vec` as the contents of the packet to
904/// be serialized.
905pub trait InnerPacketBuilder {
906    /// The number of bytes consumed by this packet.
907    fn bytes_len(&self) -> usize;
908
909    /// Serializes this packet into an existing buffer.
910    ///
911    /// `serialize` is called with a buffer of length `self.bytes_len()`, and is
912    /// responsible for serializing the packet into the buffer.
913    ///
914    /// # Security
915    ///
916    /// All of the bytes of the buffer should be initialized, even if only to
917    /// zero, in order to avoid leaking the contents of packets previously
918    /// stored in the same buffer.
919    ///
920    /// # Panics
921    ///
922    /// May panic if `buffer.len() != self.bytes_len()`.
923    fn serialize(&self, buffer: &mut [u8]);
924
925    /// Converts this `InnerPacketBuilder` into a [`Serializer`].
926    ///
927    /// `into_serializer` is like [`into_serializer_with`], except that no
928    /// buffer is provided for reuse in serialization.
929    ///
930    /// [`into_serializer_with`]: InnerPacketBuilder::into_serializer_with
931    #[inline]
932    fn into_serializer(self) -> InnerSerializer<Self, EmptyBuf>
933    where
934        Self: Sized,
935    {
936        self.into_serializer_with(EmptyBuf)
937    }
938
939    /// Converts this `InnerPacketBuilder` into a [`Serializer`] with a buffer
940    /// that can be used for serialization.
941    ///
942    /// `into_serializer_with` consumes a buffer and converts `self` into a type
943    /// which implements `Serialize` by treating it as the innermost body to be
944    /// contained within any encapsulating [`PacketBuilder`]s. During
945    /// serialization, `buffer` will be provided to the [`BufferProvider`],
946    /// allowing it to reuse the buffer for serialization and avoid allocating a
947    /// new one if possible.
948    ///
949    /// `buffer` will have its body shrunk to be zero bytes before the
950    /// `InnerSerializer` is constructed.
951    fn into_serializer_with<B: ShrinkBuffer>(self, mut buffer: B) -> InnerSerializer<Self, B>
952    where
953        Self: Sized,
954    {
955        buffer.shrink_back_to(0);
956        InnerSerializer { inner: self, buffer }
957    }
958}
959
960impl<'a, I: InnerPacketBuilder> InnerPacketBuilder for &'a I {
961    #[inline]
962    fn bytes_len(&self) -> usize {
963        I::bytes_len(self)
964    }
965    #[inline]
966    fn serialize(&self, buffer: &mut [u8]) {
967        I::serialize(self, buffer)
968    }
969}
970impl<'a, I: InnerPacketBuilder> InnerPacketBuilder for &'a mut I {
971    #[inline]
972    fn bytes_len(&self) -> usize {
973        I::bytes_len(self)
974    }
975    #[inline]
976    fn serialize(&self, buffer: &mut [u8]) {
977        I::serialize(self, buffer)
978    }
979}
980impl<'a> InnerPacketBuilder for &'a [u8] {
981    #[inline]
982    fn bytes_len(&self) -> usize {
983        self.len()
984    }
985    #[inline]
986    fn serialize(&self, buffer: &mut [u8]) {
987        buffer.copy_from_slice(self);
988    }
989}
990impl<'a> InnerPacketBuilder for &'a mut [u8] {
991    #[inline]
992    fn bytes_len(&self) -> usize {
993        self.len()
994    }
995    #[inline]
996    fn serialize(&self, buffer: &mut [u8]) {
997        buffer.copy_from_slice(self);
998    }
999}
1000impl<'a> InnerPacketBuilder for Vec<u8> {
1001    #[inline]
1002    fn bytes_len(&self) -> usize {
1003        self.len()
1004    }
1005    #[inline]
1006    fn serialize(&self, buffer: &mut [u8]) {
1007        buffer.copy_from_slice(self.as_slice());
1008    }
1009}
1010impl<const N: usize> InnerPacketBuilder for ArrayVec<u8, N> {
1011    fn bytes_len(&self) -> usize {
1012        self.as_slice().bytes_len()
1013    }
1014    fn serialize(&self, buffer: &mut [u8]) {
1015        self.as_slice().serialize(buffer);
1016    }
1017}
1018
1019/// An [`InnerPacketBuilder`] created from any [`B: SplitByteSlice`].
1020///
1021/// `ByteSliceInnerPacketBuilder<B>` implements `InnerPacketBuilder` so long as
1022/// `B: SplitByteSlice`.
1023///
1024/// [`B: SplitByteSlice`]: zerocopy::SplitByteSlice
1025pub struct ByteSliceInnerPacketBuilder<B>(pub B);
1026
1027impl<B: SplitByteSlice> InnerPacketBuilder for ByteSliceInnerPacketBuilder<B> {
1028    fn bytes_len(&self) -> usize {
1029        self.0.deref().bytes_len()
1030    }
1031    fn serialize(&self, buffer: &mut [u8]) {
1032        self.0.deref().serialize(buffer)
1033    }
1034}
1035
1036impl<B: SplitByteSlice> Debug for ByteSliceInnerPacketBuilder<B> {
1037    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1038        write!(f, "ByteSliceInnerPacketBuilder({:?})", self.0.as_ref())
1039    }
1040}
1041
1042/// An error in serializing a packet.
1043///
1044/// `SerializeError` is the type of errors returned from methods on the
1045/// [`Serializer`] trait. The `Alloc` variant indicates that a new buffer could
1046/// not be allocated, while the `SizeLimitExceeded` variant indicates that a
1047/// size limit constraint was exceeded.
1048#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1049pub enum SerializeError<A> {
1050    /// A new buffer could not be allocated.
1051    Alloc(A),
1052    /// The size limit constraint was exceeded.
1053    SizeLimitExceeded,
1054}
1055
1056impl<A> SerializeError<A> {
1057    /// Is this `SerializeError::Alloc`?
1058    #[inline]
1059    pub fn is_alloc(&self) -> bool {
1060        match self {
1061            SerializeError::Alloc(_) => true,
1062            SerializeError::SizeLimitExceeded => false,
1063        }
1064    }
1065
1066    /// Is this `SerializeError::SizeLimitExceeded`?
1067    #[inline]
1068    pub fn is_size_limit_exceeded(&self) -> bool {
1069        match self {
1070            SerializeError::Alloc(_) => false,
1071            SerializeError::SizeLimitExceeded => true,
1072        }
1073    }
1074
1075    /// Maps the [`SerializeError::Alloc`] error type.
1076    pub fn map_alloc<T, F: FnOnce(A) -> T>(self, f: F) -> SerializeError<T> {
1077        match self {
1078            SerializeError::Alloc(a) => SerializeError::Alloc(f(a)),
1079            SerializeError::SizeLimitExceeded => SerializeError::SizeLimitExceeded,
1080        }
1081    }
1082}
1083
1084impl<A> From<A> for SerializeError<A> {
1085    fn from(a: A) -> SerializeError<A> {
1086        SerializeError::Alloc(a)
1087    }
1088}
1089
1090/// The error returned when a buffer is too short to hold a serialized packet,
1091/// and the [`BufferProvider`] is incapable of allocating a new one.
1092///
1093/// `BufferTooShortError` is returned by the [`Serializer`] methods
1094/// [`serialize_no_alloc`] and [`serialize_no_alloc_outer`].
1095///
1096/// [`serialize_no_alloc`]: Serializer::serialize_no_alloc
1097/// [`serialize_no_alloc_outer`]: Serializer::serialize_no_alloc_outer
1098#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1099pub struct BufferTooShortError;
1100
1101/// An object capable of providing buffers which satisfy certain constraints.
1102///
1103/// A `BufferProvider<Input, Output>` is an object which is capable of consuming
1104/// a buffer of type `Input` and, either by reusing it or by allocating a new
1105/// one and copying the input buffer's body into it, producing a buffer of type
1106/// `Output` which meets certain prefix and suffix length constraints.
1107///
1108/// A `BufferProvider` must always be provided when serializing a
1109/// [`Serializer`].
1110///
1111/// Implementors may find the helper function [`try_reuse_buffer`] useful.
1112///
1113/// For clients who don't need the full expressive power of this trait, the
1114/// simpler [`BufferAlloc`] trait is provided. It only defines how to allocate
1115/// new buffers, and two blanket impls of `BufferProvider` are provided for all
1116/// `BufferAlloc` types.
1117pub trait BufferProvider<Input, Output> {
1118    /// The type of errors returned from [`reuse_or_realloc`].
1119    ///
1120    /// [`reuse_or_realloc`]: BufferProvider::reuse_or_realloc
1121    type Error;
1122
1123    /// Attempts to produce an output buffer with the given constraints by
1124    /// allocating a new one.
1125    ///
1126    /// `alloc_no_reuse` produces a new buffer with the following invariants:
1127    /// - The output buffer must have at least `prefix` bytes of prefix
1128    /// - The output buffer must have at least `suffix` bytes of suffix
1129    /// - The output buffer must have a body of length `body` bytes.
1130    ///
1131    /// If these requirements cannot be met, then an error is returned.
1132    fn alloc_no_reuse(
1133        self,
1134        prefix: usize,
1135        body: usize,
1136        suffix: usize,
1137    ) -> Result<Output, Self::Error>;
1138
1139    /// Consumes an input buffer and attempts to produce an output buffer with
1140    /// the given constraints, either by reusing the input buffer or by
1141    /// allocating a new one and copying the body into it.
1142    ///
1143    /// `reuse_or_realloc` consumes a buffer by value, and produces a new buffer
1144    /// with the following invariants:
1145    /// - The output buffer must have at least `prefix` bytes of prefix
1146    /// - The output buffer must have at least `suffix` bytes of suffix
1147    /// - The output buffer must have the same body as the input buffer
1148    ///
1149    /// If these requirements cannot be met, then an error is returned along
1150    /// with the input buffer, which is unmodified.
1151    fn reuse_or_realloc(
1152        self,
1153        buffer: Input,
1154        prefix: usize,
1155        suffix: usize,
1156    ) -> Result<Output, (Self::Error, Input)>;
1157}
1158
1159/// An object capable of allocating new buffers.
1160///
1161/// A `BufferAlloc<Output>` is an object which is capable of allocating new
1162/// buffers of type `Output`.
1163///
1164/// [Two blanket implementations] of [`BufferProvider`] are given for any type
1165/// which implements `BufferAlloc<O>`. One blanket implementation works for any
1166/// input buffer type, `I`, and produces buffers of type `Either<I, O>` as
1167/// output. One blanket implementation works only when the input and output
1168/// buffer types are the same, and produces buffers of that type. See the
1169/// documentation on those impls for more details.
1170///
1171/// The following implementations of `BufferAlloc` are provided:
1172/// - Any `FnOnce(usize) -> Result<O, E>` implements `BufferAlloc<O, Error = E>`
1173/// - `()` implements `BufferAlloc<Never, Error = ()>` (an allocator which
1174///   always fails)
1175/// - [`new_buf_vec`] implements `BufferAlloc<Buf<Vec<u8>>, Error = Never>` (an
1176///   allocator which infallibly heap-allocates `Vec`s)
1177///
1178/// [Two blanket implementations]: trait.BufferProvider.html#implementors
1179pub trait BufferAlloc<Output> {
1180    /// The type of errors returned from [`alloc`].
1181    ///
1182    /// [`alloc`]: BufferAlloc::alloc
1183    type Error;
1184
1185    /// Attempts to allocate a new buffer of size `len`.
1186    fn alloc(self, len: usize) -> Result<Output, Self::Error>;
1187}
1188
1189impl<O, E, F: FnOnce(usize) -> Result<O, E>> BufferAlloc<O> for F {
1190    type Error = E;
1191
1192    #[inline]
1193    fn alloc(self, len: usize) -> Result<O, E> {
1194        self(len)
1195    }
1196}
1197
1198impl BufferAlloc<Never> for () {
1199    type Error = ();
1200
1201    #[inline]
1202    fn alloc(self, _len: usize) -> Result<Never, ()> {
1203        Err(())
1204    }
1205}
1206
1207/// Allocates a new `Buf<Vec<u8>>`.
1208///
1209/// `new_buf_vec(len)` is shorthand for `Ok(Buf::new(vec![0; len], ..))`. It
1210/// implements [`BufferAlloc<Buf<Vec<u8>>, Error = Never>`], and, thanks to a
1211/// blanket impl, [`BufferProvider<I, Either<I, Buf<Vec<u8>>>, Error = Never>`]
1212/// for all `I: BufferMut`, and `BufferProvider<Buf<Vec<u8>>, Buf<Vec<u8>>,
1213/// Error = Never>`.
1214///
1215/// [`BufferAlloc<Buf<Vec<u8>>, Error = Never>`]: BufferAlloc
1216/// [`BufferProvider<I, Either<I, Buf<Vec<u8>>>, Error = Never>`]: BufferProvider
1217pub fn new_buf_vec(len: usize) -> Result<Buf<Vec<u8>>, Never> {
1218    Ok(Buf::new(vec![0; len], ..))
1219}
1220
1221/// A variant of [`BufferAlloc`] that allocates buffers with the necessary
1222/// prefix, body, suffix layout.
1223pub trait LayoutBufferAlloc<O> {
1224    /// The type of errors returned from [`layout_alloc`].
1225    ///
1226    /// [`layout_alloc`]: LayoutBufferAlloc::layout_alloc
1227    type Error;
1228
1229    /// Like [`BufferAlloc::layout_alloc`], but the returned buffer has reserved
1230    /// `prefix` and `suffix` bytes around `body`.
1231    fn layout_alloc(self, prefix: usize, body: usize, suffix: usize) -> Result<O, Self::Error>;
1232}
1233
1234impl<O: ShrinkBuffer, E, F: FnOnce(usize) -> Result<O, E>> LayoutBufferAlloc<O> for F {
1235    type Error = E;
1236
1237    #[inline]
1238    fn layout_alloc(self, prefix: usize, body: usize, suffix: usize) -> Result<O, E> {
1239        let mut b = self(prefix + body + suffix)?;
1240        b.shrink_front(prefix);
1241        b.shrink_back(suffix);
1242        Ok(b)
1243    }
1244}
1245
1246impl LayoutBufferAlloc<Never> for () {
1247    type Error = ();
1248
1249    #[inline]
1250    fn layout_alloc(self, _prefix: usize, _body: usize, _suffix: usize) -> Result<Never, ()> {
1251        Err(())
1252    }
1253}
1254
1255/// Attempts to reuse a buffer for the purposes of implementing
1256/// [`BufferProvider::reuse_or_realloc`].
1257///
1258/// `try_reuse_buffer` attempts to reuse an existing buffer to satisfy the given
1259/// prefix and suffix constraints. If it succeeds, it returns `Ok` containing a
1260/// buffer with the same body as the input, and with at least `prefix` prefix
1261/// bytes and at least `suffix` suffix bytes. Otherwise, it returns `Err`
1262/// containing the original, unmodified input buffer.
1263///
1264/// Concretely, `try_reuse_buffer` has the following behavior:
1265/// - If the prefix and suffix constraints are already met, it returns `Ok` with
1266///   the input unmodified
1267/// - If the prefix and suffix constraints are not yet met, then...
1268///   - If there is enough capacity to meet the constraints and the body is not
1269///     larger than `max_copy_bytes`, the body will be moved within the buffer
1270///     in order to meet the constraints, and it will be returned
1271///   - Otherwise, if there is not enough capacity or the body is larger than
1272///     `max_copy_bytes`, it returns `Err` with the input unmodified
1273///
1274/// `max_copy_bytes` is meant to be an estimate of how many bytes can be copied
1275/// before allocating a new buffer will be cheaper than copying.
1276#[inline]
1277pub fn try_reuse_buffer<B: GrowBufferMut + ShrinkBuffer>(
1278    mut buffer: B,
1279    prefix: usize,
1280    suffix: usize,
1281    max_copy_bytes: usize,
1282) -> Result<B, B> {
1283    let need_prefix = prefix;
1284    let need_suffix = suffix;
1285    let have_prefix = buffer.prefix_len();
1286    let have_body = buffer.len();
1287    let have_suffix = buffer.suffix_len();
1288    let need_capacity = need_prefix + have_body + need_suffix;
1289
1290    if have_prefix >= need_prefix && have_suffix >= need_suffix {
1291        // We already satisfy the prefix and suffix requirements.
1292        Ok(buffer)
1293    } else if buffer.capacity() >= need_capacity && have_body <= max_copy_bytes {
1294        // The buffer is large enough, but the body is currently too far
1295        // forward or too far backwards to satisfy the prefix or suffix
1296        // requirements, so we need to move the body within the buffer.
1297        buffer.reset();
1298
1299        // Copy the original body range to a point starting immediatley
1300        // after `prefix`. This satisfies the `prefix` constraint by
1301        // definition, and satisfies the `suffix` constraint since we know
1302        // that the total buffer capacity is sufficient to hold the total
1303        // length of the prefix, body, and suffix.
1304        buffer.copy_within(have_prefix..(have_prefix + have_body), need_prefix);
1305        buffer.shrink(need_prefix..(need_prefix + have_body));
1306        debug_assert_eq!(buffer.prefix_len(), need_prefix);
1307        debug_assert!(buffer.suffix_len() >= need_suffix);
1308        debug_assert_eq!(buffer.len(), have_body);
1309        Ok(buffer)
1310    } else {
1311        Err(buffer)
1312    }
1313}
1314
1315/// Provides an implementation of [`BufferProvider`] from a [`BufferAlloc`] `A`
1316/// that attempts to reuse the input buffer and falls back to the allocator if
1317/// the input buffer can't be reused.
1318pub struct MaybeReuseBufferProvider<A>(pub A);
1319
1320impl<I: ReusableBuffer, O: ReusableBuffer, A: BufferAlloc<O>> BufferProvider<I, Either<I, O>>
1321    for MaybeReuseBufferProvider<A>
1322{
1323    type Error = A::Error;
1324
1325    fn alloc_no_reuse(
1326        self,
1327        prefix: usize,
1328        body: usize,
1329        suffix: usize,
1330    ) -> Result<Either<I, O>, Self::Error> {
1331        let Self(alloc) = self;
1332        let need_capacity = prefix + body + suffix;
1333        BufferAlloc::alloc(alloc, need_capacity).map(|mut buf| {
1334            buf.shrink(prefix..(prefix + body));
1335            Either::B(buf)
1336        })
1337    }
1338
1339    /// If `buffer` has enough capacity to store `need_prefix + need_suffix +
1340    /// buffer.len()` bytes, then reuse `buffer`. Otherwise, allocate a new
1341    /// buffer using `A`'s [`BufferAlloc`] implementation.
1342    ///
1343    /// If there is enough capacity, but the body is too far forwards or
1344    /// backwards in the buffer to satisfy the prefix and suffix constraints,
1345    /// the body will be moved within the buffer in order to satisfy the
1346    /// constraints. This operation is linear in the length of the body.
1347    #[inline]
1348    fn reuse_or_realloc(
1349        self,
1350        buffer: I,
1351        need_prefix: usize,
1352        need_suffix: usize,
1353    ) -> Result<Either<I, O>, (A::Error, I)> {
1354        // TODO(joshlf): Maybe it's worth coming up with a heuristic for when
1355        // moving the body is likely to be more expensive than allocating
1356        // (rather than just using `usize::MAX`)? This will be tough since we
1357        // don't know anything about the performance of `A::alloc`.
1358        match try_reuse_buffer(buffer, need_prefix, need_suffix, usize::MAX) {
1359            Ok(buffer) => Ok(Either::A(buffer)),
1360            Err(buffer) => {
1361                let have_body = buffer.len();
1362                let mut buf = match BufferProvider::<I, Either<I, O>>::alloc_no_reuse(
1363                    self,
1364                    need_prefix,
1365                    have_body,
1366                    need_suffix,
1367                ) {
1368                    Ok(buf) => buf,
1369                    Err(err) => return Err((err, buffer)),
1370                };
1371
1372                buf.copy_from(&buffer);
1373                debug_assert_eq!(buf.prefix_len(), need_prefix);
1374                debug_assert!(buf.suffix_len() >= need_suffix);
1375                debug_assert_eq!(buf.len(), have_body);
1376                Ok(buf)
1377            }
1378        }
1379    }
1380}
1381
1382impl<B: ReusableBuffer, A: BufferAlloc<B>> BufferProvider<B, B> for MaybeReuseBufferProvider<A> {
1383    type Error = A::Error;
1384
1385    fn alloc_no_reuse(self, prefix: usize, body: usize, suffix: usize) -> Result<B, Self::Error> {
1386        BufferProvider::<B, Either<B, B>>::alloc_no_reuse(self, prefix, body, suffix)
1387            .map(Either::into_inner)
1388    }
1389
1390    /// If `buffer` has enough capacity to store `need_prefix + need_suffix +
1391    /// buffer.len()` bytes, then reuse `buffer`. Otherwise, allocate a new
1392    /// buffer using `A`'s [`BufferAlloc`] implementation.
1393    ///
1394    /// If there is enough capacity, but the body is too far forwards or
1395    /// backwards in the buffer to satisfy the prefix and suffix constraints,
1396    /// the body will be moved within the buffer in order to satisfy the
1397    /// constraints. This operation is linear in the length of the body.
1398    #[inline]
1399    fn reuse_or_realloc(self, buffer: B, prefix: usize, suffix: usize) -> Result<B, (A::Error, B)> {
1400        BufferProvider::<B, Either<B, B>>::reuse_or_realloc(self, buffer, prefix, suffix)
1401            .map(Either::into_inner)
1402    }
1403}
1404
1405/// Provides an implementation of [`BufferProvider`] from a [`BufferAlloc`] `A`
1406/// that never attempts to reuse the input buffer, and always create a new
1407/// buffer from the allocator `A`.
1408pub struct NoReuseBufferProvider<A>(pub A);
1409
1410impl<I: FragmentedBuffer, O: ReusableBuffer, A: BufferAlloc<O>> BufferProvider<I, O>
1411    for NoReuseBufferProvider<A>
1412{
1413    type Error = A::Error;
1414
1415    fn alloc_no_reuse(self, prefix: usize, body: usize, suffix: usize) -> Result<O, A::Error> {
1416        let Self(alloc) = self;
1417        alloc.alloc(prefix + body + suffix).map(|mut b| {
1418            b.shrink(prefix..prefix + body);
1419            b
1420        })
1421    }
1422
1423    fn reuse_or_realloc(self, buffer: I, prefix: usize, suffix: usize) -> Result<O, (A::Error, I)> {
1424        BufferProvider::<I, O>::alloc_no_reuse(self, prefix, buffer.len(), suffix)
1425            .map(|mut b| {
1426                b.copy_from(&buffer);
1427                b
1428            })
1429            .map_err(|e| (e, buffer))
1430    }
1431}
1432
1433pub trait Serializer: Sized {
1434    /// The type of buffers returned from serialization methods on this trait.
1435    type Buffer;
1436
1437    /// Serializes this `Serializer`, producing a buffer.
1438    ///
1439    /// As `Serializer`s can be nested using the [`Nested`] type (constructed
1440    /// using [`PacketBuilder::wrap_body`] and [`Serializer::wrap_in`]), the
1441    /// `serialize` method is recursive - calling it on a `Nested` will recurse
1442    /// into the inner `Serializer`, which might itself be a `Nested`, and so
1443    /// on. When the innermost `Serializer` is reached, the contained buffer is
1444    /// passed to the `provider`, allowing it to decide how to produce a buffer
1445    /// which is large enough to fit the entire packet - either by reusing the
1446    /// existing buffer, or by discarding it and allocating a new one. `outer`
1447    /// specifies [`PacketConstraints`] for the outer parts of the packet
1448    /// (header and footer).
1449    fn serialize<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>(
1450        self,
1451        outer: PacketConstraints,
1452        provider: P,
1453    ) -> Result<B, (SerializeError<P::Error>, Self)>;
1454
1455    /// Serializes the data into a new buffer without consuming `self`.
1456    ///
1457    /// Creates a new buffer using `alloc` and serializes the data into that
1458    /// that new buffer. Unlike all other serialize methods,
1459    /// `serialize_new_buf` takes `self` by reference. This allows to use the
1460    /// same `Serializer` to serialize the data more than once.
1461    fn serialize_new_buf<B: GrowBufferMut, A: LayoutBufferAlloc<B>>(
1462        &self,
1463        outer: PacketConstraints,
1464        alloc: A,
1465    ) -> Result<B, SerializeError<A::Error>>;
1466
1467    /// Serializes this `Serializer`, allocating a [`Buf<Vec<u8>>`] if the
1468    /// contained buffer isn't large enough.
1469    ///
1470    /// `serialize_vec` is like [`serialize`], except that, if the contained
1471    /// buffer isn't large enough to contain the packet, a new `Vec<u8>` is
1472    /// allocated and wrapped in a [`Buf`]. If the buffer is large enough, but
1473    /// the body is too far forwards or backwards to fit the encapsulating
1474    /// headers or footers, the body will be moved within the buffer (this
1475    /// operation's cost is linear in the size of the body).
1476    ///
1477    /// `serialize_vec` is equivalent to calling `serialize` with
1478    /// [`new_buf_vec`] as the [`BufferProvider`].
1479    ///
1480    /// [`Buf<Vec<u8>>`]: Buf
1481    /// [`serialize`]: Serializer::serialize
1482    #[inline]
1483    #[allow(clippy::type_complexity)]
1484    fn serialize_vec(
1485        self,
1486        outer: PacketConstraints,
1487    ) -> Result<Either<Self::Buffer, Buf<Vec<u8>>>, (SerializeError<Never>, Self)>
1488    where
1489        Self::Buffer: ReusableBuffer,
1490    {
1491        self.serialize(outer, MaybeReuseBufferProvider(new_buf_vec))
1492    }
1493
1494    /// Serializes this `Serializer`, failing if the existing buffer is not
1495    /// large enough.
1496    ///
1497    /// `serialize_no_alloc` is like [`serialize`], except that it will fail if
1498    /// the existing buffer isn't large enough. If the buffer is large enough,
1499    /// but the body is too far forwards or backwards to fit the encapsulating
1500    /// headers or footers, the body will be moved within the buffer (this
1501    /// operation's cost is linear in the size of the body).
1502    ///
1503    /// `serialize_no_alloc` is equivalent to calling `serialize` with a
1504    /// `BufferProvider` which cannot allocate a new buffer (such as `()`).
1505    ///
1506    /// [`serialize`]: Serializer::serialize
1507    #[inline]
1508    fn serialize_no_alloc(
1509        self,
1510        outer: PacketConstraints,
1511    ) -> Result<Self::Buffer, (SerializeError<BufferTooShortError>, Self)>
1512    where
1513        Self::Buffer: ReusableBuffer,
1514    {
1515        self.serialize(outer, MaybeReuseBufferProvider(())).map(Either::into_a).map_err(
1516            |(err, slf)| {
1517                (
1518                    match err {
1519                        SerializeError::Alloc(()) => BufferTooShortError.into(),
1520                        SerializeError::SizeLimitExceeded => SerializeError::SizeLimitExceeded,
1521                    },
1522                    slf,
1523                )
1524            },
1525        )
1526    }
1527
1528    /// Serializes this `Serializer` as the outermost packet.
1529    ///
1530    /// `serialize_outer` is like [`serialize`], except that it is called when
1531    /// this `Serializer` describes the outermost packet, not encapsulated in
1532    /// any other packets. It is equivalent to calling `serialize` with an empty
1533    /// [`PacketBuilder`] (such as `()`).
1534    ///
1535    /// [`serialize`]: Serializer::serialize
1536    #[inline]
1537    fn serialize_outer<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>(
1538        self,
1539        provider: P,
1540    ) -> Result<B, (SerializeError<P::Error>, Self)> {
1541        self.serialize(PacketConstraints::UNCONSTRAINED, provider)
1542    }
1543
1544    /// Serializes this `Serializer` as the outermost packet, allocating a
1545    /// [`Buf<Vec<u8>>`] if the contained buffer isn't large enough.
1546    ///
1547    /// `serialize_vec_outer` is like [`serialize_vec`], except that it is
1548    /// called when this `Serializer` describes the outermost packet, not
1549    /// encapsulated in any other packets. It is equivalent to calling
1550    /// `serialize_vec` with an empty [`PacketBuilder`] (such as `()`).
1551    ///
1552    /// [`Buf<Vec<u8>>`]: Buf
1553    /// [`serialize_vec`]: Serializer::serialize_vec
1554    #[inline]
1555    #[allow(clippy::type_complexity)]
1556    fn serialize_vec_outer(
1557        self,
1558    ) -> Result<Either<Self::Buffer, Buf<Vec<u8>>>, (SerializeError<Never>, Self)>
1559    where
1560        Self::Buffer: ReusableBuffer,
1561    {
1562        self.serialize_vec(PacketConstraints::UNCONSTRAINED)
1563    }
1564
1565    /// Serializes this `Serializer` as the outermost packet, failing if the
1566    /// existing buffer is not large enough.
1567    ///
1568    /// `serialize_no_alloc_outer` is like [`serialize_no_alloc`], except that
1569    /// it is called when this `Serializer` describes the outermost packet, not
1570    /// encapsulated in any other packets. It is equivalent to calling
1571    /// `serialize_no_alloc` with an empty [`PacketBuilder`] (such as `()`).
1572    ///
1573    /// [`serialize_no_alloc`]: Serializer::serialize_no_alloc
1574    #[inline]
1575    fn serialize_no_alloc_outer(
1576        self,
1577    ) -> Result<Self::Buffer, (SerializeError<BufferTooShortError>, Self)>
1578    where
1579        Self::Buffer: ReusableBuffer,
1580    {
1581        self.serialize_no_alloc(PacketConstraints::UNCONSTRAINED)
1582    }
1583
1584    /// Encapsulates this `Serializer` in a packet, producing a new
1585    /// `Serializer`.
1586    ///
1587    /// `wrap_in()` consumes this `Serializer` and a [`PacketBuilder`], and
1588    /// produces a new `Serializer` which describes encapsulating this one in
1589    /// the packet described by `outer`.
1590    #[inline]
1591    fn wrap_in<B: PacketBuilder>(self, outer: B) -> Nested<Self, B> {
1592        outer.wrap_body(self)
1593    }
1594
1595    /// Creates a new `Serializer` which will enforce a size limit.
1596    ///
1597    /// `with_size_limit` consumes this `Serializer` and limit, and produces a
1598    /// new `Serializer` which will enforce the given limit on all serialization
1599    /// requests. Note that the given limit will be enforced at this layer -
1600    /// serialization requests will be rejected if the body produced by the
1601    /// request at this layer would exceed the limit. It has no effect on
1602    /// headers or footers added by encapsulating layers outside of this one.
1603    #[inline]
1604    fn with_size_limit(self, limit: usize) -> Nested<Self, LimitedSizePacketBuilder> {
1605        self.wrap_in(LimitedSizePacketBuilder { limit })
1606    }
1607}
1608
1609/// A [`Serializer`] constructed from an [`InnerPacketBuilder`].
1610///
1611/// An `InnerSerializer` wraps an `InnerPacketBuilder` and a buffer, and
1612/// implements the `Serializer` trait. When a serialization is requested, it
1613/// either reuses the stored buffer or allocates a new one large enough to hold
1614/// itself and all outer `PacketBuilder`s.
1615#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1616pub struct InnerSerializer<I, B> {
1617    inner: I,
1618    // The buffer's length must be zero since we encapsulate the buffer in a
1619    // PacketBuilder. If the length were non-zero, that would have the effect of
1620    // retaining the contents of the buffer when serializing, and putting them
1621    // immediately after the bytes of `inner`.
1622    buffer: B,
1623}
1624
1625impl<I, B> InnerSerializer<I, B> {
1626    pub fn inner(&self) -> &I {
1627        &self.inner
1628    }
1629}
1630
1631/// A wrapper for `InnerPacketBuilders` which implements `PacketBuilder` by
1632/// treating the entire `InnerPacketBuilder` as the header of the
1633/// `PacketBuilder`. This allows us to compose our InnerPacketBuilder with
1634/// the outer `PacketBuilders` into a single, large `PacketBuilder`, and then
1635/// serialize it using `self.buffer`.
1636struct InnerPacketBuilderWrapper<I>(I);
1637
1638impl<I: InnerPacketBuilder> PacketBuilder for InnerPacketBuilderWrapper<I> {
1639    fn constraints(&self) -> PacketConstraints {
1640        let Self(wrapped) = self;
1641        PacketConstraints::new(wrapped.bytes_len(), 0, 0, usize::MAX)
1642    }
1643
1644    fn serialize(&self, target: &mut SerializeTarget<'_>, _body: FragmentedBytesMut<'_, '_>) {
1645        let Self(wrapped) = self;
1646
1647        // Note that the body might be non-empty if an outer
1648        // PacketBuilder added a minimum body length constraint that
1649        // required padding.
1650        debug_assert_eq!(target.header.len(), wrapped.bytes_len());
1651        debug_assert_eq!(target.footer.len(), 0);
1652
1653        InnerPacketBuilder::serialize(wrapped, target.header);
1654    }
1655}
1656
1657impl<I: InnerPacketBuilder, B: GrowBuffer + ShrinkBuffer> Serializer for InnerSerializer<I, B> {
1658    type Buffer = B;
1659
1660    #[inline]
1661    fn serialize<BB: GrowBufferMut, P: BufferProvider<B, BB>>(
1662        self,
1663        outer: PacketConstraints,
1664        provider: P,
1665    ) -> Result<BB, (SerializeError<P::Error>, InnerSerializer<I, B>)> {
1666        debug_assert_eq!(self.buffer.len(), 0);
1667        InnerPacketBuilderWrapper(self.inner)
1668            .wrap_body(self.buffer)
1669            .serialize(outer, provider)
1670            .map_err(|(err, Nested { inner: buffer, outer: pb })| {
1671                (err, InnerSerializer { inner: pb.0, buffer })
1672            })
1673    }
1674
1675    #[inline]
1676    fn serialize_new_buf<BB: GrowBufferMut, A: LayoutBufferAlloc<BB>>(
1677        &self,
1678        outer: PacketConstraints,
1679        alloc: A,
1680    ) -> Result<BB, SerializeError<A::Error>> {
1681        InnerPacketBuilderWrapper(&self.inner).wrap_body(EmptyBuf).serialize_new_buf(outer, alloc)
1682    }
1683}
1684
1685impl<B: GrowBuffer + ShrinkBuffer> Serializer for B {
1686    type Buffer = B;
1687
1688    #[inline]
1689    fn serialize<BB: GrowBufferMut, P: BufferProvider<Self::Buffer, BB>>(
1690        self,
1691        outer: PacketConstraints,
1692        provider: P,
1693    ) -> Result<BB, (SerializeError<P::Error>, Self)> {
1694        TruncatingSerializer::new(self, TruncateDirection::NoTruncating)
1695            .serialize(outer, provider)
1696            .map_err(|(err, ser)| (err, ser.buffer))
1697    }
1698
1699    fn serialize_new_buf<BB: GrowBufferMut, A: LayoutBufferAlloc<BB>>(
1700        &self,
1701        outer: PacketConstraints,
1702        alloc: A,
1703    ) -> Result<BB, SerializeError<A::Error>> {
1704        if self.len() > outer.max_body_len() {
1705            return Err(SerializeError::SizeLimitExceeded);
1706        }
1707
1708        let padding = outer.min_body_len().saturating_sub(self.len());
1709        let tail_size = padding + outer.footer_len();
1710        let mut buffer = alloc.layout_alloc(outer.header_len(), self.len(), tail_size)?;
1711        buffer.copy_from(self);
1712        buffer.grow_back(padding);
1713        Ok(buffer)
1714    }
1715}
1716
1717/// Either of two serializers.
1718///
1719/// An `EitherSerializer` wraps one of two different serializer types.
1720pub enum EitherSerializer<A, B> {
1721    A(A),
1722    B(B),
1723}
1724
1725impl<A: Serializer, B: Serializer<Buffer = A::Buffer>> Serializer for EitherSerializer<A, B> {
1726    type Buffer = A::Buffer;
1727
1728    fn serialize<TB: GrowBufferMut, P: BufferProvider<Self::Buffer, TB>>(
1729        self,
1730        outer: PacketConstraints,
1731        provider: P,
1732    ) -> Result<TB, (SerializeError<P::Error>, Self)> {
1733        match self {
1734            EitherSerializer::A(s) => {
1735                s.serialize(outer, provider).map_err(|(err, s)| (err, EitherSerializer::A(s)))
1736            }
1737            EitherSerializer::B(s) => {
1738                s.serialize(outer, provider).map_err(|(err, s)| (err, EitherSerializer::B(s)))
1739            }
1740        }
1741    }
1742
1743    fn serialize_new_buf<TB: GrowBufferMut, BA: LayoutBufferAlloc<TB>>(
1744        &self,
1745        outer: PacketConstraints,
1746        alloc: BA,
1747    ) -> Result<TB, SerializeError<BA::Error>> {
1748        match self {
1749            EitherSerializer::A(s) => s.serialize_new_buf(outer, alloc),
1750            EitherSerializer::B(s) => s.serialize_new_buf(outer, alloc),
1751        }
1752    }
1753}
1754
1755/// The direction a buffer's body should be truncated from to force
1756/// it to fit within a size limit.
1757#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1758pub enum TruncateDirection {
1759    /// If a buffer cannot fit within a limit, discard bytes from the
1760    /// front of the body.
1761    DiscardFront,
1762    /// If a buffer cannot fit within a limit, discard bytes from the
1763    /// end of the body.
1764    DiscardBack,
1765    /// Do not attempt to truncate a buffer to make it fit within a limit.
1766    NoTruncating,
1767}
1768
1769/// A [`Serializer`] that truncates its body if it would exceed a size limit.
1770///
1771/// `TruncatingSerializer` wraps a buffer, and implements `Serializer`. Unlike
1772/// the blanket impl of `Serializer` for `B: GrowBuffer + ShrinkBuffer`, if the
1773/// buffer's body exceeds the size limit constraint passed to
1774/// `Serializer::serialize`, the body is truncated to fit.
1775///
1776/// Note that this does not guarantee that size limit exceeded errors will not
1777/// occur. The size limit may be small enough that the encapsulating headers
1778/// alone exceed the size limit.  There may also be a minimum body length
1779/// constraint which is larger than the size limit.
1780#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1781pub struct TruncatingSerializer<B> {
1782    buffer: B,
1783    direction: TruncateDirection,
1784}
1785
1786impl<B> TruncatingSerializer<B> {
1787    /// Constructs a new `TruncatingSerializer`.
1788    pub fn new(buffer: B, direction: TruncateDirection) -> TruncatingSerializer<B> {
1789        TruncatingSerializer { buffer, direction }
1790    }
1791
1792    /// Provides shared access to the inner buffer.
1793    pub fn buffer(&self) -> &B {
1794        &self.buffer
1795    }
1796
1797    /// Provides mutable access to the inner buffer.
1798    pub fn buffer_mut(&mut self) -> &mut B {
1799        &mut self.buffer
1800    }
1801}
1802
1803impl<B: GrowBuffer + ShrinkBuffer> Serializer for TruncatingSerializer<B> {
1804    type Buffer = B;
1805
1806    fn serialize<BB: GrowBufferMut, P: BufferProvider<B, BB>>(
1807        mut self,
1808        outer: PacketConstraints,
1809        provider: P,
1810    ) -> Result<BB, (SerializeError<P::Error>, Self)> {
1811        let original_len = self.buffer.len();
1812        let excess_bytes = if original_len > outer.max_body_len {
1813            Some(original_len - outer.max_body_len)
1814        } else {
1815            None
1816        };
1817        if let Some(excess_bytes) = excess_bytes {
1818            match self.direction {
1819                TruncateDirection::DiscardFront => self.buffer.shrink_front(excess_bytes),
1820                TruncateDirection::DiscardBack => self.buffer.shrink_back(excess_bytes),
1821                TruncateDirection::NoTruncating => {
1822                    return Err((SerializeError::SizeLimitExceeded, self));
1823                }
1824            }
1825        }
1826
1827        let padding = outer.min_body_len().saturating_sub(self.buffer.len());
1828
1829        // At this point, the body and padding MUST fit within the limit. Note
1830        // that PacketConstraints guarantees that min_body_len <= max_body_len,
1831        // so the padding can't cause this assertion to fail.
1832        debug_assert!(self.buffer.len() + padding <= outer.max_body_len());
1833        match provider.reuse_or_realloc(
1834            self.buffer,
1835            outer.header_len(),
1836            padding + outer.footer_len(),
1837        ) {
1838            Ok(buffer) => Ok(buffer),
1839            Err((err, mut buffer)) => {
1840                // Undo the effects of shrinking the buffer so that the buffer
1841                // we return is unmodified from its original (which is required
1842                // by the contract of this method).
1843                if let Some(excess_bytes) = excess_bytes {
1844                    match self.direction {
1845                        TruncateDirection::DiscardFront => buffer.grow_front(excess_bytes),
1846                        TruncateDirection::DiscardBack => buffer.grow_back(excess_bytes),
1847                        TruncateDirection::NoTruncating => unreachable!(),
1848                    }
1849                }
1850
1851                Err((
1852                    SerializeError::Alloc(err),
1853                    TruncatingSerializer { buffer, direction: self.direction },
1854                ))
1855            }
1856        }
1857    }
1858
1859    fn serialize_new_buf<BB: GrowBufferMut, A: LayoutBufferAlloc<BB>>(
1860        &self,
1861        outer: PacketConstraints,
1862        alloc: A,
1863    ) -> Result<BB, SerializeError<A::Error>> {
1864        let truncated_size = cmp::min(self.buffer.len(), outer.max_body_len());
1865        let discarded_bytes = self.buffer.len() - truncated_size;
1866        let padding = outer.min_body_len().saturating_sub(truncated_size);
1867        let tail_size = padding + outer.footer_len();
1868        let mut buffer = alloc.layout_alloc(outer.header_len(), truncated_size, tail_size)?;
1869        buffer.with_bytes_mut(|mut dst| {
1870            self.buffer.with_bytes(|src| {
1871                let src = match (discarded_bytes > 0, self.direction) {
1872                    (false, _) => src,
1873                    (true, TruncateDirection::DiscardFront) => src.slice(discarded_bytes..),
1874                    (true, TruncateDirection::DiscardBack) => src.slice(..truncated_size),
1875                    (true, TruncateDirection::NoTruncating) => {
1876                        return Err(SerializeError::SizeLimitExceeded);
1877                    }
1878                };
1879                dst.copy_from(&src);
1880                Ok(())
1881            })
1882        })?;
1883        buffer.grow_back_zero(padding);
1884        Ok(buffer)
1885    }
1886}
1887
1888impl<I: Serializer, O: PacketBuilder> Serializer for Nested<I, O> {
1889    type Buffer = I::Buffer;
1890
1891    #[inline]
1892    fn serialize<B: GrowBufferMut, P: BufferProvider<I::Buffer, B>>(
1893        self,
1894        outer: PacketConstraints,
1895        provider: P,
1896    ) -> Result<B, (SerializeError<P::Error>, Self)> {
1897        let Some(outer) = self.outer.constraints().try_encapsulate(&outer) else {
1898            return Err((SerializeError::SizeLimitExceeded, self));
1899        };
1900
1901        match self.inner.serialize(outer, provider) {
1902            Ok(mut buf) => {
1903                buf.serialize(&self.outer);
1904                Ok(buf)
1905            }
1906            Err((err, inner)) => Err((err, self.outer.wrap_body(inner))),
1907        }
1908    }
1909
1910    #[inline]
1911    fn serialize_new_buf<B: GrowBufferMut, A: LayoutBufferAlloc<B>>(
1912        &self,
1913        outer: PacketConstraints,
1914        alloc: A,
1915    ) -> Result<B, SerializeError<A::Error>> {
1916        let Some(outer) = self.outer.constraints().try_encapsulate(&outer) else {
1917            return Err(SerializeError::SizeLimitExceeded);
1918        };
1919
1920        let mut buf = self.inner.serialize_new_buf(outer, alloc)?;
1921        GrowBufferMut::serialize(&mut buf, &self.outer);
1922        Ok(buf)
1923    }
1924}
1925
1926/// A packet builder used for partial packet serialization.
1927pub trait PartialPacketBuilder: PacketBuilder {
1928    /// Serializes the header to the specified `buffer`.
1929    ///
1930    /// Checksums (if any) should not calculated. The corresponding fields
1931    /// should be set to 0.
1932    ///
1933    /// `body_len` specifies size of the packet body wrapped by this
1934    /// `PacketBuilder`. It is supplied so the correct packet size can be
1935    /// written in the header.
1936    fn partial_serialize(&self, body_len: usize, buffer: &mut [u8]);
1937}
1938
1939impl PartialPacketBuilder for () {
1940    fn partial_serialize(&self, _body_len: usize, _buffer: &mut [u8]) {}
1941}
1942
1943/// Result returned by `PartialSerializer::partial_serialize`.
1944#[derive(Debug, Eq, PartialEq)]
1945pub struct PartialSerializeResult {
1946    // Number of bytes written to the output buffer.
1947    pub bytes_written: usize,
1948
1949    // Size of the whole packet.
1950    pub total_size: usize,
1951}
1952
1953/// A serializer that supports partial serialization.
1954///
1955/// Partial serialization allows to serialize only packet headers without
1956/// calculating packet checksums (if any).
1957pub trait PartialSerializer {
1958    /// Serializes the head of the packet to the specified `buffer`.
1959    ///
1960    /// If the packet contains network or transport level headers that fit in
1961    /// the provided buffer then they will be serialized. Complete or partial
1962    /// body may be copied to the output buffer as well, depending on the
1963    /// serializer type.
1964    ///
1965    /// `PartialSerializeResult.bytes_written` indicates how many bytes were
1966    /// actually serialized.
1967    fn partial_serialize(
1968        &self,
1969        outer: PacketConstraints,
1970        buffer: &mut [u8],
1971    ) -> Result<PartialSerializeResult, SerializeError<Never>>;
1972}
1973
1974impl<B: GrowBuffer + ShrinkBuffer> PartialSerializer for B {
1975    fn partial_serialize(
1976        &self,
1977        _outer: PacketConstraints,
1978        _buffer: &mut [u8],
1979    ) -> Result<PartialSerializeResult, SerializeError<Never>> {
1980        Ok(PartialSerializeResult { bytes_written: 0, total_size: self.len() })
1981    }
1982}
1983
1984impl<B: GrowBuffer + ShrinkBuffer> PartialSerializer for TruncatingSerializer<B> {
1985    fn partial_serialize(
1986        &self,
1987        outer: PacketConstraints,
1988        _buffer: &mut [u8],
1989    ) -> Result<PartialSerializeResult, SerializeError<Never>> {
1990        let total_size =
1991            cmp::max(outer.min_body_len(), cmp::min(self.buffer().len(), outer.max_body_len()));
1992        Ok(PartialSerializeResult { bytes_written: 0, total_size })
1993    }
1994}
1995
1996impl<I: InnerPacketBuilder, B: GrowBuffer + ShrinkBuffer> PartialSerializer
1997    for InnerSerializer<I, B>
1998{
1999    fn partial_serialize(
2000        &self,
2001        outer: PacketConstraints,
2002        _buffer: &mut [u8],
2003    ) -> Result<PartialSerializeResult, SerializeError<Never>> {
2004        Ok(PartialSerializeResult {
2005            bytes_written: 0,
2006            total_size: cmp::max(self.inner().bytes_len(), outer.min_body_len()),
2007        })
2008    }
2009}
2010
2011impl<A: Serializer + PartialSerializer, B: Serializer + PartialSerializer> PartialSerializer
2012    for EitherSerializer<A, B>
2013{
2014    fn partial_serialize(
2015        &self,
2016        outer: PacketConstraints,
2017        buffer: &mut [u8],
2018    ) -> Result<PartialSerializeResult, SerializeError<Never>> {
2019        match self {
2020            EitherSerializer::A(s) => s.partial_serialize(outer, buffer),
2021            EitherSerializer::B(s) => s.partial_serialize(outer, buffer),
2022        }
2023    }
2024}
2025
2026impl<I: PartialSerializer, O: PartialPacketBuilder> PartialSerializer for Nested<I, O> {
2027    fn partial_serialize(
2028        &self,
2029        outer: PacketConstraints,
2030        buffer: &mut [u8],
2031    ) -> Result<PartialSerializeResult, SerializeError<Never>> {
2032        let header_constraints = self.outer.constraints();
2033        let Some(constraints) = outer.try_encapsulate(&header_constraints) else {
2034            return Err(SerializeError::SizeLimitExceeded);
2035        };
2036
2037        let header_len = header_constraints.header_len();
2038        let inner_buf = buffer.get_mut(header_len..).unwrap_or(&mut []);
2039        let mut result = self.inner.partial_serialize(constraints, inner_buf)?;
2040        if header_len <= buffer.len() {
2041            self.outer.partial_serialize(result.total_size, &mut buffer[..header_len]);
2042            result.bytes_written += header_len;
2043        }
2044        result.total_size += header_len + header_constraints.footer_len();
2045        Ok(result)
2046    }
2047}
2048
2049mod sealed {
2050    use super::*;
2051
2052    /// The inner workings of [`DynamicSerializer`].
2053    ///
2054    /// This trait is sealed because we don't want it to be implementable
2055    /// outside this crate or for its methods to be callable.
2056    pub trait DynamicSerializerInner {
2057        /// Serializes this serializer using a dyn borrow to an allocator.
2058        ///
2059        /// This method behaves much like [`Serializer::serialize_new_buf`], but
2060        /// with a specific shape allowing for dynamic dispatch.
2061        ///
2062        /// The target buffer is allocated via [`DynamicBufferAlloc`] and,
2063        /// instead of returning an owned buffer, it returns the total number of
2064        /// bytes in `prefix`, `suffix` that the buffer taken from the allocator
2065        /// _must have_ after having serialized this entity.
2066        fn serialize_dyn_alloc(
2067            &self,
2068            outer: PacketConstraints,
2069            alloc: &mut dyn DynamicBufferAlloc,
2070        ) -> Result<(usize, usize), SerializeError<DynAllocError>>;
2071    }
2072
2073    /// Type-erased allocator allowing dynamic serializers through
2074    /// [`DynamicSerializerInner`].
2075    ///
2076    /// This has roughly the same shape as [`LayoutBufferAlloc`], but with
2077    /// dynamic dispatch capabilities.
2078    pub trait DynamicBufferAlloc {
2079        /// Allocates a buffer with `prefix`, `body`, `suffix` bytes, like
2080        /// [`LayoutBufferAlloc::layout_alloc`].
2081        ///
2082        /// Note that the returned buffer has a tied lifetime to the allocator.
2083        /// The type erasure here is achieved by storing the buffer within the
2084        /// allocator itself, which can then be extracted to fulfill the
2085        /// `Serializer` trait. See the `Adapter` implementations supporting
2086        /// [`DynamicSerializerInner`] for details.
2087        ///
2088        /// This trait is sealed because we don't want it to be implementable
2089        /// outside this crate or for its methods to be callable.
2090        ///
2091        /// `alloc` may only be called once per instance of
2092        /// `DynamicBufferAlloc`. It reflects the single-use nature of
2093        /// [`LayoutBufferAlloc`], but methods taking `self` is not dyn
2094        /// compatible. Implementors may panic if called more than once on the
2095        /// same instance.
2096        fn alloc(
2097            &mut self,
2098            prefix: usize,
2099            body: usize,
2100            suffix: usize,
2101        ) -> Result<Buf<&mut [u8]>, DynAllocError>;
2102    }
2103
2104    /// The temporary errors returned by dynamic helpers in
2105    /// [`DynamicSerializerInner`] and [`DynamicBufferAlloc`].
2106    pub struct DynAllocError;
2107}
2108
2109use sealed::{DynAllocError, DynamicBufferAlloc, DynamicSerializerInner};
2110
2111fn dyn_serialize_new_buf<B: GrowBufferMut, A: LayoutBufferAlloc<B>>(
2112    serializer: &dyn DynamicSerializerInner,
2113    outer: PacketConstraints,
2114    alloc: A,
2115) -> Result<B, SerializeError<A::Error>> {
2116    enum Adapter<A: LayoutBufferAlloc<B>, B> {
2117        Empty,
2118        Alloc(A),
2119        Buffer(B),
2120        Error(A::Error),
2121    }
2122
2123    impl<A: LayoutBufferAlloc<B>, B: GrowBufferMut> DynamicBufferAlloc for Adapter<A, B> {
2124        fn alloc(
2125            &mut self,
2126            prefix: usize,
2127            body: usize,
2128            suffix: usize,
2129        ) -> Result<Buf<&mut [u8]>, DynAllocError> {
2130            let alloc = match core::mem::replace(self, Self::Empty) {
2131                Self::Alloc(a) => a,
2132                _ => panic!("unexpected alloc state"),
2133            };
2134
2135            let buffer = match alloc.layout_alloc(prefix, body, suffix) {
2136                Ok(b) => b,
2137                Err(e) => {
2138                    *self = Self::Error(e);
2139                    return Err(DynAllocError);
2140                }
2141            };
2142            *self = Self::Buffer(buffer);
2143            let buffer = match self {
2144                Self::Buffer(b) => b.with_all_contents_mut(|b| match b.try_into_contiguous() {
2145                    Ok(b) => b,
2146                    Err(_) => todo!(
2147                        "https://fxbug.dev/428952155: support dyn serialize fragmented buffers"
2148                    ),
2149                }),
2150                // We just set buffer above.
2151                _ => unreachable!(),
2152            };
2153            Ok(Buf::new(buffer, prefix..(buffer.len() - suffix)))
2154        }
2155    }
2156
2157    let mut adapter = Adapter::Alloc(alloc);
2158    let (prefix, suffix) = match serializer.serialize_dyn_alloc(outer, &mut adapter) {
2159        Ok(b) => b,
2160        Err(SerializeError::SizeLimitExceeded) => {
2161            return Err(SerializeError::SizeLimitExceeded);
2162        }
2163        Err(SerializeError::Alloc(DynAllocError)) => match adapter {
2164            Adapter::Error(e) => {
2165                return Err(SerializeError::Alloc(e));
2166            }
2167            _ => {
2168                unreachable!();
2169            }
2170        },
2171    };
2172
2173    let mut buffer = match adapter {
2174        Adapter::Buffer(b) => b,
2175        _ => unreachable!("unexpected alloc state"),
2176    };
2177    buffer.grow_front(buffer.prefix_len().checked_sub(prefix).unwrap_or_else(|| {
2178        panic!("failed to grow buffer front; want: {} got: {}", prefix, buffer.prefix_len())
2179    }));
2180    buffer.grow_back(buffer.suffix_len().checked_sub(suffix).unwrap_or_else(|| {
2181        panic!("failed to grow buffer back; want: {} got: {}", suffix, buffer.suffix_len())
2182    }));
2183    Ok(buffer)
2184}
2185
2186/// A type that provides [`Serializer`] via dynamic dispatch.
2187///
2188/// See discussion on [`DynamicSerializer`] for when dynamically dispatched
2189/// serializers can be beneficial.
2190#[derive(Copy, Clone)]
2191pub struct DynSerializer<'a>(&'a dyn DynamicSerializerInner);
2192
2193impl<'a> DynSerializer<'a> {
2194    /// Creates a new `DynSerializer` from a borrow to a concrete serializer.
2195    pub fn new<S: Serializer>(s: &'a S) -> Self {
2196        Self::new_dyn(s)
2197    }
2198
2199    /// Creates a new `DynSerializer` from a fat `DynamicSerializer` pointer.
2200    pub fn new_dyn(s: &'a dyn DynamicSerializer) -> Self {
2201        Self(s)
2202    }
2203}
2204
2205impl Serializer for DynSerializer<'_> {
2206    type Buffer = EmptyBuf;
2207
2208    fn serialize<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>(
2209        self,
2210        outer: PacketConstraints,
2211        provider: P,
2212    ) -> Result<B, (SerializeError<P::Error>, Self)> {
2213        struct Adapter<S, P>(P, PhantomData<S>);
2214
2215        impl<S, B, P> LayoutBufferAlloc<B> for Adapter<S, P>
2216        where
2217            P: BufferProvider<S, B>,
2218        {
2219            type Error = P::Error;
2220
2221            fn layout_alloc(
2222                self,
2223                prefix: usize,
2224                body: usize,
2225                suffix: usize,
2226            ) -> Result<B, Self::Error> {
2227                let Self(provider, PhantomData) = self;
2228                provider.alloc_no_reuse(prefix, body, suffix)
2229            }
2230        }
2231
2232        let Self(serializer) = self;
2233        match dyn_serialize_new_buf(serializer, outer, Adapter(provider, PhantomData)) {
2234            Ok(b) => Ok(b),
2235            Err(e) => Err((e, self)),
2236        }
2237    }
2238
2239    fn serialize_new_buf<B: GrowBufferMut, A: LayoutBufferAlloc<B>>(
2240        &self,
2241        outer: PacketConstraints,
2242        alloc: A,
2243    ) -> Result<B, SerializeError<A::Error>> {
2244        let Self(serializer) = self;
2245        dyn_serialize_new_buf(*serializer, outer, alloc)
2246    }
2247}
2248
2249impl<O> DynamicSerializerInner for O
2250where
2251    O: Serializer,
2252{
2253    fn serialize_dyn_alloc(
2254        &self,
2255        outer: PacketConstraints,
2256        alloc: &mut dyn DynamicBufferAlloc,
2257    ) -> Result<(usize, usize), SerializeError<DynAllocError>> {
2258        struct Adapter<'a>(&'a mut dyn DynamicBufferAlloc);
2259        impl<'a> LayoutBufferAlloc<Buf<&'a mut [u8]>> for Adapter<'a> {
2260            type Error = DynAllocError;
2261
2262            fn layout_alloc(
2263                self,
2264                prefix: usize,
2265                body: usize,
2266                suffix: usize,
2267            ) -> Result<Buf<&'a mut [u8]>, Self::Error> {
2268                let Self(inner) = self;
2269                inner.alloc(prefix, body, suffix)
2270            }
2271        }
2272        self.serialize_new_buf(outer, Adapter(alloc))
2273            .map(|buffer| (buffer.prefix_len(), buffer.suffix_len()))
2274    }
2275}
2276
2277/// A marker trait that is used as an attestation of dynamic serialization
2278/// capabilities.
2279///
2280/// Use [`DynSerializer`] to create instances of dynamic serializers.
2281///
2282/// # Discussion
2283///
2284/// If serializers are passed deep down the call stack, causing local
2285/// instantiation of multiple functions, it might be beneficial to consider
2286/// using a dynamically dispatched serializer instead. The hit taken during code
2287/// generation (and compilation times) might not be worth it, depending on the
2288/// task at hand. As an example, slow-path protocols might not derive much
2289/// benefit from deep compiler optimization which tips the scales in favor of
2290/// using a dynamically dispatched serializer instead.
2291pub trait DynamicSerializer: DynamicSerializerInner {}
2292impl<O> DynamicSerializer for O where O: DynamicSerializerInner {}
2293
2294#[cfg(test)]
2295mod tests {
2296    use super::*;
2297    use crate::BufferMut;
2298    use std::fmt::Debug;
2299    use test_case::test_case;
2300    use test_util::{assert_geq, assert_leq};
2301
2302    // DummyPacketBuilder:
2303    // - Implements PacketBuilder with the stored constraints; it fills the
2304    //   header with header_byte and the footer with footer_byte
2305    // - Implements InnerPacketBuilder by consuming a `header_len`-bytes body,
2306    //   and filling it with header_byte
2307    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
2308    struct DummyPacketBuilder {
2309        header_len: usize,
2310        footer_len: usize,
2311        min_body_len: usize,
2312        max_body_len: usize,
2313        header_byte: u8,
2314        footer_byte: u8,
2315    }
2316
2317    impl DummyPacketBuilder {
2318        fn new(
2319            header_len: usize,
2320            footer_len: usize,
2321            min_body_len: usize,
2322            max_body_len: usize,
2323        ) -> DummyPacketBuilder {
2324            DummyPacketBuilder {
2325                header_len,
2326                footer_len,
2327                min_body_len,
2328                max_body_len,
2329                header_byte: 0xFF,
2330                footer_byte: 0xFE,
2331            }
2332        }
2333    }
2334
2335    impl PacketBuilder for DummyPacketBuilder {
2336        fn constraints(&self) -> PacketConstraints {
2337            PacketConstraints::new(
2338                self.header_len,
2339                self.footer_len,
2340                self.min_body_len,
2341                self.max_body_len,
2342            )
2343        }
2344
2345        fn serialize(&self, target: &mut SerializeTarget<'_>, body: FragmentedBytesMut<'_, '_>) {
2346            assert_eq!(target.header.len(), self.header_len);
2347            assert_eq!(target.footer.len(), self.footer_len);
2348            assert!(body.len() >= self.min_body_len);
2349            assert!(body.len() <= self.max_body_len);
2350            target.header.fill(self.header_byte);
2351            target.footer.fill(self.footer_byte);
2352        }
2353    }
2354
2355    impl PartialPacketBuilder for DummyPacketBuilder {
2356        fn partial_serialize(&self, _body_len: usize, buffer: &mut [u8]) {
2357            buffer.fill(self.header_byte)
2358        }
2359    }
2360
2361    impl InnerPacketBuilder for DummyPacketBuilder {
2362        fn bytes_len(&self) -> usize {
2363            self.header_len
2364        }
2365
2366        fn serialize(&self, buffer: &mut [u8]) {
2367            assert_eq!(buffer.len(), self.header_len);
2368            buffer.fill(self.header_byte);
2369        }
2370    }
2371
2372    // Helper for `VerifyingSerializer` used to verify the serialization result.
2373    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
2374    struct SerializerVerifier {
2375        // Total size if the inner body if not truncated or `None` if
2376        // serialization is expected to fail due to size limit.
2377        inner_len: Option<usize>,
2378
2379        // Is the inner Serializer truncating (a TruncatingSerializer with
2380        // TruncateDirection::DiscardFront or DiscardBack)?
2381        truncating: bool,
2382    }
2383
2384    impl SerializerVerifier {
2385        fn new<S: Serializer>(serializer: &S, truncating: bool) -> Self {
2386            let inner_len = serializer
2387                .serialize_new_buf(PacketConstraints::UNCONSTRAINED, new_buf_vec)
2388                .map(|buf| buf.len())
2389                .inspect_err(|err| assert!(err.is_size_limit_exceeded()))
2390                .ok();
2391            Self { inner_len, truncating }
2392        }
2393
2394        fn verify_result<B: GrowBufferMut, A>(
2395            &self,
2396            result: Result<&B, &SerializeError<A>>,
2397            outer: PacketConstraints,
2398        ) {
2399            let should_exceed_size_limit = match self.inner_len {
2400                Some(inner_len) => outer.max_body_len() < inner_len && !self.truncating,
2401                None => true,
2402            };
2403
2404            match result {
2405                Ok(buf) => {
2406                    assert_geq!(buf.prefix_len(), outer.header_len());
2407                    assert_geq!(buf.suffix_len(), outer.footer_len());
2408                    assert_leq!(buf.len(), outer.max_body_len());
2409
2410                    // It is `Serialize::serialize()`'s responsibility to ensure that there
2411                    // is enough suffix room to fit any post-body padding and the footer,
2412                    // but it is the caller's responsibility to actually add that padding
2413                    // (ie, move it from the suffix to the body).
2414                    let padding = outer.min_body_len().saturating_sub(buf.len());
2415                    assert_leq!(padding + outer.footer_len(), buf.suffix_len());
2416
2417                    assert!(!should_exceed_size_limit);
2418                }
2419                Err(err) => {
2420                    // If we shouldn't fail as a result of a size limit exceeded
2421                    // error, we might still fail as a result of allocation.
2422                    if should_exceed_size_limit {
2423                        assert!(err.is_size_limit_exceeded());
2424                    } else {
2425                        assert!(err.is_alloc());
2426                    }
2427                }
2428            }
2429        }
2430    }
2431
2432    // A Serializer that verifies certain invariants while operating. In
2433    // particular:
2434    // - If serialization fails, the original Serializer is returned unmodified.
2435    // - If `outer.try_constraints()` returns `None`, serialization fails.
2436    // - If the size limit is exceeded and truncation is disabled, serialization
2437    //   fails.
2438    // - If serialization succeeds, the body has the correct length, including
2439    //   taking into account `outer`'s minimum body length requirement
2440    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
2441    struct VerifyingSerializer<S> {
2442        ser: S,
2443        verifier: SerializerVerifier,
2444    }
2445
2446    impl<S: Serializer + Debug + Clone + Eq> Serializer for VerifyingSerializer<S>
2447    where
2448        S::Buffer: ReusableBuffer,
2449    {
2450        type Buffer = S::Buffer;
2451
2452        fn serialize<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>(
2453            self,
2454            outer: PacketConstraints,
2455            provider: P,
2456        ) -> Result<B, (SerializeError<P::Error>, Self)> {
2457            let Self { ser, verifier } = self;
2458            let orig = ser.clone();
2459
2460            let result = ser.serialize(outer, provider).map_err(|(err, ser)| {
2461                // If serialization fails, the original Serializer should be
2462                // unmodified.
2463                assert_eq!(ser, orig);
2464                (err, Self { ser, verifier })
2465            });
2466
2467            verifier.verify_result(result.as_ref().map_err(|(err, _ser)| err), outer);
2468
2469            result
2470        }
2471
2472        fn serialize_new_buf<B: GrowBufferMut, A: LayoutBufferAlloc<B>>(
2473            &self,
2474            outer: PacketConstraints,
2475            alloc: A,
2476        ) -> Result<B, SerializeError<A::Error>> {
2477            let res = self.ser.serialize_new_buf(outer, alloc);
2478            self.verifier.verify_result(res.as_ref(), outer);
2479            res
2480        }
2481    }
2482
2483    trait SerializerExt: Serializer {
2484        fn into_verifying(self, truncating: bool) -> VerifyingSerializer<Self>
2485        where
2486            Self::Buffer: ReusableBuffer,
2487        {
2488            let verifier = SerializerVerifier::new(&self, truncating);
2489            VerifyingSerializer { ser: self, verifier }
2490        }
2491
2492        fn wrap_in_verifying<B: PacketBuilder>(
2493            self,
2494            outer: B,
2495            truncating: bool,
2496        ) -> VerifyingSerializer<Nested<Self, B>>
2497        where
2498            Self::Buffer: ReusableBuffer,
2499        {
2500            self.wrap_in(outer).into_verifying(truncating)
2501        }
2502
2503        fn with_size_limit_verifying(
2504            self,
2505            limit: usize,
2506            truncating: bool,
2507        ) -> VerifyingSerializer<Nested<Self, LimitedSizePacketBuilder>>
2508        where
2509            Self::Buffer: ReusableBuffer,
2510        {
2511            self.with_size_limit(limit).into_verifying(truncating)
2512        }
2513    }
2514
2515    impl<S: Serializer> SerializerExt for S {}
2516
2517    #[test]
2518    fn test_either_into_inner() {
2519        fn ret_either(a: u32, b: u32, c: bool) -> Either<u32, u32> {
2520            if c { Either::A(a) } else { Either::B(b) }
2521        }
2522
2523        assert_eq!(ret_either(1, 2, true).into_inner(), 1);
2524        assert_eq!(ret_either(1, 2, false).into_inner(), 2);
2525    }
2526
2527    #[test]
2528    fn test_either_unwrap_success() {
2529        assert_eq!(Either::<u16, u32>::A(5).unwrap_a(), 5);
2530        assert_eq!(Either::<u16, u32>::B(10).unwrap_b(), 10);
2531    }
2532
2533    #[test]
2534    #[should_panic]
2535    fn test_either_unwrap_a_panic() {
2536        let _: u16 = Either::<u16, u32>::B(10).unwrap_a();
2537    }
2538
2539    #[test]
2540    #[should_panic]
2541    fn test_either_unwrap_b_panic() {
2542        let _: u32 = Either::<u16, u32>::A(5).unwrap_b();
2543    }
2544
2545    #[test_case(Buf::new((0..100).collect(), ..); "entire buf")]
2546    #[test_case(Buf::new((0..100).collect(), 0..0); "empty range")]
2547    #[test_case(Buf::new((0..100).collect(), ..50); "prefix")]
2548    #[test_case(Buf::new((0..100).collect(), 50..); "suffix")]
2549    #[test_case(Buf::new((0..100).collect(), 25..75); "middle")]
2550    fn test_buf_into_inner(buf: Buf<Vec<u8>>) {
2551        assert_eq!(buf.clone().as_ref(), buf.into_inner());
2552    }
2553
2554    #[test]
2555    fn test_packet_constraints() {
2556        use PacketConstraints as PC;
2557
2558        // Test try_new
2559
2560        // Sanity check.
2561        assert!(PC::try_new(0, 0, 0, 0).is_some());
2562        // header_len + min_body_len + footer_len doesn't overflow usize
2563        assert!(PC::try_new(usize::MAX / 2, usize::MAX / 2, 0, 0).is_some());
2564        // header_len + min_body_len + footer_len overflows usize
2565        assert_eq!(PC::try_new(usize::MAX, 1, 0, 0), None);
2566        // min_body_len > max_body_len
2567        assert_eq!(PC::try_new(0, 0, 1, 0), None);
2568
2569        // Test PacketConstraints::try_encapsulate
2570
2571        // Sanity check.
2572        let pc = PC::new(10, 10, 0, usize::MAX);
2573        assert_eq!(pc.try_encapsulate(&pc).unwrap(), PC::new(20, 20, 0, usize::MAX - 20));
2574
2575        let pc = PC::new(10, 10, 0, usize::MAX);
2576        assert_eq!(pc.try_encapsulate(&pc).unwrap(), PC::new(20, 20, 0, usize::MAX - 20));
2577
2578        // Starting here, each failure test case corresponds to one check in
2579        // either PacketConstraints::try_encapsulate or PacketConstraints::new
2580        // (which is called from PacketConstraints::try_encapsulate). Each test
2581        // case is labeled "Test case N", and a corresponding comment in either
2582        // of those two functions identifies which line is being tested.
2583
2584        // The outer PC's minimum body length requirement of 10 is more than
2585        // satisfied by the inner PC's combined 20 bytes of header and footer.
2586        // The resulting PC has its minimum body length requirement saturated to
2587        // 0.
2588        let inner = PC::new(10, 10, 0, usize::MAX);
2589        let outer = PC::new(0, 0, 10, usize::MAX);
2590        assert_eq!(inner.try_encapsulate(&outer).unwrap(), PC::new(10, 10, 0, usize::MAX - 20));
2591
2592        // Test case 1
2593        //
2594        // The sum of the inner and outer header lengths overflows `usize`.
2595        let inner = PC::new(usize::MAX, 0, 0, usize::MAX);
2596        let outer = PC::new(1, 0, 0, usize::MAX);
2597        assert_eq!(inner.try_encapsulate(&outer), None);
2598
2599        // Test case 2
2600        //
2601        // The sum of the inner and outer footer lengths overflows `usize`.
2602        let inner = PC::new(0, usize::MAX, 0, usize::MAX);
2603        let outer = PC::new(0, 1, 0, usize::MAX);
2604        assert_eq!(inner.try_encapsulate(&outer), None);
2605
2606        // Test case 3
2607        //
2608        // The sum of the resulting header, footer, and minimum body lengths
2609        // overflows `usize`. We use usize::MAX / 5 + 1 as the constant so that
2610        // none of the intermediate additions overflow, so we make sure to test
2611        // that an overflow in the final addition will be caught.
2612        let one_fifth_max = (usize::MAX / 5) + 1;
2613        let inner = PC::new(one_fifth_max, one_fifth_max, one_fifth_max, usize::MAX);
2614        let outer = PC::new(one_fifth_max, one_fifth_max, 0, usize::MAX);
2615        assert_eq!(inner.try_encapsulate(&outer), None);
2616
2617        // Test case 4
2618        //
2619        // The header and footer of the inner PC exceed the maximum body length
2620        // requirement of the outer PC.
2621        let inner = PC::new(10, 10, 0, usize::MAX);
2622        let outer = PC::new(0, 0, 0, 10);
2623        assert_eq!(inner.try_encapsulate(&outer), None);
2624
2625        // Test case 5
2626        //
2627        // The resulting minimum body length (thanks to the inner
2628        // PacketBuilder's minimum body length) is larger than the resulting
2629        // maximum body length.
2630        let inner = PC::new(0, 0, 10, usize::MAX);
2631        let outer = PC::new(0, 0, 0, 5);
2632        assert_eq!(inner.try_encapsulate(&outer), None);
2633    }
2634
2635    #[test]
2636    fn test_inner_serializer() {
2637        const INNER: &[u8] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
2638
2639        fn concat<'a, I: IntoIterator<Item = &'a &'a [u8]>>(slices: I) -> Vec<u8> {
2640            let mut v = Vec::new();
2641            for slc in slices.into_iter() {
2642                v.extend_from_slice(slc);
2643            }
2644            v
2645        }
2646
2647        // Sanity check.
2648        let buf = INNER.into_serializer().serialize_vec_outer().unwrap();
2649        assert_eq!(buf.as_ref(), INNER);
2650
2651        // A larger minimum body length requirement will cause padding to be
2652        // added.
2653        let buf = INNER
2654            .into_serializer()
2655            .into_verifying(false)
2656            .wrap_in(DummyPacketBuilder::new(0, 0, 20, usize::MAX))
2657            .serialize_vec_outer()
2658            .unwrap();
2659        assert_eq!(buf.as_ref(), concat(&[INNER, vec![0; 10].as_ref()]).as_slice());
2660
2661        // Headers and footers are added as appropriate (note that
2662        // DummyPacketBuilder fills its header with 0xFF and its footer with
2663        // 0xFE).
2664        let buf = INNER
2665            .into_serializer()
2666            .into_verifying(false)
2667            .wrap_in(DummyPacketBuilder::new(10, 10, 0, usize::MAX))
2668            .serialize_vec_outer()
2669            .unwrap();
2670        assert_eq!(
2671            buf.as_ref(),
2672            concat(&[vec![0xFF; 10].as_ref(), INNER, vec![0xFE; 10].as_ref()]).as_slice()
2673        );
2674
2675        // An exceeded maximum body size is rejected.
2676        assert_eq!(
2677            INNER
2678                .into_serializer()
2679                .into_verifying(false)
2680                .wrap_in(DummyPacketBuilder::new(0, 0, 0, 9))
2681                .serialize_vec_outer()
2682                .unwrap_err()
2683                .0,
2684            SerializeError::SizeLimitExceeded
2685        );
2686
2687        // `into_serializer_with` truncates the buffer's body to zero before
2688        // returning, so those body bytes are not included in the serialized
2689        // output.
2690        assert_eq!(
2691            INNER
2692                .into_serializer_with(Buf::new(vec![0xFF], ..))
2693                .into_verifying(false)
2694                .serialize_vec_outer()
2695                .unwrap()
2696                .as_ref(),
2697            INNER
2698        );
2699    }
2700
2701    #[test]
2702    fn test_buffer_serializer_and_inner_serializer() {
2703        fn verify_buffer_serializer<B: BufferMut + Debug>(
2704            buffer: B,
2705            header_len: usize,
2706            footer_len: usize,
2707            min_body_len: usize,
2708        ) {
2709            let old_body = buffer.to_flattened_vec();
2710            let serializer =
2711                DummyPacketBuilder::new(header_len, footer_len, min_body_len, usize::MAX)
2712                    .wrap_body(buffer);
2713
2714            let buffer0 = serializer
2715                .serialize_new_buf(PacketConstraints::UNCONSTRAINED, new_buf_vec)
2716                .unwrap();
2717            verify(buffer0, &old_body, header_len, footer_len, min_body_len);
2718
2719            let buffer = serializer.serialize_vec_outer().unwrap();
2720            verify(buffer, &old_body, header_len, footer_len, min_body_len);
2721        }
2722
2723        fn verify_inner_packet_builder_serializer(
2724            body: &[u8],
2725            header_len: usize,
2726            footer_len: usize,
2727            min_body_len: usize,
2728        ) {
2729            let buffer = DummyPacketBuilder::new(header_len, footer_len, min_body_len, usize::MAX)
2730                .wrap_body(body.into_serializer())
2731                .serialize_vec_outer()
2732                .unwrap();
2733            verify(buffer, body, header_len, footer_len, min_body_len);
2734        }
2735
2736        fn verify<B: Buffer>(
2737            buffer: B,
2738            body: &[u8],
2739            header_len: usize,
2740            footer_len: usize,
2741            min_body_len: usize,
2742        ) {
2743            let flat = buffer.to_flattened_vec();
2744            let header_bytes = &flat[..header_len];
2745            let body_bytes = &flat[header_len..header_len + body.len()];
2746            let padding_len = min_body_len.saturating_sub(body.len());
2747            let padding_bytes =
2748                &flat[header_len + body.len()..header_len + body.len() + padding_len];
2749            let total_body_len = body.len() + padding_len;
2750            let footer_bytes = &flat[header_len + total_body_len..];
2751            assert_eq!(
2752                buffer.len() - total_body_len,
2753                header_len + footer_len,
2754                "buffer.len()({}) - total_body_len({}) != header_len({}) + footer_len({})",
2755                buffer.len(),
2756                header_len,
2757                footer_len,
2758                min_body_len,
2759            );
2760
2761            // DummyPacketBuilder fills its header with 0xFF
2762            assert!(
2763                header_bytes.iter().all(|b| *b == 0xFF),
2764                "header_bytes {:?} are not filled with 0xFF's",
2765                header_bytes,
2766            );
2767            assert_eq!(body_bytes, body);
2768            // Padding bytes must be initialized to zero
2769            assert!(
2770                padding_bytes.iter().all(|b| *b == 0),
2771                "padding_bytes {:?} are not filled with 0s",
2772                padding_bytes,
2773            );
2774            // DummyPacketBuilder fills its footer with 0xFE
2775            assert!(
2776                footer_bytes.iter().all(|b| *b == 0xFE),
2777                "footer_bytes {:?} are not filled with 0xFE's",
2778                footer_bytes,
2779            );
2780        }
2781
2782        // Test for every valid combination of buf_len, range_start, range_end,
2783        // prefix, suffix, and min_body within [0, 8).
2784        for buf_len in 0..8 {
2785            for range_start in 0..buf_len {
2786                for range_end in range_start..buf_len {
2787                    for prefix in 0..8 {
2788                        for suffix in 0..8 {
2789                            for min_body in 0..8 {
2790                                let mut vec = vec![0; buf_len];
2791                                // Initialize the vector with values 0, 1, 2,
2792                                // ... so that we can check to make sure that
2793                                // the range bytes have been properly copied if
2794                                // the buffer is reallocated.
2795                                #[allow(clippy::needless_range_loop)]
2796                                for i in 0..vec.len() {
2797                                    vec[i] = i as u8;
2798                                }
2799                                verify_buffer_serializer(
2800                                    Buf::new(vec.as_mut_slice(), range_start..range_end),
2801                                    prefix,
2802                                    suffix,
2803                                    min_body,
2804                                );
2805                                if range_start == 0 {
2806                                    // Unlike verify_buffer_serializer, this
2807                                    // test doesn't make use of the prefix or
2808                                    // suffix. In order to avoid running the
2809                                    // exact same test multiple times, we only
2810                                    // run this when `range_start == 0`, which
2811                                    // has the effect of reducing the number of
2812                                    // times that this test is run by roughly a
2813                                    // factor of 8.
2814                                    verify_inner_packet_builder_serializer(
2815                                        &vec.as_slice()[range_start..range_end],
2816                                        prefix,
2817                                        suffix,
2818                                        min_body,
2819                                    );
2820                                }
2821                            }
2822                        }
2823                    }
2824                }
2825            }
2826        }
2827    }
2828
2829    #[test]
2830    fn test_min_body_len() {
2831        // Test that padding is added after the body of the packet whose minimum
2832        // body length constraint requires it. A previous version of this code
2833        // had a bug where padding was always added after the innermost body.
2834
2835        let body = &[1, 2];
2836
2837        // 4 bytes of header and footer for a total of 6 bytes (including the
2838        // body).
2839        let inner = DummyPacketBuilder::new(2, 2, 0, usize::MAX);
2840        // Minimum body length of 8 will require 2 bytes of padding.
2841        let outer = DummyPacketBuilder::new(2, 2, 8, usize::MAX);
2842        let buf = body
2843            .into_serializer()
2844            .into_verifying(false)
2845            .wrap_in_verifying(inner, false)
2846            .wrap_in_verifying(outer, false)
2847            .serialize_vec_outer()
2848            .unwrap();
2849        assert_eq!(buf.prefix_len(), 0);
2850        assert_eq!(buf.suffix_len(), 0);
2851        assert_eq!(
2852            buf.as_ref(),
2853            &[
2854                0xFF, 0xFF, // Outer header
2855                0xFF, 0xFF, // Inner header
2856                1, 2, // Inner body
2857                0xFE, 0xFE, // Inner footer
2858                0, 0, // Padding to satisfy outer minimum body length requirement
2859                0xFE, 0xFE // Outer footer
2860            ]
2861        );
2862    }
2863
2864    #[test]
2865    fn test_size_limit() {
2866        // ser is a Serializer that will consume 1 byte of buffer space
2867        fn test<S: Serializer + Clone + Debug + Eq>(ser: S)
2868        where
2869            S::Buffer: ReusableBuffer,
2870        {
2871            // Each of these tests encapsulates ser in a DummyPacketBuilder
2872            // which consumes 1 byte for the header and one byte for the footer.
2873            // Thus, the inner serializer will consume 1 byte, while the
2874            // DummyPacketBuilder will consume 2 bytes, for a total of 3 bytes.
2875
2876            let pb = DummyPacketBuilder::new(1, 1, 0, usize::MAX);
2877
2878            // Test that a size limit of 3 is OK. Note that this is an important
2879            // test since it tests the case when the size limit is exactly
2880            // sufficient. A previous version of this code had a bug where a
2881            // packet which fit the size limit exactly would be rejected.
2882            assert!(
2883                ser.clone()
2884                    .wrap_in_verifying(pb, false)
2885                    .with_size_limit_verifying(3, false)
2886                    .serialize_vec_outer()
2887                    .is_ok()
2888            );
2889            // Test that a more-than-large-enough size limit of 4 is OK.
2890            assert!(
2891                ser.clone()
2892                    .wrap_in_verifying(pb, false)
2893                    .with_size_limit_verifying(4, false)
2894                    .serialize_vec_outer()
2895                    .is_ok()
2896            );
2897            // Test that the inner size limit of 1 only applies to the inner
2898            // serializer, and so is still OK even though the outer serializer
2899            // consumes 3 bytes total.
2900            assert!(
2901                ser.clone()
2902                    .with_size_limit_verifying(1, false)
2903                    .wrap_in_verifying(pb, false)
2904                    .with_size_limit_verifying(3, false)
2905                    .serialize_vec_outer()
2906                    .is_ok()
2907            );
2908            // Test that the inner size limit of 0 is exceeded by the inner
2909            // serializer's 1 byte length.
2910            assert!(
2911                ser.clone()
2912                    .with_size_limit_verifying(0, false)
2913                    .wrap_in_verifying(pb, false)
2914                    .serialize_vec_outer()
2915                    .is_err()
2916            );
2917            // Test that a size limit which would be exceeded by the
2918            // encapsulating layer is rejected by Nested's implementation. If
2919            // this doesn't work properly, then the size limit should underflow,
2920            // resulting in a panic (see the Nested implementation of
2921            // Serialize).
2922            assert!(
2923                ser.clone()
2924                    .wrap_in_verifying(pb, false)
2925                    .with_size_limit_verifying(1, false)
2926                    .serialize_vec_outer()
2927                    .is_err()
2928            );
2929        }
2930
2931        // We use this as an InnerPacketBuilder which consumes 1 byte of body.
2932        test(DummyPacketBuilder::new(1, 0, 0, usize::MAX).into_serializer().into_verifying(false));
2933        test(Buf::new(vec![0], ..).into_verifying(false));
2934    }
2935
2936    #[test]
2937    fn test_truncating_serializer() {
2938        fn verify_result<S: Serializer + Debug>(ser: S, expected: &[u8])
2939        where
2940            S::Buffer: ReusableBuffer + AsRef<[u8]>,
2941        {
2942            let buf = ser.serialize_new_buf(PacketConstraints::UNCONSTRAINED, new_buf_vec).unwrap();
2943            assert_eq!(buf.as_ref(), &expected[..]);
2944            let buf = ser.serialize_vec_outer().unwrap();
2945            assert_eq!(buf.as_ref(), &expected[..]);
2946        }
2947
2948        // Test truncate front.
2949        let body = vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
2950        let ser =
2951            TruncatingSerializer::new(Buf::new(body.clone(), ..), TruncateDirection::DiscardFront)
2952                .into_verifying(true)
2953                .with_size_limit_verifying(4, true);
2954        verify_result(ser, &[6, 7, 8, 9]);
2955
2956        // Test truncate back.
2957        let ser =
2958            TruncatingSerializer::new(Buf::new(body.clone(), ..), TruncateDirection::DiscardBack)
2959                .into_verifying(true)
2960                .with_size_limit_verifying(7, true);
2961        verify_result(ser, &[0, 1, 2, 3, 4, 5, 6]);
2962
2963        // Test no truncating (default/original case).
2964        let ser =
2965            TruncatingSerializer::new(Buf::new(body.clone(), ..), TruncateDirection::NoTruncating)
2966                .into_verifying(false)
2967                .with_size_limit_verifying(5, true);
2968        assert!(ser.clone().serialize_vec_outer().is_err());
2969        assert!(ser.serialize_new_buf(PacketConstraints::UNCONSTRAINED, new_buf_vec).is_err());
2970        assert!(ser.serialize_vec_outer().is_err());
2971
2972        // Test that, when serialization fails, any truncation is undone.
2973
2974        // `ser` has a body of `[1, 2]` and no prefix or suffix
2975        fn test_serialization_failure<S: Serializer + Clone + Eq + Debug>(
2976            ser: S,
2977            err: SerializeError<BufferTooShortError>,
2978        ) where
2979            S::Buffer: ReusableBuffer + Debug,
2980        {
2981            // Serialize with a PacketBuilder with a size limit of 1 so that the
2982            // body (of length 2) is too large. If `ser` is configured not to
2983            // truncate, it should result in a size limit error. If it is
2984            // configured to truncate, the 2 + 2 = 4 combined bytes of header
2985            // and footer will cause allocating a new buffer to fail, and it
2986            // should result in an allocation failure. Even if the body was
2987            // truncated, it should be returned to its original un-truncated
2988            // state before being returned from `serialize`.
2989            let (e, new_ser) = DummyPacketBuilder::new(2, 2, 0, 1)
2990                .wrap_body(ser.clone())
2991                .serialize_no_alloc_outer()
2992                .unwrap_err();
2993            assert_eq!(err, e);
2994            assert_eq!(new_ser.into_inner(), ser);
2995        }
2996
2997        let body = Buf::new(vec![1, 2], ..);
2998        test_serialization_failure(
2999            TruncatingSerializer::new(body.clone(), TruncateDirection::DiscardFront)
3000                .into_verifying(true),
3001            SerializeError::Alloc(BufferTooShortError),
3002        );
3003        test_serialization_failure(
3004            TruncatingSerializer::new(body.clone(), TruncateDirection::DiscardFront)
3005                .into_verifying(true),
3006            SerializeError::Alloc(BufferTooShortError),
3007        );
3008        test_serialization_failure(
3009            TruncatingSerializer::new(body.clone(), TruncateDirection::NoTruncating)
3010                .into_verifying(false),
3011            SerializeError::SizeLimitExceeded,
3012        );
3013    }
3014
3015    #[test]
3016    fn test_try_reuse_buffer() {
3017        fn test_expect_success(
3018            body_range: Range<usize>,
3019            prefix: usize,
3020            suffix: usize,
3021            max_copy_bytes: usize,
3022        ) {
3023            let mut bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
3024            let buffer = Buf::new(&mut bytes[..], body_range);
3025            let body = buffer.as_ref().to_vec();
3026            let buffer = try_reuse_buffer(buffer, prefix, suffix, max_copy_bytes).unwrap();
3027            assert_eq!(buffer.as_ref(), body.as_slice());
3028            assert!(buffer.prefix_len() >= prefix);
3029            assert!(buffer.suffix_len() >= suffix);
3030        }
3031
3032        fn test_expect_failure(
3033            body_range: Range<usize>,
3034            prefix: usize,
3035            suffix: usize,
3036            max_copy_bytes: usize,
3037        ) {
3038            let mut bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
3039            let buffer = Buf::new(&mut bytes[..], body_range.clone());
3040            let mut bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
3041            let orig = Buf::new(&mut bytes[..], body_range.clone());
3042            let buffer = try_reuse_buffer(buffer, prefix, suffix, max_copy_bytes).unwrap_err();
3043            assert_eq!(buffer, orig);
3044        }
3045
3046        // No prefix or suffix trivially succeeds.
3047        test_expect_success(0..10, 0, 0, 0);
3048        // If we have enough prefix/suffix, it succeeds.
3049        test_expect_success(1..9, 1, 1, 0);
3050        // If we don't have enough prefix/suffix, but we have enough capacity to
3051        // move the buffer within the body, it succeeds...
3052        test_expect_success(0..9, 1, 0, 9);
3053        test_expect_success(1..10, 0, 1, 9);
3054        // ...but if we don't provide a large enough max_copy_bytes, it will fail.
3055        test_expect_failure(0..9, 1, 0, 8);
3056        test_expect_failure(1..10, 0, 1, 8);
3057    }
3058
3059    #[test]
3060    fn test_maybe_reuse_buffer_provider() {
3061        fn test_expect(body_range: Range<usize>, prefix: usize, suffix: usize, expect_a: bool) {
3062            let mut bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
3063            let buffer = Buf::new(&mut bytes[..], body_range);
3064            let body = buffer.as_ref().to_vec();
3065            let buffer = BufferProvider::reuse_or_realloc(
3066                MaybeReuseBufferProvider(new_buf_vec),
3067                buffer,
3068                prefix,
3069                suffix,
3070            )
3071            .unwrap();
3072            match &buffer {
3073                Either::A(_) if expect_a => {}
3074                Either::B(_) if !expect_a => {}
3075                Either::A(_) => panic!("expected Eitehr::B variant"),
3076                Either::B(_) => panic!("expected Eitehr::A variant"),
3077            }
3078            let bytes: &[u8] = buffer.as_ref();
3079            assert_eq!(bytes, body.as_slice());
3080            assert!(buffer.prefix_len() >= prefix);
3081            assert!(buffer.suffix_len() >= suffix);
3082        }
3083
3084        // Expect that we'll be able to reuse the existing buffer.
3085        fn test_expect_reuse(body_range: Range<usize>, prefix: usize, suffix: usize) {
3086            test_expect(body_range, prefix, suffix, true);
3087        }
3088
3089        // Expect that we'll need to allocate a new buffer.
3090        fn test_expect_realloc(body_range: Range<usize>, prefix: usize, suffix: usize) {
3091            test_expect(body_range, prefix, suffix, false);
3092        }
3093
3094        // No prefix or suffix trivially succeeds.
3095        test_expect_reuse(0..10, 0, 0);
3096        // If we have enough prefix/suffix, it succeeds.
3097        test_expect_reuse(1..9, 1, 1);
3098        // If we don't have enough prefix/suffix, but we have enough capacity to
3099        // move the buffer within the body, it succeeds.
3100        test_expect_reuse(0..9, 1, 0);
3101        test_expect_reuse(1..10, 0, 1);
3102        // If we don't have enough capacity, it fails and must realloc.
3103        test_expect_realloc(0..9, 1, 1);
3104        test_expect_realloc(1..10, 1, 1);
3105    }
3106
3107    #[test]
3108    fn test_no_reuse_buffer_provider() {
3109        #[track_caller]
3110        fn test_expect(body_range: Range<usize>, prefix: usize, suffix: usize) {
3111            let mut bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
3112            // The buffer that will not be reused.
3113            let internal_buffer: Buf<&mut [u8]> = Buf::new(&mut bytes[..], body_range);
3114            let body = internal_buffer.as_ref().to_vec();
3115            // The newly allocated buffer, note the type is different from
3116            // internal_buffer.
3117            let buffer: Buf<Vec<u8>> = BufferProvider::reuse_or_realloc(
3118                NoReuseBufferProvider(new_buf_vec),
3119                internal_buffer,
3120                prefix,
3121                suffix,
3122            )
3123            .unwrap();
3124            let bytes: &[u8] = buffer.as_ref();
3125            assert_eq!(bytes, body.as_slice());
3126            assert_eq!(buffer.prefix_len(), prefix);
3127            assert_eq!(buffer.suffix_len(), suffix);
3128        }
3129        // No prefix or suffix trivially succeeds, reuse opportunity is ignored.
3130        test_expect(0..10, 0, 0);
3131        // If we have enough prefix/suffix, reuse opportunity is ignored.
3132        test_expect(1..9, 1, 1);
3133        // Prefix and suffix and properly allocated and the body is copied.
3134        test_expect(0..9, 10, 10);
3135        test_expect(1..10, 15, 15);
3136    }
3137
3138    /// Simple Vec-backed buffer to test fragmented buffers implementation.
3139    ///
3140    /// `ScatterGatherBuf` keeps:
3141    /// - an inner buffer `inner`, which is always part of its body.
3142    /// - extra backing memory in `data`.
3143    ///
3144    /// `data` has two "root" regions, marked by the midpoint `mid`. Everything
3145    /// left of `mid` is this buffer's prefix, and after `mid` is this buffer's
3146    /// suffix.
3147    ///
3148    /// The `range` field keeps the range in `data` that contains *filled*
3149    /// prefix and suffix information. `range.start` is always less than or
3150    /// equal to `mid` and `range.end` is always greater than or equal to `mid`,
3151    /// such that growing the front of the buffer means decrementing
3152    /// `range.start` and growing the back of the buffer means incrementing
3153    /// `range.end`.
3154    ///
3155    ///  At any time this buffer's parts are:
3156    /// - Free prefix data in range `0..range.start`.
3157    /// - Used prefix data (now part of body) in range `range.start..mid`.
3158    /// - Inner buffer body in `inner`.
3159    /// - Used suffix data (now part of body) in range `mid..range.end`.
3160    /// - Free suffix data in range `range.end..`
3161    struct ScatterGatherBuf<B> {
3162        data: Vec<u8>,
3163        mid: usize,
3164        range: Range<usize>,
3165        inner: B,
3166    }
3167
3168    impl<B: BufferMut> FragmentedBuffer for ScatterGatherBuf<B> {
3169        fn len(&self) -> usize {
3170            self.inner.len() + (self.range.end - self.range.start)
3171        }
3172
3173        fn with_bytes<'a, R, F>(&'a self, f: F) -> R
3174        where
3175            F: for<'b> FnOnce(FragmentedBytes<'b, 'a>) -> R,
3176        {
3177            let (_, rest) = self.data.split_at(self.range.start);
3178            let (prefix_b, rest) = rest.split_at(self.mid - self.range.start);
3179            let (suffix_b, _) = rest.split_at(self.range.end - self.mid);
3180            let mut bytes = [prefix_b, self.inner.as_ref(), suffix_b];
3181            f(FragmentedBytes::new(&mut bytes[..]))
3182        }
3183    }
3184
3185    impl<B: BufferMut> FragmentedBufferMut for ScatterGatherBuf<B> {
3186        fn with_bytes_mut<'a, R, F>(&'a mut self, f: F) -> R
3187        where
3188            F: for<'b> FnOnce(FragmentedBytesMut<'b, 'a>) -> R,
3189        {
3190            let (_, rest) = self.data.split_at_mut(self.range.start);
3191            let (prefix_b, rest) = rest.split_at_mut(self.mid - self.range.start);
3192            let (suffix_b, _) = rest.split_at_mut(self.range.end - self.mid);
3193            let mut bytes = [prefix_b, self.inner.as_mut(), suffix_b];
3194            f(FragmentedBytesMut::new(&mut bytes[..]))
3195        }
3196    }
3197
3198    impl<B: BufferMut> GrowBuffer for ScatterGatherBuf<B> {
3199        fn with_parts<'a, O, F>(&'a self, f: F) -> O
3200        where
3201            F: for<'b> FnOnce(&'a [u8], FragmentedBytes<'b, 'a>, &'a [u8]) -> O,
3202        {
3203            let (prefix, rest) = self.data.split_at(self.range.start);
3204            let (prefix_b, rest) = rest.split_at(self.mid - self.range.start);
3205            let (suffix_b, suffix) = rest.split_at(self.range.end - self.mid);
3206            let mut bytes = [prefix_b, self.inner.as_ref(), suffix_b];
3207            f(prefix, bytes.as_fragmented_byte_slice(), suffix)
3208        }
3209        fn prefix_len(&self) -> usize {
3210            self.range.start
3211        }
3212
3213        fn suffix_len(&self) -> usize {
3214            self.data.len() - self.range.end
3215        }
3216
3217        fn grow_front(&mut self, n: usize) {
3218            self.range.start -= n;
3219        }
3220
3221        fn grow_back(&mut self, n: usize) {
3222            self.range.end += n;
3223            assert!(self.range.end <= self.data.len());
3224        }
3225    }
3226
3227    impl<B: BufferMut> GrowBufferMut for ScatterGatherBuf<B> {
3228        fn with_parts_mut<'a, O, F>(&'a mut self, f: F) -> O
3229        where
3230            F: for<'b> FnOnce(&'a mut [u8], FragmentedBytesMut<'b, 'a>, &'a mut [u8]) -> O,
3231        {
3232            let (prefix, rest) = self.data.split_at_mut(self.range.start);
3233            let (prefix_b, rest) = rest.split_at_mut(self.mid - self.range.start);
3234            let (suffix_b, suffix) = rest.split_at_mut(self.range.end - self.mid);
3235            let mut bytes = [prefix_b, self.inner.as_mut(), suffix_b];
3236            f(prefix, bytes.as_fragmented_byte_slice(), suffix)
3237        }
3238
3239        fn with_all_contents_mut<'a, O, F>(&'a mut self, _f: F) -> O
3240        where
3241            F: for<'b> FnOnce(FragmentedBytesMut<'b, 'a>) -> O,
3242        {
3243            unimplemented!()
3244        }
3245    }
3246
3247    struct ScatterGatherProvider;
3248
3249    impl<B: BufferMut> BufferProvider<B, ScatterGatherBuf<B>> for ScatterGatherProvider {
3250        type Error = Never;
3251
3252        fn alloc_no_reuse(
3253            self,
3254            _prefix: usize,
3255            _body: usize,
3256            _suffix: usize,
3257        ) -> Result<ScatterGatherBuf<B>, Self::Error> {
3258            unimplemented!("not used in tests")
3259        }
3260
3261        fn reuse_or_realloc(
3262            self,
3263            buffer: B,
3264            prefix: usize,
3265            suffix: usize,
3266        ) -> Result<ScatterGatherBuf<B>, (Self::Error, B)> {
3267            let inner = buffer;
3268            let data = vec![0; prefix + suffix];
3269            let range = Range { start: prefix, end: prefix };
3270            let mid = prefix;
3271            Ok(ScatterGatherBuf { inner, data, range, mid })
3272        }
3273    }
3274
3275    #[test]
3276    fn test_scatter_gather_serialize() {
3277        // Assert that a buffer composed of different allocations can be used as
3278        // a serialization target, while reusing an internal body buffer.
3279        let buf = Buf::new(vec![10, 20, 30, 40, 50], ..);
3280        let pb = DummyPacketBuilder::new(3, 2, 0, usize::MAX);
3281        let ser = pb.wrap_body(buf);
3282        let result = ser.serialize_outer(ScatterGatherProvider {}).unwrap();
3283        let flattened = result.to_flattened_vec();
3284        assert_eq!(&flattened[..], &[0xFF, 0xFF, 0xFF, 10, 20, 30, 40, 50, 0xFE, 0xFE]);
3285    }
3286
3287    #[test]
3288    fn dyn_serialize() {
3289        let body = Buf::new(vec![10, 20, 30, 40, 50], ..);
3290        let header1 = DummyPacketBuilder {
3291            header_len: 5,
3292            footer_len: 0,
3293            min_body_len: 0,
3294            max_body_len: usize::MAX,
3295            header_byte: 0xAA,
3296            footer_byte: 0xBB,
3297        };
3298        let header2 = DummyPacketBuilder {
3299            header_len: 3,
3300            footer_len: 2,
3301            min_body_len: 0,
3302            max_body_len: usize::MAX,
3303            header_byte: 0xCC,
3304            footer_byte: 0xDD,
3305        };
3306        // A reference serializer.
3307        let ser1 = body.clone().wrap_in(header1).wrap_in(header2);
3308        // A nested dynamic serializer.
3309        let ser2 = body.wrap_in(header1);
3310        let ser2 = DynSerializer::new(&ser2).wrap_in(header2);
3311        // An outer dynamic serializer.
3312        let ser3 = ser1.clone();
3313        let ser3 = DynSerializer::new(&ser3);
3314        // Two levels of dynamic serializer.
3315        let ser4 = DynSerializer::new(&ser2);
3316
3317        fn serialize(s: impl Serializer<Buffer: ReusableBuffer>) -> Vec<u8> {
3318            s.serialize_vec(PacketConstraints::UNCONSTRAINED)
3319                .map_err(|(e, _)| e)
3320                .unwrap()
3321                .unwrap_b()
3322                .into_inner()
3323        }
3324
3325        fn serialize_new(s: impl Serializer) -> Vec<u8> {
3326            s.serialize_new_buf(PacketConstraints::UNCONSTRAINED, new_buf_vec).unwrap().into_inner()
3327        }
3328
3329        let expect = serialize(ser1.clone());
3330        assert_eq!(serialize(ser2), expect);
3331        assert_eq!(serialize(ser3), expect);
3332        assert_eq!(serialize(ser4), expect);
3333        assert_eq!(serialize_new(ser1), expect);
3334        assert_eq!(serialize_new(ser2), expect);
3335        assert_eq!(serialize_new(ser3), expect);
3336        assert_eq!(serialize_new(ser4), expect);
3337    }
3338}