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