[cratelyn]

Rendered

note: this is still a working draft, but i wanted to open this up as i continue to flesh this proposal out.

Important

Please make line comments, instead of comments on the PR as a whole. It makes discussion much easier to keep untangled.

[cratelyn]

this remains the largest open question to me. in hyperium/http-body#90, the question was raised about why we model this as a Poll<Result<(), E>>. one alternative was suggested:

It's done purely so you can ?-propagate errors in the implementation. Maybe Poll<Result<!, E>> would be better?

to me this indicates that there is not a meaningful distinction between these. the error is the interesting value, otherwise we are indicating whether or not progress was made by the body.

[cratelyn]

tokio::net::TcpStream::poll_peek() may be a useful comparison to make here:

Note that on multiple calls to poll_peek, poll_read or poll_read_ready, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

perhaps the relationship between poll_frame and poll_progress could be described in similar terms. they are both mechanisms to poll a body, one of which does not expose the possibility of yielding a frame, and the Waker from the most recent call will receive a wakeup.

[cratelyn]

todo: these still need to be filled out. i don't see much unknown here, compared to the Pending question above.

[seanmonstar]

It's OK if there aren't any, we can just say so. But here's some questions I have off the top of my head:

• Could a wrong implementation result in truncated messages?
• Could combinators that forward to a wrapped body incorrectly?
• Could a default implementation that one forgets to override lost data?
• Could this be used as a solution to what some may feel are security issues, like stalled streams?

[cratelyn]

i've tried to outline "the rules" of this method here, in part to seed discussion about guarantees and edge cases.

to briefly summarize: (1) poll_progress() is always optional. (2) an error from poll_progress() should be treated as cause to discard the body, just like an error returned from poll_frame(). (3) poll_progress() may be called repeatedly.