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