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::future::Future as _;
40use std::pin::Pin;
41use std::sync::Arc;
42use std::task::{Context, Poll};
43use std::time::Duration;
44
45use bytes::{Bytes, BytesMut};
46use futures_core::Stream;
47use futures_util::StreamExt;
48use http_body::Frame;
49use pin_project_lite::pin_project;
50
51use crate::compression::DecompressionLimit;
52use crate::error::{Error, Result};
53use crate::timeout::ResponseDeadline;
54
55// ---------------------------------------------------------------------------
56// Request body
57// ---------------------------------------------------------------------------
58
59/// A type-erased async stream of `Result<Bytes>` chunks.
60pub type BoxBytesStream = Pin<Box<dyn Stream<Item = Result<Bytes>> + Send>>;
61
62/// Request body.
63///
64/// Supports empty bodies, fixed-size byte buffers, and async streams.
65/// `Stream` bodies are **piped through** to the transport incrementally:
66/// each chunk is sent as soon as it is produced, with no eager buffering.
67/// The optional `length` hint drives `Content-Length` for known-size
68/// streams; unknown-length streams use HTTP/1.1 chunked transfer encoding
69/// (selected by hyper).
70#[derive(Default)]
71pub enum RequestBody {
72    /// Empty body.
73    #[default]
74    Empty,
75    /// Byte body with known length.
76    Bytes(Bytes),
77    /// Async stream body.
78    ///
79    /// Chunks are sent incrementally as the stream produces them. If
80    /// `length` is `Some(n)`, a `Content-Length: n` header is set when
81    /// the user has not supplied a conflicting value. If `length` is
82    /// `None`, no `Content-Length` is set; the transport selects a
83    /// safe transfer mode (chunked for HTTP/1.1).
84    ///
85    /// Note: stream bodies are never replayable, even with
86    /// `length = Some(n)` — the bytes are consumed on first send and
87    /// retry/redirect degrades to a single attempt
88    /// (`BodyNotReplayableForRedirect` / no retry). Callers needing
89    /// retried uploads must buffer into `Bytes` first.
90    Stream {
91        /// The stream of body chunks.
92        stream: BoxBytesStream,
93        /// Known length, if available.
94        length: Option<usize>,
95    },
96}
97
98/// Replayability classification for request bodies.
99///
100/// Used by redirect and retry code to determine whether a body can be
101/// re-sent without re-consuming the original source.
102#[derive(Debug, Clone, Copy, PartialEq, Eq)]
103pub enum ReplayClass {
104    /// Empty or immutable byte body — always replayable.
105    Immutable,
106    /// Seekable body that can be replayed by resetting position.
107    Seekable,
108    /// One-shot stream — cannot be replayed.
109    OneShot,
110    /// Body has been consumed.
111    Consumed,
112}
113
114impl std::fmt::Debug for RequestBody {
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        match self {
117            Self::Empty => f.debug_tuple("Empty").finish(),
118            // Render only the length: byte bodies routinely carry form
119            // passwords and tokens, which must not appear in logs or
120            // panic messages (see `crate::redact`).
121            Self::Bytes(b) => f.debug_tuple("Bytes").field(&b.len()).finish(),
122            Self::Stream { length, .. } => f
123                .debug_struct("Stream")
124                .field("length", length)
125                .finish_non_exhaustive(),
126        }
127    }
128}
129
130impl RequestBody {
131    /// Returns `true` if the body is empty.
132    ///
133    /// For `Stream` bodies the length hint is not authoritative — a
134    /// `Some(0)` stream may still produce bytes and an unbounded stream
135    /// may be empty. This method returns `false` for all stream bodies;
136    /// callers must not use it to decide `Content-Length` (see
137    /// [`Self::len`] and [`Self::has_known_length`]).
138    #[must_use]
139    pub fn is_empty(&self) -> bool {
140        match self {
141            Self::Empty => true,
142            Self::Bytes(b) => b.is_empty(),
143            Self::Stream { .. } => false,
144        }
145    }
146
147    /// Returns the known length of the body, if available.
148    ///
149    /// Stream bodies may not have a known length until fully consumed.
150    /// Returns `0` for unknown-length streams; callers that need to
151    /// distinguish "empty" from "unknown length" must check
152    /// [`has_known_length`](Self::has_known_length) first and must not use
153    /// `len() == 0` to decide emptiness (use [`is_empty`](Self::is_empty),
154    /// which returns `false` for streams). Internal Content-Length logic
155    /// matches on the `Stream { length }` variant directly, never on `len()`.
156    #[must_use]
157    pub fn len(&self) -> usize {
158        match self {
159            Self::Empty => 0,
160            Self::Bytes(b) => b.len(),
161            Self::Stream { length, .. } => length.unwrap_or(0),
162        }
163    }
164
165    /// Returns `true` if the body length is known.
166    #[must_use]
167    pub fn has_known_length(&self) -> bool {
168        match self {
169            Self::Empty | Self::Bytes(_) => true,
170            Self::Stream { length, .. } => length.is_some(),
171        }
172    }
173
174    /// Returns `true` if this body is replayable (can be sent multiple times).
175    ///
176    /// Only byte bodies are replayable. Streams are consumed on use.
177    #[must_use]
178    pub fn is_replayable(&self) -> bool {
179        matches!(self, Self::Empty | Self::Bytes(_))
180    }
181
182    /// Returns the replayability classification for this body.
183    #[must_use]
184    pub fn replay_class(&self) -> ReplayClass {
185        match self {
186            Self::Empty | Self::Bytes(_) => ReplayClass::Immutable,
187            Self::Stream { .. } => ReplayClass::OneShot,
188        }
189    }
190
191    /// Attempt to clone this body for use in a redirect request.
192    ///
193    /// Returns a cloned body if the body is replayable (empty or bytes),
194    /// or an error if the body is a live stream that cannot be resent.
195    ///
196    /// # Errors
197    ///
198    /// Returns [`Error::BodyNotReplayableForRedirect`] if the body is a
199    /// live stream that cannot be replayed for a redirect.
200    pub fn try_clone_for_redirect(&self) -> Result<Self> {
201        match self {
202            Self::Empty => Ok(Self::Empty),
203            Self::Bytes(b) => Ok(Self::Bytes(b.clone())),
204            Self::Stream { .. } => Err(Error::BodyNotReplayableForRedirect),
205        }
206    }
207
208    /// Attempt to clone this body for use in a retry attempt.
209    ///
210    /// Only available with the `logical-retry` feature (or `proxy`, whose
211    /// CONNECT multi-address fallback reuses the same replay check). This
212    /// is the retry counterpart to [`Self::try_clone_for_redirect`]:
213    /// only replayable bodies (`Empty`/`Bytes`) succeed. One-shot streams
214    /// return the retry-specific error classification so callers preserve
215    /// the existing retry error taxonomy.
216    ///
217    /// # Errors
218    ///
219    /// Returns [`Error::BodyNotReplayableForRetry`] if the body is a
220    /// live stream that cannot be replayed for another attempt.
221    #[cfg(any(feature = "logical-retry", feature = "proxy"))]
222    pub(crate) fn try_clone_for_retry(&self) -> Result<Self> {
223        match self {
224            Self::Empty => Ok(Self::Empty),
225            Self::Bytes(b) => Ok(Self::Bytes(b.clone())),
226            Self::Stream { .. } => Err(Error::BodyNotReplayableForRetry),
227        }
228    }
229
230    /// Consume the body and return all bytes.
231    ///
232    /// For byte bodies, returns the bytes directly. For stream bodies,
233    /// collects all chunks. For empty bodies, returns empty bytes.
234    ///
235    /// # Errors
236    ///
237    /// Returns an error if a stream chunk fails.
238    pub async fn into_bytes(self) -> Result<Bytes> {
239        use futures_util::StreamExt;
240        match self {
241            Self::Empty => Ok(Bytes::new()),
242            Self::Bytes(b) => Ok(b),
243            Self::Stream { mut stream, length } => {
244                let mut buf = BytesMut::with_capacity(length.unwrap_or(0));
245                while let Some(chunk) = stream.next().await {
246                    buf.extend_from_slice(&chunk?);
247                }
248                Ok(buf.freeze())
249            }
250        }
251    }
252
253    /// Create a stream body with known length.
254    pub fn from_stream<S>(stream: S, length: Option<usize>) -> Self
255    where
256        S: Stream<Item = Result<Bytes>> + Send + 'static,
257    {
258        Self::Stream {
259            stream: Box::pin(stream),
260            length,
261        }
262    }
263
264    /// Convert into a hyper-compatible boxed body.
265    ///
266    /// Stream bodies are wrapped as a `StreamBody` so that chunks are
267    /// piped through to the transport incrementally. Bytes and empty
268    /// bodies are wrapped as `Full` and `Empty` respectively. No eager
269    /// buffering is performed.
270    #[allow(
271        clippy::type_complexity,
272        reason = "the Hyper body type is fixed by the `http-body-util` API and cannot be named more simply without changing the transport contract"
273    )]
274    pub(crate) fn into_http_body(
275        self,
276    ) -> http_body_util::combinators::UnsyncBoxBody<Bytes, Box<dyn std::error::Error + Send + Sync>>
277    {
278        use http_body_util::combinators::UnsyncBoxBody;
279        use http_body_util::{BodyExt, Empty, Full, StreamBody};
280
281        match self {
282            Self::Empty => Empty::<Bytes>::new()
283                .map_err(|err| -> Box<dyn std::error::Error + Send + Sync> { match err {} })
284                .boxed_unsync(),
285            Self::Bytes(b) => Full::new(b)
286                .map_err(|err| -> Box<dyn std::error::Error + Send + Sync> { match err {} })
287                .boxed_unsync(),
288            Self::Stream { stream, .. } => {
289                let framed = stream.map(|chunk_result| {
290                    chunk_result
291                        .map(Frame::data)
292                        .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { Box::new(e) })
293                });
294                let body: UnsyncBoxBody<Bytes, Box<dyn std::error::Error + Send + Sync>> =
295                    BodyExt::boxed_unsync(StreamBody::new(framed));
296                body
297            }
298        }
299    }
300}
301
302impl From<Bytes> for RequestBody {
303    fn from(b: Bytes) -> Self {
304        Self::Bytes(b)
305    }
306}
307
308impl From<Vec<u8>> for RequestBody {
309    fn from(v: Vec<u8>) -> Self {
310        Self::Bytes(Bytes::from(v))
311    }
312}
313
314impl From<&[u8]> for RequestBody {
315    fn from(s: &[u8]) -> Self {
316        Self::Bytes(Bytes::copy_from_slice(s))
317    }
318}
319
320impl From<String> for RequestBody {
321    fn from(s: String) -> Self {
322        Self::Bytes(Bytes::from(s))
323    }
324}
325
326impl From<&str> for RequestBody {
327    fn from(s: &str) -> Self {
328        Self::Bytes(Bytes::copy_from_slice(s.as_bytes()))
329    }
330}
331
332pin_project! {
333    /// Type-erased native request body with per-frame write deadlines.
334    ///
335    /// The deadline starts when Hyper first polls the body, so connection and
336    /// TLS setup do not consume the write budget. It is reset after every
337    /// successfully produced frame and covers stalled body producers; the
338    /// established transport I/O timeout remains a separate concern.
339    #[must_use = "request bodies do nothing unless polled"]
340    pub(crate) struct NativeRequestBody {
341        #[pin]
342        inner: Pin<Box<dyn http_body::Body<Data = Bytes, Error = Box<dyn std::error::Error + Send + Sync>> + Send>>,
343        write_timeout: Option<Duration>,
344        #[pin]
345        timer: tokio::time::Sleep,
346        started: bool,
347        done: bool,
348    }
349}
350
351impl NativeRequestBody {
352    pub(crate) fn new(
353        inner: Pin<
354            Box<
355                dyn http_body::Body<Data = Bytes, Error = Box<dyn std::error::Error + Send + Sync>>
356                    + Send,
357            >,
358        >,
359        write_timeout: Option<Duration>,
360    ) -> Self {
361        Self {
362            inner,
363            write_timeout,
364            timer: tokio::time::sleep(Duration::MAX),
365            started: false,
366            done: false,
367        }
368    }
369}
370
371impl http_body::Body for NativeRequestBody {
372    type Data = Bytes;
373    type Error = Box<dyn std::error::Error + Send + Sync>;
374
375    fn poll_frame(
376        self: Pin<&mut Self>,
377        cx: &mut Context<'_>,
378    ) -> Poll<Option<std::result::Result<Frame<Self::Data>, Self::Error>>> {
379        let mut this = self.project();
380        if *this.done {
381            return Poll::Ready(None);
382        }
383
384        if let Some(timeout) = *this.write_timeout {
385            if !*this.started {
386                *this.started = true;
387                let next = crate::timeout::saturating_tokio_now_plus(timeout);
388                this.timer.as_mut().reset(next);
389            }
390        }
391
392        match this.inner.as_mut().poll_frame(cx) {
393            Poll::Ready(Some(Ok(frame))) => {
394                if let Some(timeout) = *this.write_timeout {
395                    let next = crate::timeout::saturating_tokio_now_plus(timeout);
396                    this.timer.as_mut().reset(next);
397                }
398                Poll::Ready(Some(Ok(frame)))
399            }
400            Poll::Ready(Some(Err(error))) => {
401                *this.done = true;
402                Poll::Ready(Some(Err(error)))
403            }
404            Poll::Ready(None) => {
405                *this.done = true;
406                Poll::Ready(None)
407            }
408            Poll::Pending => {
409                if let Some(timeout) = *this.write_timeout {
410                    if this.timer.as_mut().poll(cx).is_ready() {
411                        *this.done = true;
412                        return Poll::Ready(Some(Err(Box::new(Error::Timeout {
413                            phase: crate::timeout::TimeoutPhase::Write,
414                            elapsed: timeout,
415                        }))));
416                    }
417                }
418                Poll::Pending
419            }
420        }
421    }
422
423    fn is_end_stream(&self) -> bool {
424        self.done || self.inner.as_ref().is_end_stream()
425    }
426
427    fn size_hint(&self) -> http_body::SizeHint {
428        self.inner.as_ref().size_hint()
429    }
430}
431
432// ---------------------------------------------------------------------------
433// Response body
434// ---------------------------------------------------------------------------
435
436/// A handle to a pool permit. Cloning the handle is cheap; dropping the
437/// last handle releases the permit back to the pool.
438pub(crate) type PoolGuardArc = Arc<crate::pool::PoolGuard>;
439
440pin_project! {
441    /// A native frame-preserving response body.
442    ///
443    /// Unlike [`ResponseBody`], this type exposes the `http_body` frame
444    /// boundary directly. DATA and trailer frames are returned unchanged,
445    /// while the internal pool lease remains held until EOF, an error, or
446    /// drop. The type is opaque so Hyper's `Incoming` does not become part
447    /// of eggfetch's public API.
448    ///
449    /// Enforces the per-frame read inactivity timeout (starts on first
450    /// frame poll, resets per frame) and the absolute native total deadline
451    /// (starts with the logical request, never resets, may already be
452    /// expired on first poll). Total wins when already expired or when both
453    /// deadlines fire together. Timers are created on first poll in the
454    /// consuming runtime; no Tokio sleep crosses a runtime boundary.
455    pub struct NativeResponseBody {
456        #[pin]
457        inner: Pin<Box<dyn http_body::Body<Data = Bytes, Error = Error> + Send>>,
458        lease: Option<PoolGuardArc>,
459        read_timeout: Option<Duration>,
460        total_deadline: Option<ResponseDeadline>,
461        read_sleep: Option<Pin<Box<tokio::time::Sleep>>>,
462        total_sleep: Option<Pin<Box<tokio::time::Sleep>>>,
463        started: bool,
464        done: bool,
465    }
466}
467
468impl std::fmt::Debug for NativeResponseBody {
469    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
470        f.debug_struct("NativeResponseBody")
471            .field("read_timeout", &self.read_timeout)
472            .field("done", &self.done)
473            .finish_non_exhaustive()
474    }
475}
476
477impl NativeResponseBody {
478    /// Construct a native body around an eggfetch-owned response body.
479    pub(crate) fn new<B>(
480        body: B,
481        lease: Option<PoolGuardArc>,
482        read_timeout: Option<Duration>,
483        total_deadline: Option<ResponseDeadline>,
484    ) -> Self
485    where
486        B: http_body::Body<Data = Bytes, Error = Error> + Send + 'static,
487    {
488        Self {
489            inner: Box::pin(body),
490            lease,
491            read_timeout,
492            total_deadline,
493            read_sleep: None,
494            total_sleep: None,
495            started: false,
496            done: false,
497        }
498    }
499
500    fn total_timeout_error(total: &ResponseDeadline) -> Error {
501        Error::Timeout {
502            phase: crate::timeout::TimeoutPhase::Total,
503            elapsed: total.elapsed(),
504        }
505    }
506}
507
508impl http_body::Body for NativeResponseBody {
509    type Data = Bytes;
510    type Error = Error;
511
512    fn poll_frame(
513        self: Pin<&mut Self>,
514        cx: &mut Context<'_>,
515    ) -> Poll<Option<Result<Frame<Self::Data>>>> {
516        let mut this = self.project();
517        if *this.done {
518            return Poll::Ready(None);
519        }
520
521        // First poll in the consuming runtime: materialize timers here so
522        // no Tokio sleep crosses a runtime boundary. An already-expired
523        // total deadline wins without polling the inner transport.
524        if !*this.started {
525            *this.started = true;
526            if let Some(total) = this.total_deadline.as_ref() {
527                if total.is_expired() {
528                    *this.done = true;
529                    this.lease.take();
530                    return Poll::Ready(Some(Err(Self::total_timeout_error(total))));
531                }
532                let tokio_deadline = tokio::time::Instant::from_std(total.deadline());
533                *this.total_sleep = Some(Box::pin(tokio::time::sleep_until(tokio_deadline)));
534            }
535            if let Some(timeout) = *this.read_timeout {
536                *this.read_sleep = Some(Box::pin(tokio::time::sleep(timeout)));
537            }
538        }
539
540        // Absolute deadline is authoritative: a ready frame at or after the
541        // deadline must not extend the request.
542        if let Some(total) = this.total_deadline.as_ref() {
543            if total.is_expired() {
544                *this.read_sleep = None;
545                *this.total_sleep = None;
546                *this.done = true;
547                this.lease.take();
548                return Poll::Ready(Some(Err(Self::total_timeout_error(total))));
549            }
550        }
551
552        match this.inner.as_mut().poll_frame(cx) {
553            Poll::Ready(Some(Ok(frame))) => {
554                // Same-poll race: frame and absolute deadline observable
555                // together; the outer lifecycle cap wins.
556                if let Some(total) = this.total_deadline.as_ref() {
557                    if total.is_expired() {
558                        *this.read_sleep = None;
559                        *this.total_sleep = None;
560                        *this.done = true;
561                        this.lease.take();
562                        return Poll::Ready(Some(Err(Self::total_timeout_error(total))));
563                    }
564                }
565                if let (Some(read_sleep), Some(timeout)) =
566                    (this.read_sleep.as_mut(), this.read_timeout.as_ref())
567                {
568                    let next = crate::timeout::saturating_tokio_now_plus(*timeout);
569                    read_sleep.as_mut().reset(next);
570                }
571                Poll::Ready(Some(Ok(frame)))
572            }
573            Poll::Ready(Some(Err(error))) => {
574                *this.done = true;
575                this.lease.take();
576                Poll::Ready(Some(Err(error)))
577            }
578            Poll::Ready(None) => {
579                *this.done = true;
580                this.lease.take();
581                Poll::Ready(None)
582            }
583            Poll::Pending => {
584                // Total wins when both deadlines fire together.
585                let total_fired = match this.total_sleep.as_mut() {
586                    Some(sleep) => sleep.as_mut().poll(cx).is_ready(),
587                    None => false,
588                };
589                if total_fired {
590                    if let Some(total) = this.total_deadline.as_ref() {
591                        let err = Self::total_timeout_error(total);
592                        *this.read_sleep = None;
593                        *this.total_sleep = None;
594                        *this.done = true;
595                        this.lease.take();
596                        return Poll::Ready(Some(Err(err)));
597                    }
598                }
599                if let (Some(read_sleep), Some(timeout)) =
600                    (this.read_sleep.as_mut(), this.read_timeout.as_ref())
601                {
602                    if read_sleep.as_mut().poll(cx).is_ready() {
603                        *this.read_sleep = None;
604                        *this.total_sleep = None;
605                        *this.done = true;
606                        this.lease.take();
607                        return Poll::Ready(Some(Err(Error::Timeout {
608                            phase: crate::timeout::TimeoutPhase::Read,
609                            elapsed: *timeout,
610                        })));
611                    }
612                }
613                Poll::Pending
614            }
615        }
616    }
617
618    fn is_end_stream(&self) -> bool {
619        self.done || self.inner.as_ref().is_end_stream()
620    }
621
622    fn size_hint(&self) -> http_body::SizeHint {
623        self.inner.as_ref().size_hint()
624    }
625}
626
627pin_project! {
628    struct IncomingErrorBody {
629        #[pin]
630        inner: hyper::body::Incoming,
631    }
632}
633
634impl http_body::Body for IncomingErrorBody {
635    type Data = Bytes;
636    type Error = Error;
637
638    fn poll_frame(
639        self: Pin<&mut Self>,
640        cx: &mut Context<'_>,
641    ) -> Poll<Option<Result<Frame<Self::Data>>>> {
642        self.project()
643            .inner
644            .poll_frame(cx)
645            .map_ok(|frame| frame)
646            .map_err(|error| Error::Hyper(Arc::new(error)))
647    }
648
649    fn is_end_stream(&self) -> bool {
650        self.inner.is_end_stream()
651    }
652
653    fn size_hint(&self) -> http_body::SizeHint {
654        self.inner.size_hint()
655    }
656}
657
658impl NativeResponseBody {
659    /// Wrap a Hyper response body while converting transport errors to the
660    /// stable eggfetch error type.
661    pub(crate) fn from_incoming(
662        incoming: hyper::body::Incoming,
663        lease: Option<PoolGuardArc>,
664        read_timeout: Option<Duration>,
665        total_deadline: Option<ResponseDeadline>,
666    ) -> Self {
667        Self::new(
668            IncomingErrorBody { inner: incoming },
669            lease,
670            read_timeout,
671            total_deadline,
672        )
673    }
674}
675
676/// Shared trailer store populated during body streaming.
677///
678/// Hyper yields trailers as a final `Frame::trailers` after data frames
679/// (HTTP/1.1 chunked trailers and HTTP/2 trailing HEADERS). The store is
680/// filled exactly once when that frame arrives; it stays `None` until the
681/// body has advanced far enough, when no trailers were sent, or when a body
682/// error occurred before trailers. It never buffers the body to obtain
683/// trailers and never fabricates trailer state on errors.
684///
685/// Cloning is cheap (`Arc`); the [`crate::Response`] holds one clone while
686/// the body stream holds another, so `Response::trailers()` remains
687/// available after `bytes()` collection. Dropping the body early leaves the
688/// store as `None` and releases the pool permit without waiting for
689/// trailers.
690#[derive(Debug, Clone, Default)]
691pub struct SharedTrailers {
692    inner: Arc<std::sync::Mutex<Option<http::HeaderMap>>>,
693}
694
695impl SharedTrailers {
696    /// Create an empty trailer store.
697    #[must_use]
698    pub fn new() -> Self {
699        Self {
700            inner: Arc::new(std::sync::Mutex::new(None)),
701        }
702    }
703
704    /// Store trailers received from the wire (first write wins).
705    pub(crate) fn store(&self, trailers: http::HeaderMap) {
706        if let Ok(mut guard) = self.inner.lock() {
707            if guard.is_none() {
708                *guard = Some(trailers);
709            }
710        }
711    }
712
713    /// Returns cloned trailers if they have arrived, else `None`.
714    ///
715    /// `None` means either the body has not been fully consumed yet, the
716    /// response carried no trailers, or a body error occurred before
717    /// trailers. Callers must fully consume the body stream (or `bytes()`)
718    /// before expecting trailers.
719    #[must_use]
720    pub fn get(&self) -> Option<http::HeaderMap> {
721        self.inner
722            .lock()
723            .unwrap_or_else(std::sync::PoisonError::into_inner)
724            .clone()
725    }
726}
727
728pin_project! {
729    /// A response stream that keeps the pool lease alive while it is in use.
730    struct LeasedResponseStream {
731        #[pin]
732        inner: BoxBytesStream,
733        _lease: Option<PoolGuardArc>,
734    }
735}
736
737impl Stream for LeasedResponseStream {
738    type Item = Result<Bytes>;
739
740    fn poll_next(
741        self: Pin<&mut Self>,
742        cx: &mut std::task::Context<'_>,
743    ) -> std::task::Poll<Option<Self::Item>> {
744        let mut this = self.project();
745        let item = this.inner.as_mut().poll_next(cx);
746        if matches!(item, std::task::Poll::Ready(Some(Err(_)) | None)) {
747            // Release the permit as soon as the stream reaches a terminal
748            // state, rather than waiting for the caller to drop the iterator.
749            this._lease.take();
750        }
751        item
752    }
753}
754
755pin_project! {
756    /// A response stream that bounds the total decoded bytes collected.
757    struct LimitedResponseStream {
758        #[pin]
759        inner: BoxBytesStream,
760        max: usize,
761        decoded_bytes: usize,
762        limit_exceeded: bool,
763    }
764}
765
766impl Stream for LimitedResponseStream {
767    type Item = Result<Bytes>;
768
769    fn poll_next(
770        self: Pin<&mut Self>,
771        cx: &mut std::task::Context<'_>,
772    ) -> std::task::Poll<Option<Self::Item>> {
773        let mut this = self.project();
774        // Once the limit trips, fuse without polling the inner transport
775        // again (releases the connection earlier and avoids unbounded
776        // inner buffering under hostile streams). Returning `None`
777        // (rather than repeating the error) keeps combinators like
778        // `collect` terminating: callers observe the first error, then EOF.
779        if *this.limit_exceeded {
780            return std::task::Poll::Ready(None);
781        }
782        match this.inner.as_mut().poll_next(cx) {
783            std::task::Poll::Ready(Some(Ok(chunk))) => {
784                *this.decoded_bytes = this.decoded_bytes.saturating_add(chunk.len());
785                if *this.decoded_bytes > *this.max {
786                    *this.limit_exceeded = true;
787                    std::task::Poll::Ready(Some(Err(Error::DecodedBodyTooLarge)))
788                } else {
789                    std::task::Poll::Ready(Some(Ok(chunk)))
790                }
791            }
792            other => other,
793        }
794    }
795}
796
797/// Response body handle.
798///
799/// Supports two consumption modes:
800///
801/// - **Buffered**: the entire body is held in memory. Created by
802///   `ResponseBody::buffered()`. Calling `bytes()` or `text()` is O(1).
803/// - **Streaming**: body chunks are yielded incrementally. Created by
804///   `ResponseBody::streaming()`. The stream must be fully consumed or
805///   dropped before the attached pool lease is released.
806///
807/// # Single-consumption semantics
808///
809/// A response body can be consumed once via `bytes()`, `text()`,
810/// `bytes_stream()`, or `raw_bytes_stream()`. For compressed streaming bodies,
811/// raw and decoded selection are mutually exclusive. After consumption,
812/// further reads return an error.
813pub enum ResponseBody {
814    /// Fully buffered body.
815    Buffered {
816        /// The buffered body bytes.
817        bytes: Bytes,
818    },
819    /// Streaming body.
820    Streaming {
821        /// The body stream.
822        stream: BoxBytesStream,
823        /// Optional pool permit holder. Released on drop.
824        ///
825        /// The guard privately carries the response read/total lifecycle
826        /// policy; see [`crate::pool::PoolGuard`]. Manually constructed
827        /// lease-free bodies carry no implicit client timeout.
828        lease: Option<PoolGuardArc>,
829    },
830    /// A compressed streaming body whose encoded source is retained until
831    /// the caller selects raw or decoded consumption.
832    EncodedStreaming {
833        /// The encoded body stream.
834        stream: BoxBytesStream,
835        /// Optional pool permit holder. Released on drop.
836        ///
837        /// As with [`ResponseBody::Streaming`], the guard privately carries
838        /// the read/total policy applied to the final selected stream.
839        lease: Option<PoolGuardArc>,
840        /// The original `Content-Encoding` header value.
841        content_encoding: String,
842        /// Limits applied when decoded mode is selected.
843        limit: DecompressionLimit,
844    },
845    /// The streaming body has already been consumed.
846    Consumed,
847}
848
849impl std::fmt::Debug for ResponseBody {
850    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
851        match self {
852            Self::Buffered { bytes } => f
853                .debug_struct("Buffered")
854                .field("len", &bytes.len())
855                .finish(),
856            Self::Streaming { .. } => f.debug_struct("Streaming").finish_non_exhaustive(),
857            Self::EncodedStreaming { .. } => {
858                f.debug_struct("EncodedStreaming").finish_non_exhaustive()
859            }
860            Self::Consumed => f.debug_struct("Consumed").finish(),
861        }
862    }
863}
864
865impl ResponseBody {
866    /// Create a buffered response body.
867    #[must_use]
868    pub fn buffered(bytes: Bytes) -> Self {
869        Self::Buffered { bytes }
870    }
871
872    /// Create a streaming response body from a type-erased stream.
873    #[must_use]
874    pub fn streaming(stream: BoxBytesStream) -> Self {
875        Self::Streaming {
876            stream,
877            lease: None,
878        }
879    }
880
881    /// Create a streaming response body with an attached pool permit.
882    /// The permit is released when the body is dropped.
883    #[allow(
884        dead_code,
885        reason = "the lease-carrying constructor is only called by the pool-lease test; production bodies attach their lease through `attach_lease`"
886    )]
887    pub(crate) fn streaming_with_lease(stream: BoxBytesStream, lease: PoolGuardArc) -> Self {
888        Self::Streaming {
889            stream,
890            lease: Some(lease),
891        }
892    }
893
894    /// Attach the pool lease to a streaming or encoded-streaming body.
895    ///
896    /// This is the single finalization ownership point: transports create
897    /// lease-free bodies, finalization installs the read/total policy behind
898    /// the guard before it is placed behind the lease `Arc`, and consumption
899    /// enforces that private policy at the final stream boundary.
900    /// Buffered/consumed bodies drop the lease; they are already complete.
901    pub(crate) fn attach_lease(self, lease: PoolGuardArc) -> Self {
902        match self {
903            Self::Streaming { stream, .. } => Self::Streaming {
904                stream,
905                lease: Some(lease),
906            },
907            Self::EncodedStreaming {
908                stream,
909                content_encoding,
910                limit,
911                ..
912            } => Self::EncodedStreaming {
913                stream,
914                lease: Some(lease),
915                content_encoding,
916                limit,
917            },
918            other => {
919                drop(lease);
920                other
921            }
922        }
923    }
924
925    /// Create a deferred-decode streaming response body.
926    pub(crate) fn encoded_streaming(
927        stream: BoxBytesStream,
928        content_encoding: String,
929        limit: DecompressionLimit,
930    ) -> Self {
931        Self::EncodedStreaming {
932            stream,
933            lease: None,
934            content_encoding,
935            limit,
936        }
937    }
938
939    /// Create a deferred-decode streaming response body with an attached
940    /// pool permit.
941    pub(crate) fn encoded_streaming_with_lease(
942        stream: BoxBytesStream,
943        lease: PoolGuardArc,
944        content_encoding: String,
945        limit: DecompressionLimit,
946    ) -> Self {
947        Self::EncodedStreaming {
948            stream,
949            lease: Some(lease),
950            content_encoding,
951            limit,
952        }
953    }
954
955    /// Returns `true` if the body is empty.
956    #[must_use]
957    pub fn is_empty(&self) -> bool {
958        match self {
959            Self::Buffered { bytes } => bytes.is_empty(),
960            Self::Streaming { .. } | Self::EncodedStreaming { .. } => false, // unknown until consumed
961            Self::Consumed => true,
962        }
963    }
964
965    /// Returns the buffered body length, if available.
966    ///
967    /// For streaming bodies, returns `None` until the body is fully
968    /// collected.
969    #[must_use]
970    pub fn len(&self) -> Option<usize> {
971        match self {
972            Self::Buffered { bytes } => Some(bytes.len()),
973            Self::Streaming { .. } | Self::EncodedStreaming { .. } => None,
974            Self::Consumed => Some(0),
975        }
976    }
977
978    /// Returns `true` if this is a buffered body.
979    #[must_use]
980    pub fn is_buffered(&self) -> bool {
981        matches!(self, Self::Buffered { .. })
982    }
983
984    /// Consume the body and return all bytes.
985    ///
986    /// For buffered bodies, this is O(1). For streaming bodies, this
987    /// collects all chunks into a single `Bytes` buffer.
988    ///
989    /// # Limits
990    ///
991    /// The configured decoded-body limit is enforced for both encoded and
992    /// unencoded response bodies.
993    ///
994    /// [`DecompressionLimit`]: crate::compression::DecompressionLimit
995    ///
996    /// # Errors
997    ///
998    /// Returns an error if the body has already been consumed or if a
999    /// stream chunk fails.
1000    pub async fn bytes(&mut self) -> Result<Bytes> {
1001        // Buffered fast path stays O(1); streaming paths share the final
1002        // stream boundary (`take_stream`) so timeouts, decompression,
1003        // limits, and lease release cannot diverge between `bytes()` and
1004        // `bytes_stream()`.
1005        if matches!(self, Self::Buffered { .. }) {
1006            let old = std::mem::replace(self, Self::Consumed);
1007            if let Self::Buffered { bytes } = old {
1008                return Ok(bytes);
1009            }
1010            return Err(Error::Body("response body state mismatch".into()));
1011        }
1012        let mut stream = self.take_stream(false)?;
1013        let mut buf = BytesMut::new();
1014        while let Some(chunk) = stream.next().await {
1015            buf.extend_from_slice(&chunk?);
1016        }
1017        Ok(buf.freeze())
1018    }
1019
1020    /// Enforce a maximum decoded size for this body.
1021    pub(crate) fn limit_decoded_size(self, max: usize) -> Result<Self> {
1022        match self {
1023            Self::Buffered { bytes } if bytes.len() > max => Err(Error::DecodedBodyTooLarge),
1024            Self::Buffered { bytes } => Ok(Self::Buffered { bytes }),
1025            Self::Streaming { stream, lease } => Ok(Self::Streaming {
1026                stream: Box::pin(LimitedResponseStream {
1027                    inner: stream,
1028                    max,
1029                    decoded_bytes: 0,
1030                    limit_exceeded: false,
1031                }),
1032                lease,
1033            }),
1034            Self::EncodedStreaming {
1035                stream,
1036                lease,
1037                content_encoding,
1038                limit: mut existing_limit,
1039            } => {
1040                existing_limit.max_decoded_body_size = Some(
1041                    existing_limit
1042                        .max_decoded_body_size
1043                        .map_or(max, |current| current.min(max)),
1044                );
1045                Ok(Self::EncodedStreaming {
1046                    stream,
1047                    lease,
1048                    content_encoding,
1049                    limit: existing_limit,
1050                })
1051            }
1052            body @ Self::Consumed => Ok(body),
1053        }
1054    }
1055
1056    /// Consume the body and return it as a UTF-8 string.
1057    ///
1058    /// # Errors
1059    ///
1060    /// Returns an error if the body is not valid UTF-8 or has already
1061    /// been consumed.
1062    pub async fn text(&mut self) -> Result<String> {
1063        let bytes = self.bytes().await?;
1064        String::from_utf8(bytes.to_vec()).map_err(|e| Error::Body(e.to_string()))
1065    }
1066
1067    /// Consume the body and return a stream of byte chunks.
1068    ///
1069    /// For buffered bodies, yields the entire body as a single chunk.
1070    /// For streaming bodies, yields chunks incrementally.
1071    ///
1072    /// # Errors
1073    ///
1074    /// Returns an error if the body has already been consumed.
1075    pub fn bytes_stream(&mut self) -> Result<BoxBytesStream> {
1076        self.take_stream(false)
1077    }
1078
1079    /// Consume the body and return the encoded response byte stream.
1080    ///
1081    /// For compressed streaming responses, this selects the original encoded
1082    /// transport body and bypasses the existing decoder chain. The selection
1083    /// is one-shot; a body cannot subsequently be consumed in decoded mode.
1084    /// Buffered bodies follow the ordinary streaming path because their
1085    /// encoded representation is no longer available.
1086    ///
1087    /// # Errors
1088    ///
1089    /// Returns an error if the body has already been consumed or if the
1090    /// decoder configuration is invalid while selecting a stream.
1091    pub fn raw_bytes_stream(&mut self) -> Result<BoxBytesStream> {
1092        self.take_stream(true)
1093    }
1094
1095    fn take_stream(&mut self, raw: bool) -> Result<BoxBytesStream> {
1096        match self {
1097            Self::Buffered { bytes } => {
1098                let bytes = std::mem::take(bytes);
1099                *self = Self::Consumed;
1100                Ok(Box::pin(futures_util::stream::once(
1101                    async move { Ok(bytes) },
1102                )))
1103            }
1104            Self::Streaming { .. } => {
1105                let old = std::mem::replace(self, Self::Consumed);
1106                if let Self::Streaming { stream, lease } = old {
1107                    // Final stream boundary: read the private lifecycle
1108                    // policy from the lease and cover it with one unified
1109                    // timeout wrapper; the lease wrapper then releases the
1110                    // pool permit on terminal timeout/EOF/error.
1111                    // Lease-free manually constructed bodies carry no
1112                    // implicit client timeout.
1113                    let (read_timeout, total_deadline) =
1114                        lease.as_ref().map_or((None, None), |guard| {
1115                            (
1116                                guard.response_read_timeout(),
1117                                guard.response_total_deadline(),
1118                            )
1119                        });
1120                    let timed =
1121                        crate::stream::body_timeout_stream(stream, read_timeout, total_deadline);
1122                    Ok(Box::pin(LeasedResponseStream {
1123                        inner: timed,
1124                        _lease: lease,
1125                    }))
1126                } else {
1127                    // Defensive: the outer match guarantees this arm, but
1128                    // a future variant addition must surface as an error,
1129                    // not a panic.
1130                    Err(Error::Body("response body state mismatch".into()))
1131                }
1132            }
1133            Self::EncodedStreaming { .. } => {
1134                let old = std::mem::replace(self, Self::Consumed);
1135                if let Self::EncodedStreaming {
1136                    stream,
1137                    lease,
1138                    content_encoding,
1139                    limit,
1140                } = old
1141                {
1142                    let (read_timeout, total_deadline) =
1143                        lease.as_ref().map_or((None, None), |guard| {
1144                            (
1145                                guard.response_read_timeout(),
1146                                guard.response_total_deadline(),
1147                            )
1148                        });
1149                    let stream = if raw {
1150                        Ok(stream)
1151                    } else {
1152                        crate::compression::decompress_stream(
1153                            stream,
1154                            Some(&content_encoding),
1155                            true,
1156                            limit,
1157                        )
1158                    }?;
1159                    // Same single mechanism on the final selected stream:
1160                    // raw encoded bytes and decoded bytes share total/read
1161                    // semantics; decoder buffering cannot bypass the outer
1162                    // absolute deadline because it sits outside the decoder.
1163                    let timed =
1164                        crate::stream::body_timeout_stream(stream, read_timeout, total_deadline);
1165                    Ok(Box::pin(LeasedResponseStream {
1166                        inner: timed,
1167                        _lease: lease,
1168                    }))
1169                } else {
1170                    // Defensive: the outer match guarantees this arm, but
1171                    // a future variant addition must surface as an error,
1172                    // not a panic.
1173                    Err(Error::Body("response body state mismatch".into()))
1174                }
1175            }
1176            Self::Consumed => Err(Error::Body("streaming body already consumed".into())),
1177        }
1178    }
1179}
1180
1181// ---------------------------------------------------------------------------
1182// Tests
1183// ---------------------------------------------------------------------------
1184
1185#[cfg(test)]
1186mod tests {
1187    use super::*;
1188
1189    #[test]
1190    fn request_body_empty() {
1191        let body = RequestBody::Empty;
1192        assert!(body.is_empty());
1193        assert_eq!(body.len(), 0);
1194        assert!(body.has_known_length());
1195        assert!(body.is_replayable());
1196    }
1197
1198    #[test]
1199    fn request_body_bytes() {
1200        let body = RequestBody::from(Bytes::from("hello"));
1201        assert!(!body.is_empty());
1202        assert_eq!(body.len(), 5);
1203        assert!(body.has_known_length());
1204        assert!(body.is_replayable());
1205    }
1206
1207    #[test]
1208    fn request_body_stream_unknown_length() {
1209        let stream = futures_util::stream::empty::<Result<Bytes>>();
1210        let body = RequestBody::from_stream(stream, None);
1211        assert!(!body.is_empty());
1212        assert_eq!(body.len(), 0);
1213        assert!(!body.has_known_length());
1214        assert!(!body.is_replayable());
1215    }
1216
1217    #[test]
1218    fn request_body_stream_known_length() {
1219        let stream = futures_util::stream::empty::<Result<Bytes>>();
1220        let body = RequestBody::from_stream(stream, Some(1024));
1221        assert!(!body.is_empty());
1222        assert_eq!(body.len(), 1024);
1223        assert!(body.has_known_length());
1224        assert!(!body.is_replayable());
1225    }
1226
1227    #[test]
1228    fn try_clone_for_redirect_empty() {
1229        let body = RequestBody::Empty;
1230        let cloned = body.try_clone_for_redirect().unwrap();
1231        assert!(cloned.is_empty());
1232    }
1233
1234    #[test]
1235    fn try_clone_for_redirect_bytes() {
1236        let body = RequestBody::from(Bytes::from("hello"));
1237        let cloned = body.try_clone_for_redirect().unwrap();
1238        match cloned {
1239            RequestBody::Bytes(b) => assert_eq!(b, "hello"),
1240            _ => panic!("expected bytes"),
1241        }
1242    }
1243
1244    #[test]
1245    fn try_clone_for_redirect_stream_errors() {
1246        let stream = futures_util::stream::empty::<Result<Bytes>>();
1247        let body = RequestBody::from_stream(stream, None);
1248        assert!(body.try_clone_for_redirect().is_err());
1249    }
1250
1251    #[test]
1252    fn request_body_bytes_debug_redacts_contents() {
1253        let body = RequestBody::from(Bytes::from("form-password=hunter2"));
1254        let debug = format!("{body:?}");
1255        assert!(
1256            !debug.contains("hunter2"),
1257            "RequestBody Debug must not leak byte contents: {debug}"
1258        );
1259        assert!(
1260            debug.contains("Bytes(21)"),
1261            "RequestBody Debug reports the length only: {debug}"
1262        );
1263    }
1264
1265    #[test]
1266    fn response_body_buffered() {
1267        let body = ResponseBody::buffered(Bytes::from("hello"));
1268        assert!(!body.is_empty());
1269        assert_eq!(body.len(), Some(5));
1270        assert!(body.is_buffered());
1271    }
1272
1273    #[test]
1274    fn response_body_streaming() {
1275        let stream = Box::pin(futures_util::stream::empty());
1276        let body = ResponseBody::streaming(stream);
1277        assert!(!body.is_buffered());
1278    }
1279
1280    #[tokio::test]
1281    async fn response_body_buffered_bytes() {
1282        let mut body = ResponseBody::buffered(Bytes::from("hello world"));
1283        let bytes = body.bytes().await.unwrap();
1284        assert_eq!(bytes, "hello world");
1285    }
1286
1287    #[tokio::test]
1288    async fn response_body_buffered_text() {
1289        let mut body = ResponseBody::buffered(Bytes::from("hello"));
1290        let text = body.text().await.unwrap();
1291        assert_eq!(text, "hello");
1292    }
1293
1294    #[tokio::test]
1295    async fn response_body_buffered_stream_yields_single_chunk() {
1296        let mut body = ResponseBody::buffered(Bytes::from("data"));
1297        let mut stream = body.bytes_stream().unwrap();
1298        let chunk = stream.next().await.unwrap().unwrap();
1299        assert_eq!(chunk, "data");
1300        assert!(stream.next().await.is_none());
1301    }
1302
1303    #[tokio::test]
1304    async fn response_body_streaming_yields_chunks() {
1305        let chunks = vec![
1306            Ok(Bytes::from("a")),
1307            Ok(Bytes::from("bb")),
1308            Ok(Bytes::from("ccc")),
1309        ];
1310        let stream = Box::pin(futures_util::stream::iter(chunks));
1311        let mut body = ResponseBody::streaming(stream);
1312        let mut stream = body.bytes_stream().unwrap();
1313        assert_eq!(stream.next().await.unwrap().unwrap(), "a");
1314        assert_eq!(stream.next().await.unwrap().unwrap(), "bb");
1315        assert_eq!(stream.next().await.unwrap().unwrap(), "ccc");
1316        assert!(stream.next().await.is_none());
1317    }
1318
1319    #[tokio::test]
1320    async fn response_body_streaming_collect() {
1321        let chunks = vec![Ok(Bytes::from("hello ")), Ok(Bytes::from("world"))];
1322        let stream = Box::pin(futures_util::stream::iter(chunks));
1323        let mut body = ResponseBody::streaming(stream);
1324        let bytes = body.bytes().await.unwrap();
1325        assert_eq!(bytes, "hello world");
1326    }
1327
1328    #[tokio::test]
1329    async fn response_body_unencoded_size_limit_is_enforced() {
1330        let stream = Box::pin(futures_util::stream::iter(vec![
1331            Ok(Bytes::from("ab")),
1332            Ok(Bytes::from("cd")),
1333        ]));
1334        let mut body = ResponseBody::streaming(stream)
1335            .limit_decoded_size(3)
1336            .unwrap();
1337        assert_eq!(
1338            body.bytes().await.unwrap_err().kind(),
1339            "decoded_body_too_large"
1340        );
1341    }
1342
1343    #[test]
1344    fn response_body_buffered_size_limit_is_enforced() {
1345        let body = ResponseBody::buffered(Bytes::from_static(b"body"));
1346        assert_eq!(
1347            body.limit_decoded_size(3).unwrap_err().kind(),
1348            "decoded_body_too_large"
1349        );
1350    }
1351
1352    #[tokio::test]
1353    async fn response_body_double_consume_replaces() {
1354        let mut body = ResponseBody::buffered(Bytes::from("data"));
1355        let _ = body.bytes().await.unwrap();
1356        assert!(body.bytes().await.is_err());
1357    }
1358
1359    #[tokio::test]
1360    async fn response_body_double_stream_errors() {
1361        let stream = Box::pin(futures_util::stream::iter(vec![Ok(Bytes::from("x"))]));
1362        let mut body = ResponseBody::streaming(stream);
1363        let _ = body.bytes_stream().unwrap();
1364        let err = body.bytes_stream();
1365        assert!(err.is_err());
1366    }
1367
1368    #[cfg(feature = "compression-gzip")]
1369    fn gzip_bytes(input: &[u8]) -> Bytes {
1370        use std::io::Write;
1371
1372        let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast());
1373        encoder.write_all(input).unwrap();
1374        Bytes::from(encoder.finish().unwrap())
1375    }
1376
1377    #[cfg(feature = "compression-gzip")]
1378    #[tokio::test]
1379    async fn encoded_streaming_selects_raw_once() {
1380        let encoded = gzip_bytes(b"compressed body");
1381        let expected = encoded.clone();
1382        let stream = Box::pin(futures_util::stream::iter(vec![Ok(encoded)]));
1383        let mut body = ResponseBody::encoded_streaming(
1384            stream,
1385            "gzip".to_owned(),
1386            DecompressionLimit::default(),
1387        );
1388
1389        let mut raw = body.raw_bytes_stream().unwrap();
1390        assert_eq!(raw.next().await.unwrap().unwrap(), expected);
1391        assert!(raw.next().await.is_none());
1392        assert!(body.bytes_stream().is_err());
1393    }
1394
1395    #[cfg(feature = "compression-gzip")]
1396    #[tokio::test]
1397    async fn encoded_streaming_selects_decoded_once() {
1398        let encoded = gzip_bytes(b"compressed body");
1399        let stream = Box::pin(futures_util::stream::iter(vec![Ok(encoded)]));
1400        let mut body = ResponseBody::encoded_streaming(
1401            stream,
1402            "gzip".to_owned(),
1403            DecompressionLimit::default(),
1404        );
1405
1406        let mut decoded = body.bytes_stream().unwrap();
1407        assert_eq!(decoded.next().await.unwrap().unwrap(), "compressed body");
1408        assert!(decoded.next().await.is_none());
1409        assert!(body.raw_bytes_stream().is_err());
1410    }
1411
1412    #[cfg(feature = "compression-gzip")]
1413    #[tokio::test]
1414    async fn encoded_streaming_limit_is_applied_when_added_after_construction() {
1415        let encoded = gzip_bytes(b"compressed body");
1416        let stream = Box::pin(futures_util::stream::iter(vec![Ok(encoded)]));
1417        let mut body = ResponseBody::encoded_streaming(
1418            stream,
1419            "gzip".to_owned(),
1420            DecompressionLimit::default(),
1421        )
1422        .limit_decoded_size(3)
1423        .unwrap();
1424
1425        assert_eq!(
1426            body.bytes().await.unwrap_err().kind(),
1427            "decoded_body_too_large"
1428        );
1429    }
1430
1431    #[tokio::test]
1432    async fn uncompressed_raw_selection_is_passthrough() {
1433        let stream = Box::pin(futures_util::stream::iter(vec![Ok(Bytes::from("body"))]));
1434        let mut body = ResponseBody::streaming(stream);
1435        let mut raw = body.raw_bytes_stream().unwrap();
1436        assert_eq!(raw.next().await.unwrap().unwrap(), "body");
1437        assert!(raw.next().await.is_none());
1438    }
1439
1440    #[tokio::test]
1441    async fn response_body_buffered_double_bytes_errors() {
1442        let mut body = ResponseBody::buffered(Bytes::from("data"));
1443        let first = body.bytes().await.unwrap();
1444        assert_eq!(first, "data");
1445        assert!(body.bytes().await.is_err());
1446    }
1447
1448    #[tokio::test]
1449    async fn response_body_buffered_text_invalid_utf8() {
1450        let mut body = ResponseBody::buffered(Bytes::from(vec![0xFF, 0xFE]));
1451        let err = body.text().await;
1452        assert!(err.is_err());
1453    }
1454
1455    #[tokio::test]
1456    async fn response_body_streaming_bytes_then_stream_returns_empty() {
1457        let stream = Box::pin(futures_util::stream::iter(vec![Ok(Bytes::from("x"))]));
1458        let mut body = ResponseBody::streaming(stream);
1459        let _ = body.bytes().await.unwrap();
1460        assert!(body.bytes_stream().is_err());
1461    }
1462
1463    #[tokio::test]
1464    async fn response_body_consumed_is_empty() {
1465        let body = ResponseBody::Consumed;
1466        assert!(body.is_empty());
1467        assert_eq!(body.len(), Some(0));
1468    }
1469
1470    #[tokio::test]
1471    async fn response_body_buffered_bytes_stream_then_bytes_returns_empty() {
1472        let mut body = ResponseBody::buffered(Bytes::from("data"));
1473        let mut stream = body.bytes_stream().unwrap();
1474        let chunk = stream.next().await.unwrap().unwrap();
1475        assert_eq!(chunk, "data");
1476        assert!(stream.next().await.is_none());
1477        assert!(body.bytes().await.is_err());
1478    }
1479
1480    #[tokio::test]
1481    async fn into_http_body_empty_produces_empty_body() {
1482        use http_body::Body;
1483        use http_body_util::BodyExt;
1484
1485        let body = RequestBody::Empty;
1486        let mut hyper_body = body.into_http_body();
1487        let frame = futures_util::future::poll_fn(|cx| {
1488            use std::pin::Pin;
1489            Pin::new(&mut hyper_body).poll_frame(cx)
1490        })
1491        .await;
1492        assert!(frame.is_none());
1493        let _ = hyper_body.collect().await;
1494    }
1495
1496    #[tokio::test]
1497    async fn into_http_body_bytes_produces_one_data_frame() {
1498        use http_body::Body;
1499        use std::pin::Pin;
1500
1501        let body = RequestBody::from(Bytes::from("hello"));
1502        let mut hyper_body = body.into_http_body();
1503
1504        let frame = futures_util::future::poll_fn(|cx| Pin::new(&mut hyper_body).poll_frame(cx))
1505            .await
1506            .expect("frame present")
1507            .expect("frame ok");
1508        assert!(frame.is_data());
1509        let data = frame.into_data().unwrap();
1510        assert_eq!(data, "hello");
1511
1512        let end =
1513            futures_util::future::poll_fn(|cx| Pin::new(&mut hyper_body).poll_frame(cx)).await;
1514        assert!(end.is_none());
1515    }
1516
1517    #[tokio::test]
1518    async fn into_http_body_stream_pipes_through_without_eager_buffering() {
1519        use http_body::Body;
1520        use std::pin::Pin;
1521        use std::sync::atomic::{AtomicUsize, Ordering};
1522
1523        let polled = Arc::new(AtomicUsize::new(0));
1524        let polled_inner = polled.clone();
1525
1526        let chunks = vec![
1527            Ok(Bytes::from("a")),
1528            Ok(Bytes::from("b")),
1529            Ok(Bytes::from("c")),
1530        ];
1531        let chunk_stream = futures_util::stream::iter(chunks).inspect(move |_| {
1532            polled_inner.fetch_add(1, Ordering::SeqCst);
1533        });
1534        let body = RequestBody::from_stream(chunk_stream.map(|r| -> Result<Bytes> { r }), Some(3));
1535        let mut hyper_body = body.into_http_body();
1536
1537        let frame = futures_util::future::poll_fn(|cx| Pin::new(&mut hyper_body).poll_frame(cx))
1538            .await
1539            .expect("frame present")
1540            .expect("frame ok");
1541        let data = frame.into_data().unwrap();
1542        assert_eq!(data, "a");
1543        assert_eq!(
1544            polled.load(Ordering::SeqCst),
1545            1,
1546            "stream should not be eagerly polled"
1547        );
1548    }
1549
1550    #[tokio::test]
1551    async fn limited_stream_fuses_after_limit_trips() {
1552        use futures_util::StreamExt;
1553        use std::sync::atomic::{AtomicUsize, Ordering};
1554
1555        let polls = Arc::new(AtomicUsize::new(0));
1556        let polls_inner = polls.clone();
1557        let tracked = futures_util::stream::iter(vec![
1558            Ok(Bytes::from("ab")),
1559            Ok(Bytes::from("cd")),
1560            Ok(Bytes::from("ef")),
1561        ])
1562        .inspect(move |_| {
1563            polls_inner.fetch_add(1, Ordering::SeqCst);
1564        });
1565        let inner: super::BoxBytesStream = Box::pin(tracked);
1566        let mut limited = super::LimitedResponseStream {
1567            inner,
1568            max: 3,
1569            decoded_bytes: 0,
1570            limit_exceeded: false,
1571        };
1572        // "ab" ok (2 bytes), "cd" trips the limit (4 > 3).
1573        assert!(limited.next().await.unwrap().is_ok());
1574        assert!(limited.next().await.unwrap().is_err());
1575        let polls_after_error = polls.load(Ordering::SeqCst);
1576        // Further polls fuse (EOF) without polling inner again.
1577        assert!(limited.next().await.is_none());
1578        assert_eq!(
1579            polls.load(Ordering::SeqCst),
1580            polls_after_error,
1581            "inner stream must not be re-polled after the limit trips"
1582        );
1583    }
1584
1585    #[tokio::test]
1586    async fn leased_stream_holds_pool_slot_until_drop() {
1587        let pool = crate::pool::Pool::new(crate::pool::PoolConfig {
1588            max_connections_per_host: Some(1),
1589            ..Default::default()
1590        });
1591        let origin = crate::pool::OriginKey::from_parts("http", "example.com", 80);
1592        let guard = pool.acquire(Some(&origin)).await.unwrap();
1593        let mut body = ResponseBody::streaming_with_lease(
1594            Box::pin(futures_util::stream::pending()),
1595            Arc::new(guard),
1596        );
1597        let stream = body.bytes_stream().unwrap();
1598
1599        assert!(tokio::time::timeout(
1600            std::time::Duration::from_millis(10),
1601            pool.acquire(Some(&origin))
1602        )
1603        .await
1604        .is_err());
1605
1606        drop(stream);
1607        assert!(tokio::time::timeout(
1608            std::time::Duration::from_millis(100),
1609            pool.acquire(Some(&origin))
1610        )
1611        .await
1612        .is_ok());
1613    }
1614}