Deadlines Per Call

## What the field is `http.Client` in Go's `net/http` package has four fields: `Transport`, `CheckRedirect`, `Jar` and `Timeout`. `Timeout` is a `time.Duration`, and its documentation describes it as "a time limit for requests made by this Client". The important word is *requests*, singular: it is a budget for one logical call, measured on the wall clock, from the moment you hand the request to the client until you are finished with the response. ## The timeline it covers A single outbound HTTP call is not one operation, it is a sequence: 1. Resolve the host name to an address. 2. Open a TCP connection (or take an idle one from the transport's connection cache). 3. If the scheme is `https`, complete the TLS handshake. 4. Write the request line, headers and body. 5. Wait for the server to send response headers. 6. Read the response body. 7. Close the body. `Timeout` spans **all of it**, plus any redirect hops the client follows on your behalf — the budget is not restarted per hop. This is what makes it the single most useful knob for an engineer who just wants their program not to hang. ## The part that surprises people Most timeout mechanisms people meet elsewhere stop once the response "arrives". Go's does not. The client arranges for the request to be aborted when the deadline passes, and that abort reaches an in-flight `Read` on `resp.Body`. Concretely: ```go client := &http.Client{Timeout: 5 * time.Second} resp, err := client.Get(url) // returns after 100ms // ... 6 seconds of slow reading later ... b, err := io.ReadAll(resp.Body) // err: the 5s budget is already gone ``` That is a feature, not a wart: a server that sends headers immediately and then trickles the body one byte a minute is exactly the failure a naive timeout misses. But it has a direct consequence for design — **you cannot use `Client.Timeout` on a client that streams large or long-lived responses**, because the download itself is spending the budget. For those, bound the earlier phases (dial, handshake, waiting for headers) instead and police the body separately. ## The zero value is a trap `var c http.Client` has `Timeout: 0`, which means *no limit*. So does `http.DefaultClient`, which is what the package-level helpers `http.Get`, `http.Post` and `http.Head` use. `http.DefaultTransport` does bound two of the phases — its dialer has a 30-second timeout and `TLSHandshakeTimeout` is 10 seconds — but nothing bounds waiting for response headers or reading the body. A hung server therefore holds a goroutine of yours indefinitely, and a program that fans out to such a server accumulates stuck goroutines and connections until something else breaks. "Never use `http.DefaultClient` in a service" is a rule of thumb worth stating in a review. ## What it is *not* - **Not per connection.** It is per call. If a function makes three sequential calls with the same client and a 5-second `Timeout`, the worst case is roughly 15 seconds, not 5. If you need "this whole unit of work finishes in 5 seconds", you need one absolute deadline shared by every call, not a client field. - **Not per redirect hop.** Ten redirects share one budget. - **Not adjustable per call.** The field lives on the client object. Every call that client makes gets the same ceiling. To make one call tighter, build the request with `http.NewRequestWithContext` and a context carrying a deadline — both limits then apply and the earlier one wins. Nothing on the request can *raise* the client's ceiling. - **Not a guarantee about server-side work.** When your side gives up, the server may still be executing. That is a distributed-systems property, not something a client field can fix. ## Practical shape Construct one client per dependency, at start-up, with a `Timeout` chosen from that dependency's measured latency plus headroom, and share it — `http.Client` is safe for concurrent use by multiple goroutines and is designed to be reused so its transport can cache connections. Then use per-request contexts where a specific call deserves less. That gives you a documented ceiling in the code that owns the dependency, and a caller-controlled budget on top of it.