Skip to main content

ntex_bytes/
pages.rs

1#![allow(clippy::missing_panics_doc, clippy::box_collection)]
2use std::{borrow::Borrow, cell::Cell, cmp, collections::VecDeque, fmt, io, mem, ops};
3
4use crate::{Buf, BufMut, BytePageSize, ByteString, Bytes, BytesMut};
5use crate::{buf::UninitSlice, stvec::StorageVec};
6
7/// A growable sequence of byte pages.
8///
9/// Data is stored in fixed-capacity pages selected by [`BytePageSize`]. This
10/// avoids reallocating and copying one large contiguous buffer as data grows.
11pub struct BytePages {
12    st: Option<Box<Inner>>,
13    current: Option<StorageVec>,
14}
15
16#[derive(Debug)]
17struct Inner {
18    size: BytePageSize,
19    /// Total length of `pages`, so `len()` does not walk them.
20    len: usize,
21    pages: VecDeque<BytePage>,
22}
23
24thread_local! {
25    static CACHE: Cell<Option<Box<Vec<Box<Inner>>>>> = Cell::new(Some(Box::default()));
26}
27const CACHE_SIZE: usize = 128;
28
29/// Appended data up to this size is copied into the current page.
30const APPEND_COPY_LIMIT: usize = 4096;
31
32impl BytePages {
33    /// Creates a new `BytePages` with the specified page size.
34    ///
35    /// Pages are allocated lazily using the specified capacity category. Like
36    /// [`BytesMut::with_page_size`], a new page can be a cached page of the
37    /// next smaller size.
38    ///
39    /// # Panics
40    ///
41    /// Panics if `size` is [`BytePageSize::Unset`].
42    pub fn new(size: BytePageSize) -> Self {
43        assert!(size != BytePageSize::Unset, "Page size cannot be Unset");
44
45        // the cache is unavailable while the thread-local is being destroyed
46        let cached = CACHE
47            .try_with(|c| {
48                let mut cache = c.take()?;
49                let item = cache.pop();
50                c.set(Some(cache));
51                item
52            })
53            .ok()
54            .flatten();
55
56        let st = if let Some(mut item) = cached {
57            item.size = size;
58            item
59        } else {
60            Box::new(Inner {
61                size,
62                len: 0,
63                pages: VecDeque::with_capacity(8),
64            })
65        };
66
67        BytePages {
68            st: Some(st),
69            current: None,
70        }
71    }
72
73    fn pages(&self) -> &VecDeque<BytePage> {
74        &self.st.as_ref().unwrap().pages
75    }
76
77    // Pages are only added and removed through these methods, which keep
78    // `Inner::len` up to date. A page in the list is never modified in place.
79    fn push_front(&mut self, page: BytePage) {
80        let st = self.st.as_mut().unwrap();
81        st.len += page.len();
82        st.pages.push_front(page);
83    }
84
85    fn pop_front(&mut self) -> Option<BytePage> {
86        let st = self.st.as_mut().unwrap();
87        let page = st.pages.pop_front()?;
88        st.len -= page.len();
89        Some(page)
90    }
91
92    fn push_back(&mut self, page: BytePage) {
93        let st = self.st.as_mut().unwrap();
94        st.len += page.len();
95        st.pages.push_back(page);
96    }
97
98    /// Returns the capacity category used for new pages.
99    pub fn page_size(&self) -> BytePageSize {
100        self.st.as_ref().unwrap().size
101    }
102
103    /// Sets the page size for new pages.
104    ///
105    /// # Panics
106    ///
107    /// Panics if `size` is [`BytePageSize::Unset`].
108    pub fn set_page_size(&mut self, size: BytePageSize) {
109        assert!(size != BytePageSize::Unset, "Page size cannot be Unset");
110        self.st.as_mut().unwrap().size = size;
111    }
112
113    /// Inserts a non-empty page at the front of the collection.
114    ///
115    /// Returns whether a page was inserted.
116    pub fn prepend<T>(&mut self, buf: T) -> bool
117    where
118        BytePage: From<T>,
119    {
120        let p = BytePage::from(buf);
121        if p.is_empty() {
122            false
123        } else {
124            self.push_front(p);
125            true
126        }
127    }
128
129    /// Appends a page to the back of the collection.
130    ///
131    /// Empty pages are ignored. If the current page holds no data and `buf` is
132    /// a unique buffer with spare capacity, it becomes the new current page.
133    /// Data of up to 4 KiB is copied into the current page, and into new
134    /// pages as needed. Larger data is added as a separate page without
135    /// copying: the filled part of the current page is split off in front of
136    /// it, and the spare capacity of the current page stays available for
137    /// later writes.
138    pub fn append<T>(&mut self, buf: T)
139    where
140        BytePage: From<T>,
141    {
142        let p = BytePage::from(buf);
143        if !p.is_empty() {
144            if self.current_len() == 0 {
145                match p.into_storage() {
146                    Ok(st) => {
147                        self.current = Some(st);
148                    }
149                    Err(page) => {
150                        // add buffer to the page list
151                        self.push_back(page);
152                    }
153                }
154            } else if p.len() <= APPEND_COPY_LIMIT {
155                self.put_slice(p.as_ref());
156            } else {
157                // the spare capacity of the current page is kept
158                if let Some(st) = self.current.as_mut() {
159                    let head = st.split_to(st.len());
160                    self.push_back(<BytePage as From<Bytes>>::from(Bytes { storage: head }));
161                }
162                self.push_back(p);
163            }
164        }
165    }
166
167    #[inline]
168    /// Appends the given bytes to this page object.
169    ///
170    /// Tries to write the data into the current page first. If there
171    /// is insufficient space, one or more new pages are allocated as
172    /// needed, and the remaining data is copied into them.
173    pub fn extend_from_slice(&mut self, extend: &[u8]) {
174        self.put_slice(extend);
175    }
176
177    /// Appends the given slices in order.
178    ///
179    /// The result is the same as calling [`put_slice`](BufMut::put_slice) for
180    /// each slice. If all slices fit into the current page, the free space is
181    /// checked once and the slices are copied straight into it.
182    ///
183    /// # Examples
184    ///
185    /// ```
186    /// use ntex_bytes::{BytePages, BytePageSize};
187    ///
188    /// let mut pages = BytePages::new(BytePageSize::Size8);
189    /// pages.put_slices(&[b"content-type", b": ", b"text/plain", b"\r\n"]);
190    ///
191    /// assert_eq!(pages.freeze(), b"content-type: text/plain\r\n"[..]);
192    /// ```
193    pub fn put_slices(&mut self, src: &[&[u8]]) {
194        let len = src.iter().map(|s| s.len()).sum::<usize>();
195
196        // a small write that leaves the current page non-full is copied in place
197        if let Some(st) = self.current.as_mut()
198            && st.remaining() > len
199        {
200            let start = st.len();
201            let spare = st.spare_mut();
202            let mut pos = 0;
203            for s in src {
204                spare[pos..pos + s.len()].copy_from_slice(s);
205                pos += s.len();
206            }
207            // SAFETY: the copies above initialized `len` bytes after `start`
208            unsafe { st.set_len(start + len) };
209        } else {
210            for s in src {
211                self.put_slice(s);
212            }
213        }
214    }
215
216    #[inline]
217    /// Returns the total number of buffered bytes.
218    pub fn len(&self) -> usize {
219        self.st.as_ref().unwrap().len + self.current_len()
220    }
221
222    fn current_len(&self) -> usize {
223        self.current
224            .as_ref()
225            .map(StorageVec::len)
226            .unwrap_or_default()
227    }
228
229    // spare capacity of the current page
230    fn spare(&self) -> usize {
231        self.current
232            .as_ref()
233            .map(StorageVec::remaining)
234            .unwrap_or_default()
235    }
236
237    #[inline]
238    /// Returns `true` if no bytes are buffered.
239    pub fn is_empty(&self) -> bool {
240        self.len() == 0
241    }
242
243    #[inline]
244    /// Returns the number of allocated pages containing buffered data.
245    pub fn num_pages(&self) -> usize {
246        if self.current_len() == 0 {
247            self.pages().len()
248        } else {
249            self.pages().len() + 1
250        }
251    }
252
253    /// Removes and returns the first page from the collection.
254    ///
255    /// The current writable page is returned last. Returns `None` if there are
256    /// no pages with data, an empty current page keeps its spare capacity for
257    /// later writes.
258    pub fn take(&mut self) -> Option<BytePage> {
259        if let Some(page) = self.pop_front() {
260            Some(page)
261        } else if self.current_len() == 0 {
262            None
263        } else {
264            self.current.take().map(BytePage::from)
265        }
266    }
267
268    /// Returns an iterator over the buffered data, one slice per page.
269    ///
270    /// The current writable page is yielded last, if it holds data. The
271    /// pages are stored on the heap, so their data stays at the same address
272    /// when `self` is moved, until `self` is modified or dropped.
273    pub fn iter(&self) -> impl Iterator<Item = &[u8]> {
274        self.pages().iter().map(BytePage::as_ref).chain(
275            self.current
276                .as_ref()
277                .map(StorageVec::as_ref)
278                .filter(|s| !s.is_empty()),
279        )
280    }
281
282    /// Advance the internal cursor.
283    ///
284    /// Afterwards `self` contains elements `[cnt, len)`. Fully consumed pages
285    /// are dropped, the current writable page keeps its spare capacity.
286    ///
287    /// # Panics
288    ///
289    /// Panics if `cnt > len`.
290    pub fn advance_to(&mut self, mut cnt: usize) {
291        assert!(
292            cnt <= self.len(),
293            "cannot advance past the end of the buffer, cnt:{cnt} len:{}",
294            self.len()
295        );
296
297        while cnt > 0
298            && let Some(mut page) = self.pop_front()
299        {
300            if cnt < page.len() {
301                page.advance_to(cnt);
302                self.push_front(page);
303                return;
304            }
305            cnt -= page.len();
306        }
307        if cnt > 0
308            && let Some(st) = self.current.as_mut()
309        {
310            // SAFETY: `cnt <= st.len()`, checked by the assert above
311            unsafe { st.set_start(cnt) };
312        }
313    }
314
315    #[inline]
316    /// Appends all buffered data to another [`BytePages`] value, `self` is
317    /// left unchanged.
318    ///
319    /// Pages are shared with `pages` rather than copied, unless they are small
320    /// enough to be copied into the current page of `pages`, see
321    /// [`append`](Self::append).
322    pub fn copy_to(&self, pages: &mut BytePages) {
323        for p in self.pages() {
324            pages.append(p.clone());
325        }
326
327        if let Some(st) = &self.current {
328            // an immutable view, `st` stays the only handle that can write
329            // to the spare capacity
330            pages.append(Bytes {
331                storage: st.shallow_freeze(),
332            });
333        }
334    }
335
336    /// Moves all buffered data to the back of another [`BytePages`] value,
337    /// leaving `self` empty.
338    ///
339    /// Pages are moved as is, without merging. If the current page of `self`
340    /// is 8 KiB or bigger (for a buffer without a page size, its capacity is
341    /// at least 8 KiB) and holds less than 4 KiB, its data is copied into
342    /// the current page of `pages` if it fits there, so a mostly empty page
343    /// is not kept alive, and `self` keeps that page for later writes.
344    /// Otherwise the current page of `self` is moved as a regular page.
345    /// Nothing is allocated. The filled part of
346    /// the current page of `pages` is split off in front of moved pages, its
347    /// spare capacity stays available for later writes.
348    pub fn move_to(&mut self, pages: &mut BytePages) {
349        if self.is_empty() {
350            return;
351        }
352
353        let len = self.current_len();
354        let copy = len != 0
355            && len < APPEND_COPY_LIMIT
356            && len < pages.spare()
357            && self
358                .current
359                .as_ref()
360                .is_some_and(|st| match st.page_size() {
361                    BytePageSize::Size4 => false,
362                    BytePageSize::Unset => st.capacity() >= 8 * 1024,
363                    _ => true,
364                });
365
366        if !self.pages().is_empty() {
367            pages.split_current();
368            let src = self.st.as_mut().unwrap();
369            let dst = pages.st.as_mut().unwrap();
370            if dst.pages.is_empty() {
371                mem::swap(&mut src.pages, &mut dst.pages);
372                dst.len = mem::take(&mut src.len);
373            } else {
374                while let Some(page) = self.pop_front() {
375                    pages.push_back(page);
376                }
377            }
378        }
379
380        if copy {
381            let st = self.current.as_mut().unwrap();
382            pages.put_slice(st.as_ref());
383            // a clone of `self` can still share the copied data, so the start
384            // is moved past it, `truncate` reclaims the page only if it is unique
385            // SAFETY: `len` is the length of the current page
386            unsafe { st.set_start(len) };
387            st.truncate(0);
388        } else if len != 0
389            && let Some(st) = self.current.take()
390        {
391            pages.split_current();
392            pages.push_back(BytePage::from(st));
393        }
394    }
395
396    // moves the filled part of the current page to the page list,
397    // the spare capacity stays in the current page
398    fn split_current(&mut self) {
399        if let Some(st) = self.current.as_mut()
400            && st.len() != 0
401        {
402            let head = st.split_to(st.len());
403            self.push_back(<BytePage as From<Bytes>>::from(Bytes { storage: head }));
404        }
405    }
406
407    /// Splits the buffer into two at the given index.
408    ///
409    /// Afterwards, `self` contains elements `[at, len)`, and the returned [`BytePages`]
410    /// contains elements `[0, at)`. If `at > len`, all data is moved.
411    ///
412    /// Unlike [`Bytes::split_to`] and [`BytesMut::split_to`](crate::BytesMut::split_to),
413    /// which panic when `at` is out of bounds, this clamps `at` to the length.
414    /// Check `len()` first if a short split is an error.
415    ///
416    /// Depending on the underlying storage, this operation might be `O(1)` or could
417    /// involve a memory copy.
418    #[must_use]
419    pub fn split_to(&mut self, at: usize) -> BytePages {
420        let mut pages = BytePages::new(self.page_size());
421        self.split_into(at, &mut pages);
422        pages
423    }
424
425    /// Splits the buffer, adding the resulting items to the supplied pages object.
426    ///
427    /// Afterwards, `self` contains elements `[at, len)`, and elements `[0, at)`
428    /// are appended to `to`. If `at > len`, all data is moved.
429    ///
430    /// Like [`split_to`](Self::split_to), this clamps `at` to the length instead
431    /// of panicking.
432    ///
433    /// Depending on the underlying storage, this operation might be `O(1)` or could
434    /// involve a memory copy.
435    pub fn split_into(&mut self, mut at: usize, to: &mut BytePages) {
436        while let Some(mut page) = self.pop_front() {
437            let len = cmp::min(page.len(), at);
438            to.append(page.split_to(len));
439
440            if !page.is_empty() {
441                self.push_front(page);
442                return;
443            }
444            at -= len;
445        }
446        if at > 0
447            && let Some(mut st) = self.current.take()
448        {
449            if at < st.len() {
450                // the remainder stays writable, so its spare capacity is kept
451                to.append(Bytes {
452                    storage: st.split_to(at),
453                });
454                self.current = Some(st);
455            } else if st.len() == 0 {
456                self.current = Some(st);
457            } else {
458                to.append(BytePage::from(st));
459            }
460        }
461    }
462
463    /// Clears the buffer, removing all data.
464    #[inline]
465    pub fn clear(&mut self) {
466        while self.take().is_some() {}
467    }
468
469    /// Drains all pages into one immutable [`Bytes`] value.
470    #[inline]
471    #[must_use]
472    pub fn freeze(&mut self) -> Bytes {
473        let pages = self.num_pages();
474        if pages == 0 || self.is_empty() {
475            Bytes::new()
476        } else if pages == 1 {
477            self.take().unwrap().freeze()
478        } else {
479            let mut buf = BytesMut::with_capacity(self.len());
480            while let Some(p) = self.take() {
481                buf.extend_from_slice(&p);
482            }
483            buf.freeze()
484        }
485    }
486
487    #[inline]
488    /// Moves the current writable page from `pages` if this value is empty.
489    pub fn try_get_current_from(&mut self, pages: &mut BytePages) {
490        if self.pages().is_empty()
491            && self.current.is_none()
492            && let Some(st) = pages.current.take()
493        {
494            self.current = Some(st);
495        }
496    }
497
498    /// Passes a new mutable buffer to `f` and appends its contents.
499    ///
500    /// After `f` returns, the buffer is appended according to the rules of
501    /// [`append`](Self::append). Existing pages and the current writable page
502    /// are not exposed to `f`. If `f` panics, the temporary buffer is dropped
503    /// and this collection is unchanged.
504    ///
505    /// This is a low-level API intended for ntex internals and may change
506    /// without notice.
507    #[doc(hidden)]
508    #[deprecated(
509        since = "1.10.0",
510        note = "use the `BufMut` methods of `BytePages` instead"
511    )]
512    pub fn with_bytes_mut<F, R>(&mut self, f: F) -> R
513    where
514        F: FnOnce(&mut BytesMut) -> R,
515    {
516        let mut buf = BytesMut::new();
517        let res = f(&mut buf);
518        self.append(buf);
519        res
520    }
521
522    // Returns the current page if it has spare capacity, or a new page.
523    //
524    // The current page can be full, for example after `advance_mut` filled
525    // it, a full page moves to the page list, an empty one is dropped.
526    fn take_writable(&mut self) -> StorageVec {
527        match self.current.take() {
528            Some(st) if !st.is_full() => st,
529            Some(st) => {
530                if st.len() != 0 {
531                    self.push_back(BytePage::from(st));
532                }
533                StorageVec::sized(self.page_size())
534            }
535            None => StorageVec::sized(self.page_size()),
536        }
537    }
538
539    fn with_current<F, R>(&mut self, f: F) -> R
540    where
541        F: FnOnce(&mut StorageVec) -> R,
542    {
543        let mut st = self.take_writable();
544        let result = f(&mut st);
545
546        // a full page moves to the page list
547        if st.is_full() {
548            self.push_back(BytePage::from(st));
549        } else {
550            self.current = Some(st);
551        }
552
553        result
554    }
555}
556
557impl Drop for BytePages {
558    fn drop(&mut self) {
559        if let Some(mut st) = self.st.take() {
560            st.pages.clear();
561            // a large write must not pin its page list in the cache
562            st.pages.shrink_to(8);
563            st.len = 0;
564            // the cache is unavailable while the thread-local is being destroyed
565            let _ = CACHE.try_with(move |c| {
566                if let Some(mut cache) = c.take() {
567                    if cache.len() < CACHE_SIZE {
568                        cache.push(st);
569                    }
570                    c.set(Some(cache));
571                }
572            });
573        }
574    }
575}
576
577impl fmt::Debug for BytePages {
578    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
579        let mut f = fmt.debug_tuple("BytePages");
580        for p in self.pages() {
581            f.field(p);
582        }
583        if let Some(st) = &self.current {
584            f.field(&crate::debug::BsDebug(st.as_ref()));
585        }
586        f.finish()
587    }
588}
589
590impl Default for BytePages {
591    fn default() -> Self {
592        BytePages::new(BytePageSize::Size8)
593    }
594}
595
596/// Pages are allocated on demand, so `remaining_mut()` reports
597/// `usize::MAX - len` and `chunk_mut()` is never empty. The chunk covers the
598/// spare capacity of the current page only.
599impl BufMut for BytePages {
600    #[inline]
601    fn remaining_mut(&self) -> usize {
602        usize::MAX - self.len()
603    }
604
605    #[inline]
606    unsafe fn advance_mut(&mut self, cnt: usize) {
607        if cnt == 0 {
608            return;
609        }
610        let spare = self.spare();
611        assert!(
612            cnt <= spare,
613            "cannot advance past the current page: {cnt:?} <= {spare:?}"
614        );
615        let st = self.current.as_mut().unwrap();
616        st.set_len(st.len() + cnt);
617    }
618
619    #[inline]
620    fn chunk_mut(&mut self) -> &mut UninitSlice {
621        let st = self.take_writable();
622        self.current.insert(st).spare_mut()
623    }
624
625    fn put<T: Buf>(&mut self, mut src: T)
626    where
627        Self: Sized,
628    {
629        while src.has_remaining() {
630            let chunk = src.chunk();
631            let len = chunk.len();
632            self.put_slice(chunk);
633            src.advance(len);
634        }
635    }
636
637    #[inline]
638    fn put_slice(&mut self, src: &[u8]) {
639        // a small write that leaves the current page non-full is copied in place
640        if let Some(st) = self.current.as_mut()
641            && st.remaining() > src.len()
642        {
643            st.put_slice_partial(src);
644        } else {
645            self.put_slice_pages(src);
646        }
647    }
648
649    #[inline]
650    fn put_u8(&mut self, n: u8) {
651        self.with_current(|st| st.put_u8(n));
652    }
653
654    #[inline]
655    fn put_i8(&mut self, n: i8) {
656        self.put_u8(n as u8);
657    }
658}
659
660impl BytePages {
661    fn put_slice_pages(&mut self, mut src: &[u8]) {
662        while !src.is_empty() {
663            let amount = self.with_current(|st| st.put_slice_partial(src));
664
665            src = &src[amount..];
666        }
667    }
668}
669
670impl Clone for BytePages {
671    fn clone(&self) -> Self {
672        let size = self.page_size();
673        let mut pages = BytePages::new(size);
674        self.copy_to(&mut pages);
675        pages
676    }
677}
678
679impl io::Write for BytePages {
680    fn write(&mut self, src: &[u8]) -> Result<usize, io::Error> {
681        self.put_slice(src);
682        Ok(src.len())
683    }
684
685    fn flush(&mut self) -> Result<(), io::Error> {
686        Ok(())
687    }
688}
689
690impl From<BytePages> for Bytes {
691    /// A single page is converted without copying.
692    fn from(mut pages: BytePages) -> Bytes {
693        pages.freeze()
694    }
695}
696
697impl From<BytePages> for BytesMut {
698    /// A single page is converted without copying if nothing else refers to
699    /// its buffer.
700    fn from(mut pages: BytePages) -> BytesMut {
701        if pages.num_pages() == 1 {
702            return BytesMut::from(pages.take().unwrap());
703        }
704
705        let mut buf = BytesMut::with_capacity(pages.len());
706        while let Some(p) = pages.take() {
707            buf.extend_from_slice(&p);
708        }
709        buf
710    }
711}
712
713/// A contiguous chunk stored by [`BytePages`].
714pub struct BytePage {
715    inner: StorageType,
716}
717
718enum StorageType {
719    Bytes(Bytes),
720    Storage(StorageVec),
721    Vec(Vec<u8>),
722}
723
724impl BytePage {
725    #[inline]
726    /// Returns the number of bytes contained in this `BytePage`.
727    pub fn len(&self) -> usize {
728        self.as_ref().len()
729    }
730
731    #[inline]
732    /// Returns `true` if the page is empty.
733    pub fn is_empty(&self) -> bool {
734        self.len() == 0
735    }
736
737    #[inline]
738    /// Returns a raw pointer to the data.
739    ///
740    /// # Safety
741    ///
742    /// The returned pointer may only be dereferenced while the page is neither
743    /// moved, modified nor dropped, and only for [`len`](Self::len) bytes. An
744    /// inline page stores its data inside the `BytePage` itself, so moving the
745    /// page invalidates the pointer, see [`is_inline`](Self::is_inline).
746    pub unsafe fn as_ptr(&self) -> *const u8 {
747        // SAFETY: Each variant keeps its backing storage alive; the caller must preserve the page
748        // while using the pointer.
749        unsafe {
750            match &self.inner {
751                StorageType::Bytes(b) => b.storage.as_ptr(),
752                StorageType::Storage(b) => b.as_ptr(),
753                StorageType::Vec(b) => b.as_ptr(),
754            }
755        }
756    }
757
758    #[inline]
759    #[doc(hidden)]
760    /// Returns the kind of storage backing this page.
761    pub fn info(&self) -> crate::info::PageKind {
762        match &self.inner {
763            StorageType::Bytes(_) => crate::info::PageKind::Bytes,
764            StorageType::Storage(_) => crate::info::PageKind::Storage,
765            StorageType::Vec(_) => crate::info::PageKind::Vec,
766        }
767    }
768
769    #[inline]
770    #[doc(hidden)]
771    /// Returns `true` if the data is stored inside the `BytePage` itself.
772    ///
773    /// Moving an inline page moves its data, pointers from `as_ptr()` do not
774    /// survive the move.
775    pub fn is_inline(&self) -> bool {
776        matches!(&self.inner, StorageType::Bytes(b) if b.is_inline())
777    }
778
779    /// Splits the buffer into two at the given index.
780    ///
781    /// Afterwards, `self` contains elements `[at, len)`, and the returned `BytePage`
782    /// contains elements `[0, at)`. If `at > len`, all data is moved.
783    ///
784    /// Unlike [`Bytes::split_to`] and [`BytesMut::split_to`](crate::BytesMut::split_to),
785    /// which panic when `at` is out of bounds, this clamps `at` to the length.
786    /// Check `len()` first if a short split is an error.
787    ///
788    /// Depending on the underlying storage, this operation might be `O(1)` or could
789    /// involve a memory copy.
790    #[must_use]
791    pub fn split_to(&mut self, at: usize) -> BytePage {
792        match &mut self.inner {
793            StorageType::Bytes(b) => {
794                let buf = b.split_to(cmp::min(at, b.len()));
795                BytePage {
796                    inner: StorageType::Bytes(buf),
797                }
798            }
799            StorageType::Storage(_) => {
800                let inner = mem::replace(&mut self.inner, StorageType::Bytes(Bytes::new()));
801                if let StorageType::Storage(st) = inner {
802                    self.inner = StorageType::Bytes(Bytes {
803                        storage: st.freeze(),
804                    });
805                    self.split_to(at)
806                } else {
807                    unreachable!()
808                }
809            }
810            StorageType::Vec(_) => {
811                let inner = mem::replace(&mut self.inner, StorageType::Bytes(Bytes::new()));
812                if let StorageType::Vec(b) = inner {
813                    self.inner = StorageType::Bytes(Bytes::copy_from_slice(&b));
814                    self.split_to(at)
815                } else {
816                    unreachable!()
817                }
818            }
819        }
820    }
821
822    /// Advance the internal cursor.
823    ///
824    /// Afterwards `self` contains elements `[cnt, len)`.
825    /// This is an `O(1)` operation, except for pages backed by a `Vec<u8>`,
826    /// whose remaining data is copied.
827    ///
828    /// # Panics
829    ///
830    /// Panics if `cnt > len`.
831    #[inline]
832    pub fn advance_to(&mut self, cnt: usize) {
833        match &mut self.inner {
834            StorageType::Bytes(b) => b.advance_to(cnt),
835            // SAFETY: `set_start` checks `cnt <= len` before advancing within the live, exclusively
836            // owned view.
837            StorageType::Storage(b) => unsafe { b.set_start(cnt) },
838            StorageType::Vec(b) => {
839                assert!(
840                    cnt <= b.len(),
841                    "cannot advance past the end of the buffer, cnt:{cnt} len:{}",
842                    b.len()
843                );
844                self.inner = StorageType::Bytes(Bytes::copy_from_slice(&b[cnt..]));
845            }
846        }
847    }
848
849    /// Converts `self` into an immutable `Bytes`.
850    #[inline]
851    #[must_use]
852    pub fn freeze(self) -> Bytes {
853        match self.inner {
854            StorageType::Bytes(b) => b,
855            StorageType::Storage(st) => Bytes {
856                storage: st.freeze(),
857            },
858            StorageType::Vec(v) => Bytes::from(v),
859        }
860    }
861
862    fn into_storage(self) -> Result<StorageVec, Self> {
863        if let StorageType::Storage(st) = self.inner {
864            // Converting back to `StorageVec` requires uniqueness.
865            if !st.is_full() && st.is_unique() {
866                Ok(st)
867            } else {
868                Err(Self {
869                    inner: StorageType::Storage(st),
870                })
871            }
872        } else {
873            Err(self)
874        }
875    }
876}
877
878impl Clone for BytePage {
879    fn clone(&self) -> Self {
880        let inner = match &self.inner {
881            StorageType::Bytes(b) => StorageType::Bytes(b.clone()),
882            // The clone is an immutable view, `st` must stay the only
883            // handle that can modify the shared header and spare capacity
884            StorageType::Storage(st) => StorageType::Bytes(Bytes {
885                storage: st.shallow_freeze(),
886            }),
887            StorageType::Vec(b) => StorageType::Bytes(Bytes::copy_from_slice(b)),
888        };
889
890        Self { inner }
891    }
892}
893
894impl AsRef<[u8]> for BytePage {
895    #[inline]
896    fn as_ref(&self) -> &[u8] {
897        match &self.inner {
898            StorageType::Bytes(b) => b.as_ref(),
899            StorageType::Storage(b) => b.as_ref(),
900            StorageType::Vec(b) => b.as_ref(),
901        }
902    }
903}
904
905impl Borrow<[u8]> for BytePage {
906    #[inline]
907    fn borrow(&self) -> &[u8] {
908        self.as_ref()
909    }
910}
911
912impl From<Bytes> for BytePage {
913    fn from(buf: Bytes) -> Self {
914        BytePage {
915            inner: StorageType::Bytes(buf),
916        }
917    }
918}
919
920impl<'a> From<&'a Bytes> for BytePage {
921    fn from(buf: &'a Bytes) -> Self {
922        BytePage {
923            inner: StorageType::Bytes(buf.clone()),
924        }
925    }
926}
927
928impl From<BytesMut> for BytePage {
929    fn from(buf: BytesMut) -> Self {
930        BytePage {
931            inner: StorageType::Storage(buf.storage),
932        }
933    }
934}
935
936impl From<ByteString> for BytePage {
937    fn from(s: ByteString) -> Self {
938        s.into_bytes().into()
939    }
940}
941
942impl<'a> From<&'a ByteString> for BytePage {
943    fn from(s: &'a ByteString) -> Self {
944        s.clone().into_bytes().into()
945    }
946}
947
948impl From<StorageVec> for BytePage {
949    fn from(buf: StorageVec) -> Self {
950        BytePage {
951            inner: StorageType::Storage(buf),
952        }
953    }
954}
955
956impl From<Vec<u8>> for BytePage {
957    fn from(buf: Vec<u8>) -> Self {
958        BytePage {
959            inner: StorageType::Vec(buf),
960        }
961    }
962}
963
964impl From<&'static str> for BytePage {
965    fn from(buf: &'static str) -> Self {
966        Bytes::from_static(buf.as_bytes()).into()
967    }
968}
969
970impl From<&'static [u8]> for BytePage {
971    fn from(buf: &'static [u8]) -> Self {
972        Bytes::from_static(buf).into()
973    }
974}
975
976impl<const N: usize> From<&'static [u8; N]> for BytePage {
977    fn from(buf: &'static [u8; N]) -> Self {
978        Bytes::from_static(buf).into()
979    }
980}
981
982impl From<BytePage> for Bytes {
983    fn from(page: BytePage) -> Self {
984        match page.inner {
985            StorageType::Bytes(b) => b,
986            StorageType::Storage(storage) => BytesMut { storage }.freeze(),
987            StorageType::Vec(v) => Bytes::copy_from_slice(&v),
988        }
989    }
990}
991
992impl From<BytePage> for BytesMut {
993    fn from(page: BytePage) -> Self {
994        match page.inner {
995            StorageType::Bytes(b) => b.into(),
996            // clones of the page may still read the data
997            StorageType::Storage(storage) => {
998                if storage.is_unique() {
999                    BytesMut { storage }
1000                } else {
1001                    BytesMut::copy_from_slice(storage.as_ref())
1002                }
1003            }
1004            StorageType::Vec(v) => BytesMut::copy_from_slice(&v),
1005        }
1006    }
1007}
1008
1009impl PartialEq for BytePage {
1010    fn eq(&self, other: &BytePage) -> bool {
1011        self.as_ref() == other.as_ref()
1012    }
1013}
1014
1015impl_partial_eq!(BytePage);
1016
1017impl_read!(BytePage);
1018
1019impl ops::Deref for BytePage {
1020    type Target = [u8];
1021
1022    #[inline]
1023    fn deref(&self) -> &[u8] {
1024        self.as_ref()
1025    }
1026}
1027
1028impl fmt::Debug for BytePage {
1029    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1030        fmt::Debug::fmt(&crate::debug::BsDebug(self.as_ref()), fmt)
1031    }
1032}
1033
1034#[cfg(test)]
1035mod tests {
1036    use rand::Rng;
1037
1038    use super::*;
1039
1040    /// STATEMENT: `BytePage` compares by content across byte and string types and supports consuming reads.
1041    ///
1042    /// HOW:
1043    /// - Compare a vector-backed `hello` page with borrowed and owned equivalents in both directions and reject `hell`.
1044    /// - Read it into a three-byte array, checking `hel`, the `lo` remainder, short and exhausted reads, and final emptiness.
1045    #[test]
1046    #[allow(clippy::op_ref, clippy::cmp_owned)]
1047    fn page_eq_and_read() {
1048        use std::io::Read;
1049
1050        let mut page = BytePage::from(Vec::from(&b"hello"[..]));
1051        assert_eq!(page, b"hello"[..]);
1052        assert_eq!(page, *b"hello");
1053        assert_eq!(page, b"hello");
1054        assert_eq!(page, &b"hello"[..]);
1055        assert_eq!(page, "hello");
1056        assert_eq!(page, *"hello");
1057        assert_eq!(page, b"hello".to_vec());
1058        assert_eq!(page, String::from("hello"));
1059        assert_eq!(b"hello"[..], page);
1060        assert_eq!(*b"hello", page);
1061        assert_eq!(b"hello", page);
1062        assert_eq!(&b"hello"[..], page);
1063        assert_eq!("hello", page);
1064        assert_eq!(*"hello", page);
1065        assert_eq!(b"hello".to_vec(), page);
1066        assert_eq!(String::from("hello"), page);
1067        assert_ne!(page, "hell");
1068
1069        let mut buf = [0u8; 3];
1070        assert_eq!(page.read(&mut buf).unwrap(), 3);
1071        assert_eq!(&buf, b"hel");
1072        assert_eq!(page, "lo");
1073        assert_eq!(page.read(&mut buf).unwrap(), 2);
1074        assert_eq!(page.read(&mut buf).unwrap(), 0);
1075        assert!(page.is_empty());
1076    }
1077
1078    /// STATEMENT: Page metadata distinguishes bytes, mutable storage, vector storage, and inline bytes.
1079    ///
1080    /// HOW:
1081    /// - Convert 64-byte `Bytes`, `BytesMut`, and vectors and check their `PageKind` values.
1082    /// - Compare inline status for four-byte and 64-byte immutable buffers and a short mutable buffer.
1083    #[test]
1084    fn page_info() {
1085        use crate::info::PageKind;
1086
1087        let p = BytePage::from(Bytes::copy_from_slice(&[1; 64]));
1088        assert_eq!(p.info(), PageKind::Bytes);
1089        let p = BytePage::from(BytesMut::copy_from_slice(&[1; 64][..]));
1090        assert_eq!(p.info(), PageKind::Storage);
1091        let p = BytePage::from(vec![1; 64]);
1092        assert_eq!(p.info(), PageKind::Vec);
1093        assert!(!p.is_inline());
1094
1095        assert!(BytePage::from(Bytes::copy_from_slice(&[1; 4])).is_inline());
1096        assert!(!BytePage::from(Bytes::copy_from_slice(&[1; 64])).is_inline());
1097        assert!(!BytePage::from(BytesMut::copy_from_slice(&[1; 4][..])).is_inline());
1098    }
1099
1100    /// STATEMENT: Appending small data copies into the current page while large data retains its own allocation.
1101    ///
1102    /// HOW:
1103    /// - Append payloads at and above `APPEND_COPY_LIMIT` after a header and check page counts, spare capacity, and storage pointers.
1104    /// - Add a trailer, drain pages in order, compare concatenated contents, and verify an empty current page remains reusable.
1105    #[test]
1106    fn append_copies_small_and_splits_for_large() {
1107        let cap = BytePageSize::Size16.capacity();
1108        let mut pages = BytePages::new(BytePageSize::Size16);
1109        pages.extend_from_slice(b"head\r\n");
1110
1111        // small data is copied into the current page
1112        pages.append(Bytes::copy_from_slice(&[1; APPEND_COPY_LIMIT]));
1113        assert_eq!(pages.num_pages(), 1);
1114        assert_eq!(pages.current_len(), 6 + APPEND_COPY_LIMIT);
1115
1116        // large data is not copied, the filled part is split off in front
1117        let body = Bytes::copy_from_slice(&[2; APPEND_COPY_LIMIT + 1]);
1118        let body_ptr = body.as_ptr();
1119        pages.append(body.clone());
1120        assert_eq!(pages.num_pages(), 2);
1121        assert_eq!(pages.current_len(), 0);
1122        assert_eq!(pages.spare(), cap - 6 - APPEND_COPY_LIMIT);
1123
1124        // later writes use the spare capacity of the current page
1125        let page_ptr = pages.pages()[0].as_ref().as_ptr();
1126        pages.extend_from_slice(b"\r\n");
1127        assert_eq!(pages.num_pages(), 3);
1128        let tail_ptr = pages.current.as_ref().unwrap().as_ref().as_ptr();
1129        assert_eq!(tail_ptr, page_ptr.wrapping_add(6 + APPEND_COPY_LIMIT));
1130
1131        let mut expected = b"head\r\n".to_vec();
1132        expected.extend_from_slice(&[1; APPEND_COPY_LIMIT]);
1133        expected.extend_from_slice(&body);
1134        expected.extend_from_slice(b"\r\n");
1135        assert_eq!(pages.len(), expected.len());
1136
1137        let first = pages.take().unwrap();
1138        let second = pages.take().unwrap();
1139        assert_eq!(second.as_ref().as_ptr(), body_ptr);
1140        let third = pages.take().unwrap();
1141        assert!(pages.take().is_none());
1142        let data = [first.as_ref(), second.as_ref(), third.as_ref()].concat();
1143        assert_eq!(data, expected);
1144
1145        // draining the pages keeps an empty current page for later writes
1146        pages.extend_from_slice(b"x");
1147        pages.append(body);
1148        assert_eq!(pages.take().unwrap().as_ref(), b"x");
1149        assert_eq!(pages.take().unwrap().len(), APPEND_COPY_LIMIT + 1);
1150        assert!(pages.take().is_none());
1151        assert_eq!(pages.num_pages(), 0);
1152        assert_eq!(pages.spare(), cap - 1);
1153    }
1154
1155    /// STATEMENT: Pages track lengths, page boundaries, conversions, and debug output as data is added and removed.
1156    ///
1157    /// HOW:
1158    /// - Fill `Size8` buffers across page boundaries, append a full page, and check lengths, page counts, spare capacity, and drained contents.
1159    /// - Convert byte and string inputs to pages, advance and freeze them, then check debug ordering and clearing.
1160    #[test]
1161    fn pages() {
1162        let cap = BytePageSize::Size8.capacity();
1163        // SAFETY: Each `as_ptr` result is compared immediately while its page remains live,
1164        // unmoved, and unchanged.
1165        unsafe {
1166            // pages
1167            let mut pages = BytePages::new(BytePageSize::Size8);
1168            assert!(pages.is_empty());
1169            assert_eq!(pages.len(), 0);
1170            assert_eq!(pages.num_pages(), 0);
1171            pages.extend_from_slice(b"b");
1172            assert_eq!(pages.len(), 1);
1173            assert_eq!(pages.num_pages(), 1);
1174            pages.extend_from_slice("a".repeat(9 * 1024).as_bytes());
1175            assert_eq!(pages.len(), 9217);
1176            assert_eq!(pages.num_pages(), 2);
1177            assert!(!pages.is_empty());
1178
1179            let mut pgs = BytePages::new(BytePageSize::Size8);
1180            pgs.put_i8(b'a' as i8);
1181            let p = pgs.take().unwrap();
1182            assert_eq!(p.len(), 1);
1183            assert_eq!(p.as_ref(), b"a");
1184
1185            pgs.extend_from_slice("a".repeat(cap - 1).as_bytes());
1186            assert_eq!(pgs.num_pages(), 1);
1187            pgs.put_u8(b'a');
1188            assert_eq!(pgs.num_pages(), 1);
1189            assert!(pgs.current.is_none());
1190
1191            pgs.put_u8(b'a');
1192            assert_eq!(pgs.num_pages(), 2);
1193
1194            pgs.append(Bytes::copy_from_slice("a".repeat(cap).as_bytes()));
1195            assert_eq!(pgs.num_pages(), 3);
1196            assert_eq!(pgs.current_len(), 0);
1197            assert_eq!(pgs.spare(), cap - 1);
1198
1199            // page
1200            let p = pages.take().unwrap();
1201            assert_eq!(p.len(), cap);
1202            let p = pages.take().unwrap();
1203            assert_eq!(p.len(), 9217 - cap);
1204            assert!(!p.is_empty());
1205            assert_eq!(p.as_ref().as_ptr(), p.as_ptr());
1206            assert_eq!(p.as_ref(), "a".repeat(9217 - cap).as_bytes());
1207            assert!(pages.take().is_none());
1208
1209            let p = BytePage::from(Bytes::copy_from_slice(b"123"));
1210            assert_eq!(p.len(), 3);
1211            assert!(!p.is_empty());
1212            assert_eq!(p.as_ref(), b"123");
1213            assert_eq!(p.as_ref().as_ptr(), p.as_ptr());
1214
1215            let p = BytePage::from(&b"123"[..]);
1216            assert_eq!(p.len(), 3);
1217            assert!(!p.is_empty());
1218            assert_eq!(p.as_ref(), b"123");
1219            assert_eq!(p.as_ref().as_ptr(), p.as_ptr());
1220
1221            let p = BytePage::from(b"123");
1222            assert_eq!(p.len(), 3);
1223            assert!(!p.is_empty());
1224            assert_eq!(p.as_ref(), b"123");
1225            assert_eq!(p.as_ref().as_ptr(), p.as_ptr());
1226
1227            let p = BytePage::from("123");
1228            assert_eq!(p.len(), 3);
1229            assert!(!p.is_empty());
1230            assert_eq!(p.as_ref(), b"123");
1231            assert_eq!(p.as_ref().as_ptr(), p.as_ptr());
1232            assert_eq!(p.freeze(), b"123");
1233
1234            let p = BytePage::from(vec![b'1', b'2', b'3']);
1235            assert_eq!(p.len(), 3);
1236            assert!(!p.is_empty());
1237            assert_eq!(p.as_ref(), b"123");
1238            assert_eq!(p.as_ref().as_ptr(), p.as_ptr());
1239            assert_eq!(p.freeze(), b"123");
1240
1241            let mut p = BytePage::from(vec![b'1', b'2', b'3']);
1242            p.advance_to(1);
1243            assert_eq!(p.len(), 2);
1244            assert!(!p.is_empty());
1245            assert_eq!(p.as_ref(), b"23");
1246
1247            // debug
1248            let mut pages = BytePages::new(BytePageSize::Size8);
1249            pages.extend_from_slice(b"b");
1250            assert_eq!(format!("{pages:?}"), "BytePages(b\"b\")");
1251            let p = pages.take().unwrap();
1252            assert_eq!(p.as_ref(), b"b");
1253
1254            let mut pages = BytePages::new(BytePageSize::Size8);
1255            pages.extend_from_slice(b"a");
1256            pages.append(Bytes::copy_from_slice(b"123"));
1257            pages.push_back(p);
1258            assert_eq!(format!("{pages:?}"), "BytePages(b\"b\", b\"a123\")");
1259
1260            assert_eq!(pages.len(), 5);
1261            pages.clear();
1262            assert_eq!(pages.len(), 0);
1263        }
1264    }
1265
1266    /// Checks the tracked length against the pages.
1267    fn assert_len(pages: &BytePages) {
1268        let len = pages.pages().iter().map(BytePage::len).sum::<usize>() + pages.current_len();
1269        assert_eq!(pages.len(), len);
1270        assert_eq!(pages.is_empty(), len == 0);
1271    }
1272
1273    /// STATEMENT: Tracked total length stays consistent with page contents across mixed buffer operations.
1274    ///
1275    /// HOW:
1276    /// - Randomly extend, append, prepend, take, split, move, copy, and write bytes while maintaining an expected length.
1277    /// - Check both buffers against their constituent page lengths after each operation, then verify freezing and clearing leave empty buffers.
1278    #[test]
1279    fn pages_len_tracking() {
1280        let mut rng = rand::rng();
1281        let mut pages = BytePages::new(BytePageSize::Size8);
1282        let mut other = BytePages::new(BytePageSize::Size8);
1283        let mut expected = 0;
1284
1285        let (iters, max) = if cfg!(miri) { (100, 256) } else { (2000, 12 * 1024) };
1286        for _ in 0..iters {
1287            let n = rng.random_range(0..max);
1288            match rng.random_range(0..9) {
1289                0 => {
1290                    pages.extend_from_slice(&vec![1; n]);
1291                    expected += n;
1292                }
1293                1 => {
1294                    pages.append(Bytes::copy_from_slice(&vec![2; n]));
1295                    expected += n;
1296                }
1297                2 => {
1298                    if pages.prepend(BytesMut::copy_from_slice(vec![3; n])) {
1299                        expected += n;
1300                    }
1301                }
1302                3 => {
1303                    if let Some(p) = pages.take() {
1304                        expected -= p.len();
1305                    }
1306                }
1307                4 => {
1308                    let at = cmp::min(n, expected);
1309                    let split = pages.split_to(at);
1310                    assert_len(&split);
1311                    assert_eq!(split.len(), at);
1312                    expected -= at;
1313                }
1314                5 => {
1315                    let at = cmp::min(n, expected);
1316                    pages.split_into(at, &mut other);
1317                    expected -= at;
1318                }
1319                6 => {
1320                    other.move_to(&mut pages);
1321                    assert_len(&other);
1322                    assert!(other.is_empty());
1323                    expected = pages.len();
1324                }
1325                7 => {
1326                    let mut copy = BytePages::new(BytePageSize::Size8);
1327                    pages.copy_to(&mut copy);
1328                    assert_len(&copy);
1329                    assert_eq!(copy.len(), expected);
1330                }
1331                _ => {
1332                    pages.put_u8(4);
1333                    expected += 1;
1334                }
1335            }
1336            assert_len(&pages);
1337            assert_len(&other);
1338            assert_eq!(pages.len(), expected);
1339        }
1340
1341        let len = pages.len();
1342        assert_eq!(pages.freeze().len(), len);
1343        assert_len(&pages);
1344        assert!(pages.is_empty());
1345        pages.extend_from_slice(b"123");
1346        pages.clear();
1347        assert_len(&pages);
1348        assert!(pages.is_empty());
1349    }
1350
1351    /// STATEMENT: A cached page-list allocation does not retain the previous buffer's tracked length.
1352    ///
1353    /// HOW:
1354    /// - Append two 64-byte buffers, drop the `BytePages`, then create another and verify empty length and page consistency.
1355    #[test]
1356    fn pages_len_after_cache_reuse() {
1357        let mut pages = BytePages::new(BytePageSize::Size8);
1358        pages.append(Bytes::copy_from_slice(&[1; 64]));
1359        pages.append(Bytes::copy_from_slice(&[1; 64]));
1360        drop(pages);
1361
1362        let pages = BytePages::new(BytePageSize::Size8);
1363        assert_len(&pages);
1364        assert!(pages.is_empty());
1365    }
1366
1367    /// STATEMENT: Copying the current page shares its data while allowing the source to append safely.
1368    ///
1369    /// HOW:
1370    /// - Copy 64 bytes with `copy_to`, take the copied page, and verify it shares the current page's pointer.
1371    /// - Append another 64 bytes to the source and drop it, checking the copied page stays unchanged and valid.
1372    #[test]
1373    fn pages_copy_to_shares_current() {
1374        let mut pages = BytePages::new(BytePageSize::Size8);
1375        pages.put_slice(&[1; 64]);
1376        // SAFETY: The current page owns a live allocation; the pointer is only recorded for
1377        // comparison.
1378        let ptr = unsafe { pages.current.as_ref().unwrap().as_ptr() };
1379
1380        let mut copy = BytePages::new(BytePageSize::Size8);
1381        pages.copy_to(&mut copy);
1382        let page = copy.take().unwrap();
1383        // SAFETY: The page is live and unmoved during this pointer comparison.
1384        assert_eq!(unsafe { page.as_ptr() }, ptr.cast_const());
1385        assert_eq!(page.as_ref(), &[1; 64][..]);
1386
1387        // the source keeps writing to the page it shares with the copy
1388        pages.put_slice(&[2; 64]);
1389        // SAFETY: The current page owns a live allocation; the pointer is only compared, not
1390        // dereferenced.
1391        assert_eq!(unsafe { pages.current.as_ref().unwrap().as_ptr() }, ptr);
1392        assert_eq!(page.as_ref(), &[1; 64][..]);
1393        assert_eq!(pages.len(), 128);
1394
1395        drop(pages);
1396        assert_eq!(page.as_ref(), &[1; 64][..]);
1397    }
1398
1399    /// STATEMENT: Splitting pages preserves writable spare capacity and transfers a whole current page without copying.
1400    ///
1401    /// HOW:
1402    /// - Split a 40-byte head from 64 bytes, append to the tail, and check lengths, contents, spare capacity, and pointer offsets.
1403    /// - Repeat with an inline head, a whole-page split, and an empty current page, checking ownership and retained capacity.
1404    #[test]
1405    fn pages_split_keeps_current_writable() {
1406        let mut pages = BytePages::new(BytePageSize::Size8);
1407        pages.put_slice(&[1; 64]);
1408        // SAFETY: The current page owns a live allocation; the pointer is only recorded for
1409        // comparison.
1410        let ptr = unsafe { pages.current.as_ref().unwrap().as_ptr() };
1411        let remaining = pages.spare();
1412
1413        let mut head = pages.split_to(40);
1414        assert_eq!(head.len(), 40);
1415        assert_eq!(pages.len(), 24);
1416        assert_eq!(pages.num_pages(), 1);
1417        assert_eq!(pages.spare(), remaining);
1418
1419        // new data goes into the same page
1420        pages.put_slice(&[2; 16]);
1421        assert_eq!(pages.num_pages(), 1);
1422        assert_eq!(
1423            // SAFETY: The current page owns a live allocation; the pointer is only compared, not
1424            // dereferenced.
1425            unsafe { pages.current.as_ref().unwrap().as_ptr() },
1426            ptr.wrapping_add(40)
1427        );
1428        let mut expected = vec![1; 24];
1429        expected.extend_from_slice(&[2; 16]);
1430        assert_eq!(&pages.freeze()[..], &expected[..]);
1431        assert_eq!(&head.freeze()[..], &[1; 40][..]);
1432
1433        // an inline head
1434        let mut pages = BytePages::new(BytePageSize::Size8);
1435        pages.put_slice(&[1; 64]);
1436        let mut to = BytePages::new(BytePageSize::Size8);
1437        pages.split_into(2, &mut to);
1438        assert_eq!(&to.freeze()[..], &[1; 2][..]);
1439        assert_eq!(pages.spare(), remaining);
1440        assert_eq!(pages.len(), 62);
1441
1442        // the whole current page moves with its spare capacity
1443        let mut pages = BytePages::new(BytePageSize::Size8);
1444        pages.put_slice(&[1; 64]);
1445        // SAFETY: The current page owns a live allocation; the pointer is only recorded for
1446        // comparison.
1447        let ptr = unsafe { pages.current.as_ref().unwrap().as_ptr() };
1448        let to = pages.split_to(64);
1449        assert!(pages.is_empty());
1450        assert_eq!(pages.num_pages(), 0);
1451        assert_eq!(to.spare(), remaining);
1452        // SAFETY: The destination owns the moved allocation; its pointer is only compared, not
1453        // dereferenced.
1454        assert_eq!(unsafe { to.current.as_ref().unwrap().as_ptr() }, ptr);
1455
1456        // an empty current page stays in place
1457        let mut pages = BytePages::new(BytePageSize::Size8);
1458        let _ = pages.chunk_mut();
1459        let head = pages.split_to(10);
1460        assert!(head.is_empty());
1461        assert_eq!(pages.spare(), remaining + 64);
1462    }
1463
1464    /// STATEMENT: `BytePages` mutable-buffer writes grow across page boundaries and account for all written bytes.
1465    ///
1466    /// HOW:
1467    /// - Fill a writable chunk, advance it, write into the next page, and check page counts, length, and remaining writable space.
1468    /// - Combine `put` and `Write::write_all`, then freeze and compare the complete payload.
1469    #[test]
1470    fn pages_buf_mut_grows() {
1471        let mut pages = BytePages::new(BytePageSize::Size8);
1472        assert!(pages.has_remaining_mut());
1473        assert_eq!(pages.remaining_mut(), usize::MAX);
1474        // SAFETY: Advancing by zero exposes no uninitialized bytes.
1475        unsafe { pages.advance_mut(0) };
1476
1477        // filling the current page through `chunk_mut` starts a new one
1478        let n = pages.chunk_mut().len();
1479        // SAFETY: The writable chunk has `n` bytes, all initialized by `write_bytes` before
1480        // advancing.
1481        unsafe {
1482            std::ptr::write_bytes(pages.chunk_mut().as_mut_ptr(), 1, n);
1483            pages.advance_mut(n);
1484        }
1485        assert!(pages.chunk_mut().len() > 0);
1486        // the new current page holds no data yet
1487        assert_eq!(pages.num_pages(), 1);
1488        // SAFETY: The nonempty writable chunk receives one initialized byte before advancing by
1489        // one.
1490        unsafe {
1491            *pages.chunk_mut().as_mut_ptr() = 2;
1492            pages.advance_mut(1);
1493        }
1494        assert_eq!(pages.len(), n + 1);
1495        assert_eq!(pages.remaining_mut(), usize::MAX - n - 1);
1496
1497        // `put` and `io::Write` are not limited to the current page
1498        let mut pages = BytePages::new(BytePageSize::Size8);
1499        pages.put(&[3u8; 200][..]);
1500        pages.put(Bytes::from_static(b"abcd"));
1501        io::Write::write_all(&mut pages, &[4; 100]).unwrap();
1502        let mut expected = vec![3; 200];
1503        expected.extend_from_slice(b"abcd");
1504        expected.extend_from_slice(&[4; 100]);
1505        assert_eq!(&pages.freeze()[..], &expected[..]);
1506    }
1507
1508    /// STATEMENT: Single-byte writes after a full current page allocate usable storage without adding empty pages.
1509    ///
1510    /// HOW:
1511    /// - Fill a current page through `advance_mut`, append signed and unsigned bytes, and check page counts and frozen data.
1512    /// - Repeat after appending a large separate payload, verifying all listed pages are nonempty and byte order is preserved.
1513    #[test]
1514    fn pages_byte_write_after_full_page() {
1515        // `advance_mut` leaves a full current page
1516        let mut pages = BytePages::new(BytePageSize::Size8);
1517        let n = pages.chunk_mut().len();
1518        // SAFETY: The writable chunk has `n` bytes, all initialized by `write_bytes` before
1519        // advancing.
1520        unsafe {
1521            std::ptr::write_bytes(pages.chunk_mut().as_mut_ptr(), 1, n);
1522            pages.advance_mut(n);
1523        }
1524        pages.put_u8(2);
1525        pages.put_i8(3);
1526        assert_eq!(pages.num_pages(), 2);
1527        assert_eq!(pages.pages()[0].len(), n);
1528        let mut expected = vec![1; n];
1529        expected.extend_from_slice(&[2, 3]);
1530        assert_eq!(&pages.freeze()[..], &expected[..]);
1531
1532        // splitting off a full current page leaves an empty page without capacity
1533        let mut pages = BytePages::new(BytePageSize::Size8);
1534        let n = pages.chunk_mut().len();
1535        // SAFETY: The writable chunk has `n` bytes, all initialized by `write_bytes` before
1536        // advancing.
1537        unsafe {
1538            std::ptr::write_bytes(pages.chunk_mut().as_mut_ptr(), 1, n);
1539            pages.advance_mut(n);
1540        }
1541        pages.append(vec![2; APPEND_COPY_LIMIT + 1]);
1542        pages.put_u8(3);
1543        assert!(pages.pages().iter().all(|p| !p.is_empty()));
1544        let mut expected = vec![1; n];
1545        expected.extend_from_slice(&[2; APPEND_COPY_LIMIT + 1]);
1546        expected.push(3);
1547        assert_eq!(&pages.freeze()[..], &expected[..]);
1548    }
1549
1550    /// STATEMENT: Mutable advancement cannot exceed the current page's writable chunk.
1551    ///
1552    /// HOW:
1553    /// - Get a `Size8` buffer's chunk length, advance by one more, and expect the current-page bounds panic.
1554    #[test]
1555    #[should_panic(expected = "cannot advance past the current page")]
1556    fn pages_advance_past_current_page() {
1557        let mut pages = BytePages::new(BytePageSize::Size8);
1558        let n = pages.chunk_mut().len();
1559        // SAFETY: The implementation checks the chunk bound and panics before exposing any
1560        // uninitialized bytes.
1561        unsafe { pages.advance_mut(n + 1) };
1562    }
1563
1564    /// STATEMENT: Creating `BytePages` with an unspecified page size is rejected.
1565    ///
1566    /// HOW:
1567    /// - Call `BytePages::new` with `BytePageSize::Unset` and expect the page-size panic.
1568    #[test]
1569    #[should_panic(expected = "Page size cannot be Unset")]
1570    fn pages_new_unset() {
1571        let _ = BytePages::new(BytePageSize::Unset);
1572    }
1573
1574    /// STATEMENT: An existing `BytePages` buffer cannot switch to an unspecified page size.
1575    ///
1576    /// HOW:
1577    /// - Create a `Size8` buffer, set its page size to `Unset`, and expect the page-size panic.
1578    #[test]
1579    #[should_panic(expected = "Page size cannot be Unset")]
1580    fn pages_set_page_size_unset() {
1581        let mut pages = BytePages::new(BytePageSize::Size8);
1582        pages.set_page_size(BytePageSize::Unset);
1583    }
1584
1585    /// STATEMENT: Caching a large page list does not retain its excessive list capacity.
1586    ///
1587    /// HOW:
1588    /// - Append 200 pages, check list capacity is at least 200, drop the buffer, and verify a new list has smaller capacity.
1589    #[test]
1590    fn cached_pages_list_is_shrunk() {
1591        let mut pages = BytePages::new(BytePageSize::Size4);
1592        for _ in 0..200 {
1593            pages.append(Bytes::from_static(b"page"));
1594        }
1595        assert!(pages.pages().capacity() >= 200);
1596        drop(pages);
1597
1598        let pages = BytePages::new(BytePageSize::Size4);
1599        assert!(
1600            pages.pages().capacity() < 200,
1601            "{}",
1602            pages.pages().capacity()
1603        );
1604    }
1605
1606    /// STATEMENT: Single-page conversion reuses unique storage but copies shared storage before making it mutable.
1607    ///
1608    /// HOW:
1609    /// - Convert current pages to `BytesMut` and `Bytes`, checking pointer reuse, contents, and writable spare capacity.
1610    /// - Convert unique and shared prepended `Bytes`, checking reuse only for the unique case and source isolation after mutation.
1611    #[test]
1612    fn pages_into_bytes_single_page() {
1613        // the current page
1614        let mut pages = BytePages::new(BytePageSize::Size8);
1615        pages.put_slice(&[1; 64]);
1616        // SAFETY: The current page owns a live allocation; the pointer is only recorded for
1617        // comparison.
1618        let ptr = unsafe { pages.current.as_ref().unwrap().as_ptr() };
1619        let mut buf = BytesMut::from(pages);
1620        assert_eq!(buf.as_ptr(), ptr.cast_const());
1621        assert_eq!(&buf[..], &[1; 64][..]);
1622        // the rest of the page is spare capacity
1623        assert_eq!(buf.capacity(), BytePageSize::Size8.capacity());
1624        buf.extend_from_slice(&[2; 64]);
1625        assert_eq!(buf.as_ptr(), ptr.cast_const());
1626
1627        let mut pages = BytePages::new(BytePageSize::Size8);
1628        pages.put_slice(&[1; 64]);
1629        // SAFETY: The current page owns a live allocation; the pointer is only recorded for
1630        // comparison.
1631        let ptr = unsafe { pages.current.as_ref().unwrap().as_ptr() };
1632        let b = Bytes::from(pages);
1633        assert_eq!(b.as_ptr(), ptr.cast_const());
1634        assert_eq!(&b[..], &[1; 64][..]);
1635
1636        // a `Bytes` page
1637        let src = Bytes::copy_from_slice(&[3; 64]);
1638        let ptr = src.as_ptr();
1639        let mut pages = BytePages::new(BytePageSize::Size8);
1640        pages.prepend(src);
1641        assert_eq!(BytesMut::from(pages).as_ptr(), ptr);
1642
1643        // a shared page is copied
1644        let src = Bytes::copy_from_slice(&[3; 64]);
1645        let mut pages = BytePages::new(BytePageSize::Size8);
1646        pages.prepend(&src);
1647        let mut buf = BytesMut::from(pages);
1648        assert_ne!(buf.as_ptr(), src.as_ptr());
1649        buf[0] = 4;
1650        assert_eq!(&src[..], &[3; 64][..]);
1651    }
1652
1653    /// STATEMENT: Converting multiple pages concatenates them in order and converting an empty buffer stays empty.
1654    ///
1655    /// HOW:
1656    /// - Prepend 64 ones and write 64 twos, convert separately to `BytesMut` and `Bytes`, and check each half.
1657    /// - Convert empty `Size8` buffers to both destination types and verify emptiness.
1658    #[test]
1659    fn pages_into_bytes_multiple_pages() {
1660        let mut pages = BytePages::new(BytePageSize::Size8);
1661        pages.prepend(Bytes::copy_from_slice(&[1; 64]));
1662        pages.put_slice(&[2; 64]);
1663        assert_eq!(pages.num_pages(), 2);
1664        let buf = BytesMut::from(pages);
1665        assert_eq!(&buf[..64], &[1; 64][..]);
1666        assert_eq!(&buf[64..], &[2; 64][..]);
1667
1668        let mut pages = BytePages::new(BytePageSize::Size8);
1669        pages.prepend(Bytes::copy_from_slice(&[1; 64]));
1670        pages.put_slice(&[2; 64]);
1671        let b = Bytes::from(pages);
1672        assert_eq!(&b[..64], &[1; 64][..]);
1673        assert_eq!(&b[64..], &[2; 64][..]);
1674
1675        assert!(BytesMut::from(BytePages::new(BytePageSize::Size8)).is_empty());
1676        assert!(Bytes::from(BytePages::new(BytePageSize::Size8)).is_empty());
1677    }
1678
1679    /// STATEMENT: Copied and cloned page buffers retain their original contents when the source grows.
1680    ///
1681    /// HOW:
1682    /// - Copy pages containing `123456`, freeze both, and compare their contents.
1683    /// - Repeat with `copy_to` and `clone`, append `7` only to the source, and verify each destination remains `123456`.
1684    #[test]
1685    fn pages_copy_to() {
1686        let mut pages = BytePages::default();
1687        let mut pages2 = BytePages::default();
1688        pages.put_slice(b"456");
1689        pages.prepend(BytePage::from(Bytes::copy_from_slice(b"123")));
1690        pages.copy_to(&mut pages2);
1691        let p = pages.freeze();
1692        assert_eq!(p, b"123456");
1693        let p2 = pages2.freeze();
1694        assert_eq!(p2, b"123456");
1695
1696        let mut pages = BytePages::default();
1697        let mut pages2 = BytePages::default();
1698        pages.put_slice(b"456");
1699        pages.prepend(BytePage::from(Bytes::copy_from_slice(b"123")));
1700        pages.copy_to(&mut pages2);
1701        pages.put_u8(b'7');
1702        let p = pages.freeze();
1703        assert_eq!(p, b"1234567");
1704        let p2 = pages2.freeze();
1705        assert_eq!(p2, b"123456");
1706
1707        let mut pages = BytePages::default();
1708        pages.put_slice(b"456");
1709        pages.prepend(BytePage::from(Bytes::copy_from_slice(b"123")));
1710        let mut pages2 = pages.clone();
1711        pages.put_u8(b'7');
1712        let p = pages.freeze();
1713        assert_eq!(p, b"1234567");
1714        let p2 = pages2.freeze();
1715        assert_eq!(p2, b"123456");
1716    }
1717
1718    /// STATEMENT: Page splitting, mutable access, borrowing, and byte conversion preserve the requested data ranges.
1719    ///
1720    /// HOW:
1721    /// - Split `123456` within and across pages with `split_to` and `split_into` and check both resulting buffers.
1722    /// - Write short and 65,536-byte payloads through `with_bytes_mut`, then check lengths, frozen bytes, and page borrowing/conversion.
1723    #[test]
1724    fn pages_methods() {
1725        // .split_to()
1726        let mut pages = BytePages::default();
1727        pages.put_slice(b"456");
1728        pages.prepend(BytePage::from(&Bytes::copy_from_slice(b"123")));
1729        let mut pages2 = pages.split_to(1);
1730        let p = pages.freeze();
1731        assert_eq!(p, b"23456");
1732        let p2 = pages2.freeze();
1733        assert_eq!(p2, b"1");
1734
1735        let mut pages = BytePages::default();
1736        pages.put_slice(b"456");
1737        pages.prepend(BytePage::from(Bytes::copy_from_slice(b"123")));
1738        let mut pages2 = pages.split_to(4);
1739        let p = pages.freeze();
1740        assert_eq!(p, b"56");
1741        let p2 = pages2.freeze();
1742        assert_eq!(p2, b"1234");
1743
1744        // .split_into()
1745        let mut pages = BytePages::default();
1746        pages.put_slice(b"456");
1747        pages.prepend(BytePage::from(crate::ByteString::from_static("123")));
1748        let mut pages2 = BytePages::default();
1749        pages.split_into(1, &mut pages2);
1750        let p = pages.freeze();
1751        assert_eq!(p, b"23456");
1752        let p2 = pages2.freeze();
1753        assert_eq!(p2, b"1");
1754
1755        // .with_bytes_mut()
1756        let mut pages = BytePages::default();
1757        #[allow(deprecated)]
1758        pages.with_bytes_mut(|buf| buf.extend_from_slice(b"123"));
1759        assert_eq!(pages.len(), 3);
1760        let p = pages.freeze();
1761        assert_eq!(p, b"123");
1762
1763        let data = b"0123456789abcdef".repeat(4096);
1764
1765        let mut pages = BytePages::default();
1766        #[allow(deprecated)]
1767        pages.with_bytes_mut(|buf| buf.extend_from_slice(&data));
1768        assert_eq!(pages.len(), 65_536);
1769        let p = pages.freeze();
1770        assert_eq!(p, data[..]);
1771
1772        // into bytes
1773        let page = BytePage::from(Bytes::copy_from_slice(b"123"));
1774        assert_eq!(page, b"123");
1775        assert_eq!(<BytePage as Borrow<[u8]>>::borrow(&page), b"123");
1776        let b = Bytes::from(page);
1777        assert_eq!(b, b"123");
1778    }
1779
1780    /// STATEMENT: A slice written into the current page stays there until it fills the page, which then moves to the page list.
1781    ///
1782    /// HOW:
1783    /// - Write slices that leave one spare byte in the first page and check that no page was pushed.
1784    /// - Write the last byte and check that the full page is pushed with no current page left.
1785    /// - Write a slice larger than the page and check the page count, length, and frozen bytes.
1786    #[test]
1787    fn put_slice_current_page() {
1788        let mut pages = BytePages::new(BytePageSize::Size4);
1789        pages.put_slice(b"abc");
1790        let spare = pages.spare();
1791        assert!(spare > 1);
1792        assert_eq!(pages.pages().len(), 0);
1793        assert_eq!(pages.num_pages(), 1);
1794
1795        let fill = vec![b'x'; spare - 1];
1796        pages.put_slice(&fill);
1797        assert_eq!(pages.spare(), 1);
1798        assert_eq!(pages.pages().len(), 0);
1799
1800        pages.put_slice(b"y");
1801        assert_eq!(pages.pages().len(), 1);
1802        assert!(pages.current.is_none());
1803        assert_eq!(pages.num_pages(), 1);
1804        let page_len = pages.len();
1805        assert_eq!(page_len, spare + 3);
1806
1807        let large = vec![b'z'; page_len + 10];
1808        pages.put_slice(&large);
1809        assert_eq!(pages.len(), page_len * 2 + 10);
1810        assert_eq!(pages.num_pages(), 3);
1811
1812        let mut expected = b"abc".to_vec();
1813        expected.extend_from_slice(&fill);
1814        expected.push(b'y');
1815        expected.extend_from_slice(&large);
1816        assert_eq!(pages.freeze(), expected[..]);
1817    }
1818
1819    /// STATEMENT: `put_slices` copies slices that fit into the current page in order, in place.
1820    ///
1821    /// HOW:
1822    /// - Start a `Size4` page with `abc` and record its spare capacity.
1823    /// - Put three slices, one of them empty, and check that the spare shrank by their total,
1824    ///   no page moved to the page list, and the bytes follow `abc` in order.
1825    #[test]
1826    fn put_slices_current_page() {
1827        let mut pages = BytePages::new(BytePageSize::Size4);
1828        pages.put_slice(b"abc");
1829        let spare = pages.spare();
1830
1831        pages.put_slices(&[b"de", b"", b"fgh"]);
1832        assert_eq!(pages.spare(), spare - 5);
1833        assert_eq!(pages.pages().len(), 0);
1834        assert_eq!(pages.len(), 8);
1835        assert_eq!(pages.freeze(), b"abcdefgh"[..]);
1836    }
1837
1838    /// STATEMENT: `put_slices` gives the same pages as `put_slice` calls when the slices do not
1839    /// fit into the current page.
1840    ///
1841    /// HOW:
1842    /// - Put slices into pages with no current page, slices that fill the current page exactly,
1843    ///   and slices that overflow it.
1844    /// - Do the same with one `put_slice` call per slice and compare the page count, the
1845    ///   current page and the frozen bytes.
1846    #[test]
1847    fn put_slices_matches_put_slice() {
1848        fn check(prefix: &[u8], src: &[&[u8]]) {
1849            let mut pages = BytePages::new(BytePageSize::Size4);
1850            let mut expected = BytePages::new(BytePageSize::Size4);
1851            if !prefix.is_empty() {
1852                pages.put_slice(prefix);
1853                expected.put_slice(prefix);
1854            }
1855            pages.put_slices(src);
1856            for s in src {
1857                expected.put_slice(s);
1858            }
1859            assert_eq!(pages.num_pages(), expected.num_pages());
1860            assert_eq!(pages.current.is_none(), expected.current.is_none());
1861            assert_eq!(pages.len(), expected.len());
1862            assert_eq!(pages.freeze(), expected.freeze());
1863        }
1864
1865        check(b"", &[b"abc", b"de"]);
1866
1867        let mut pages = BytePages::new(BytePageSize::Size4);
1868        pages.put_slice(b"abc");
1869        let spare = pages.spare();
1870        let fill = vec![b'x'; spare - 2];
1871        let large = vec![b'z'; spare * 2];
1872
1873        check(b"abc", &[&fill, b"yz"]);
1874        check(b"abc", &[&fill, b"yz!"]);
1875        check(b"abc", &[b"y", &large, b"z"]);
1876    }
1877
1878    /// STATEMENT: Cloned pages preserve contents while short storage is copied inline and longer mutable storage is shared.
1879    ///
1880    /// HOW:
1881    /// - Clone `Bytes`, short and long `BytesMut`, and vector-backed pages, checking equal contents and resulting storage variants.
1882    /// - Inspect mutable-storage uniqueness before and after cloning and dropping the longer clone.
1883    #[test]
1884    fn page_clone() {
1885        // Bytes storage
1886        let p = BytePage::from(Bytes::copy_from_slice(b"123"));
1887        let p2 = p.clone();
1888        assert_eq!(p, p2);
1889
1890        // StorageVec
1891        let mut p = BytePage::from(BytesMut::copy_from_slice(b"123"));
1892        if let StorageType::Storage(ref mut st) = p.inner {
1893            assert!(st.is_unique());
1894        } else {
1895            panic!()
1896        }
1897        let p2 = p.clone();
1898        assert_eq!(p, p2);
1899        // short data is copied into an inline view
1900        assert!(matches!(p2.inner, StorageType::Bytes(_)));
1901        if let StorageType::Storage(st) = p.inner {
1902            assert!(st.is_unique());
1903        } else {
1904            panic!()
1905        }
1906
1907        let mut p = BytePage::from(BytesMut::copy_from_slice([b'1'; 64]));
1908        let p2 = p.clone();
1909        assert_eq!(p, p2);
1910        assert!(matches!(p2.inner, StorageType::Bytes(_)));
1911        if let StorageType::Storage(ref mut st) = p.inner {
1912            assert!(!st.is_unique());
1913        } else {
1914            panic!()
1915        }
1916        drop(p2);
1917        if let StorageType::Storage(st) = p.inner {
1918            assert!(st.is_unique());
1919        } else {
1920            panic!()
1921        }
1922
1923        // Vec<u8> storage
1924        let p = BytePage::from(vec![b'1', b'2', b'3']);
1925        let p2 = p.clone();
1926        assert_eq!(p, p2);
1927        if let StorageType::Bytes(_) = p2.inner {
1928        } else {
1929            panic!()
1930        }
1931    }
1932
1933    /// STATEMENT: Splitting a page behaves consistently for immutable, mutable-storage, and vector-backed data.
1934    ///
1935    /// HOW:
1936    /// - Create `123` pages from each storage type, split one byte, and verify the returned `1` and retained `23`.
1937    #[test]
1938    fn page_split_to() {
1939        // Bytes storage
1940        let mut p = BytePage::from(Bytes::copy_from_slice(b"123"));
1941        let p2 = p.split_to(1);
1942        assert_eq!(p, b"23");
1943        assert_eq!(p2, b"1");
1944
1945        // StorageVec
1946        let mut p = BytePage::from(BytesMut::copy_from_slice(b"123"));
1947        let p2 = p.split_to(1);
1948        assert_eq!(p, b"23");
1949        assert_eq!(p2, b"1");
1950
1951        // Vec<u8> storage
1952        let mut p = BytePage::from(vec![b'1', b'2', b'3']);
1953        let p2 = p.split_to(1);
1954        assert_eq!(p, b"23");
1955        assert_eq!(p2, b"1");
1956    }
1957
1958    /// STATEMENT: Reading a page consumes its bytes and leaves unused destination bytes untouched.
1959    ///
1960    /// HOW:
1961    /// - Read `123` into a ten-byte zeroed array and verify a three-byte read, zero remaining length, and seven trailing zeros.
1962    #[test]
1963    fn page_read() {
1964        use std::io::Read;
1965
1966        let mut page = BytePage::from(Bytes::copy_from_slice(b"123"));
1967
1968        let mut buf = [0; 10];
1969        assert_eq!(page.read(&mut buf).unwrap(), 3);
1970        assert_eq!(page.len(), 0);
1971        assert_eq!(buf, [49, 50, 51, 0, 0, 0, 0, 0, 0, 0]);
1972    }
1973
1974    /// STATEMENT: Page-size updates, prepending, stream writes, and borrowed string appends preserve data.
1975    ///
1976    /// HOW:
1977    /// - Change `Size4` to `Size8`, reject an empty prepend, prepend `a`, write and flush `bc`, and freeze to `abc`.
1978    /// - Append a borrowed `ByteString` afterward and verify the next frozen value is `str`.
1979    #[test]
1980    fn pages_misc() {
1981        let mut pages = BytePages::new(BytePageSize::Size4);
1982        pages.set_page_size(BytePageSize::Size8);
1983        assert_eq!(pages.page_size(), BytePageSize::Size8);
1984        assert!(!pages.prepend(Bytes::new()));
1985        assert!(pages.prepend(Bytes::from_static(b"a")));
1986
1987        io::Write::write_all(&mut pages, b"bc").unwrap();
1988        io::Write::flush(&mut pages).unwrap();
1989        assert_eq!(pages.freeze(), "abc");
1990
1991        let s = ByteString::from_static("str");
1992        pages.append(&s);
1993        assert_eq!(pages.freeze(), "str");
1994    }
1995
1996    /// STATEMENT: Current-page transfer only fills an empty destination and leaves transferred storage writable.
1997    ///
1998    /// HOW:
1999    /// - Attempt to transfer `data` into a destination containing `x` and check both lengths stay unchanged.
2000    /// - Transfer into an empty buffer, check source and destination lengths, append `!`, and freeze to `data!`.
2001    #[test]
2002    fn pages_try_get_current_from() {
2003        let mut src = BytePages::new(BytePageSize::Size4);
2004        src.extend_from_slice(b"data");
2005
2006        // the target already holds data
2007        let mut dst = BytePages::new(BytePageSize::Size4);
2008        dst.append(Bytes::from_static(b"x"));
2009        dst.try_get_current_from(&mut src);
2010        assert_eq!(src.len(), 4);
2011        assert_eq!(dst.len(), 1);
2012
2013        let mut dst = BytePages::new(BytePageSize::Size4);
2014        dst.try_get_current_from(&mut src);
2015        assert_eq!(src.len(), 0);
2016        assert_eq!(dst.len(), 4);
2017        dst.extend_from_slice(b"!");
2018        assert_eq!(dst.freeze(), "data!");
2019    }
2020
2021    /// STATEMENT: The page-list cache enforces its maximum size and skips caching while already in use.
2022    ///
2023    /// HOW:
2024    /// - Drop `CACHE_SIZE + 1` buffers into an empty cache and verify exactly `CACHE_SIZE` lists are retained.
2025    /// - Take the cache while dropping another buffer, restore it, and verify no list was added.
2026    #[test]
2027    fn pages_drop_cache() {
2028        CACHE.with(|c| c.set(Some(Box::default())));
2029        let cached = || {
2030            CACHE.with(|c| {
2031                let cache = c.take().unwrap();
2032                let len = cache.len();
2033                c.set(Some(cache));
2034                len
2035            })
2036        };
2037
2038        // the cache is full
2039        let pages: Vec<_> = (0..=CACHE_SIZE)
2040            .map(|_| BytePages::new(BytePageSize::Size4))
2041            .collect();
2042        drop(pages);
2043        assert_eq!(cached(), CACHE_SIZE);
2044
2045        // the cache is in use
2046        CACHE.with(|c| c.set(Some(Box::default())));
2047        let pages = BytePages::new(BytePageSize::Size4);
2048        let cache = CACHE.with(Cell::take);
2049        drop(pages);
2050        CACHE.with(|c| c.set(cache));
2051        assert_eq!(cached(), 0);
2052    }
2053
2054    /// STATEMENT: Page conversions preserve payloads from mutable storage, vectors, and borrowed byte strings.
2055    ///
2056    /// HOW:
2057    /// - Check `Storage` and `Vec` page kinds, convert their 64-byte payloads to `Bytes` or `BytesMut`, and compare contents.
2058    /// - Convert a borrowed `ByteString` to a page and check `string` remains intact.
2059    #[test]
2060    fn page_conversions() {
2061        let page = BytePage::from(BytesMut::copy_from_slice([1; 64]));
2062        assert_eq!(page.info(), crate::info::PageKind::Storage);
2063        assert_eq!(Bytes::from(page), &[1; 64][..]);
2064
2065        let page = BytePage::from(vec![2; 64]);
2066        assert_eq!(page.info(), crate::info::PageKind::Vec);
2067        assert_eq!(Bytes::from(page), &[2; 64][..]);
2068
2069        let page = BytePage::from(vec![3; 64]);
2070        assert_eq!(BytesMut::from(page), &[3; 64][..]);
2071
2072        let s = ByteString::from_static("string");
2073        assert_eq!(BytePage::from(&s), "string");
2074    }
2075
2076    /// STATEMENT: Appending unique storage with spare capacity makes it writable current storage, unlike full or shared pages.
2077    ///
2078    /// HOW:
2079    /// - Append a mutable page containing `a`, write `b`, and check a single page freezes to `ab`.
2080    /// - Append full and shared pages followed by `z`, checking page count, total length, and unchanged shared contents.
2081    #[test]
2082    fn append_storage_page() {
2083        // a page with spare capacity becomes the current page
2084        let mut pages = BytePages::new(BytePageSize::Size4);
2085        let mut buf = BytesMut::with_capacity(64);
2086        buf.extend_from_slice(b"a");
2087        pages.append(buf);
2088        pages.extend_from_slice(b"b");
2089        assert_eq!(pages.num_pages(), 1);
2090        assert_eq!(pages.freeze(), "ab");
2091
2092        // full and shared pages are added to the page list
2093        let mut buf = BytesMut::with_capacity(64);
2094        let cap = buf.capacity();
2095        buf.resize(cap, b'x');
2096        pages.append(buf);
2097        let page = BytePage::from(BytesMut::copy_from_slice([b'y'; 64]));
2098        let shared = page.clone();
2099        pages.append(page);
2100        pages.extend_from_slice(b"z");
2101        assert_eq!(pages.num_pages(), 3);
2102        assert_eq!(pages.len(), cap + 65);
2103        assert_eq!(shared, &[b'y'; 64][..]);
2104    }
2105
2106    // inline page, shared page, then the current page
2107    fn mixed_pages() -> BytePages {
2108        let mut pages = BytePages::new(BytePageSize::Size4);
2109        pages.extend_from_slice(b"current");
2110        pages.prepend(Bytes::copy_from_slice(&[b'b'; 64]));
2111        pages.prepend(Bytes::copy_from_slice(b"ab"));
2112        assert!(pages.pages()[0].is_inline());
2113        pages
2114    }
2115
2116    /// STATEMENT: Page iteration preserves order and addresses across moves and omits empty current pages.
2117    ///
2118    /// HOW:
2119    /// - Check empty iteration, then collect inline, shared, and current chunks from `mixed_pages` and compare their order and count.
2120    /// - Move the buffer into a box and compare chunk addresses, then consume another buffer and verify empty iteration.
2121    #[test]
2122    fn iter_pages() {
2123        let pages = BytePages::default();
2124        assert_eq!(pages.iter().count(), 0);
2125
2126        let pages = mixed_pages();
2127        let chunks: Vec<&[u8]> = pages.iter().collect();
2128        assert_eq!(chunks, [&b"ab"[..], &[b'b'; 64][..], &b"current"[..]]);
2129        assert_eq!(chunks.len(), pages.num_pages());
2130
2131        // data, including inline pages, does not move with `self`
2132        let ptrs: Vec<*const u8> = pages.iter().map(<[u8]>::as_ptr).collect();
2133        let moved = Box::new(pages);
2134        let moved_ptrs: Vec<*const u8> = moved.iter().map(<[u8]>::as_ptr).collect();
2135        assert_eq!(ptrs, moved_ptrs);
2136
2137        // an empty current page is skipped
2138        let mut pages = BytePages::new(BytePageSize::Size4);
2139        pages.extend_from_slice(b"data");
2140        pages.prepend(Bytes::copy_from_slice(b"ab"));
2141        pages.advance_to(6);
2142        assert_eq!(pages.iter().count(), 0);
2143        assert_eq!(pages.num_pages(), 0);
2144    }
2145
2146    /// STATEMENT: Advancing across pages drops consumed data while retaining the current page's reusable spare capacity.
2147    ///
2148    /// HOW:
2149    /// - Advance by zero, whole pages, and partial pages in `mixed_pages`, checking lengths, page counts, and remaining chunks.
2150    /// - Consume the current page, write `next`, and verify its pointer continues after the consumed bytes.
2151    #[test]
2152    fn advance_to_pages() {
2153        let mut pages = mixed_pages();
2154        let len = pages.len();
2155        pages.advance_to(0);
2156        assert_eq!(pages.len(), len);
2157
2158        // whole page
2159        pages.advance_to(2);
2160        assert_eq!(pages.len(), len - 2);
2161        assert_eq!(pages.num_pages(), 2);
2162        assert_eq!(pages.iter().next().unwrap(), &[b'b'; 64][..]);
2163
2164        // part of a page
2165        pages.advance_to(60);
2166        assert_eq!(pages.len(), 11);
2167        assert_eq!(pages.num_pages(), 2);
2168        let chunks: Vec<&[u8]> = pages.iter().collect();
2169        assert_eq!(chunks, [&b"bbbb"[..], &b"current"[..]]);
2170
2171        // rest of the page and part of the current page
2172        pages.advance_to(6);
2173        assert_eq!(pages.len(), 5);
2174        assert_eq!(pages.num_pages(), 1);
2175        assert_eq!(pages.iter().next().unwrap(), b"rrent");
2176
2177        // the current page keeps its spare capacity
2178        let ptr = pages.iter().next().unwrap().as_ptr();
2179        pages.advance_to(5);
2180        assert!(pages.is_empty());
2181        assert_eq!(pages.num_pages(), 0);
2182        pages.extend_from_slice(b"next");
2183        assert_eq!(pages.num_pages(), 1);
2184        assert_eq!(pages.iter().next().unwrap().as_ptr(), ptr.wrapping_add(5));
2185        assert_eq!(pages.freeze(), "next");
2186    }
2187
2188    /// STATEMENT: Moving buffers retains page allocations, destination size settings, and page order without merging small pages.
2189    ///
2190    /// HOW:
2191    /// - Move `mixed_pages` into an empty `Size16` buffer and check source emptiness, destination size, lengths, and non-inline pointers.
2192    /// - Move into a populated buffer, compare all chunk boundaries, append again, and verify moving an empty source changes nothing.
2193    #[test]
2194    fn move_to_keeps_pages() {
2195        // into empty pages, the page list is swapped
2196        let mut src = mixed_pages();
2197        let ptrs: Vec<*const u8> = src
2198            .iter()
2199            .filter(|s| s.len() > 2)
2200            .map(<[u8]>::as_ptr)
2201            .collect();
2202        let mut dst = BytePages::new(BytePageSize::Size16);
2203        src.move_to(&mut dst);
2204        assert!(src.is_empty());
2205        assert_eq!(src.num_pages(), 0);
2206        assert_eq!(dst.page_size(), BytePageSize::Size16);
2207        assert_eq!(dst.num_pages(), 3);
2208        assert_eq!(dst.len(), 73);
2209        let moved: Vec<*const u8> = dst
2210            .iter()
2211            .filter(|s| s.len() > 2)
2212            .map(<[u8]>::as_ptr)
2213            .collect();
2214        assert_eq!(ptrs, moved);
2215
2216        // small pages are not merged, the filled part of the current page
2217        // of `dst` goes first and its spare capacity is kept, the 4 KiB
2218        // current page of `src` is moved
2219        let mut dst = BytePages::new(BytePageSize::Size4);
2220        dst.extend_from_slice(b"first");
2221        dst.prepend(Bytes::copy_from_slice(b"0"));
2222        let mut src = mixed_pages();
2223        src.move_to(&mut dst);
2224        let chunks: Vec<&[u8]> = dst.iter().collect();
2225        assert_eq!(
2226            chunks,
2227            [
2228                &b"0"[..],
2229                &b"first"[..],
2230                &b"ab"[..],
2231                &[b'b'; 64][..],
2232                &b"current"[..]
2233            ]
2234        );
2235        assert_eq!(dst.len(), 79);
2236        dst.extend_from_slice(b"last");
2237        assert_eq!(dst.num_pages(), 6);
2238
2239        // empty source
2240        let mut src = BytePages::default();
2241        src.move_to(&mut dst);
2242        assert_eq!(dst.num_pages(), 6);
2243    }
2244
2245    /// STATEMENT: `move_to` copies less than 4 KiB of current data from a page of 8 KiB or more only into existing spare capacity of the destination and never allocates for it.
2246    ///
2247    /// HOW:
2248    /// - Move a 5-byte current page into a destination with a partially filled current page and check that the bytes are appended there, no page is added, and the source keeps its emptied page.
2249    /// - Move into a destination without a current page and check that the source page pointer is moved instead.
2250    /// - Move into a destination whose spare capacity is too small and check that the source page is moved after the split destination data.
2251    /// - Move exactly `APPEND_COPY_LIMIT` bytes and check that the page is moved even though it would fit.
2252    /// - Move a 5-byte current `Size4` page and check that the page is moved even though it would fit.
2253    /// - Append `BytesMut` buffers without a page size as the current page; check that 5 bytes are copied from a buffer with at least 8 KiB capacity and moved from a smaller one, and that `APPEND_COPY_LIMIT` bytes are moved from a large one.
2254    #[test]
2255    fn move_to_copies_small_current() {
2256        let mut src = BytePages::new(BytePageSize::Size8);
2257        src.extend_from_slice(b"hello");
2258        let src_ptr = src.iter().next().unwrap().as_ptr();
2259        let mut dst = BytePages::new(BytePageSize::Size8);
2260        dst.extend_from_slice(b"head ");
2261        let dst_ptr = dst.iter().next().unwrap().as_ptr();
2262        src.move_to(&mut dst);
2263        assert!(src.is_empty());
2264        assert_eq!(src.num_pages(), 0);
2265        assert_eq!(dst.num_pages(), 1);
2266        assert_eq!(dst.iter().next().unwrap(), b"head hello");
2267        assert_eq!(dst.iter().next().unwrap().as_ptr(), dst_ptr);
2268        src.extend_from_slice(b"again");
2269        assert_eq!(src.iter().next().unwrap().as_ptr(), src_ptr);
2270
2271        // no current page in `dst`
2272        let mut src = BytePages::new(BytePageSize::Size8);
2273        src.extend_from_slice(b"hello");
2274        let src_ptr = src.iter().next().unwrap().as_ptr();
2275        let mut dst = BytePages::new(BytePageSize::Size8);
2276        src.move_to(&mut dst);
2277        assert_eq!(dst.num_pages(), 1);
2278        assert_eq!(dst.iter().next().unwrap().as_ptr(), src_ptr);
2279
2280        // not enough spare capacity in `dst`
2281        let mut src = BytePages::new(BytePageSize::Size8);
2282        src.extend_from_slice(b"hello");
2283        let src_ptr = src.iter().next().unwrap().as_ptr();
2284        let mut dst = BytePages::new(BytePageSize::Size4);
2285        dst.extend_from_slice(b"a");
2286        let spare = dst.spare();
2287        dst.extend_from_slice(&vec![b'a'; spare - 3]);
2288        src.move_to(&mut dst);
2289        let chunks: Vec<&[u8]> = dst.iter().collect();
2290        assert_eq!(chunks.len(), 2);
2291        assert_eq!(chunks[0].len(), spare - 2);
2292        assert_eq!(chunks[1], b"hello");
2293        assert_eq!(chunks[1].as_ptr(), src_ptr);
2294
2295        // at the copy limit
2296        let mut src = BytePages::new(BytePageSize::Size8);
2297        src.extend_from_slice(&[b'x'; APPEND_COPY_LIMIT]);
2298        let src_ptr = src.iter().next().unwrap().as_ptr();
2299        let mut dst = BytePages::new(BytePageSize::Size16);
2300        dst.extend_from_slice(b"head");
2301        src.move_to(&mut dst);
2302        let chunks: Vec<&[u8]> = dst.iter().collect();
2303        assert_eq!(chunks.len(), 2);
2304        assert_eq!(chunks[1].as_ptr(), src_ptr);
2305
2306        // 4 KiB page is not copied
2307        let mut src = BytePages::new(BytePageSize::Size4);
2308        src.extend_from_slice(b"hello");
2309        let src_ptr = src.iter().next().unwrap().as_ptr();
2310        let mut dst = BytePages::new(BytePageSize::Size8);
2311        dst.extend_from_slice(b"head");
2312        src.move_to(&mut dst);
2313        let chunks: Vec<&[u8]> = dst.iter().collect();
2314        assert_eq!(chunks, [&b"head"[..], &b"hello"[..]]);
2315        assert_eq!(chunks[1].as_ptr(), src_ptr);
2316
2317        // unsized pages are copied if the capacity is at least 8 KiB
2318        for (cap, copied) in [(10_000, true), (1000, false)] {
2319            let mut buf = BytesMut::with_capacity(cap);
2320            buf.extend_from_slice(b"hello");
2321            let mut src = BytePages::new(BytePageSize::Size8);
2322            src.append(buf);
2323            let st = src.current.as_ref().unwrap();
2324            assert_eq!(st.page_size(), BytePageSize::Unset);
2325            assert_eq!(st.capacity() >= 8 * 1024, copied);
2326            let mut dst = BytePages::new(BytePageSize::Size8);
2327            dst.extend_from_slice(b"head");
2328            src.move_to(&mut dst);
2329            assert!(src.is_empty());
2330            let chunks: Vec<&[u8]> = dst.iter().collect();
2331            if copied {
2332                assert_eq!(chunks, [&b"headhello"[..]]);
2333            } else {
2334                assert_eq!(chunks, [&b"head"[..], &b"hello"[..]]);
2335            }
2336        }
2337
2338        // the copy limit applies to unsized pages too
2339        let mut buf = BytesMut::with_capacity(20_000);
2340        buf.extend_from_slice(&[b'x'; APPEND_COPY_LIMIT]);
2341        let mut src = BytePages::new(BytePageSize::Size8);
2342        src.append(buf);
2343        assert_eq!(
2344            src.current.as_ref().unwrap().page_size(),
2345            BytePageSize::Unset
2346        );
2347        let src_ptr = src.iter().next().unwrap().as_ptr();
2348        let mut dst = BytePages::new(BytePageSize::Size16);
2349        dst.extend_from_slice(b"head");
2350        src.move_to(&mut dst);
2351        let chunks: Vec<&[u8]> = dst.iter().collect();
2352        assert_eq!(chunks.len(), 2);
2353        assert_eq!(chunks[1].as_ptr(), src_ptr);
2354    }
2355
2356    /// STATEMENT: When `move_to` copies a current page that a clone still shares, later writes to the source do not overwrite the clone's data.
2357    ///
2358    /// HOW:
2359    /// - Fill an 8 KiB source page with 100 bytes (above the inline size), clone the source, and borrow a slice from the clone.
2360    /// - Move the source into a destination with spare capacity and check that the data was copied and that the source keeps its page.
2361    /// - Write 100 different bytes into the source and check that the borrowed slice and the clone still read the original bytes, and that the new bytes follow the copied ones in the shared page.
2362    /// - Drop the clone, move again, and check that the now-unique page is reclaimed, so the next write starts at the same address as the original data.
2363    #[test]
2364    fn move_to_copy_keeps_shared_current() {
2365        let mut src = BytePages::new(BytePageSize::Size8);
2366        src.put_slice(&[1; 100]);
2367        let src_ptr = src.iter().next().unwrap().as_ptr();
2368        let clone = src.clone();
2369        let view = clone.iter().next().unwrap();
2370        assert_eq!(view.as_ptr(), src_ptr);
2371
2372        let mut dst = BytePages::new(BytePageSize::Size8);
2373        dst.put_slice(b"head");
2374        src.move_to(&mut dst);
2375        assert!(src.is_empty());
2376        assert_eq!(dst.num_pages(), 1);
2377        assert_eq!(dst.len(), 104);
2378
2379        src.put_slice(&[2; 100]);
2380        assert_eq!(view, &[1; 100][..]);
2381        assert_eq!(
2382            clone.iter().flatten().copied().collect::<Vec<_>>(),
2383            [1; 100]
2384        );
2385        let chunk = src.iter().next().unwrap();
2386        assert_eq!(chunk, &[2; 100][..]);
2387        assert_eq!(chunk.as_ptr(), src_ptr.wrapping_add(100));
2388
2389        drop(clone);
2390        let mut dst = BytePages::new(BytePageSize::Size8);
2391        dst.put_slice(b"head");
2392        src.move_to(&mut dst);
2393        src.put_slice(&[3; 100]);
2394        assert_eq!(src.iter().next().unwrap().as_ptr(), src_ptr);
2395    }
2396
2397    /// STATEMENT: Advancing a vector-backed page retains the correct suffix.
2398    ///
2399    /// HOW:
2400    /// - Prepend a vector containing `hello world`, advance six bytes, and verify length five and frozen `world`.
2401    #[test]
2402    fn advance_to_vec_page() {
2403        let mut pages = BytePages::default();
2404        pages.prepend(b"hello world".to_vec());
2405        pages.advance_to(6);
2406        assert_eq!(pages.len(), 5);
2407        assert_eq!(pages.freeze(), "world");
2408    }
2409
2410    /// STATEMENT: Advancing beyond total page-buffer length panics.
2411    ///
2412    /// HOW:
2413    /// - Build `mixed_pages`, advance by its length plus one, and expect the end-of-buffer bounds panic.
2414    #[test]
2415    #[should_panic(expected = "cannot advance past the end of the buffer")]
2416    fn advance_to_past_end() {
2417        let mut pages = mixed_pages();
2418        pages.advance_to(pages.len() + 1);
2419    }
2420}