← All posts

Go HTTP/1.1 connection reuse, and the body handling that decides it

Go HTTP clients only reuse HTTP/1.1 connections when response bodies are handled correctly. Inspect drain-and-close paths first, then tune transport settings and measure reuse with httptrace.

Go’s net/http client does a lot for you. It pools TCP connections, keeps them alive, and reuses them across requests. When reuse works, your services spend less time in handshakes and less time opening sockets. Latency drops. File descriptor pressure drops. Tail behavior often improves.

When reuse fails, the symptoms look vague. A client appears slower under load. You see more TIME_WAIT sockets. TLS handshakes rise. The remote service reports more short-lived connections than expected. The source item, Go’s post “Better HTTP/1 connection reuse”, points at one of the core causes: reuse depends on how response bodies are handled. That detail matters in any Go service which talks to APIs, storage gateways, LLM endpoints, or internal microservices.

This is worth your attention because the failure mode is easy to introduce in clean-looking code. A request succeeds, you decode part of the body, then move on. Everything passes tests. Under production concurrency, the transport stops reusing connections and starts paying setup cost on each request. The fix is often small, but you need to know what to inspect.

Inspect how every response body ends

For HTTP/1.1 keep-alive reuse, the transport needs the connection in a clean state before it returns it to the idle pool. In practice, your code needs to do two things with resp.Body.

  • Read it to EOF, or otherwise discard the unread remainder
  • Close it

Closing alone is not enough when unread bytes remain. If the transport cannot tell where the current response ends in a way it trusts for reuse, it will throw the connection away.

This pattern is safe when you need the full payload:

resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

body, err := io.ReadAll(resp.Body)
if err != nil {
    return err
}

_ = body

This pattern is safer when you only need headers or a small prefix:

resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

_, _ = io.Copy(io.Discard, resp.Body)

Common breakpoints include:

  • Returning early after checking StatusCode
  • Decoding one JSON object from a larger stream, then exiting
  • Reading a fixed-size prefix for content sniffing
  • Wrapping resp.Body in another reader and losing track of closure

If you review a codebase, search for client.Do( and http.Get( first. Then trace every return path after success. You want proof that each path drains or deliberately abandons the connection.

Distinguish small one-shot calls from streaming calls

Not every response should be drained for reuse. Some endpoints are streams by design.

Examples:

  • Server-sent events
  • Long polling
  • Log tail endpoints
  • Token streaming from LLM APIs
  • Large object downloads where the caller stops early on purpose

In those cases, the connection often serves one response and then ends. Trying to force a drain would waste time and bandwidth. The practical step is to separate these call types in your client design.

Use one client profile for ordinary API requests where reuse matters. Use another for streams and early-abort downloads. This keeps your metrics honest and your expectations clear.

For ordinary API traffic, tune the transport for pooling:

tr := &http.Transport{
    MaxIdleConns:        100,
    MaxIdleConnsPerHost: 20,
    MaxConnsPerHost:     100,
    IdleConnTimeout:     90 * time.Second,
}
client := &http.Client{Transport: tr}

For streaming traffic, you often care more about deadlines, cancellation, and backpressure than idle reuse. Put those requests behind explicit context handling and document that they are exempt from your normal pooling assumptions.

A common mistake is sharing one client across two opposite workloads, then reading aggregate metrics as if they describe one thing. You end up chasing a pooling issue which is partly a workload classification issue.

Verify reuse with transport-aware signals

You do not need to guess whether reuse is happening. Go exposes enough hooks to measure it.

The first tool is httptrace. It tells you whether a request got a reused connection.

trace := &httptrace.ClientTrace{
    GotConn: func(info httptrace.GotConnInfo) {
        log.Printf("reused=%v idle=%v", info.Reused, info.WasIdle)
    },
}
req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))

Run this on a hot path in staging. If repeated requests to the same host show Reused=false more often than expected, inspect body handling before changing transport knobs.

The second signal is socket churn at the process or host level.

Look for:

  • Rising outbound connects per second
  • High TIME_WAIT counts
  • Increased TLS handshakes per request
  • File descriptor growth during bursts
  • Remote-side logs showing many short-lived sessions from one client

The third signal is latency shape. Failed reuse does not always blow up median latency. It often hits p95 and p99 first, because handshake and queueing costs amplify under concurrency.

If you need a structured review of a service integration workflow, Pigfox Workflow Audit fits well here. It helps map which steps are manual, repeated, or hidden behind helper layers where response cleanup often gets lost.

Watch for helper abstractions that hide the bug

The bug often sits one layer above net/http. Teams build wrappers for JSON, retries, auth, and metrics. Those wrappers improve consistency, but they also hide response lifecycle mistakes.

A few patterns deserve close inspection.

JSON helpers

This is a classic trap:

func getThing(ctx context.Context, url string, out any) error {
    req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("bad status: %s", resp.Status)
    }

    return json.NewDecoder(resp.Body).Decode(out)
}

It looks fine. But if the body contains trailing data, or your non-200 path returns without draining, you lose reuse opportunities. A stronger helper drains on error paths and defines whether successful decode must consume the entire body.

Retry middleware

Retry loops multiply the cost of bad cleanup. One failed attempt with an unread body drops one connection. Under load, a retrying client creates bursts of fresh dials and fresh handshakes.

Check whether your retry wrapper:

  • Closes bodies on all error paths
  • Drains small error responses before retrying
  • Stops retrying on context cancellation
  • Limits total concurrency per host

Observability wrappers

Metrics code often reads status and duration, then returns early. If the wrapper owns the request execution, it also owns body cleanup rules. Make those rules explicit in code review checklists.

Tune transport settings after fixing code paths

Connection reuse issues tempt teams to reach for transport tuning first. Tune second, not first.

These settings matter, but only after body handling is correct:

  • MaxIdleConns
  • MaxIdleConnsPerHost
  • MaxConnsPerHost
  • IdleConnTimeout
  • ResponseHeaderTimeout
  • ExpectContinueTimeout

A pool with tiny idle limits produces churn even with correct body handling. A pool with generous limits still churns if callers leave unread bodies behind. You need both pieces aligned.

Also remember scope. These details are about HTTP/1.x reuse. HTTP/2 changes the picture because many requests share one connection concurrently. Even then, request and response lifecycle discipline still matters. Leaked bodies and weak cancellation handling still waste resources, only in different ways.

For production services, add two lightweight checks:

  • A benchmark or integration test which issues repeated requests to one test server and records reuse ratio with httptrace
  • A lint or review rule for all Do call sites, requiring visible body-close behavior

These checks catch regressions early, especially after wrapper refactors.

What to watch next

Go keeps improving transport behavior and documentation around these edge cases. Track release notes for net/http, especially around connection pooling, cancellation, and HTTP/2 and HTTP/3 behavior. In your own code, keep watching reuse ratio, socket churn, and tail latency together. Those three signals tell you more than any one transport setting in isolation.