hyper/body/
mod.rs

1//! Streaming bodies for Requests and Responses.
2//!
3//! For both [Clients](crate::client) and [Servers](crate::server), requests and
4//! responses use streaming bodies, instead of complete buffering. This
5//! allows applications to not use memory they don't need, and allows exerting
6//! back-pressure on connections by only reading when asked.
7//!
8//! There are two pieces to this in hyper:
9//!
10//! - **The [`Body`] trait** describes all possible bodies.
11//!   hyper allows any body type that implements `Body`, allowing
12//!   applications to have fine-grained control over their streaming.
13//! - **The [`Incoming`] concrete type**, which is an implementation
14//!   of `Body`, and returned by hyper as a "receive stream" (so, for server
15//!   requests and client responses).
16//!
17//! There are additional implementations available in [`http-body-util`][],
18//! such as a `Full` or `Empty` body.
19//!
20//! ## Reading a body
21//!
22//! The [`BodyExt`][] extension trait provides an asynchronous way to read the
23//! frames of a body. A frame can contain either data or trailers:
24//!
25//! ```
26//! use http_body_util::BodyExt as _;
27//! use hyper::body::Incoming;
28//!
29//! async fn read_body(mut body: Incoming) -> Result<(), hyper::Error> {
30//!     while let Some(frame) = body.frame().await {
31//!         let frame = frame?;
32//!
33//!         if let Some(data) = frame.data_ref() {
34//!             println!("received {} bytes", data.len());
35//!         }
36//!
37//!         if let Some(trailers) = frame.trailers_ref() {
38//!             println!("received trailers: {trailers:?}");
39//!         }
40//!     }
41//!
42//!     Ok(())
43//! }
44//! ```
45//!
46//! A body only advances when it is polled. Processing each frame before
47//! polling for the next one preserves back-pressure on the connection.
48//!
49//! If a body is known to be small, it can be collected into memory instead:
50//!
51//! ```
52//! use http_body_util::BodyExt as _;
53//! use hyper::body::{Bytes, Incoming};
54//!
55//! /// Consider using `Limited` if the body is untrusted.
56//! async fn read_entire_body(body: Incoming) -> Result<Bytes, hyper::Error> {
57//!     Ok(body.collect().await?.to_bytes())
58//! }
59//! ```
60//!
61//! Collecting buffers the whole body, so it should be avoided for large or
62//! untrusted bodies unless their size is limited.
63//!
64//! [`http-body-util`]: https://docs.rs/http-body-util
65//! [`BodyExt`]: https://docs.rs/http-body-util/latest/http_body_util/trait.BodyExt.html
66
67pub use bytes::{Buf, Bytes};
68pub use http_body::Body;
69pub use http_body::Frame;
70pub use http_body::SizeHint;
71
72pub use self::incoming::Incoming;
73
74#[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
75pub(crate) use self::incoming::Sender;
76#[cfg(all(
77    any(feature = "http1", feature = "http2"),
78    any(feature = "client", feature = "server")
79))]
80pub(crate) use self::length::DecodedLength;
81
82mod incoming;
83#[cfg(all(
84    any(feature = "http1", feature = "http2"),
85    any(feature = "client", feature = "server")
86))]
87mod length;
88
89fn _assert_send_sync() {
90    fn _assert_send<T: Send>() {}
91    fn _assert_sync<T: Sync>() {}
92
93    _assert_send::<Incoming>();
94    _assert_sync::<Incoming>();
95}
hyper/body/mod.rs

hyper/body/
mod.rs
