Context timeout configuration for HTTP handlers with downstream database calls in Go

Direct answer

To tell whether a context.DeadlineExceeded error came from a child stage timeout or from the parent request being cancelled, check the parent context’s error after the stage returns:

if errors.Is(err, context.DeadlineExceeded) {
    if parentCtx.Err() != nil {
        // parent request cancelled or its deadline expired
    } else {
        // this stage’s own deadline fired
    }
}

For a cache write that must survive request cancellation, use context.WithoutCancel (Go 1.21+) to detach it, then give the detached work its own timeout:

detached := context.WithoutCancel(reqCtx)
// give the cache write a bounded lifetime of its own
cacheCtx, cacheCancel := context.WithTimeout(detached, 200*time.Millisecond)
defer cacheCancel()
// perform the cache write using cacheCtx

Stage timeouts are normally expressed as absolute durations (e.g. 2 s for DB, 50 ms for cache). Deriving them from the parent’s remaining time is only needed when you want to enforce a proportional budget; otherwise absolute values are simpler and more predictable.

Confirmed facts

• Child contexts created with context.WithTimeout(parent, d) inherit the parent’s deadline; they can only be stricter, never longer.
• Both parent and child deadline expirations produce the same sentinel error context.DeadlineExceeded; the only way to differentiate them is to inspect parentCtx.Err() after the child returns.
• context.WithoutCancel drops cancellation and deadline propagation while preserving values, making it suitable for best‑effort work that should outlive the request.
• Every derived cancel function must be deferred (or called explicitly) to avoid leaking the internal timer goroutine.

Likely explanation / trade‑offs

• Using parentCtx.Err() adds negligible overhead and is the idiomatic way to map child‑timeout → HTTP 504 and parent‑cancellation → log‑only or 499/503 handling.
• context.WithoutCancel frees the detached work from the request deadline, but you must impose a new timeout (or risk unbounded execution) and consider that the work may outlive the handler, complicating graceful shutdown and tracing.
• Absolute stage timeouts are easier to reason about and configure; deriving from remaining time introduces coupling and is rarely required unless you have a strict global budget to split.

Steps for this case

1. At the HTTP handler entry, create a base request context with the desired overall deadline: reqCtx, reqCancel := context.WithTimeout(r.Context(), 5*time.Second); defer reqCancel().
2. For each downstream stage that needs a stricter limit, derive a child: stageCtx, stageCancel := context.WithTimeout(reqCtx, stageLimit); defer stageCancel().
3. After the stage call, if the returned error is context.DeadlineExceeded, inspect reqCtx.Err() to decide whether to treat it as a stage timeout or a parent cancellation.
4. For the cache write that must survive request cancellation, obtain a detached context: detached := context.WithoutCancel(reqCtx), then apply its own timeout: cacheCtx, cacheCancel := context.WithTimeout(detached, 200*time.Millisecond); defer cacheCancel().
5. Ensure every stageCancel and cacheCancel is deferred on all paths (success and error) to prevent timer goroutine leaks.

Verification checklist

• Run a unit test where a child timeout (e.g. 50 ms) fires before the parent deadline (e.g. 5 s); assert that parentCtx.Err() == nil and the stage error is context.DeadlineExceeded.
• Run go vet and a goroutine‑leak detector (e.g. goleak) to confirm all cancel functions are invoked.
• Confirm your toolchain version with go version; context.WithoutCancel is available only from Go 1.21 onward.
• Simulate a client disconnect mid‑request and verify that the detached cache write still completes within its own timeout.

Missing diagnostic detail

If you are unsure whether your environment runs Go 1.21 or later, please confirm the Go version; without context.WithoutCancel you would need an alternative detached context (e.g. context.Background() with request‑scoped values) and its own timeout.