feat(util): introduce TryFutureBody<F, B> - #177
Merged
Conversation
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
force-pushed
the
try-future-body
branch
from
August 21, 2026 22:10
491595b to
0424d86
Compare
cratelyn
marked this pull request as ready for review
August 21, 2026 22:12
Member
|
Reminds me of tower's FutureService. Sounds good. Perhaps it should be an opaque struct publicly, and the enum variants internal? |
this prevents future additions or alterations to the inner mechanics of `TryFutureBody<F, B>` from being breaking changes w.r.t. semantic versioning. this applies a review suggestion from: hyperium#177 (comment). Signed-off-by: katelyn martin <git@katelyn.world>
this helps explain the state transitions of the `Inner` enum. Signed-off-by: katelyn martin <git@katelyn.world>
Member
Author
that's a great idea, that prevents changes to the enum from becoming breaking changes. 3fb9507 applies that, and cc8bc8b introduces a small ascii diagram to outline the state machine's transitions. |
cratelyn
marked this pull request as draft
August 31, 2026 19:01
Member
Author
|
i believe this can be written without relying on any handwritten unsafe code. i'm going to rework this slightly to avoid the manually written pin projection code before marking it as ready for another round of review. |
Signed-off-by: katelyn martin <git@katelyn.world>
cratelyn
marked this pull request as ready for review
August 31, 2026 19:14
cratelyn
commented
Aug 31, 2026
Comment on lines
-135
to
-160
| impl<F, B> TryFutureBody<F, B> { | ||
| /// Returns an [`InnerProj<'pin, F, B>`] projection. | ||
| /// | ||
| /// This is used internally by [`TryFutureBody<F, B>`] to access its inner future and body. | ||
| pub(super) fn project<'pin>(self: Pin<&'pin mut Self>) -> InnerProj<'pin, F, B> { | ||
| // Safety: | ||
| // | ||
| // We never move the inner future, or the inner body, out of the mutable reference | ||
| // we receive from `Pin::get_unchecked_mut()`. We project their "pinnedness" forwards | ||
| // into a `Pin<&mut F>` or a `Pin<&mut B>`, respectively. If the body is finished, | ||
| // there is no data that could be moved out. | ||
| // | ||
| // - https://doc.rust-lang.org/std/pin/struct.Pin.html#method.get_unchecked_mut | ||
| // | ||
| // For more information on structural pinning, see: | ||
| // <https://doc.rust-lang.org/std/pin/index.html#projections-and-structural-pinning> | ||
| unsafe { | ||
| let Self { inner } = self.get_unchecked_mut(); | ||
| match inner { | ||
| Inner::Future(fut) => InnerProj::Future(Pin::new_unchecked(fut)), | ||
| Inner::Body(body) => InnerProj::Body(Pin::new_unchecked(body)), | ||
| Inner::Failed => InnerProj::Failed, | ||
| } | ||
| } | ||
| } | ||
| } |
Member
Author
seanmonstar
approved these changes
Aug 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
fixes #157.
this commit introduces a new utility to
http-body-util, permittingcallers to treat a fallible
Future<Output = Result<Body, _>>as abody. 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 theEither<L, R>middleware, this adapter type works around someminor limitations in
pin-project-lite. namely, enum tuple variants arenot supported, and doc-comments (required here per the
missing_docslint enforced in this library) also were not parsed properly.
aprojsubmodule contains code derived from the output generated bythe
pin_project!macro, with some additional commentary added to bethorough 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 thanFutureBody<F, B>. because this works with futures whose output is afallible
Result<B, E>, it felt like a forward-compatible choice tochoose this name instead. that will permit the future addition of a
FutureBody<F, B>that wraps futures that emit a plainBbody. thatis not included in this commit, so as to facilitate review, but can be
added as a simple follow-up to this proposal.