Skip to main content

buffa/
encode_sink.rs

1//! Output abstraction for message encoding.
2//!
3//! [`EncodeSink`] is the byte sink every encode path writes into. Its four
4//! required methods are the [`BufMut`] primitives the encoders bottom out
5//! in (the fixed-width signed/float writers are provided on top), plus
6//! [`put_shared`](EncodeSink::put_shared) for splicing an owned [`Bytes`]
7//! segment into the output without copying it.
8//!
9//! Every [`BufMut`] implementor is an `EncodeSink` through a blanket impl,
10//! with `put_shared` copying. [`Rope`] implements the trait directly (it is deliberately
11//! *not* a `BufMut`) and captures large segments by reference count instead,
12//! so encoding a message whose dominant content is one large `bytes` field
13//! costs O(everything-but-the-payload) rather than O(payload).
14//!
15//! # One `write_to` instance per message
16//!
17//! `Message::write_to` is generic over the sink, so a program that encodes
18//! into a `Vec<u8>` in one place and a `BytesMut` in another would compile
19//! two copies of every message's `write_to`. The provided encode methods of
20//! [`Message`](crate::Message) and [`ViewEncode`](crate::ViewEncode)
21//! (`encode`, `encode_to_vec`, and their `try_`, `_with_cache`, bounded and
22//! length-delimited variants) therefore write every [`BufMut`] through one
23//! shared, pre-sized cursor. They compute the exact size first and ask the
24//! sink for that many contiguous bytes: `Vec<u8>` and `BytesMut` offer
25//! their spare capacity, and `write_to` fills it with stores that are
26//! bounds-checked but never grow the sink. A sink whose current chunk is
27//! shorter than the message (an empty `Vec::new()` or `BytesMut::new()`
28//! offers 64 bytes, and a chain of buffers offers its first) is filled
29//! through a scratch `Vec` of the exact size and appended with one
30//! [`put_slice`](EncodeSink::put_slice), so reserving
31//! [`encoded_len`](crate::Message::encoded_len) bytes first avoids the
32//! extra allocation and copy. The length prefix of
33//! `encode_length_delimited` is written to the sink before the message, so
34//! reserve up to five bytes more for it.
35//!
36//! A type that implements `EncodeSink` and not `BufMut`, and a segmented
37//! sink ([`IS_SEGMENTED`](EncodeSink::IS_SEGMENTED), such as [`Rope`]),
38//! receives every write individually through its own instantiation of
39//! `write_to`.
40//! Generated lazy views and `DynamicMessage` have their own encode methods,
41//! which do not use the shared cursor.
42
43use core::mem::MaybeUninit;
44
45use bytes::{Buf, BufMut, Bytes, BytesMut};
46
47use crate::alloc::vec::Vec;
48
49/// Byte sink for message encoding.
50///
51/// The write surface is deliberately the narrow subset of [`BufMut`] that
52/// the encoding primitives use ([`put_u8`](Self::put_u8),
53/// [`put_slice`](Self::put_slice), the little-endian fixed-width writers),
54/// plus [`put_shared`](Self::put_shared) for owned segments. Other `BufMut`
55/// methods (`put_u16`, big-endian writers, `advance_mut`, …) are
56/// intentionally absent — a manual `write_to` that needs them should
57/// assemble into a concrete buffer first.
58///
59/// # Implementors
60///
61/// You almost never implement this trait: the blanket impl covers every
62/// [`BufMut`] (`Vec<u8>`, [`BytesMut`], `&mut [u8]`, …), and [`Rope`] is the
63/// built-in segmented sink. A custom implementation must append bytes in
64/// call order — the encoders rely on the sink being strictly sequential —
65/// and receives every write individually.
66///
67/// # Contiguous callers
68///
69/// The blanket impl's `put_shared` copies. The encode entry points write a
70/// `BufMut` through its `chunk_mut` and `advance_mut` rather than through
71/// `put_slice` and `put_u8` (see the [module documentation](self)), with
72/// two consequences:
73///
74/// - A `write_to` that produces more bytes than its `compute_size`
75///   declared panics.
76/// - A `BufMut` wrapper that observes bytes in its own `put_*` overrides,
77///   such as a checksum or a tee, does not see them individually: it sees
78///   `advance_mut` when the message fits its chunk and one `put_slice`
79///   otherwise. Observe them in `advance_mut`, or implement `EncodeSink`
80///   and not `BufMut`.
81///
82/// # Method-name overlap with `BufMut`
83///
84/// The method names intentionally match `BufMut`'s. If both traits are in
85/// scope, calling `put_u8`/`put_slice`/`put_u32_le`/`put_u64_le` on a
86/// concrete `BufMut` type is ambiguous (E0034) — disambiguate with
87/// `BufMut::put_slice(&mut buf, ..)` or drop the unneeded import.
88pub trait EncodeSink {
89    /// Whether this sink can take ownership of [`Bytes`] segments without
90    /// copying ([`put_shared`](Self::put_shared) is more than a copy).
91    ///
92    /// Encode helpers use this to skip producing a shared handle (an atomic
93    /// refcount clone) when the sink would only copy it anyway, and the
94    /// encode entry points write a segmented sink through its own `write_to`
95    /// instantiation instead of the shared pre-sized cursor. The constant
96    /// folds at monomorphization. `false` is correct for any sink that does not
97    /// capture segments.
98    const IS_SEGMENTED: bool = false;
99
100    /// Append a single byte.
101    fn put_u8(&mut self, value: u8);
102
103    /// Append a borrowed slice.
104    fn put_slice(&mut self, src: &[u8]);
105
106    /// Append a `u32` in little-endian byte order (protobuf `fixed32`).
107    fn put_u32_le(&mut self, value: u32);
108
109    /// Append a `u64` in little-endian byte order (protobuf `fixed64`).
110    fn put_u64_le(&mut self, value: u64);
111
112    /// Append an `i32` in little-endian byte order (protobuf `sfixed32`).
113    #[inline]
114    fn put_i32_le(&mut self, value: i32) {
115        // Bit-preserving cast: sfixed32 is the two's-complement bytes.
116        #[allow(clippy::cast_sign_loss)]
117        self.put_u32_le(value as u32);
118    }
119
120    /// Append an `i64` in little-endian byte order (protobuf `sfixed64`).
121    #[inline]
122    fn put_i64_le(&mut self, value: i64) {
123        // Bit-preserving cast: sfixed64 is the two's-complement bytes.
124        #[allow(clippy::cast_sign_loss)]
125        self.put_u64_le(value as u64);
126    }
127
128    /// Append an `f32` in little-endian byte order (protobuf `float`).
129    #[inline]
130    fn put_f32_le(&mut self, value: f32) {
131        self.put_u32_le(value.to_bits());
132    }
133
134    /// Append an `f64` in little-endian byte order (protobuf `double`).
135    #[inline]
136    fn put_f64_le(&mut self, value: f64) {
137        self.put_u64_le(value.to_bits());
138    }
139
140    /// Append an owned segment.
141    ///
142    /// Contiguous sinks copy (the default). Segmented sinks such as
143    /// [`Rope`] may take ownership of `bytes` by reference count when it is
144    /// large enough to be worth a segment, making the append O(1) in the
145    /// segment's length.
146    #[inline]
147    fn put_shared(&mut self, bytes: Bytes) {
148        self.put_slice(&bytes);
149    }
150
151    /// Whether the encode entry points may write this sink through a
152    /// [`PreSized`] cursor by calling
153    /// [`__write_pre_sized`](Self::__write_pre_sized). The blanket `BufMut`
154    /// impl sets it.
155    #[doc(hidden)]
156    const __PRE_SIZED: bool = false;
157
158    /// Run `f` on this sink if it is a [`PreSized`] cursor, and return
159    /// whether it did.
160    ///
161    /// Lets the table interpreters switch, once per message, from an instance
162    /// generic over the sink to one compiled in this crate. `f` gets the
163    /// cursor itself, and a `PreSized` cannot be built or altered outside this
164    /// crate, so `f` cannot claim more bytes than were written:
165    ///
166    /// ```compile_fail,E0616
167    /// use buffa::EncodeSink;
168    ///
169    /// let mut vec: Vec<u8> = Vec::new();
170    /// vec.__with_pre_sized(&mut |cursor| cursor.pos = 4);
171    /// ```
172    ///
173    /// Implementations outside this crate keep the default, which does not
174    /// call `f`.
175    #[doc(hidden)]
176    #[inline]
177    fn __with_pre_sized(&mut self, f: &mut dyn FnMut(&mut PreSized<'_>)) -> bool {
178        let _ = f;
179        false
180    }
181
182    /// Run `fill` over `len` bytes of contiguous space at the end of the
183    /// sink and append the bytes it wrote, or give `fill` back unrun if the
184    /// sink's current chunk is shorter than `len`.
185    ///
186    /// `fill` may write fewer than `len` bytes, and only those are appended.
187    /// If it panics the sink is unchanged. Implementations that override
188    /// this must also set [`__PRE_SIZED`](Self::__PRE_SIZED). Outside this
189    /// crate, forward to another sink's `__write_pre_sized` or keep the
190    /// default: a [`PreSized`] cannot be built, or read, from outside.
191    #[doc(hidden)]
192    #[inline]
193    fn __write_pre_sized<F: FnOnce(&mut PreSized<'_>)>(
194        &mut self,
195        len: usize,
196        fill: F,
197    ) -> Result<(), F> {
198        let _ = len;
199        Err(fill)
200    }
201}
202
203impl<T: BufMut + ?Sized> EncodeSink for T {
204    const __PRE_SIZED: bool = true;
205
206    #[inline]
207    fn __write_pre_sized<F: FnOnce(&mut PreSized<'_>)>(
208        &mut self,
209        len: usize,
210        fill: F,
211    ) -> Result<(), F> {
212        // An empty message asks nothing of the sink: `chunk_mut` may reserve.
213        let spare: &mut [MaybeUninit<u8>] = if len == 0 {
214            &mut []
215        } else {
216            let chunk = BufMut::chunk_mut(self);
217            if chunk.len() < len {
218                return Err(fill);
219            }
220            // SAFETY: `chunk` is writable memory of at least `len` bytes, and
221            // `MaybeUninit<u8>` has the layout of `u8`. `fill` cannot reach
222            // `self`, so the slice is the only access to those bytes until
223            // `advance_mut`, and it is only ever written through.
224            unsafe {
225                core::slice::from_raw_parts_mut(chunk.as_mut_ptr().cast::<MaybeUninit<u8>>(), len)
226            }
227        };
228        let mut cursor = PreSized::new(spare);
229        fill(&mut cursor);
230        let written = cursor.written();
231        // SAFETY: the cursor initialised its first `written` bytes, all inside
232        // `chunk`, and counts only bytes it wrote itself.
233        unsafe { BufMut::advance_mut(self, written) };
234        Ok(())
235    }
236
237    #[inline]
238    fn put_u8(&mut self, value: u8) {
239        BufMut::put_u8(self, value);
240    }
241
242    #[inline]
243    fn put_slice(&mut self, src: &[u8]) {
244        BufMut::put_slice(self, src);
245    }
246
247    #[inline]
248    fn put_u32_le(&mut self, value: u32) {
249        BufMut::put_u32_le(self, value);
250    }
251
252    #[inline]
253    fn put_u64_le(&mut self, value: u64) {
254        BufMut::put_u64_le(self, value);
255    }
256}
257
258/// A cursor over a fixed-size, possibly uninitialised buffer, sized exactly
259/// by a preceding `compute_size` pass.
260///
261/// Each write is a bounds check against the end of the buffer followed by a
262/// store, with no call to grow. A write past the end means `write_to`
263/// produced more bytes than `compute_size` declared, which is a bug in a
264/// manual implementation: the cursor panics rather than write out of
265/// bounds. It counts only the bytes it has written, so the first `written`
266/// bytes of the buffer are initialised.
267#[doc(hidden)]
268pub struct PreSized<'a> {
269    dst: &'a mut [MaybeUninit<u8>],
270    pos: usize,
271}
272
273#[cold]
274#[inline(never)]
275fn pre_sized_overflow() -> ! {
276    panic!("write_to produced more bytes than compute_size declared (two-pass traversal mismatch)")
277}
278
279impl<'a> PreSized<'a> {
280    /// A cursor at the start of `dst`.
281    ///
282    /// Not public: [`EncodeSink::__write_pre_sized`] trusts the count of a
283    /// cursor it built itself, which is only sound if code outside this crate
284    /// cannot build a different cursor and swap it in.
285    #[inline]
286    pub(crate) fn new(dst: &'a mut [MaybeUninit<u8>]) -> Self {
287        Self { dst, pos: 0 }
288    }
289
290    /// The number of bytes written so far.
291    #[inline]
292    pub(crate) const fn written(&self) -> usize {
293        self.pos
294    }
295}
296
297impl EncodeSink for PreSized<'_> {
298    #[inline]
299    fn __with_pre_sized(&mut self, f: &mut dyn FnMut(&mut PreSized<'_>)) -> bool {
300        f(self);
301        true
302    }
303
304    #[inline]
305    fn put_u8(&mut self, value: u8) {
306        let Some(slot) = self.dst.get_mut(self.pos) else {
307            pre_sized_overflow()
308        };
309        slot.write(value);
310        self.pos += 1;
311    }
312
313    #[inline]
314    fn put_slice(&mut self, src: &[u8]) {
315        let Some(dst) = self
316            .dst
317            .get_mut(self.pos..)
318            .and_then(|rest| rest.get_mut(..src.len()))
319        else {
320            pre_sized_overflow()
321        };
322        // SAFETY: `dst` is `src.len()` writable bytes, and `src` cannot
323        // overlap it because `dst` is behind an exclusive borrow.
324        unsafe {
325            core::ptr::copy_nonoverlapping(src.as_ptr(), dst.as_mut_ptr().cast::<u8>(), src.len());
326        }
327        self.pos += src.len();
328    }
329
330    #[inline]
331    fn put_u32_le(&mut self, value: u32) {
332        self.put_slice(&value.to_le_bytes());
333    }
334
335    #[inline]
336    fn put_u64_le(&mut self, value: u64) {
337        self.put_slice(&value.to_le_bytes());
338    }
339}
340
341/// Write a message whose encoded size is `size` into `buf`.
342///
343/// `pre_sized` writes through a [`PreSized`] cursor and `per_write` writes to
344/// the sink itself; exactly one runs. A `BufMut` takes `pre_sized`, so
345/// however many `BufMut` types a program encodes into, one copy of each
346/// message's `write_to` serves them all. Any other sink takes `per_write` and
347/// receives every write individually.
348///
349/// `pre_sized` may write fewer than `size` bytes, in which case only the
350/// bytes written are appended, and a debug build panics; writing more panics
351/// (see [`PreSized`]). The cache is a parameter so that the two closures,
352/// which cannot both capture it mutably, need only borrow the message.
353#[inline]
354pub(crate) fn write_contiguous<S: EncodeSink>(
355    size: usize,
356    cache: &mut crate::SizeCache,
357    buf: &mut S,
358    pre_sized: impl FnOnce(&mut crate::SizeCache, &mut PreSized<'_>),
359    per_write: impl FnOnce(&mut crate::SizeCache, &mut S),
360) {
361    if S::IS_SEGMENTED || !S::__PRE_SIZED {
362        per_write(cache, buf);
363        return;
364    }
365    let fill = move |cursor: &mut PreSized<'_>| {
366        pre_sized(cache, cursor);
367        crate::message::debug_assert_two_pass(cursor.written(), size);
368    };
369    if let Err(fill) = buf.__write_pre_sized(size, fill) {
370        let scratch = write_to_new_vec(size, fill);
371        buf.put_slice(&scratch);
372    }
373}
374
375/// Write a message whose encoded size is `size` into a new `Vec` of exactly
376/// that capacity.
377#[inline]
378pub(crate) fn write_to_new_vec(size: usize, fill: impl FnOnce(&mut PreSized<'_>)) -> Vec<u8> {
379    debug_assert!(size <= crate::MAX_MESSAGE_BYTES as usize);
380    let mut vec = Vec::with_capacity(size);
381    let written = {
382        let mut cursor = PreSized::new(&mut vec.spare_capacity_mut()[..size]);
383        fill(&mut cursor);
384        cursor.written()
385    };
386    // SAFETY: the cursor initialised the first `written` bytes of the
387    // vector's spare capacity, and `written <= size <= capacity`.
388    unsafe { vec.set_len(written) };
389    vec
390}
391
392/// Default minimum segment size for [`Rope`]: payloads below this are
393/// copied into the small-write tail buffer rather than kept as their own
394/// segment.
395///
396/// The trade-off is a payload-sized memcpy (tens of GiB/s) against the
397/// per-segment overhead downstream: refcount bookkeeping, one more vectored
398/// I/O slot, one more frame for HTTP bodies. The crossover is in the
399/// single-digit KiB; 4 KiB is conservative.
400pub const DEFAULT_MIN_SEGMENT: usize = 4 * 1024;
401
402/// A segmented encode sink: an ordered sequence of [`Bytes`] segments.
403///
404/// Small writes (tags, varints, scalar fields, short strings) accumulate in
405/// a tail buffer; large owned segments arriving via
406/// [`put_shared`](EncodeSink::put_shared) — and large borrowed slices that
407/// provably lie inside the optional [backing buffer](Self::with_backing) —
408/// are captured by reference count instead of copied. Concatenating the
409/// [`segments`](Self::into_segments) reproduces exactly the bytes a
410/// contiguous sink would have received.
411///
412/// ```rust,ignore
413/// let mut rope = Rope::new();
414/// message.encode(&mut rope);
415/// for segment in rope.into_segments() {
416///     body.send_data(segment); // refcount handles, no payload copy
417/// }
418/// ```
419// Deliberately NOT a `BufMut`: the blanket `impl<T: BufMut> EncodeSink for T`
420// would overlap with `Rope`'s own impl (E0119) if it ever became one.
421#[derive(Debug)]
422pub struct Rope {
423    /// Finalized segments, in output order.
424    segments: Vec<Bytes>,
425    /// Accumulator for writes below the segment threshold.
426    tail: BytesMut,
427    /// Buffer that borrowed slices may point into (view encoding); a slice
428    /// inside it can be captured zero-copy via `Bytes::slice_ref`.
429    backing: Option<Bytes>,
430    /// Minimum length for a write to become its own segment.
431    min_segment: usize,
432}
433
434impl Default for Rope {
435    /// Equivalent to [`Rope::new`]. (Not derived: the derive would default
436    /// `min_segment` to `0`, bypassing the clamp every constructor applies.)
437    fn default() -> Self {
438        Self::new()
439    }
440}
441
442impl Rope {
443    /// Create a rope with [`DEFAULT_MIN_SEGMENT`].
444    #[must_use]
445    pub fn new() -> Self {
446        Self::with_min_segment(DEFAULT_MIN_SEGMENT)
447    }
448
449    /// Create a rope with a custom minimum segment size.
450    ///
451    /// `min_segment = usize::MAX` never segments (every write is copied
452    /// into one contiguous tail — useful for differential testing);
453    /// `min_segment = 0` is clamped to 1 so empty payloads never produce
454    /// empty segments.
455    #[must_use]
456    pub fn with_min_segment(min_segment: usize) -> Self {
457        Self {
458            segments: Vec::new(),
459            tail: BytesMut::new(),
460            backing: None,
461            min_segment: min_segment.max(1),
462        }
463    }
464
465    /// Attach the buffer that borrowed slices were decoded from.
466    ///
467    /// With a backing buffer attached, [`put_slice`](EncodeSink::put_slice)
468    /// captures any large slice that lies inside it via
469    /// [`Bytes::slice_ref`] — zero-copy — instead of copying. This is the
470    /// view-encoding hook: a view's `&[u8]` fields borrow from the buffer
471    /// the view was decoded from, so re-encoding a view through a rope
472    /// backed by that buffer never copies the large fields.
473    ///
474    /// Pass exactly the buffer the view was decoded from. Slices outside
475    /// the backing buffer (modified fields, other sources, a mismatched
476    /// buffer) are copied as usual — the output stays correct, but the
477    /// zero-copy capture silently does not engage. The containment check is
478    /// two pointer compares.
479    #[must_use]
480    pub fn with_backing(mut self, backing: Bytes) -> Self {
481        self.backing = Some(backing);
482        self
483    }
484
485    /// Total byte length across all segments and the tail.
486    #[must_use]
487    pub fn len(&self) -> usize {
488        self.segments.iter().map(Bytes::len).sum::<usize>() + self.tail.len()
489    }
490
491    /// Whether the rope contains no bytes.
492    #[must_use]
493    pub fn is_empty(&self) -> bool {
494        // Segments are never empty: every path that pushes one requires
495        // `len >= min_segment >= 1` (or a non-empty tail flush).
496        self.tail.is_empty() && self.segments.is_empty()
497    }
498
499    /// Number of segments [`into_segments`](Self::into_segments) will yield
500    /// (including the pending tail, if non-empty).
501    #[must_use]
502    pub fn segment_count(&self) -> usize {
503        self.segments.len() + usize::from(!self.tail.is_empty())
504    }
505
506    /// Finish the rope, yielding its segments in output order.
507    #[must_use]
508    pub fn into_segments(mut self) -> Vec<Bytes> {
509        self.flush_tail();
510        self.segments
511    }
512
513    /// Copy the rope out into one contiguous [`Bytes`].
514    ///
515    /// For consumers that need contiguous output after all — this performs
516    /// the copies the rope avoided, so prefer
517    /// [`into_segments`](Self::into_segments) wherever the consumer can
518    /// take a segment sequence. (Named distinctly from
519    /// [`Buf::copy_to_bytes`], which consumes a length-bounded prefix; this
520    /// is a non-consuming full copy.)
521    #[must_use]
522    pub fn to_contiguous_bytes(&self) -> Bytes {
523        let mut out = Vec::with_capacity(self.len());
524        for segment in &self.segments {
525            out.extend_from_slice(segment);
526        }
527        out.extend_from_slice(&self.tail);
528        Bytes::from(out)
529    }
530
531    /// Move the accumulated tail into the segment list.
532    fn flush_tail(&mut self) {
533        if !self.tail.is_empty() {
534            self.segments.push(self.tail.split().freeze());
535        }
536    }
537}
538
539impl EncodeSink for Rope {
540    const IS_SEGMENTED: bool = true;
541
542    // The tail is written through `BytesMut::extend_from_slice` (inherent,
543    // `#[inline]` since bytes 1.5) rather than its `BufMut::put_*` impls,
544    // which are an out-of-line call per tag/varint byte even under fat LTO.
545    #[inline]
546    fn put_u8(&mut self, value: u8) {
547        self.tail.extend_from_slice(&[value]);
548    }
549
550    #[inline]
551    fn put_slice(&mut self, src: &[u8]) {
552        // `min_segment >= 1` also excludes empty slices, whose dangling
553        // pointers must not reach the containment check.
554        if src.len() >= self.min_segment {
555            if let Some(segment) = self
556                .backing
557                .as_ref()
558                .and_then(|b| crate::view::try_slice_ref(b, src))
559            {
560                self.flush_tail();
561                self.segments.push(segment);
562                return;
563            }
564        }
565        self.tail.extend_from_slice(src);
566    }
567
568    #[inline]
569    fn put_u32_le(&mut self, value: u32) {
570        self.tail.extend_from_slice(&value.to_le_bytes());
571    }
572
573    #[inline]
574    fn put_u64_le(&mut self, value: u64) {
575        self.tail.extend_from_slice(&value.to_le_bytes());
576    }
577
578    #[inline]
579    fn put_shared(&mut self, bytes: Bytes) {
580        if bytes.len() >= self.min_segment {
581            self.flush_tail();
582            self.segments.push(bytes);
583        } else {
584            self.tail.extend_from_slice(&bytes);
585        }
586    }
587}
588
589// The reborrow pattern (`&mut rope` passed where `impl EncodeSink` is
590// expected) needs an explicit forwarding impl: the blanket impl only covers
591// `BufMut` types, whose own `impl BufMut for &mut T` supplies this for
592// contiguous sinks. A generic `impl EncodeSink for &mut S` would overlap
593// with the blanket, so `Rope` forwards concretely.
594impl EncodeSink for &mut Rope {
595    const IS_SEGMENTED: bool = true;
596
597    #[inline]
598    fn put_u8(&mut self, value: u8) {
599        Rope::put_u8(self, value);
600    }
601
602    #[inline]
603    fn put_slice(&mut self, src: &[u8]) {
604        Rope::put_slice(self, src);
605    }
606
607    #[inline]
608    fn put_u32_le(&mut self, value: u32) {
609        Rope::put_u32_le(self, value);
610    }
611
612    #[inline]
613    fn put_u64_le(&mut self, value: u64) {
614        Rope::put_u64_le(self, value);
615    }
616
617    #[inline]
618    fn put_shared(&mut self, bytes: Bytes) {
619        Rope::put_shared(self, bytes);
620    }
621}
622
623/// A [`Buf`] over a finished rope's segments, for consumers (hyper, h2,
624/// vectored writers) that take any `Buf` and iterate its chunks.
625#[derive(Debug)]
626pub struct RopeBuf {
627    /// Segments not yet fully consumed, in order; `pos` indexes the front.
628    segments: Vec<Bytes>,
629    pos: usize,
630    remaining: usize,
631}
632
633impl From<Rope> for RopeBuf {
634    fn from(rope: Rope) -> Self {
635        let segments = rope.into_segments();
636        let remaining = segments.iter().map(Bytes::len).sum();
637        Self {
638            segments,
639            pos: 0,
640            remaining,
641        }
642    }
643}
644
645impl Buf for RopeBuf {
646    fn remaining(&self) -> usize {
647        self.remaining
648    }
649
650    fn chunk(&self) -> &[u8] {
651        self.segments.get(self.pos).map_or(&[], |b| &b[..])
652    }
653
654    fn advance(&mut self, mut cnt: usize) {
655        assert!(cnt <= self.remaining, "advance past end of RopeBuf");
656        self.remaining -= cnt;
657        while cnt > 0 {
658            let front = &mut self.segments[self.pos];
659            if cnt < front.len() {
660                front.advance(cnt);
661                return;
662            }
663            cnt -= front.len();
664            // Release the consumed segment's refcount now — for
665            // backing-captured segments it may pin an entire wire buffer —
666            // rather than holding every consumed handle until drop.
667            *front = Bytes::new();
668            self.pos += 1;
669        }
670    }
671
672    /// Returns a prefix that lies within one segment without copying it. A
673    /// prefix that spans segments is copied into one contiguous buffer.
674    ///
675    /// An uncopied prefix is a reference-counted slice of its segment's
676    /// backing allocation and keeps that allocation alive until it is dropped.
677    /// The allocation holds at least the whole segment, and more when the
678    /// segment was spliced in with `put_shared` from a larger buffer.
679    #[inline]
680    fn copy_to_bytes(&mut self, len: usize) -> Bytes {
681        assert!(len <= self.remaining, "copy_to_bytes past end of RopeBuf");
682        if len == 0 {
683            return Bytes::new();
684        }
685        if len <= self.chunk().len() {
686            let front = &mut self.segments[self.pos];
687            let bytes = front.split_to(len);
688            self.remaining -= len;
689            if front.is_empty() {
690                self.pos += 1;
691            }
692            return bytes;
693        }
694
695        let mut bytes = BytesMut::with_capacity(len);
696        bytes.put(self.take(len));
697        bytes.freeze()
698    }
699
700    /// Expose every remaining segment as its own I/O slice so vectored
701    /// writers (h2, tokio `write_vectored`) can emit the whole rope in one
702    /// syscall without copying. The trait's default would surface only the
703    /// front segment per call.
704    #[cfg(feature = "std")]
705    fn chunks_vectored<'a>(&'a self, dst: &mut [std::io::IoSlice<'a>]) -> usize {
706        let mut n = 0;
707        for segment in &self.segments[self.pos..] {
708            if n == dst.len() {
709                break;
710            }
711            // `Rope` never yields empty segments, and consumed segments sit
712            // behind `pos`.
713            debug_assert!(!segment.is_empty());
714            dst[n] = std::io::IoSlice::new(segment);
715            n += 1;
716        }
717        n
718    }
719}
720
721#[cfg(test)]
722mod tests {
723    use super::*;
724    use crate::test_doubles::Probe;
725
726    /// `Rope::default()` must behave exactly like `Rope::new()` — the
727    /// hand-written impl exists because a derived `Default` would zero
728    /// `min_segment`, bypassing the clamp and permitting empty segments.
729    #[test]
730    fn default_matches_new() {
731        let mut rope = Rope::default();
732        // A small shared write must coalesce into the tail (min_segment is
733        // the 4 KiB default, not 0).
734        rope.put_shared(Bytes::from_static(b"tiny"));
735        rope.put_shared(Bytes::new());
736        assert_eq!(rope.segment_count(), 1);
737        let segments = rope.into_segments();
738        assert_eq!(segments.len(), 1);
739        assert!(!segments[0].is_empty());
740    }
741
742    /// `&mut Rope` is itself an `EncodeSink` (the reborrow pattern users
743    /// get for free from `BufMut`'s `&mut T` impl on contiguous sinks).
744    #[test]
745    fn mut_ref_forwarding_impl() {
746        fn write_through(mut sink: impl EncodeSink) {
747            sink.put_slice(b"via reborrow");
748            sink.put_shared(Bytes::from(crate::alloc::vec![9u8; 64]));
749        }
750        let mut rope = Rope::with_min_segment(64);
751        write_through(&mut rope);
752        assert_eq!(rope.segment_count(), 2);
753        assert_eq!(rope.len(), 12 + 64);
754    }
755
756    /// Consuming a segment through `RopeBuf::advance` releases its
757    /// refcount immediately, not at `RopeBuf` drop.
758    #[test]
759    fn advance_releases_consumed_segments() {
760        let payload = Bytes::from(crate::alloc::vec![3u8; 128]);
761        let mut rope = Rope::with_min_segment(64);
762        rope.put_shared(payload.clone());
763        rope.put_slice(b"after");
764        let mut buf = RopeBuf::from(rope);
765
766        // Two handles exist: `payload` and the segment inside `buf`.
767        assert!(payload.clone().try_into_mut().is_err(), "not unique yet");
768        buf.advance(128);
769        // The consumed segment's handle is dropped; `payload` is unique.
770        assert!(
771            payload.try_into_mut().is_ok(),
772            "consumed segment must be released before RopeBuf drop"
773        );
774        assert_eq!(buf.copy_to_bytes(buf.remaining()), &b"after"[..]);
775    }
776
777    /// Writes below the threshold accumulate in one tail segment.
778    #[test]
779    fn small_writes_coalesce() {
780        let mut rope = Rope::with_min_segment(16);
781        rope.put_u8(1);
782        rope.put_slice(b"abc");
783        rope.put_u32_le(7);
784        rope.put_u64_le(9);
785        assert_eq!(rope.segment_count(), 1);
786        let segments = rope.into_segments();
787        assert_eq!(segments.len(), 1);
788        assert_eq!(segments[0].len(), 1 + 3 + 4 + 8);
789    }
790
791    /// A large shared segment is captured by refcount, and ordering with
792    /// surrounding small writes is preserved.
793    #[test]
794    fn large_shared_segment_is_not_copied() {
795        let payload = Bytes::from(crate::alloc::vec![0xAB; 64]);
796        let ptr = payload.as_ptr();
797
798        let mut rope = Rope::with_min_segment(64);
799        rope.put_slice(b"head");
800        rope.put_shared(payload);
801        rope.put_slice(b"tail");
802
803        let segments = rope.into_segments();
804        assert_eq!(segments.len(), 3);
805        assert_eq!(&segments[0][..], b"head");
806        assert!(core::ptr::eq(segments[1].as_ptr(), ptr), "must not copy");
807        assert_eq!(&segments[2][..], b"tail");
808    }
809
810    /// A small shared write folds into the tail instead of fragmenting.
811    #[test]
812    fn small_shared_write_coalesces() {
813        let mut rope = Rope::with_min_segment(64);
814        rope.put_slice(b"a");
815        rope.put_shared(Bytes::from_static(b"bc"));
816        rope.put_slice(b"d");
817        let segments = rope.into_segments();
818        assert_eq!(segments.len(), 1);
819        assert_eq!(&segments[0][..], b"abcd");
820    }
821
822    /// Borrowed slices inside the backing buffer are captured zero-copy.
823    #[test]
824    fn backed_slice_is_captured_zero_copy() {
825        let backing = Bytes::from(crate::alloc::vec![0x5A; 256]);
826        let inside: &[u8] = &backing[32..224];
827        let outside = crate::alloc::vec![0x5A; 192];
828
829        let mut rope = Rope::with_min_segment(64).with_backing(backing.clone());
830        rope.put_slice(inside);
831        rope.put_slice(&outside);
832
833        let segments = rope.into_segments();
834        assert_eq!(segments.len(), 2);
835        assert!(
836            core::ptr::eq(segments[0].as_ptr(), inside.as_ptr()),
837            "backed slice must be zero-copy"
838        );
839        assert!(
840            !core::ptr::eq(segments[1].as_ptr(), outside.as_ptr()),
841            "unbacked slice must be copied"
842        );
843        assert_eq!(&segments[1][..], &outside[..]);
844    }
845
846    /// Concatenated segments reproduce a contiguous sink's bytes exactly.
847    #[test]
848    fn segments_concatenate_to_contiguous_output() {
849        let payload = Bytes::from(crate::alloc::vec![0x11; 128]);
850
851        let mut contiguous: Vec<u8> = Vec::new();
852        EncodeSink::put_u8(&mut contiguous, 0x0A);
853        EncodeSink::put_slice(&mut contiguous, &payload);
854        EncodeSink::put_u32_le(&mut contiguous, 42);
855        EncodeSink::put_u64_le(&mut contiguous, 0x0102_0304_0506_0708);
856
857        let mut rope = Rope::with_min_segment(64);
858        rope.put_u8(0x0A);
859        rope.put_shared(payload);
860        rope.put_u32_le(42);
861        rope.put_u64_le(0x0102_0304_0506_0708);
862
863        assert_eq!(&rope.to_contiguous_bytes()[..], &contiguous[..]);
864    }
865
866    /// `RopeBuf` walks the segments in order and honors partial advances.
867    #[test]
868    fn rope_buf_traverses_segments() {
869        let mut rope = Rope::with_min_segment(4);
870        rope.put_slice(b"ab");
871        rope.put_shared(Bytes::from_static(b"cdefgh"));
872        rope.put_slice(b"ij");
873        let mut buf = RopeBuf::from(rope);
874
875        assert_eq!(buf.remaining(), 10);
876        assert_eq!(buf.chunk(), b"ab");
877        buf.advance(3); // cross a segment boundary
878        assert_eq!(buf.chunk(), b"defgh");
879        let rest = buf.copy_to_bytes(buf.remaining());
880        assert_eq!(&rest[..], b"defghij");
881    }
882
883    fn rope_buf(segments: &[Bytes]) -> RopeBuf {
884        let mut rope = Rope::with_min_segment(1);
885        for segment in segments {
886            rope.put_shared(segment.clone());
887        }
888        RopeBuf::from(rope)
889    }
890
891    #[test]
892    fn rope_buf_copy_to_bytes_shares_whole_segment() {
893        let payload = Bytes::from(crate::alloc::vec![0xAB; 64]);
894        let ptr = payload.as_ptr();
895        let mut rope = Rope::with_min_segment(1);
896        rope.put_shared(payload);
897        let mut buf = RopeBuf::from(rope);
898
899        let copied = buf.copy_to_bytes(64);
900        assert_eq!(copied.as_ptr(), ptr);
901        assert_eq!(copied.as_ref(), &[0xAB; 64]);
902        assert_eq!(buf.remaining(), 0);
903        assert!(buf.chunk().is_empty());
904        assert!(copied.try_into_mut().is_ok());
905    }
906
907    #[test]
908    fn rope_buf_copy_to_bytes_shares_partial_segment() {
909        let payload = Bytes::copy_from_slice(b"abcdefgh");
910        let mut buf = rope_buf(core::slice::from_ref(&payload));
911        let copied = buf.copy_to_bytes(3);
912        assert_eq!(copied, &b"abc"[..]);
913        assert_eq!(copied.as_ptr(), payload.as_ptr());
914        assert_eq!(buf.remaining(), 5);
915        assert_eq!(buf.chunk(), b"defgh");
916        let rest = buf.copy_to_bytes(5);
917        assert_eq!(rest.as_ptr(), payload.as_ptr().wrapping_add(3));
918        assert_eq!(rest, &b"defgh"[..]);
919        assert_eq!(buf.remaining(), 0);
920    }
921
922    #[test]
923    fn rope_buf_copy_to_bytes_partial_result_outlives_buffer() {
924        let (copied, ptr) = {
925            let payload = Bytes::copy_from_slice(b"abcdefgh");
926            let ptr = payload.as_ptr();
927            let mut buf = rope_buf(&[payload]);
928            (buf.copy_to_bytes(3), ptr)
929        };
930        assert_eq!(copied.as_ptr(), ptr);
931        assert_eq!(copied, &b"abc"[..]);
932        assert!(copied.try_into_mut().is_ok());
933    }
934
935    #[test]
936    fn rope_buf_copy_to_bytes_shares_segment_after_advance() {
937        let payload = Bytes::from(crate::alloc::vec![0x5A; 64]);
938        let mut buf = rope_buf(&[Bytes::from_static(b"head"), payload.clone()]);
939        buf.advance(7);
940        let copied = buf.copy_to_bytes(10);
941        assert_eq!(copied.as_ptr(), payload.as_ptr().wrapping_add(3));
942        assert_eq!(copied.as_ref(), &[0x5A; 10]);
943        assert_eq!(buf.remaining(), 51);
944        assert_eq!(buf.chunk().as_ptr(), payload.as_ptr().wrapping_add(13));
945    }
946
947    #[test]
948    fn rope_buf_copy_to_bytes_zero_does_not_advance() {
949        let mut empty = RopeBuf::from(Rope::new());
950        assert!(empty.copy_to_bytes(0).is_empty());
951        assert_eq!(empty.remaining(), 0);
952
953        let mut buf = rope_buf(&[Bytes::from_static(b"abc")]);
954        assert!(buf.copy_to_bytes(0).is_empty());
955        assert_eq!(buf.remaining(), 3);
956        assert_eq!(buf.chunk(), b"abc");
957        assert_eq!(buf.copy_to_bytes(3), &b"abc"[..]);
958        assert!(buf.copy_to_bytes(0).is_empty());
959        assert!(buf.chunk().is_empty());
960    }
961
962    #[test]
963    fn rope_buf_copy_to_bytes_matches_contiguous_buffer_at_every_boundary() {
964        let segments = [
965            Bytes::from_static(b"a"),
966            Bytes::from_static(b"bcde"),
967            Bytes::from_static(b"fgh"),
968            Bytes::from_static(b"ijklmn"),
969        ];
970        let expected = b"abcdefghijklmn";
971        for offset in 0..=expected.len() {
972            for len in 0..=expected.len() - offset {
973                let mut buf = rope_buf(&segments);
974                buf.advance(offset);
975                assert_eq!(buf.copy_to_bytes(len), &expected[offset..offset + len]);
976                assert_eq!(buf.remaining(), expected.len() - offset - len);
977                let remaining = buf.remaining();
978                assert_eq!(buf.copy_to_bytes(remaining), &expected[offset + len..]);
979                assert!(buf.chunk().is_empty());
980            }
981        }
982    }
983
984    #[test]
985    fn rope_buf_copy_to_bytes_take_preserves_limit_and_sharing() {
986        let payload = Bytes::from_static(b"abcdefgh");
987        let mut buf = rope_buf(core::slice::from_ref(&payload));
988        let mut limited = (&mut buf).take(3);
989        let copied = limited.copy_to_bytes(2);
990        assert_eq!(copied.as_ptr(), payload.as_ptr());
991        assert_eq!(copied, &b"ab"[..]);
992        assert_eq!(limited.remaining(), 1);
993        assert_eq!(limited.copy_to_bytes(1), &b"c"[..]);
994        assert_eq!(limited.remaining(), 0);
995        assert_eq!(buf.remaining(), 5);
996        assert_eq!(buf.chunk(), b"defgh");
997    }
998
999    #[cfg(feature = "std")]
1000    #[test]
1001    fn rope_buf_copy_to_bytes_updates_vectored_chunks() {
1002        let segments = [Bytes::from_static(b"abc"), Bytes::from_static(b"def")];
1003        let mut buf = rope_buf(&segments);
1004        assert_eq!(buf.copy_to_bytes(3), &b"abc"[..]);
1005        {
1006            let mut slices = [std::io::IoSlice::new(&[]); 2];
1007            assert_eq!(buf.chunks_vectored(&mut slices), 1);
1008            assert_eq!(slices[0].as_ref(), b"def");
1009        }
1010        assert_eq!(buf.copy_to_bytes(3), &b"def"[..]);
1011        let mut slices = [std::io::IoSlice::new(&[]); 2];
1012        assert_eq!(buf.chunks_vectored(&mut slices), 0);
1013    }
1014
1015    #[test]
1016    #[should_panic(expected = "copy_to_bytes past end of RopeBuf")]
1017    fn rope_buf_copy_to_bytes_rejects_overread() {
1018        let mut buf = rope_buf(&[Bytes::from_static(b"a"), Bytes::from_static(b"bc")]);
1019        buf.copy_to_bytes(4);
1020    }
1021
1022    #[test]
1023    #[should_panic(expected = "copy_to_bytes past end of RopeBuf")]
1024    fn rope_buf_copy_to_bytes_rejects_read_from_empty_buffer() {
1025        let mut buf = RopeBuf::from(Rope::new());
1026        buf.copy_to_bytes(1);
1027    }
1028
1029    /// `min_segment = usize::MAX` degrades to fully contiguous output.
1030    #[test]
1031    fn max_threshold_never_segments() {
1032        let mut rope = Rope::with_min_segment(usize::MAX);
1033        rope.put_shared(Bytes::from(crate::alloc::vec![1u8; 1024]));
1034        rope.put_slice(&crate::alloc::vec![2u8; 1024]);
1035        assert_eq!(rope.segment_count(), 1);
1036    }
1037
1038    // ── Pre-sized cursor and contiguous writes ─────────────────────────
1039
1040    /// 1 + 3 + 4 + 8 = 16 bytes through every write primitive.
1041    const PAYLOAD_LEN: usize = 16;
1042
1043    fn write_payload<S: EncodeSink>(sink: &mut S) {
1044        sink.put_u8(0xAA);
1045        sink.put_slice(b"abc");
1046        sink.put_u32_le(0x0403_0201);
1047        sink.put_u64_le(0x0807_0605_0403_0201);
1048    }
1049
1050    fn payload() -> Vec<u8> {
1051        let mut expected = Vec::new();
1052        write_payload(&mut expected);
1053        assert_eq!(expected.len(), PAYLOAD_LEN);
1054        expected
1055    }
1056
1057    /// Which closure `write_contiguous` ran.
1058    #[derive(Debug, PartialEq)]
1059    enum Ran {
1060        Cursor,
1061        Sink,
1062        Neither,
1063    }
1064
1065    fn run<S: EncodeSink>(size: usize, buf: &mut S) -> Ran {
1066        let ran = core::cell::Cell::new(Ran::Neither);
1067        write_contiguous(
1068            size,
1069            &mut crate::SizeCache::new(),
1070            buf,
1071            |_, cursor| {
1072                ran.set(Ran::Cursor);
1073                write_payload(cursor);
1074            },
1075            |_, sink| {
1076                ran.set(Ran::Sink);
1077                write_payload(sink);
1078            },
1079        );
1080        ran.into_inner()
1081    }
1082
1083    #[test]
1084    fn pre_sized_matches_vec_for_every_write() {
1085        let mut storage = [MaybeUninit::<u8>::uninit(); PAYLOAD_LEN];
1086        let mut cursor = PreSized::new(&mut storage);
1087        write_payload(&mut cursor);
1088        assert_eq!(cursor.written(), PAYLOAD_LEN);
1089        // SAFETY: the cursor initialised all `PAYLOAD_LEN` bytes.
1090        let got: Vec<u8> = storage.iter().map(|b| unsafe { b.assume_init() }).collect();
1091        assert_eq!(got, payload());
1092    }
1093
1094    #[test]
1095    #[should_panic(expected = "more bytes than compute_size declared")]
1096    fn pre_sized_put_u8_past_end_panics() {
1097        let mut storage = [MaybeUninit::<u8>::uninit(); 1];
1098        let mut cursor = PreSized::new(&mut storage);
1099        cursor.put_u8(1);
1100        cursor.put_u8(2);
1101    }
1102
1103    #[test]
1104    #[should_panic(expected = "more bytes than compute_size declared")]
1105    fn pre_sized_put_slice_past_end_panics() {
1106        let mut storage = [MaybeUninit::<u8>::uninit(); 2];
1107        PreSized::new(&mut storage).put_slice(b"abc");
1108    }
1109
1110    #[test]
1111    #[should_panic(expected = "more bytes than compute_size declared")]
1112    fn pre_sized_fixed_width_past_end_panics() {
1113        let mut storage = [MaybeUninit::<u8>::uninit(); 7];
1114        PreSized::new(&mut storage).put_u64_le(1);
1115    }
1116
1117    #[test]
1118    fn spare_capacity_is_filled_in_place() {
1119        let mut sink = Probe {
1120            inner: Vec::with_capacity(64),
1121            ..Probe::default()
1122        };
1123        sink.inner.extend_from_slice(b"prefix");
1124        assert_eq!(run(PAYLOAD_LEN, &mut sink), Ran::Cursor);
1125        assert_eq!(sink.put_slice_calls, 0, "no scratch buffer");
1126        assert_eq!(sink.advance_mut_calls, 1);
1127        assert_eq!(&sink.inner[..6], b"prefix");
1128        assert_eq!(&sink.inner[6..], &payload()[..]);
1129        assert_eq!(sink.inner.capacity(), 64, "the sink did not grow");
1130    }
1131
1132    /// A chunk shorter than the message (an empty `Vec` offers 64 bytes, a
1133    /// chain offers its first buffer) is filled through one `put_slice`.
1134    #[test]
1135    fn short_chunk_is_filled_through_a_scratch_buffer() {
1136        let mut sink = Probe {
1137            chunk_limit: Some(PAYLOAD_LEN - 1),
1138            ..Probe::default()
1139        };
1140        assert_eq!(run(PAYLOAD_LEN, &mut sink), Ran::Cursor);
1141        assert_eq!(sink.advance_mut_calls, 0);
1142        assert_eq!(sink.put_slice_calls, 1);
1143        assert_eq!(sink.inner, payload());
1144    }
1145
1146    #[test]
1147    fn chained_buffers_receive_the_bytes_across_the_boundary() {
1148        let mut head = [0u8; 4];
1149        let mut tail = Vec::new();
1150        let mut sink = (&mut head[..]).chain_mut(&mut tail);
1151        assert_eq!(run(PAYLOAD_LEN, &mut sink), Ran::Cursor);
1152        let expected = payload();
1153        assert_eq!(head, expected[..4]);
1154        assert_eq!(tail, expected[4..]);
1155    }
1156
1157    #[test]
1158    fn bytes_mut_and_slice_sinks_receive_the_same_bytes() {
1159        let expected = payload();
1160
1161        let mut bytes_mut = BytesMut::with_capacity(PAYLOAD_LEN);
1162        assert_eq!(run(PAYLOAD_LEN, &mut bytes_mut), Ran::Cursor);
1163        assert_eq!(&bytes_mut[..], &expected[..]);
1164
1165        let mut storage = [0u8; PAYLOAD_LEN];
1166        let mut slice: &mut [u8] = &mut storage;
1167        assert_eq!(run(PAYLOAD_LEN, &mut slice), Ran::Cursor);
1168        assert_eq!(
1169            slice.len(),
1170            0,
1171            "the slice sink was advanced past the message"
1172        );
1173        assert_eq!(&storage[..], &expected[..]);
1174    }
1175
1176    /// The panic text belongs to `bytes`, so only the panic is asserted.
1177    #[test]
1178    #[should_panic]
1179    fn slice_sink_too_small_still_panics() {
1180        let mut storage = [0u8; PAYLOAD_LEN - 1];
1181        let mut slice: &mut [u8] = &mut storage;
1182        run(PAYLOAD_LEN, &mut slice);
1183    }
1184
1185    #[test]
1186    fn empty_message_appends_nothing() {
1187        let mut sink = Probe::default();
1188        write_contiguous(
1189            0,
1190            &mut crate::SizeCache::new(),
1191            &mut sink,
1192            |_, _| {},
1193            |_, _| unreachable!("a `BufMut` is written through the cursor"),
1194        );
1195        assert!(sink.inner.is_empty());
1196        assert_eq!(sink.chunk_mut_calls, 0);
1197        assert_eq!(sink.put_slice_calls, 0);
1198    }
1199
1200    /// A type that implements `EncodeSink` and not `BufMut` keeps receiving
1201    /// each write individually.
1202    #[test]
1203    fn direct_encode_sink_receives_every_write() {
1204        #[derive(Default)]
1205        struct Recording {
1206            puts: Vec<&'static str>,
1207            bytes: Vec<u8>,
1208        }
1209        impl EncodeSink for Recording {
1210            fn put_u8(&mut self, v: u8) {
1211                self.puts.push("u8");
1212                self.bytes.push(v);
1213            }
1214            fn put_slice(&mut self, src: &[u8]) {
1215                self.puts.push("slice");
1216                self.bytes.extend_from_slice(src);
1217            }
1218            fn put_u32_le(&mut self, v: u32) {
1219                self.puts.push("u32");
1220                self.bytes.extend_from_slice(&v.to_le_bytes());
1221            }
1222            fn put_u64_le(&mut self, v: u64) {
1223                self.puts.push("u64");
1224                self.bytes.extend_from_slice(&v.to_le_bytes());
1225            }
1226        }
1227
1228        let mut sink = Recording::default();
1229        assert_eq!(run(PAYLOAD_LEN, &mut sink), Ran::Sink);
1230        assert_eq!(sink.puts, ["u8", "slice", "u32", "u64"]);
1231        assert_eq!(sink.bytes, payload());
1232    }
1233
1234    /// Segmented sinks take the per-write path, so `Rope` still sees each write.
1235    #[test]
1236    fn rope_takes_the_sink_path() {
1237        let mut rope = Rope::new();
1238        assert_eq!(run(PAYLOAD_LEN, &mut rope), Ran::Sink);
1239        assert_eq!(&rope.to_contiguous_bytes()[..], &payload()[..]);
1240    }
1241
1242    #[cfg(debug_assertions)]
1243    #[test]
1244    #[should_panic(expected = "two-pass traversal mismatch")]
1245    fn under_writing_is_caught_in_debug_builds() {
1246        write_contiguous(
1247            10,
1248            &mut crate::SizeCache::new(),
1249            &mut Vec::with_capacity(32),
1250            |_, cursor| cursor.put_slice(b"abc"),
1251            |_, _| unreachable!("a Vec is written through the cursor"),
1252        );
1253    }
1254
1255    #[test]
1256    fn write_to_new_vec_is_exactly_sized() {
1257        let vec = write_to_new_vec(PAYLOAD_LEN, |cursor| write_payload(cursor));
1258        assert_eq!(vec, payload());
1259        assert_eq!(vec.capacity(), PAYLOAD_LEN);
1260    }
1261
1262    #[test]
1263    fn under_writing_publishes_only_the_written_bytes() {
1264        let mut vec = Vec::with_capacity(32);
1265        assert!(vec
1266            .__write_pre_sized(10, |cursor| cursor.put_slice(b"abc"))
1267            .is_ok());
1268        assert_eq!(vec, b"abc");
1269
1270        let scratch = write_to_new_vec(10, |cursor| cursor.put_slice(b"abc"));
1271        assert_eq!(scratch, b"abc");
1272        assert_eq!(scratch.capacity(), 10);
1273    }
1274
1275    #[cfg(feature = "std")]
1276    #[test]
1277    fn a_panic_mid_write_leaves_the_sink_unchanged() {
1278        let mut vec = Vec::with_capacity(32);
1279        vec.extend_from_slice(b"kept");
1280        let result = std::panic::catch_unwind(core::panic::AssertUnwindSafe(|| {
1281            let _ = vec.__write_pre_sized(8, |cursor| {
1282                cursor.put_slice(b"abc");
1283                panic!("write_to failed");
1284            });
1285        }));
1286        assert!(result.is_err());
1287        assert_eq!(vec, b"kept");
1288    }
1289
1290    #[test]
1291    fn limit_sink_is_filled_within_its_limit() {
1292        let mut sink = Vec::new().limit(PAYLOAD_LEN);
1293        assert_eq!(run(PAYLOAD_LEN, &mut sink), Ran::Cursor);
1294        assert_eq!(sink.remaining_mut(), 0);
1295        assert_eq!(sink.into_inner(), payload());
1296    }
1297
1298    #[test]
1299    #[should_panic(expected = "more bytes than compute_size declared")]
1300    fn empty_message_that_writes_anyway_panics() {
1301        run(0, &mut Vec::<u8>::new());
1302    }
1303}