https://golang.org/pkg/net/http/#Response

The default HTTP client's Transport may not
// reuse HTTP/1.x "keep-alive" TCP connections if the Body is
// not read to completion and closed.

I believe this is sufficient, and pretty clearly mentioned.

Please let us know if you had anything else in mind or maybe you missed this part ?

Here https://golang.org/pkg/net/http/#Client.Do:

If the returned error is nil, the Response will contain a non-nil Body which the user is expected to close. If the Body is not closed, the Client's underlying RoundTripper (typically Transport) may not be able to re-use a persistent TCP connection to the server for a subsequent "keep-alive" request.

I think it would also be good on top in the examples section to put a example with io.Copy(ioutil.Discard, resp.Body) if you just do a GET request to check the return code.

@agnivade the text you've highlighted is clear on what needs to be done (read to completion and closed) to avoid something bad (may not reuse connection), but I think the problem is the other places where closing the body is mentioned. This is a very common complaint so I think it's worth digging deeper on this.

• Overview: "The client must close the response body when finished with it" The code that follows has ioutil.ReadAll, but "finished with it" is vague. "finished with it" could be interpreted as used it to completion OR not interested in using it all and ignoring it. So someone might think that if they aren't using the response body, then this rule doesn't apply to them.
• Client.Get: "Caller should close resp.Body when done reading from it." "done reading from it" is less vague than "finished with it", but for some reason the word "should" is used instead of "must", which weakens the point. But even if it had "must" someone might think that if they don't want to read the body, this rule doesn't apply to them. Also this rule doesn't explain the consequences of ignoring it.
• Client.Post: "Caller should close resp.Body when done reading from it."
• Client.PostForm: "Caller should close resp.Body when done reading from it."

Perhaps we've been trying to avoid duplicating:

The default HTTP client's Transport may not reuse HTTP/1.x "keep-alive" TCP connections if the Body is not read to completion and closed.

all over the docs because it's verbose and because some people might not care about connection reuse. One alternative is to to be more concise and say "the caller must read the body to completion and close" without saying why, but that's dishonest since they don't really need to in all cases.

@bradfitz am I missing any nuance here?

I see.

Then this line If the Body is not closed, the Client's underlying RoundTripper (typically Transport) may not be able to re-use a persistent TCP connection to the server for a subsequent "keep-alive" request. in https://golang.org/pkg/net/http/#Client.Do is technically incorrect I believe. Because you need to close and read body.

Exactly. I would love to see it documented in every function but it's a lot copy paste. Are there references in godocs which we can use so the phrase is only documented once?

Another option would be to change the Body.Close() method to automatically read all data before closing it but I think this would be a bigger change

Didn't this "read body to completion" come up as a security issue at some point? I don't remember if it was just server or client related (or both), but basically if Go automatically read the body to completion than it would be trivial for the program to be DoS'd (cpu/memory consumption). The counterpart could just send an infinite body and the Go program would sit there consuming it all, and if you're not consuming it explicitly in your code (ioutil.Discard or otherwise) then the developer of the program might not know it was happening.

I thought I saw a commit a while back that had Go read part of the body to a certain point but if it kept going then it would close the connection abruptly, to avoid this potiental DoS. If thats the case, and you make another request while some goroutine is doing this, it would make sense that a new connection would be made (what you're seeing here and why reading the body to completion is the "solution"). In fact, if you don't read the body to completion from both a security and "HTTP" standpoint doesn't it make more sense to close the connection on (or near) body close and reopen a new connection when needed? That way it's only one connection at a time.

The default HTTP client's Transport may not reuse HTTP/1.x "keep-alive" TCP connections if the Body is not read to completion and closed.

To be precise, what does it mean for a Body to be read to completion?

If the Body is not closed, the Client's underlying RoundTripper (typically Transport) may not be able to re-use a persistent TCP connection

The RFC verbiage doesn't help me understand under what conditions it may or may not reuse the connection. I suspect this was chosen because the request might return an error, but this information is already fuzzy when reading the package documentation:

# note: godoc is gone in 1.12
# it now has to be installed separately
# go get github.com/golang/tools/cmd/godoc
; godoc net/http 

package http
    import "net/http"

    Package http provides HTTP client and server implementations.

    Get, Head, Post, and PostForm make HTTP (or HTTPS) requests:

        resp, err := http.Get("http://example.com/")
        ...
        resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf)
        ...
        resp, err := http.PostForm("http://example.com/form",
                url.Values{"key": {"Value"}, "id": {"123"}})

    The client must close the response body when finished with it:

        resp, err := http.Get("http://example.com/")
        if err != nil {
                // handle error
        }
        defer resp.Body.Close()
        body, err := ioutil.ReadAll(resp.Body)
        // ...

Above, the example fails to convey the careful dance required to make connections reusable. The error
handling and return is replaced by a // handle error comment that falls through to the defer.

Second, the Body is consumed and assigned to a variable called body. This doesn't show what the user needs to do if they don't care about the Body.

The number of users that do this correctly in private repositories is none. I have never seen it, nor can I remember the last time I've seen it in open source projects. I suspect it's because of the term finished, which does not imply that the body must be read in full. I don't think saying must be read is clear either, because an io.Reader isn't guaranteed to consume the Body with one call to read. The term is likely to be lost in translation.

I think the term consume is more appropriate than finished or read.

paging @bradfitz. Thoughts on this ? We need some clarity on how do we make the docs more clear. In particular @meirf's comment here outlines the various places where things are not uniform.

@bradfitz sorry for a noisy comment, but this looks to be part of the Go 1.12 milestone. Wanted to ping you again for 👀.

Change https://golang.org/cl/158417 mentions this issue: net/http: clarify Transport connection reuse docs a bit

I sent off https://golang.org/cl/158417 to add a bit more. That's probably enough for Go 1.12.

From what i see in the source code, response.Body.Close() method should take care of draining body:

Took me some hours to find this hack
Adding io.Copy(ioutil.Discard, resp.Body) and I finally get connection reuse

@dmarkhas @drscre this issue has gone stale. I am going to close it based on @bradfitz 's comment #26095 (comment).

If there is work unaddressed I would appreciate if it you can open a new issue that captures the delta. Thank you.