Skip to content

feat(util): introduce TryFutureBody<F, B> - #177

Open
cratelyn wants to merge 1 commit into
hyperium:masterfrom
cratelyn:try-future-body
Open

feat(util): introduce TryFutureBody<F, B>#177
cratelyn wants to merge 1 commit into
hyperium:masterfrom
cratelyn:try-future-body

Conversation

@cratelyn

@cratelyn cratelyn commented Aug 21, 2026

Copy link
Copy Markdown
Member

fixes #157.

this commit introduces a new utility to http-body-util, permitting
callers to treat a fallible Future<Output = Result<Body, _>> as a
body. while the future is still pending, the inner future will be
polled. once the future yields a body, the body will then be polled for
its contents.

one important difference in the code in this commit as compared to the
original snippet proposed in #157 is that if the future fails and yields
an error, the error will be propagated and the body will be marked as
having failed.

like the Either<L, R> middleware, this adapter type works around some
minor limitations in pin-project-lite. namely, enum tuple variants are
not supported, and doc-comments (required here per the missing_docs
lint enforced in this library
) also were not parsed properly.

a proj submodule contains code derived from the output generated by
the pin_project! macro, with some additional commentary added to be
thorough about noting safety with respect to Pin<T> projection.

a small test suite is included to show that error propagation works as
expected, hints work correctly, and that data from the inner body is
returned correctly.

one other detail about the code in this commit worth calling out is
that this middleware is named TryFutureBody<F, B> rather than
FutureBody<F, B>. because this works with futures whose output is a
fallible Result<B, E>, it felt like a forward-compatible choice to
choose this name instead. that will permit the future addition of a
FutureBody<F, B> that wraps futures that emit a plain B body. that
is not included in this commit, so as to facilitate review, but can be
added as a simple follow-up to this proposal.

fixes hyperium#157.

this commit introduces a new utility to `http-body-util`, permitting
callers to treat a fallible `Future<Output = Result<Body, _>>` as a
body. while the future is still pending, the inner future will be
polled. once the future yields a body, the body will then be polled for
its contents.

one important difference in the code in this commit as compared to the
original snippet proposed in hyperium#157 is that if the future fails and yields
an error, the error will be propagated and the body will be marked as
having failed.

like the `Either<L, R>` middleware, this adapter type works around some
minor limitations in `pin-project-lite`. namely, enum tuple variants are
not supported, and doc-comments (_required here per the `missing_docs`
lint enforced in this library_) also were not parsed properly.

a `proj` submodule contains code derived from the output generated by
the `pin_project!` macro, with some additional commentary added to be
thorough about noting safety with respect to `Pin<T>` projection.

a small test suite is included to show that error propagation works as
expected, hints work correctly, and that data from the inner body is
returned correctly.

one _other_ detail about the code in this commit worth calling out is
that this middleware is named `TryFutureBody<F, B>` rather than
`FutureBody<F, B>`. because this works with futures whose output is a
fallible `Result<B, E>`, it felt like a forward-compatible choice to
choose this name instead. that will permit the future addition of a
`FutureBody<F, B>` that wraps futures that emit a plain `B` body. that
is not included in this commit, so as to facilitate review, but can be
added as a simple follow-up to this proposal.

Signed-off-by: katelyn martin <git@katelyn.world>
@cratelyn
cratelyn marked this pull request as ready for review August 21, 2026 22:12
@seanmonstar

Copy link
Copy Markdown
Member

Reminds me of tower's FutureService. Sounds good.

Perhaps it should be an opaque struct publicly, and the enum variants internal?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Convert Future<Body> into Body

2 participants