Clarify documentation of Body::is_end_stream

[nox]

Prior to http-body 0.1, when there was still Body::poll_data, Body::is_end_stream was meant to return true when Body::poll_data would return Poll::Ready(None).

Now it says that Body::is_end_stream is meant to return true when Body::poll_frame returns Poll::Ready(None), but that means it should return false if the body is going to return a trailers frame from the next call to Body::poll_frame.

That seems like a documentation problem to me, as Hyper's Incoming::is_end_stream can return true prior to trailers frames, when the body is using Content-Length.

Is the intention of Body::is_end_stream in fact to return true prior trailers?

[seanmonstar]

I actually think the documentation is correct. Let me explain what the point of the method was originally: in HTTP/2, a frame can include an END_STREAM (EOS) flag. So, instead of sending an empty DATA frame with EOS, this method allowed us to mark the final frame with some data as EOS, and save a frame.

It would be incorrect to send the last DATA frame of content with EOS if there was supposed to be a trailers frame after it.

[nox]

That makes it very inconvenient for downstream users to do something at the end of the body and before the trailers in HTTP/1, because you now need to call poll_frame and be careful to buffer the trailers frame, if any.

Also that means there is a bug in the Incoming::Chan impl in Hyper, right?

[seanmonstar]

Hm, how so? That's the reality, isn't it? With either HTTP/1 and 2, we might not know a body will end until we receive the trailers.