Why drain an http.Response body with io.Copy(io.Discard, resp.Body) before closing it?

### Framing is why it matters An HTTP/1.1 keep-alive connection carries one response after another over a single byte stream. The end of a response is defined either by its `Content-Length` or by the terminating zero-length chunk of a chunked body. Until those bytes have actually been consumed, the position of the *next* response on that connection is unknown. So when a caller closes a response body with payload still unread, Go's `net/http` Transport has exactly two choices: keep reading on your behalf, or throw the connection away. Historically it threw the connection away. That is the whole mechanism. The `http.Response` documentation states it plainly: the default Transport may not reuse HTTP/1.x keep-alive connections if the body is not read to completion and closed. "Closed" alone is not the condition; "read to completion **and** closed" is. ### What it looks like when you get it wrong The code compiles, the tests pass, and nothing is leaked — descriptors are released, because you *did* close. What you lose is reuse. Every request opens a new connection: * a DNS resolution (or at least a cache hit), * a TCP three-way handshake, * a TLS handshake, which for a fresh session means certificate verification and asymmetric crypto, * and, on the way out, a socket sitting in the kernel's post-close states for a while. On a client doing a handful of calls a minute this is invisible. On one doing hundreds a second against the same host it is a large, permanent latency floor and a steady churn of sockets and ephemeral ports — and it looks nothing like a bug, because the only symptom is "we are slower than we should be". ### The drain idiom ```go defer func() { _, _ = io.Copy(io.Discard, resp.Body) resp.Body.Close() }() ``` `io.Discard` is a writer that throws away everything written to it, so `io.Copy` here exists purely for its side effect of reading to EOF. Order matters: drain first, close second. In most code you never write this, because you already read the body to completion — `json.NewDecoder(resp.Body).Decode(&v)` normally stops at the end of the JSON value, `io.ReadAll` reads to EOF by definition. The idiom is for the paths where you *don't* consume the body: an early `return` on a bad status code, a decode that fails halfway, a caller that only wanted the headers. ### Bound the drain Draining is not free — you are transferring bytes you are going to throw away, over a network you are paying for. Against an untrusted or unbounded endpoint it is also a way to be made to read forever. The disciplined form caps it: ```go _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 64<<10)) resp.Body.Close() ``` If the remainder fits in the cap you reach EOF and keep the connection; if it does not, you gave up after a bounded amount and pay for a new connection — which is the right trade when the alternative is downloading megabytes to save one handshake. ### Go 1.27 made the common case automatic Recent Go closed most of this gap: on Go 1.27, closing an HTTP/1 response body drains a limited amount of the remaining data automatically so the connection can still be reused. That removes the penalty for the everyday case — a small error body you never read — without introducing an unbounded read. It does not remove the discipline: a body with more left than that bound still costs the connection, and code that must run on older toolchains still needs the explicit drain. Treat the automatic drain as a safety net, not as permission to stop thinking about it. ### HTTP/2 behaves differently On an HTTP/2 connection each request is its own stream multiplexed over one TCP connection, and framing is per-stream. Closing a body early cancels *that stream* (the client sends a stream reset) and the underlying connection carries on serving everything else. So the reuse penalty described here is an HTTP/1 phenomenon. Since Go's `http.DefaultTransport` negotiates HTTP/2 over TLS with servers that support it, the same client code can show the problem against one endpoint and not another — which is exactly the kind of thing that makes it hard to spot from the code alone. ### Where it sits relative to closing Closing and draining answer two different questions. Closing is about *resources*: fail to close and you hold a socket forever. Draining is about *reuse*: fail to drain and you release the socket but never get to use it again. A body you neither drained nor closed is both bugs at once; a body you closed without draining is only the second, which is why it survives code review so easily.