net/http: clarify when it is safe to reuse a request

The godoc for RoundTrip already specifies when it's ok to reuse a
request that contains a body: the caller must wait until RoundTrip
calls Close on Request.Body.

This CL adds a small clarification: If the request does not have a
body, it can be reused as long as the caller does not mutate the
Request until RoundTrip fails or the Response.Body is closed.

Fixes #19653

Change-Id: I56652a9369978d11650e2e6314104831c2ce5e78
Reviewed-on: https://go-review.googlesource.com/75671
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/net/http/client.go b/src/net/http/client.go
index 65e0fa2bc4142dfa646d9ca8cbf8585ca8df6586..6f6024ed4d88b6e48e2d3be032757cc3d01b702f 100644 (file)
--- a/src/net/http/client.go
+++ b/src/net/http/client.go
@@ -127,7 +127,10 @@ type RoundTripper interface {
        // authentication, or cookies.
        //
        // RoundTrip should not modify the request, except for
-       // consuming and closing the Request's Body.
+       // consuming and closing the Request's Body. RoundTrip may
+       // read fields of the request in a separate goroutine. Callers
+       // should not mutate the request until the Response's Body has
+       // been closed.
        //
        // RoundTrip must always close the body, including on errors,
        // but depending on the implementation may do so in a separate