Repository navigation
Split apart the Body type #2345
Description
This has been suggested before: the current trait hyper::body::HttpBody should be renamed to hyper::Body, and the existing struct hyper::Body should be split up into more descriptive implementations. I'm coming around to that idea, so here's the full proposal.
Proposal
- Change the trait
hyper::body::HttpBodytohyper::Body - Split up the
hyper::Bodytype:hyper::body::Empty: an empty body, yielding no data or trailers. Since it never yields data, itsBuftype could even be someenum NeverBuf {}.hyper::body::Full: the full body, able to yield 1 data buffer (whathyper::Body::from(buf)is in 0.13).hyper::body::Streaming: the streaming bodies received from a remote over HTTP/1 or 2.- (Optional)
hyper::body::BoxBody
A client response would then be Response<Streaming> (as would a server Request<Streaming>), since they are streamed from the connection. Hopefully, this should make the intent clearer when you have a Request<Empty> or Response<Full>, instead of just Request<Body>.
Status: Accepted
Progress
- Remove
streamvariant - Remove Body's
Oncevariant - Make
body::Sendertype andBody::channel()constructor private. - Rename
BodytoRecvtemporarily - Rename
HttpBodyre-export toBody - Determine name for
Recvbody type #2971 - Document
hyper::bodymodule with how to use different body types #3103 - website: Add more in-depth Body guide #3104
Activity
seanmonstar commentedon Nov 26, 2020
cc @LucioFranco @hawkw
davidbarsky commentedon Nov 26, 2020
As a consumer, I like this proposal.
I don't want to jinx this, but it's possible that
!might get stabilized with rust-lang/rust#79366. I don't think it'll be stable in time for Hyper 0.14, but there's a chance it might be stable in time for Hyper 0.15 (if planned).sfackler commentedon Nov 26, 2020
Does this imply that the Client type can drop its body type parameter? That'd be quite nice for reasons even beyond this issue, like allowing non
'staticbodies.seanmonstar commentedon Nov 26, 2020
I don't see how the client would drop its body type parameter... it still needs to know what kind of bodies you expect to send.
LucioFranco commentedon Nov 27, 2020
I like this proposal, I'd also consider adding a
GenericBodywhich is an enum of all of the bodies + the boxed one? We may also want to provide utils likeEitherBodyto compose them. Overall, I am a fan of this, no major nits.peku33 commentedon Nov 29, 2020
Would be nice to still be able to use all types at once, as @LucioFranco said. I belive most of apps mix those, eg.
Fullfor data,Streamingfor SSE etc. If body type goes into server template parameter, it would be a bit harder to return multi-variant version. Boxing is an option, but still requires some allocations. Having enum of three types doesn't sound bad.davidbarsky commentedon Nov 30, 2020
Something I didn't consider when responding to this initially: what implications, if any, does this proposed change have for h2-style patterns where the initial handshake request has a body of
()but the client subsequently expected to write to a stream handle?seanmonstar commentedon Nov 30, 2020
If you expect different requests to have different body behaviors, you can use a body type that captures that.
seanmonstar commentedon Dec 3, 2020
So, it does seem like this is desirable, but I'm going to punt to the next milestone, since proposing this right when 0.14 was almost ready is kinda late.
6 remaining items
seanmonstar commentedon Jun 15, 2022
The
http-body-utilcrate now has many of these variants. We likely won't re-export directly from hyper, since that util crate is less stable. Next steps for hyper 1.0 are to remove the internal variants ofhyper::Body, and replace their usage in tests and examples with those fromhttp-body-util.Xuanwo commentedon Jul 26, 2022
seanmonstar commentedon Jul 26, 2022
Add `StreamBody` (#237)