net/http: document that context cancellation does not apply to writable bodies

[nhooyr]

#26937

To enable http.ReverseProxy to cleanly support websocket connections, http.Transport began returning writable response bodies.

This is documented. But what's undocumented is how this response body deals with the request context's cancellation.

See #26101

Right now, the documentation says the cancellation of the request context will cause the response body to close, even if it is writable. However, this is not the case. If a writable response body is returned, cancellation of the request context does not affect it. This is certainly the right behaviour but should be documented.

[gopherbot]

Change https://golang.org/cl/167682 mentions this issue: net/http: document behaviour of cancellation on writable response bodies

[katiehockman]

/cc @bradfitz

Is this intended behavior, and if so, do you think the additional comment in their PR is helping clarify?

[bradfitz]

If a writable response body is returned, cancellation of the request context does not affect it. This is certainly the right behaviour but should be documented.

Why is that certainly the right behavior?

I don't recall that being discussed or designed.

[nhooyr]

Why is that certainly the right behavior?

If you use this feature to do a WebSocket handshake, you will want to have a timeout on the handshake but not on the connection afterwards as WebSocket's can be long lived. Its best to let the caller handle timeouts via the Close method on the returned body.

If the context applied on the returned body for upgraded requests, it would become impossible to cleanly set a timeout on the handshake but not the body.

[nhooyr]

I definitely do see how this could be unexpected as a server could make client code hang if it returns an unexpected upgrade response..

I think the solution here is to only return a writable body if the request is a upgrade request as well, meaning the client understands the body will be writable and not affected by the request context.