Skip to main content

eggfetch_core/
body.rs

1//! Body model for requests and responses.
2//!
3//! # Body ownership rules
4//!
5//! Both request and response bodies follow single-consumption semantics:
6//! a body can be consumed exactly once (by buffering or streaming). Once
7//! consumed, further reads return an error or produce no data.
8//!
9//! # Streaming vs buffering
10//!
11//! Response bodies can be consumed in two ways:
12//!
13//! - **Buffered**: `bytes()` or `text()` collects the entire body into
14//!   memory. Suitable for small-to-medium responses.
15//! - **Streaming**: `bytes_stream()` yields body chunks incrementally.
16//!   Suitable for large responses or when incremental processing is needed.
17//!
18//! Request bodies can be:
19//!
20//! - **Empty**: no body sent.
21//! - **Bytes**: a fixed-size byte buffer with known length. Sent as a
22//!   `Content-Length`-delimited body.
23//! - **Stream**: an async stream of bytes. Piped through to the transport
24//!   incrementally (no eager buffering). When `length` is `Some(n)`, the
25//!   body is sent as a `Content-Length`-delimited body. When `length` is
26//!   `None`, hyper's HTTP/1.1 machinery selects a safe transfer mode
27//!   (e.g. chunked transfer encoding for HTTP/1.1).
28//!
29//! # Response lease (pool permit lifecycle)
30//!
31//! Streaming response bodies carry an internal `Arc<PoolGuard>` that
32//! holds the pool permits acquired for the request. The permits are
33//! released when the response body is dropped or fully consumed. This
34//! guarantees that per-origin concurrency limits remain meaningful while
35//! response bodies are in flight: a streaming response that is held
36//! but not consumed continues to occupy its pool slot. Buffered and
37//! already-consumed responses do not carry a lease.
38
39use std::pin::Pin;
40use std::sync::Arc;
41
42use bytes::{Bytes, BytesMut};
43use futures_core::Stream;
44use futures_util::StreamExt;
45use http_body::Frame;
46use pin_project_lite::pin_project;
47
48use crate::compression::DecompressionLimit;
49use crate::error::{Error, Result};
50
51// ---------------------------------------------------------------------------
52// Request body
53// ---------------------------------------------------------------------------
54
55/// A type-erased async stream of `Result<Bytes>` chunks.
56pub type BoxBytesStream = Pin<Box<dyn Stream<Item = Result<Bytes>> + Send>>;
57
58/// Request body.
59///
60/// Supports empty bodies, fixed-size byte buffers, and async streams.
61/// `Stream` bodies are **piped through** to the transport incrementally:
62/// each chunk is sent as soon as it is produced, with no eager buffering.
63/// The optional `length` hint drives `Content-Length` for known-size
64/// streams; unknown-length streams use HTTP/1.1 chunked transfer encoding
65/// (selected by hyper).
66#[derive(Default)]
67pub enum RequestBody {
68    /// Empty body.
69    #[default]
70    Empty,
71    /// Byte body with known length.
72    Bytes(Bytes),
73    /// Async stream body.
74    ///
75    /// Chunks are sent incrementally as the stream produces them. If
76    /// `length` is `Some(n)`, a `Content-Length: n` header is set when
77    /// the user has not supplied a conflicting value. If `length` is
78    /// `None`, no `Content-Length` is set; the transport selects a
79    /// safe transfer mode (chunked for HTTP/1.1).
80    Stream {
81        /// The stream of body chunks.
82        stream: BoxBytesStream,
83        /// Known length, if available.
84        length: Option<usize>,
85    },
86}
87
88/// Replayability classification for request bodies.
89///
90/// Used by redirect and retry code to determine whether a body can be
91/// re-sent without re-consuming the original source.
92#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93pub enum ReplayClass {
94    /// Empty or immutable byte body — always replayable.
95    Immutable,
96    /// Seekable body that can be replayed by resetting position.
97    Seekable,
98    /// One-shot stream — cannot be replayed.
99    OneShot,
100    /// Body has been consumed.
101    Consumed,
102}
103
104impl std::fmt::Debug for RequestBody {
105    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
106        match self {
107            Self::Empty => f.debug_tuple("Empty").finish(),
108            // Render only the length: byte bodies routinely carry form
109            // passwords and tokens, which must not appear in logs or
110            // panic messages (see `crate::redact`).
111            Self::Bytes(b) => f.debug_tuple("Bytes").field(&b.len()).finish(),
112            Self::Stream { length, .. } => f
113                .debug_struct("Stream")
114                .field("length", length)
115                .finish_non_exhaustive(),
116        }
117    }
118}
119
120impl RequestBody {
121    /// Returns `true` if the body is empty.
122    ///
123    /// For `Stream` bodies the length hint is not authoritative — a
124    /// `Some(0)` stream may still produce bytes and an unbounded stream
125    /// may be empty. This method returns `false` for all stream bodies;
126    /// callers must not use it to decide `Content-Length` (see
127    /// [`Self::len`] and [`Self::has_known_length`]).
128    #[must_use]
129    pub fn is_empty(&self) -> bool {
130        match self {
131            Self::Empty => true,
132            Self::Bytes(b) => b.is_empty(),
133            Self::Stream { .. } => false,
134        }
135    }
136
137    /// Returns the known length of the body, if available.
138    ///
139    /// Stream bodies may not have a known length until fully consumed.
140    /// Returns `0` for unknown-length streams; callers that need to
141    /// distinguish "empty" from "unknown length" must check
142    /// [`has_known_length`](Self::has_known_length) first.
143    #[must_use]
144    pub fn len(&self) -> usize {
145        match self {
146            Self::Empty => 0,
147            Self::Bytes(b) => b.len(),
148            Self::Stream { length, .. } => length.unwrap_or(0),
149        }
150    }
151
152    /// Returns `true` if the body length is known.
153    #[must_use]
154    pub fn has_known_length(&self) -> bool {
155        match self {
156            Self::Empty | Self::Bytes(_) => true,
157            Self::Stream { length, .. } => length.is_some(),
158        }
159    }
160
161    /// Returns `true` if this body is replayable (can be sent multiple times).
162    ///
163    /// Only byte bodies are replayable. Streams are consumed on use.
164    #[must_use]
165    pub fn is_replayable(&self) -> bool {
166        matches!(self, Self::Empty | Self::Bytes(_))
167    }
168
169    /// Returns the replayability classification for this body.
170    #[must_use]
171    pub fn replay_class(&self) -> ReplayClass {
172        match self {
173            Self::Empty | Self::Bytes(_) => ReplayClass::Immutable,
174            Self::Stream { .. } => ReplayClass::OneShot,
175        }
176    }
177
178    /// Attempt to clone this body for use in a redirect request.
179    ///
180    /// Returns a cloned body if the body is replayable (empty or bytes),
181    /// or an error if the body is a live stream that cannot be resent.
182    ///
183    /// # Errors
184    ///
185    /// Returns [`Error::BodyNotReplayableForRedirect`] if the body is a
186    /// live stream that cannot be replayed for a redirect.
187    pub fn try_clone_for_redirect(&self) -> Result<Self> {
188        match self {
189            Self::Empty => Ok(Self::Empty),
190            Self::Bytes(b) => Ok(Self::Bytes(b.clone())),
191            Self::Stream { .. } => Err(Error::BodyNotReplayableForRedirect),
192        }
193    }
194
195    /// Attempt to clone this body for use in a retry attempt.
196    ///
197    /// This is the retry counterpart to [`Self::try_clone_for_redirect`]:
198    /// only replayable bodies (`Empty`/`Bytes`) succeed. One-shot streams
199    /// return the retry-specific error classification so callers preserve
200    /// the existing retry error taxonomy.
201    ///
202    /// # Errors
203    ///
204    /// Returns [`Error::BodyNotReplayableForRetry`] if the body is a
205    /// live stream that cannot be replayed for another attempt.
206    pub(crate) fn try_clone_for_retry(&self) -> Result<Self> {
207        match self {
208            Self::Empty => Ok(Self::Empty),
209            Self::Bytes(b) => Ok(Self::Bytes(b.clone())),
210            Self::Stream { .. } => Err(Error::BodyNotReplayableForRetry),
211        }
212    }
213
214    /// Consume the body and return all bytes.
215    ///
216    /// For byte bodies, returns the bytes directly. For stream bodies,
217    /// collects all chunks. For empty bodies, returns empty bytes.
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if a stream chunk fails.
222    pub async fn into_bytes(self) -> Result<Bytes> {
223        use futures_util::StreamExt;
224        match self {
225            Self::Empty => Ok(Bytes::new()),
226            Self::Bytes(b) => Ok(b),
227            Self::Stream { mut stream, length } => {
228                let mut buf = BytesMut::with_capacity(length.unwrap_or(0));
229                while let Some(chunk) = stream.next().await {
230                    buf.extend_from_slice(&chunk?);
231                }
232                Ok(buf.freeze())
233            }
234        }
235    }
236
237    /// Create a stream body with known length.
238    pub fn from_stream<S>(stream: S, length: Option<usize>) -> Self
239    where
240        S: Stream<Item = Result<Bytes>> + Send + 'static,
241    {
242        Self::Stream {
243            stream: Box::pin(stream),
244            length,
245        }
246    }
247
248    /// Convert into a hyper-compatible boxed body.
249    ///
250    /// Stream bodies are wrapped as a `StreamBody` so that chunks are
251    /// piped through to the transport incrementally. Bytes and empty
252    /// bodies are wrapped as `Full` and `Empty` respectively. No eager
253    /// buffering is performed.
254    #[allow(clippy::type_complexity)]
255    pub(crate) fn into_http_body(
256        self,
257    ) -> http_body_util::combinators::UnsyncBoxBody<Bytes, Box<dyn std::error::Error + Send + Sync>>
258    {
259        use http_body_util::combinators::UnsyncBoxBody;
260        use http_body_util::{BodyExt, Empty, Full, StreamBody};
261
262        match self {
263            Self::Empty => Empty::<Bytes>::new()
264                .map_err(|err| -> Box<dyn std::error::Error + Send + Sync> { match err {} })
265                .boxed_unsync(),
266            Self::Bytes(b) => Full::new(b)
267                .map_err(|err| -> Box<dyn std::error::Error + Send + Sync> { match err {} })
268                .boxed_unsync(),
269            Self::Stream { stream, .. } => {
270                let framed = stream.map(|chunk_result| {
271                    chunk_result
272                        .map(Frame::data)
273                        .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { Box::new(e) })
274                });
275                let body: UnsyncBoxBody<Bytes, Box<dyn std::error::Error + Send + Sync>> =
276                    BodyExt::boxed_unsync(StreamBody::new(framed));
277                body
278            }
279        }
280    }
281}
282
283impl From<Bytes> for RequestBody {
284    fn from(b: Bytes) -> Self {
285        Self::Bytes(b)
286    }
287}
288
289impl From<Vec<u8>> for RequestBody {
290    fn from(v: Vec<u8>) -> Self {
291        Self::Bytes(Bytes::from(v))
292    }
293}
294
295impl From<&[u8]> for RequestBody {
296    fn from(s: &[u8]) -> Self {
297        Self::Bytes(Bytes::copy_from_slice(s))
298    }
299}
300
301impl From<String> for RequestBody {
302    fn from(s: String) -> Self {
303        Self::Bytes(Bytes::from(s))
304    }
305}
306
307impl From<&str> for RequestBody {
308    fn from(s: &str) -> Self {
309        Self::Bytes(Bytes::copy_from_slice(s.as_bytes()))
310    }
311}
312
313// ---------------------------------------------------------------------------
314// Response body
315// ---------------------------------------------------------------------------
316
317/// A handle to a pool permit. Cloning the handle is cheap; dropping the
318/// last handle releases the permit back to the pool.
319pub(crate) type PoolGuardArc = Arc<crate::pool::PoolGuard>;
320
321/// Shared trailer store populated during body streaming.
322///
323/// Hyper yields trailers as a final `Frame::trailers` after data frames
324/// (HTTP/1.1 chunked trailers and HTTP/2 trailing HEADERS). The store is
325/// filled exactly once when that frame arrives; it stays `None` until the
326/// body has advanced far enough, when no trailers were sent, or when a body
327/// error occurred before trailers. It never buffers the body to obtain
328/// trailers and never fabricates trailer state on errors.
329///
330/// Cloning is cheap (`Arc`); the [`crate::Response`] holds one clone while
331/// the body stream holds another, so `Response::trailers()` remains
332/// available after `bytes()` collection. Dropping the body early leaves the
333/// store as `None` and releases the pool permit without waiting for
334/// trailers.
335#[derive(Debug, Clone, Default)]
336pub struct SharedTrailers {
337    inner: Arc<std::sync::Mutex<Option<http::HeaderMap>>>,
338}
339
340impl SharedTrailers {
341    /// Create an empty trailer store.
342    #[must_use]
343    pub fn new() -> Self {
344        Self {
345            inner: Arc::new(std::sync::Mutex::new(None)),
346        }
347    }
348
349    /// Store trailers received from the wire (first write wins).
350    pub(crate) fn store(&self, trailers: http::HeaderMap) {
351        if let Ok(mut guard) = self.inner.lock() {
352            if guard.is_none() {
353                *guard = Some(trailers);
354            }
355        }
356    }
357
358    /// Returns cloned trailers if they have arrived, else `None`.
359    ///
360    /// `None` means either the body has not been fully consumed yet, the
361    /// response carried no trailers, or a body error occurred before
362    /// trailers. Callers must fully consume the body stream (or `bytes()`)
363    /// before expecting trailers.
364    #[must_use]
365    pub fn get(&self) -> Option<http::HeaderMap> {
366        self.inner.lock().ok().and_then(|guard| guard.clone())
367    }
368}
369
370pin_project! {
371    /// A response stream that keeps the pool lease alive while it is in use.
372    struct LeasedResponseStream {
373        #[pin]
374        inner: BoxBytesStream,
375        _lease: Option<PoolGuardArc>,
376    }
377}
378
379impl Stream for LeasedResponseStream {
380    type Item = Result<Bytes>;
381
382    fn poll_next(
383        self: Pin<&mut Self>,
384        cx: &mut std::task::Context<'_>,
385    ) -> std::task::Poll<Option<Self::Item>> {
386        let mut this = self.project();
387        let item = this.inner.as_mut().poll_next(cx);
388        if matches!(item, std::task::Poll::Ready(Some(Err(_)) | None)) {
389            // Release the permit as soon as the stream reaches a terminal
390            // state, rather than waiting for the caller to drop the iterator.
391            this._lease.take();
392        }
393        item
394    }
395}
396
397pin_project! {
398    /// A response stream that bounds the total decoded bytes collected.
399    struct LimitedResponseStream {
400        #[pin]
401        inner: BoxBytesStream,
402        max: usize,
403        decoded_bytes: usize,
404        limit_exceeded: bool,
405    }
406}
407
408impl Stream for LimitedResponseStream {
409    type Item = Result<Bytes>;
410
411    fn poll_next(
412        self: Pin<&mut Self>,
413        cx: &mut std::task::Context<'_>,
414    ) -> std::task::Poll<Option<Self::Item>> {
415        let mut this = self.project();
416        // Once the limit trips, fuse without polling the inner transport
417        // again (releases the connection earlier and avoids unbounded
418        // inner buffering under hostile streams). Returning `None`
419        // (rather than repeating the error) keeps combinators like
420        // `collect` terminating: callers observe the first error, then EOF.
421        if *this.limit_exceeded {
422            return std::task::Poll::Ready(None);
423        }
424        match this.inner.as_mut().poll_next(cx) {
425            std::task::Poll::Ready(Some(Ok(chunk))) => {
426                *this.decoded_bytes = this.decoded_bytes.saturating_add(chunk.len());
427                if *this.decoded_bytes > *this.max {
428                    *this.limit_exceeded = true;
429                    std::task::Poll::Ready(Some(Err(Error::DecodedBodyTooLarge)))
430                } else {
431                    std::task::Poll::Ready(Some(Ok(chunk)))
432                }
433            }
434            other => other,
435        }
436    }
437}
438
439/// Response body handle.
440///
441/// Supports two consumption modes:
442///
443/// - **Buffered**: the entire body is held in memory. Created by
444///   `ResponseBody::buffered()`. Calling `bytes()` or `text()` is O(1).
445/// - **Streaming**: body chunks are yielded incrementally. Created by
446///   `ResponseBody::streaming()`. The stream must be fully consumed or
447///   dropped before the attached pool lease is released.
448///
449/// # Single-consumption semantics
450///
451/// A response body can be consumed once via `bytes()`, `text()`,
452/// `bytes_stream()`, or `raw_bytes_stream()`. For compressed streaming bodies,
453/// raw and decoded selection are mutually exclusive. After consumption,
454/// further reads return an error.
455pub enum ResponseBody {
456    /// Fully buffered body.
457    Buffered {
458        /// The buffered body bytes.
459        bytes: Bytes,
460    },
461    /// Streaming body.
462    Streaming {
463        /// The body stream.
464        stream: BoxBytesStream,
465        /// Optional pool permit holder. Released on drop.
466        lease: Option<PoolGuardArc>,
467    },
468    /// A compressed streaming body whose encoded source is retained until
469    /// the caller selects raw or decoded consumption.
470    EncodedStreaming {
471        /// The encoded body stream.
472        stream: BoxBytesStream,
473        /// Optional pool permit holder. Released on drop.
474        lease: Option<PoolGuardArc>,
475        /// The original `Content-Encoding` header value.
476        content_encoding: String,
477        /// Limits applied when decoded mode is selected.
478        limit: DecompressionLimit,
479    },
480    /// The streaming body has already been consumed.
481    Consumed,
482}
483
484impl std::fmt::Debug for ResponseBody {
485    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
486        match self {
487            Self::Buffered { bytes } => f
488                .debug_struct("Buffered")
489                .field("len", &bytes.len())
490                .finish(),
491            Self::Streaming { .. } => f.debug_struct("Streaming").finish_non_exhaustive(),
492            Self::EncodedStreaming { .. } => {
493                f.debug_struct("EncodedStreaming").finish_non_exhaustive()
494            }
495            Self::Consumed => f.debug_struct("Consumed").finish(),
496        }
497    }
498}
499
500impl ResponseBody {
501    /// Create a buffered response body.
502    #[must_use]
503    pub fn buffered(bytes: Bytes) -> Self {
504        Self::Buffered { bytes }
505    }
506
507    /// Create a streaming response body from a type-erased stream.
508    #[must_use]
509    pub fn streaming(stream: BoxBytesStream) -> Self {
510        Self::Streaming {
511            stream,
512            lease: None,
513        }
514    }
515
516    /// Create a streaming response body with an attached pool permit.
517    /// The permit is released when the body is dropped.
518    pub(crate) fn streaming_with_lease(stream: BoxBytesStream, lease: PoolGuardArc) -> Self {
519        Self::Streaming {
520            stream,
521            lease: Some(lease),
522        }
523    }
524
525    /// Create a deferred-decode streaming response body.
526    pub(crate) fn encoded_streaming(
527        stream: BoxBytesStream,
528        content_encoding: String,
529        limit: DecompressionLimit,
530    ) -> Self {
531        Self::EncodedStreaming {
532            stream,
533            lease: None,
534            content_encoding,
535            limit,
536        }
537    }
538
539    /// Create a deferred-decode streaming response body with an attached
540    /// pool permit.
541    pub(crate) fn encoded_streaming_with_lease(
542        stream: BoxBytesStream,
543        lease: PoolGuardArc,
544        content_encoding: String,
545        limit: DecompressionLimit,
546    ) -> Self {
547        Self::EncodedStreaming {
548            stream,
549            lease: Some(lease),
550            content_encoding,
551            limit,
552        }
553    }
554
555    /// Returns `true` if the body is empty.
556    #[must_use]
557    pub fn is_empty(&self) -> bool {
558        match self {
559            Self::Buffered { bytes } => bytes.is_empty(),
560            Self::Streaming { .. } | Self::EncodedStreaming { .. } => false, // unknown until consumed
561            Self::Consumed => true,
562        }
563    }
564
565    /// Returns the buffered body length, if available.
566    ///
567    /// For streaming bodies, returns `None` until the body is fully
568    /// collected.
569    #[must_use]
570    pub fn len(&self) -> Option<usize> {
571        match self {
572            Self::Buffered { bytes } => Some(bytes.len()),
573            Self::Streaming { .. } | Self::EncodedStreaming { .. } => None,
574            Self::Consumed => Some(0),
575        }
576    }
577
578    /// Returns `true` if this is a buffered body.
579    #[must_use]
580    pub fn is_buffered(&self) -> bool {
581        matches!(self, Self::Buffered { .. })
582    }
583
584    /// Consume the body and return all bytes.
585    ///
586    /// For buffered bodies, this is O(1). For streaming bodies, this
587    /// collects all chunks into a single `Bytes` buffer.
588    ///
589    /// # Limits
590    ///
591    /// The configured decoded-body limit is enforced for both encoded and
592    /// unencoded response bodies.
593    ///
594    /// [`DecompressionLimit`]: crate::compression::DecompressionLimit
595    ///
596    /// # Errors
597    ///
598    /// Returns an error if the body has already been consumed or if a
599    /// stream chunk fails.
600    pub async fn bytes(&mut self) -> Result<Bytes> {
601        let old = std::mem::replace(self, Self::Consumed);
602        match old {
603            Self::Buffered { bytes } => Ok(bytes),
604            Self::Streaming {
605                mut stream, lease, ..
606            } => {
607                let mut buf = BytesMut::new();
608                while let Some(chunk) = stream.next().await {
609                    buf.extend_from_slice(&chunk?);
610                }
611                drop(lease);
612                Ok(buf.freeze())
613            }
614            Self::EncodedStreaming {
615                stream,
616                lease,
617                content_encoding,
618                limit,
619            } => {
620                let mut stream = crate::compression::decompress_stream(
621                    stream,
622                    Some(&content_encoding),
623                    true,
624                    limit,
625                )?;
626                let mut buf = BytesMut::new();
627                while let Some(chunk) = stream.next().await {
628                    buf.extend_from_slice(&chunk?);
629                }
630                drop(lease);
631                Ok(buf.freeze())
632            }
633            Self::Consumed => Err(Error::Body("body already consumed".into())),
634        }
635    }
636
637    /// Enforce a maximum decoded size for this body.
638    pub(crate) fn limit_decoded_size(self, max: usize) -> Result<Self> {
639        match self {
640            Self::Buffered { bytes } if bytes.len() > max => Err(Error::DecodedBodyTooLarge),
641            Self::Buffered { bytes } => Ok(Self::Buffered { bytes }),
642            Self::Streaming { stream, lease } => Ok(Self::Streaming {
643                stream: Box::pin(LimitedResponseStream {
644                    inner: stream,
645                    max,
646                    decoded_bytes: 0,
647                    limit_exceeded: false,
648                }),
649                lease,
650            }),
651            Self::EncodedStreaming {
652                stream,
653                lease,
654                content_encoding,
655                limit: mut existing_limit,
656            } => {
657                existing_limit.max_decoded_body_size = Some(
658                    existing_limit
659                        .max_decoded_body_size
660                        .map_or(max, |current| current.min(max)),
661                );
662                Ok(Self::EncodedStreaming {
663                    stream,
664                    lease,
665                    content_encoding,
666                    limit: existing_limit,
667                })
668            }
669            body @ Self::Consumed => Ok(body),
670        }
671    }
672
673    /// Consume the body and return it as a UTF-8 string.
674    ///
675    /// # Errors
676    ///
677    /// Returns an error if the body is not valid UTF-8 or has already
678    /// been consumed.
679    pub async fn text(&mut self) -> Result<String> {
680        let bytes = self.bytes().await?;
681        String::from_utf8(bytes.to_vec()).map_err(|e| Error::Body(e.to_string()))
682    }
683
684    /// Consume the body and return a stream of byte chunks.
685    ///
686    /// For buffered bodies, yields the entire body as a single chunk.
687    /// For streaming bodies, yields chunks incrementally.
688    ///
689    /// # Errors
690    ///
691    /// Returns an error if the body has already been consumed.
692    pub fn bytes_stream(&mut self) -> Result<BoxBytesStream> {
693        self.take_stream(false)
694    }
695
696    /// Consume the body and return the encoded response byte stream.
697    ///
698    /// For compressed streaming responses, this selects the original encoded
699    /// transport body and bypasses the existing decoder chain. The selection
700    /// is one-shot; a body cannot subsequently be consumed in decoded mode.
701    /// Buffered bodies follow the ordinary streaming path because their
702    /// encoded representation is no longer available.
703    ///
704    /// # Errors
705    ///
706    /// Returns an error if the body has already been consumed or if the
707    /// decoder configuration is invalid while selecting a stream.
708    pub fn raw_bytes_stream(&mut self) -> Result<BoxBytesStream> {
709        self.take_stream(true)
710    }
711
712    fn take_stream(&mut self, raw: bool) -> Result<BoxBytesStream> {
713        match self {
714            Self::Buffered { bytes } => {
715                let bytes = std::mem::take(bytes);
716                *self = Self::Consumed;
717                Ok(Box::pin(futures_util::stream::once(
718                    async move { Ok(bytes) },
719                )))
720            }
721            Self::Streaming { .. } => {
722                let old = std::mem::replace(self, Self::Consumed);
723                if let Self::Streaming { stream, lease } = old {
724                    Ok(Box::pin(LeasedResponseStream {
725                        inner: stream,
726                        _lease: lease,
727                    }))
728                } else {
729                    // Defensive: the outer match guarantees this arm, but
730                    // a future variant addition must surface as an error,
731                    // not a panic.
732                    Err(Error::Body("response body state mismatch".into()))
733                }
734            }
735            Self::EncodedStreaming { .. } => {
736                let old = std::mem::replace(self, Self::Consumed);
737                if let Self::EncodedStreaming {
738                    stream,
739                    lease,
740                    content_encoding,
741                    limit,
742                } = old
743                {
744                    let stream = if raw {
745                        Ok(stream)
746                    } else {
747                        crate::compression::decompress_stream(
748                            stream,
749                            Some(&content_encoding),
750                            true,
751                            limit,
752                        )
753                    }?;
754                    Ok(Box::pin(LeasedResponseStream {
755                        inner: stream,
756                        _lease: lease,
757                    }))
758                } else {
759                    // Defensive: the outer match guarantees this arm, but
760                    // a future variant addition must surface as an error,
761                    // not a panic.
762                    Err(Error::Body("response body state mismatch".into()))
763                }
764            }
765            Self::Consumed => Err(Error::Body("streaming body already consumed".into())),
766        }
767    }
768}
769
770// ---------------------------------------------------------------------------
771// Tests
772// ---------------------------------------------------------------------------
773
774#[cfg(test)]
775mod tests {
776    use super::*;
777
778    #[test]
779    fn request_body_empty() {
780        let body = RequestBody::Empty;
781        assert!(body.is_empty());
782        assert_eq!(body.len(), 0);
783        assert!(body.has_known_length());
784        assert!(body.is_replayable());
785    }
786
787    #[test]
788    fn request_body_bytes() {
789        let body = RequestBody::from(Bytes::from("hello"));
790        assert!(!body.is_empty());
791        assert_eq!(body.len(), 5);
792        assert!(body.has_known_length());
793        assert!(body.is_replayable());
794    }
795
796    #[test]
797    fn request_body_stream_unknown_length() {
798        let stream = futures_util::stream::empty::<Result<Bytes>>();
799        let body = RequestBody::from_stream(stream, None);
800        assert!(!body.is_empty());
801        assert_eq!(body.len(), 0);
802        assert!(!body.has_known_length());
803        assert!(!body.is_replayable());
804    }
805
806    #[test]
807    fn request_body_stream_known_length() {
808        let stream = futures_util::stream::empty::<Result<Bytes>>();
809        let body = RequestBody::from_stream(stream, Some(1024));
810        assert!(!body.is_empty());
811        assert_eq!(body.len(), 1024);
812        assert!(body.has_known_length());
813        assert!(!body.is_replayable());
814    }
815
816    #[test]
817    fn try_clone_for_redirect_empty() {
818        let body = RequestBody::Empty;
819        let cloned = body.try_clone_for_redirect().unwrap();
820        assert!(cloned.is_empty());
821    }
822
823    #[test]
824    fn try_clone_for_redirect_bytes() {
825        let body = RequestBody::from(Bytes::from("hello"));
826        let cloned = body.try_clone_for_redirect().unwrap();
827        match cloned {
828            RequestBody::Bytes(b) => assert_eq!(b, "hello"),
829            _ => panic!("expected bytes"),
830        }
831    }
832
833    #[test]
834    fn try_clone_for_redirect_stream_errors() {
835        let stream = futures_util::stream::empty::<Result<Bytes>>();
836        let body = RequestBody::from_stream(stream, None);
837        assert!(body.try_clone_for_redirect().is_err());
838    }
839
840    #[test]
841    fn request_body_bytes_debug_redacts_contents() {
842        let body = RequestBody::from(Bytes::from("form-password=hunter2"));
843        let debug = format!("{body:?}");
844        assert!(
845            !debug.contains("hunter2"),
846            "RequestBody Debug must not leak byte contents: {debug}"
847        );
848        assert!(
849            debug.contains("Bytes(21)"),
850            "RequestBody Debug reports the length only: {debug}"
851        );
852    }
853
854    #[test]
855    fn response_body_buffered() {
856        let body = ResponseBody::buffered(Bytes::from("hello"));
857        assert!(!body.is_empty());
858        assert_eq!(body.len(), Some(5));
859        assert!(body.is_buffered());
860    }
861
862    #[test]
863    fn response_body_streaming() {
864        let stream = Box::pin(futures_util::stream::empty());
865        let body = ResponseBody::streaming(stream);
866        assert!(!body.is_buffered());
867    }
868
869    #[tokio::test]
870    async fn response_body_buffered_bytes() {
871        let mut body = ResponseBody::buffered(Bytes::from("hello world"));
872        let bytes = body.bytes().await.unwrap();
873        assert_eq!(bytes, "hello world");
874    }
875
876    #[tokio::test]
877    async fn response_body_buffered_text() {
878        let mut body = ResponseBody::buffered(Bytes::from("hello"));
879        let text = body.text().await.unwrap();
880        assert_eq!(text, "hello");
881    }
882
883    #[tokio::test]
884    async fn response_body_buffered_stream_yields_single_chunk() {
885        let mut body = ResponseBody::buffered(Bytes::from("data"));
886        let mut stream = body.bytes_stream().unwrap();
887        let chunk = stream.next().await.unwrap().unwrap();
888        assert_eq!(chunk, "data");
889        assert!(stream.next().await.is_none());
890    }
891
892    #[tokio::test]
893    async fn response_body_streaming_yields_chunks() {
894        let chunks = vec![
895            Ok(Bytes::from("a")),
896            Ok(Bytes::from("bb")),
897            Ok(Bytes::from("ccc")),
898        ];
899        let stream = Box::pin(futures_util::stream::iter(chunks));
900        let mut body = ResponseBody::streaming(stream);
901        let mut stream = body.bytes_stream().unwrap();
902        assert_eq!(stream.next().await.unwrap().unwrap(), "a");
903        assert_eq!(stream.next().await.unwrap().unwrap(), "bb");
904        assert_eq!(stream.next().await.unwrap().unwrap(), "ccc");
905        assert!(stream.next().await.is_none());
906    }
907
908    #[tokio::test]
909    async fn response_body_streaming_collect() {
910        let chunks = vec![Ok(Bytes::from("hello ")), Ok(Bytes::from("world"))];
911        let stream = Box::pin(futures_util::stream::iter(chunks));
912        let mut body = ResponseBody::streaming(stream);
913        let bytes = body.bytes().await.unwrap();
914        assert_eq!(bytes, "hello world");
915    }
916
917    #[tokio::test]
918    async fn response_body_unencoded_size_limit_is_enforced() {
919        let stream = Box::pin(futures_util::stream::iter(vec![
920            Ok(Bytes::from("ab")),
921            Ok(Bytes::from("cd")),
922        ]));
923        let mut body = ResponseBody::streaming(stream)
924            .limit_decoded_size(3)
925            .unwrap();
926        assert_eq!(
927            body.bytes().await.unwrap_err().kind(),
928            "decoded_body_too_large"
929        );
930    }
931
932    #[test]
933    fn response_body_buffered_size_limit_is_enforced() {
934        let body = ResponseBody::buffered(Bytes::from_static(b"body"));
935        assert_eq!(
936            body.limit_decoded_size(3).unwrap_err().kind(),
937            "decoded_body_too_large"
938        );
939    }
940
941    #[tokio::test]
942    async fn response_body_double_consume_replaces() {
943        let mut body = ResponseBody::buffered(Bytes::from("data"));
944        let _ = body.bytes().await.unwrap();
945        assert!(body.bytes().await.is_err());
946    }
947
948    #[tokio::test]
949    async fn response_body_double_stream_errors() {
950        let stream = Box::pin(futures_util::stream::iter(vec![Ok(Bytes::from("x"))]));
951        let mut body = ResponseBody::streaming(stream);
952        let _ = body.bytes_stream().unwrap();
953        let err = body.bytes_stream();
954        assert!(err.is_err());
955    }
956
957    #[cfg(feature = "compression-gzip")]
958    fn gzip_bytes(input: &[u8]) -> Bytes {
959        use std::io::Write;
960
961        let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast());
962        encoder.write_all(input).unwrap();
963        Bytes::from(encoder.finish().unwrap())
964    }
965
966    #[cfg(feature = "compression-gzip")]
967    #[tokio::test]
968    async fn encoded_streaming_selects_raw_once() {
969        let encoded = gzip_bytes(b"compressed body");
970        let expected = encoded.clone();
971        let stream = Box::pin(futures_util::stream::iter(vec![Ok(encoded)]));
972        let mut body = ResponseBody::encoded_streaming(
973            stream,
974            "gzip".to_owned(),
975            DecompressionLimit::default(),
976        );
977
978        let mut raw = body.raw_bytes_stream().unwrap();
979        assert_eq!(raw.next().await.unwrap().unwrap(), expected);
980        assert!(raw.next().await.is_none());
981        assert!(body.bytes_stream().is_err());
982    }
983
984    #[cfg(feature = "compression-gzip")]
985    #[tokio::test]
986    async fn encoded_streaming_selects_decoded_once() {
987        let encoded = gzip_bytes(b"compressed body");
988        let stream = Box::pin(futures_util::stream::iter(vec![Ok(encoded)]));
989        let mut body = ResponseBody::encoded_streaming(
990            stream,
991            "gzip".to_owned(),
992            DecompressionLimit::default(),
993        );
994
995        let mut decoded = body.bytes_stream().unwrap();
996        assert_eq!(decoded.next().await.unwrap().unwrap(), "compressed body");
997        assert!(decoded.next().await.is_none());
998        assert!(body.raw_bytes_stream().is_err());
999    }
1000
1001    #[cfg(feature = "compression-gzip")]
1002    #[tokio::test]
1003    async fn encoded_streaming_limit_is_applied_when_added_after_construction() {
1004        let encoded = gzip_bytes(b"compressed body");
1005        let stream = Box::pin(futures_util::stream::iter(vec![Ok(encoded)]));
1006        let mut body = ResponseBody::encoded_streaming(
1007            stream,
1008            "gzip".to_owned(),
1009            DecompressionLimit::default(),
1010        )
1011        .limit_decoded_size(3)
1012        .unwrap();
1013
1014        assert_eq!(
1015            body.bytes().await.unwrap_err().kind(),
1016            "decoded_body_too_large"
1017        );
1018    }
1019
1020    #[tokio::test]
1021    async fn uncompressed_raw_selection_is_passthrough() {
1022        let stream = Box::pin(futures_util::stream::iter(vec![Ok(Bytes::from("body"))]));
1023        let mut body = ResponseBody::streaming(stream);
1024        let mut raw = body.raw_bytes_stream().unwrap();
1025        assert_eq!(raw.next().await.unwrap().unwrap(), "body");
1026        assert!(raw.next().await.is_none());
1027    }
1028
1029    #[tokio::test]
1030    async fn response_body_buffered_double_bytes_errors() {
1031        let mut body = ResponseBody::buffered(Bytes::from("data"));
1032        let first = body.bytes().await.unwrap();
1033        assert_eq!(first, "data");
1034        assert!(body.bytes().await.is_err());
1035    }
1036
1037    #[tokio::test]
1038    async fn response_body_buffered_text_invalid_utf8() {
1039        let mut body = ResponseBody::buffered(Bytes::from(vec![0xFF, 0xFE]));
1040        let err = body.text().await;
1041        assert!(err.is_err());
1042    }
1043
1044    #[tokio::test]
1045    async fn response_body_streaming_bytes_then_stream_returns_empty() {
1046        let stream = Box::pin(futures_util::stream::iter(vec![Ok(Bytes::from("x"))]));
1047        let mut body = ResponseBody::streaming(stream);
1048        let _ = body.bytes().await.unwrap();
1049        assert!(body.bytes_stream().is_err());
1050    }
1051
1052    #[tokio::test]
1053    async fn response_body_consumed_is_empty() {
1054        let body = ResponseBody::Consumed;
1055        assert!(body.is_empty());
1056        assert_eq!(body.len(), Some(0));
1057    }
1058
1059    #[tokio::test]
1060    async fn response_body_buffered_bytes_stream_then_bytes_returns_empty() {
1061        let mut body = ResponseBody::buffered(Bytes::from("data"));
1062        let mut stream = body.bytes_stream().unwrap();
1063        let chunk = stream.next().await.unwrap().unwrap();
1064        assert_eq!(chunk, "data");
1065        assert!(stream.next().await.is_none());
1066        assert!(body.bytes().await.is_err());
1067    }
1068
1069    #[tokio::test]
1070    async fn into_http_body_empty_produces_empty_body() {
1071        use http_body::Body;
1072        use http_body_util::BodyExt;
1073
1074        let body = RequestBody::Empty;
1075        let mut hyper_body = body.into_http_body();
1076        let frame = futures_util::future::poll_fn(|cx| {
1077            use std::pin::Pin;
1078            Pin::new(&mut hyper_body).poll_frame(cx)
1079        })
1080        .await;
1081        assert!(frame.is_none());
1082        let _ = hyper_body.collect().await;
1083    }
1084
1085    #[tokio::test]
1086    async fn into_http_body_bytes_produces_one_data_frame() {
1087        use http_body::Body;
1088        use std::pin::Pin;
1089
1090        let body = RequestBody::from(Bytes::from("hello"));
1091        let mut hyper_body = body.into_http_body();
1092
1093        let frame = futures_util::future::poll_fn(|cx| Pin::new(&mut hyper_body).poll_frame(cx))
1094            .await
1095            .expect("frame present")
1096            .expect("frame ok");
1097        assert!(frame.is_data());
1098        let data = frame.into_data().unwrap();
1099        assert_eq!(data, "hello");
1100
1101        let end =
1102            futures_util::future::poll_fn(|cx| Pin::new(&mut hyper_body).poll_frame(cx)).await;
1103        assert!(end.is_none());
1104    }
1105
1106    #[tokio::test]
1107    async fn into_http_body_stream_pipes_through_without_eager_buffering() {
1108        use http_body::Body;
1109        use std::pin::Pin;
1110        use std::sync::atomic::{AtomicUsize, Ordering};
1111
1112        let polled = Arc::new(AtomicUsize::new(0));
1113        let polled_inner = polled.clone();
1114
1115        let chunks = vec![
1116            Ok(Bytes::from("a")),
1117            Ok(Bytes::from("b")),
1118            Ok(Bytes::from("c")),
1119        ];
1120        let chunk_stream = futures_util::stream::iter(chunks).inspect(move |_| {
1121            polled_inner.fetch_add(1, Ordering::SeqCst);
1122        });
1123        let body = RequestBody::from_stream(chunk_stream.map(|r| -> Result<Bytes> { r }), Some(3));
1124        let mut hyper_body = body.into_http_body();
1125
1126        let frame = futures_util::future::poll_fn(|cx| Pin::new(&mut hyper_body).poll_frame(cx))
1127            .await
1128            .expect("frame present")
1129            .expect("frame ok");
1130        let data = frame.into_data().unwrap();
1131        assert_eq!(data, "a");
1132        assert_eq!(
1133            polled.load(Ordering::SeqCst),
1134            1,
1135            "stream should not be eagerly polled"
1136        );
1137    }
1138
1139    #[tokio::test]
1140    async fn limited_stream_fuses_after_limit_trips() {
1141        use futures_util::StreamExt;
1142        use std::sync::atomic::{AtomicUsize, Ordering};
1143
1144        let polls = Arc::new(AtomicUsize::new(0));
1145        let polls_inner = polls.clone();
1146        let tracked = futures_util::stream::iter(vec![
1147            Ok(Bytes::from("ab")),
1148            Ok(Bytes::from("cd")),
1149            Ok(Bytes::from("ef")),
1150        ])
1151        .inspect(move |_| {
1152            polls_inner.fetch_add(1, Ordering::SeqCst);
1153        });
1154        let inner: super::BoxBytesStream = Box::pin(tracked);
1155        let mut limited = super::LimitedResponseStream {
1156            inner,
1157            max: 3,
1158            decoded_bytes: 0,
1159            limit_exceeded: false,
1160        };
1161        // "ab" ok (2 bytes), "cd" trips the limit (4 > 3).
1162        assert!(limited.next().await.unwrap().is_ok());
1163        assert!(limited.next().await.unwrap().is_err());
1164        let polls_after_error = polls.load(Ordering::SeqCst);
1165        // Further polls fuse (EOF) without polling inner again.
1166        assert!(limited.next().await.is_none());
1167        assert_eq!(
1168            polls.load(Ordering::SeqCst),
1169            polls_after_error,
1170            "inner stream must not be re-polled after the limit trips"
1171        );
1172    }
1173
1174    #[tokio::test]
1175    async fn leased_stream_holds_pool_slot_until_drop() {
1176        let pool = crate::pool::Pool::new(crate::pool::PoolConfig {
1177            max_connections_per_host: Some(1),
1178            ..Default::default()
1179        });
1180        let origin = crate::pool::OriginKey::from_parts("http", "example.com", 80);
1181        let guard = pool.acquire(Some(&origin)).await.unwrap();
1182        let mut body = ResponseBody::streaming_with_lease(
1183            Box::pin(futures_util::stream::pending()),
1184            Arc::new(guard),
1185        );
1186        let stream = body.bytes_stream().unwrap();
1187
1188        assert!(tokio::time::timeout(
1189            std::time::Duration::from_millis(10),
1190            pool.acquire(Some(&origin))
1191        )
1192        .await
1193        .is_err());
1194
1195        drop(stream);
1196        assert!(tokio::time::timeout(
1197            std::time::Duration::from_millis(100),
1198            pool.acquire(Some(&origin))
1199        )
1200        .await
1201        .is_ok());
1202    }
1203}