With one shared http.Client, how do you give a single outbound call a tighter deadline?

## Why the client field is not enough `http.Client.Timeout` is a property of the client object, and a client is meant to be built once and shared — it is safe for concurrent use and its transport caches connections, so a client per call is wasteful and defeats connection reuse. That leaves a tension: one shared client, but calls with genuinely different budgets. A health check to the same host should fail in 200 milliseconds; a report fetch might deserve five seconds. Go resolves this by putting per-call deadlines on the **request**, carried in a `context.Context`. ## The mechanism ```go ctx, cancel := context.WithTimeout(ctx, 800*time.Millisecond) defer cancel() req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) if err != nil { return err } resp, err := shared.Do(req) ``` `http.NewRequestWithContext` stores the context on the request; the transport watches it for the whole life of the exchange. When the context is done — deadline passed, or someone called `cancel` — the transport aborts the call and any in-flight read of the body fails. ## Both limits apply If the shared client has `Timeout: 5 * time.Second` and the request context carries 800 milliseconds, the call is bounded at 800 milliseconds. If the context carries 30 seconds, the call is still bounded at 5 seconds. **The request context can tighten the client's ceiling but never raise it**, because the client applies its own limit independently. If a particular dependency legitimately needs longer than the ceiling, that is a signal to give it its own client rather than to argue with the context. ## Where the clock actually starts `context.WithTimeout(parent, d)` computes an absolute deadline of *now plus d* at the moment it is called. This trips people in loops: ```go ctx, cancel := context.WithTimeout(parent, time.Second) defer cancel() for _, url := range urls { // every iteration shares the same one-second deadline } ``` That may be exactly what you want — one second for the whole batch — but it is not "one second each". For per-call budgets, derive a fresh context inside the loop and cancel it each iteration (`defer` inside a loop body accumulates until the function returns, so either wrap the body in a closure or call `cancel()` explicitly). ## The `defer cancel()` trap Calling `cancel` is mandatory: skipping it leaks the timer and the child context until the parent is done, and `go vet`'s `lostcancel` check will flag the obvious cases. But the natural `defer cancel()` is wrong in one specific shape — a helper that returns the response for someone else to read: ```go func fetch(ctx context.Context, c *http.Client, url string) (*http.Response, error) { ctx, cancel := context.WithTimeout(ctx, time.Second) defer cancel() // fires on return; the caller's Body read now fails req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) if err != nil { return nil, err } return c.Do(req) } ``` The function returns, `cancel` runs, the context is done, and the caller gets an error the first time it reads the body — usually reported as a cancelled request, which sends people hunting for a network fault. Three honest fixes: consume the body inside `fetch` and return bytes or a decoded value; return the `cancel` function alongside the response so the caller defers it; or let the deadline live in the caller's context and take it as a parameter, which is usually the cleanest because the caller is the one who knows the budget. ## Cancellation, not just expiry A context deadline buys more than a timer. Because the same context can be cancelled explicitly, a per-call context lets you abandon in-flight work when it stops being useful: the user hit Ctrl-C, a sibling request in a fan-out already failed, or an outer deadline fired. `Client.Timeout` has no equivalent — there is no way to say "never mind" to a call already in flight through a client field. That is the main reason context deadlines are the default advice in modern Go code and the client field is treated as a backstop. ## Review checklist - Every outbound request built with `NewRequestWithContext`, never `NewRequest` plus a hopeful client field. - A `cancel` reachable on every path, and not deferred across a returned response body. - The context created as close to the call as the budget's meaning allows. - The shared client still shared — deriving a context is free, constructing clients is not.