How do you decide whether a shared Go client package sets its own context.WithTimeout or only honours the caller's deadline?

## What the mechanism decides for you Before any judgment, one fact narrows the choice: a derived context can only make a deadline **earlier**. `context.WithTimeout(ctx, 30*time.Second)` inside a package, called with a context that has 500 ms left, produces a context with 500 ms left. So the two options are not symmetric. "Set my own timeout" cannot mean "guarantee myself 30 seconds"; it can only ever mean "refuse to run longer than 30 seconds". A package-set timeout is a ceiling, and the only situation where the ceiling is the *operative* number is when the caller's budget is larger - or absent. That reframes the decision as: **who owns the ceiling, and when does the ceiling matter?** ## The three cases, and what to do in each **The caller supplied a deadline tighter than your cap.** Nothing to decide - the caller wins, automatically. Pass the context through. The only thing to get right is not *degrading* it: do not start work on `context.Background()` internally, and do not do the expensive part before you derive anything. **The caller supplied no deadline at all** - `ctx.Deadline()` returns `ok == false`. This is the case a library default genuinely exists for. Without one, a hung dependency means a goroutine, a connection and a pool slot held forever, and the failure mode is a slow resource leak rather than an error. A default cap here is defensible and I would ship one. **The caller's deadline is longer than anything your dependency can usefully survive.** This is the contested case. Imposing your cap overrules a caller who may have deliberately chosen a long budget for a batch job. My default is to allow it but make it visible: a field on the client, documented, with the default value stated in the package docs, so the batch team can raise it for their client instance without forking your package. ## Why the constant is a policy question A number compiled into a package that forty services import is a latency and capacity policy that forty teams inherit without ever having reviewed it. It shows up in three ways they will notice: - **Capacity.** If your cap outlives the front door's budget, every timed-out request still holds a connection and a pool slot for the remainder of your cap. The user gave up; your library did not. Under load that inflates effective service time and saturates pools - the classic shape of a cascading timeout incident, where the postmortem's root cause is one constant in a package nobody on the incident call maintains. - **Attribution.** When your cap fires, the error surfaces from your package. Every importing team reads it as "the client library timed out" and files it against you, whether or not your cap was the binding one. - **Change control.** Raising or lowering that constant is a behaviour change shipped through a dependency bump. Someone must own that upgrade and its blast radius - which is precisely the sort of decision an SRE reviewing the incident is entitled to overrule you on. The design that survives review: **a configurable field with a documented default, plus per-hop timings you export**, so that when a deadline fires the histogram shows which layer's budget was binding instead of leaving the postmortem to guess. ## Retries: per-attempt versus overall If the package retries, it is no longer just honouring a budget - it is *spending* one, and the split becomes explicit. The rule I hold to is that **the caller's context is the overall budget** and it is never restarted, extended, or replaced between attempts. Each attempt derives a shorter child from it. Two consequences follow directly from the mechanism: - The loop must stop when the parent is done, and the check is on the parent, not on the per-attempt child, because a per-attempt expiry and the overall one look identical at the error value. Retrying after the caller's budget is gone is pure waste that the caller cannot see. - The per-attempt number is not derivable by the library alone. It is a function of the caller's tolerance for tail latency versus its tolerance for a single slow dependency, so it belongs in configuration next to the cap, not in a constant. A package that retries silently, without either of those, is also making a load decision on its importers' behalf: N attempts multiplies the traffic every importing service sends to a struggling dependency. ## What I actually ship A client struct with a `Timeout` field defaulting to something conservative, documented as applying only when the caller's context has no earlier deadline; the caller's context passed to every network call unchanged; a per-attempt budget and attempt cap that are configurable and default to something modest; `ctx.Err()` returned rather than wrapped into an opaque error; and a metric per attempt so the caller can see which budget bound the call. The judgment I am explicitly *not* making for my importers is what their latency SLO is. ## The position to be able to defend either way The opposite call is legitimate in one situation: a package guarding a shared resource whose availability is everyone's problem - a connection to a database with a fixed pool, say. There, a hard cap that importers cannot raise is a protection mechanism rather than policy overreach, and "no caller may hold this for more than N seconds" is the whole point. State which of the two you are building, because the review comment you will get is exactly that question.