From e23de8a99d4f85acd76b30d97a0d64dd7ff44199 Mon Sep 17 00:00:00 2001 From: Morax Date: Sun, 9 Aug 2026 14:33:38 +0200 Subject: [PATCH 1/2] docs(body): add streaming read examples Show how to process data and trailer frames while preserving back-pressure, and contrast that with intentionally collecting a bounded body in memory. Closes #2201 --- src/body/mod.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/src/body/mod.rs b/src/body/mod.rs index 2df3319dd5..ad0673b495 100644 --- a/src/body/mod.rs +++ b/src/body/mod.rs @@ -17,7 +17,51 @@ //! There are additional implementations available in [`http-body-util`][], //! such as a `Full` or `Empty` body. //! +//! ## Reading a body +//! +//! The [`BodyExt`][] extension trait provides an asynchronous way to read the +//! frames of a body. A frame can contain either data or trailers: +//! +//! ``` +//! use http_body_util::BodyExt as _; +//! use hyper::body::Incoming; +//! +//! async fn read_body(mut body: Incoming) -> Result<(), hyper::Error> { +//! while let Some(frame) = body.frame().await { +//! let frame = frame?; +//! +//! if let Some(data) = frame.data_ref() { +//! println!("received {} bytes", data.len()); +//! } +//! +//! if let Some(trailers) = frame.trailers_ref() { +//! println!("received trailers: {trailers:?}"); +//! } +//! } +//! +//! Ok(()) +//! } +//! ``` +//! +//! A body only advances when it is polled. Processing each frame before +//! polling for the next one preserves back-pressure on the connection. +//! +//! If a body is known to be small, it can be collected into memory instead: +//! +//! ``` +//! use http_body_util::BodyExt as _; +//! use hyper::body::{Bytes, Incoming}; +//! +//! async fn read_entire_body(body: Incoming) -> Result { +//! Ok(body.collect().await?.to_bytes()) +//! } +//! ``` +//! +//! Collecting buffers the whole body, so it should be avoided for large or +//! untrusted bodies unless their size is limited. +//! //! [`http-body-util`]: https://docs.rs/http-body-util +//! [`BodyExt`]: https://docs.rs/http-body-util/latest/http_body_util/trait.BodyExt.html pub use bytes::{Buf, Bytes}; pub use http_body::Body; From ab74ab653bdaa6b52531e0a5f1f669e9a78eff90 Mon Sep 17 00:00:00 2001 From: Morax Date: Mon, 10 Aug 2026 17:50:01 +0200 Subject: [PATCH 2/2] docs(body): warn about collecting untrusted bodies --- src/body/mod.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/body/mod.rs b/src/body/mod.rs index ad0673b495..c34d019d21 100644 --- a/src/body/mod.rs +++ b/src/body/mod.rs @@ -52,6 +52,7 @@ //! use http_body_util::BodyExt as _; //! use hyper::body::{Bytes, Incoming}; //! +//! /// Consider using `Limited` if the body is untrusted. //! async fn read_entire_body(body: Incoming) -> Result { //! Ok(body.collect().await?.to_bytes()) //! }