Documentation
¶
Overview ¶
Package timeout provides cooperative request-deadline middleware and an explicit hard timeout variant for handlers that need a synthesized timeout response when downstream code ignores context cancellation.
Hard timeout buffers the handler response before committing it to the client so late writes can be discarded after the deadline. It is not suitable for streaming responses, server-sent events, websocket upgrades, or handlers that require optional http.ResponseWriter interfaces such as http.Flusher, http.Hijacker, http.Pusher, or io.ReaderFrom. Handler panics are recovered inside the hard-timeout goroutine: before timeout they produce deterministic Problem Details responses, and after timeout they are contained after the 504 response has already won.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrHardTimeoutCaptureLimitExceeded = errors.New("hard timeout response capture limit exceeded")
Functions ¶
This section is empty.
Types ¶
type HardTimeout ¶ added in v2.1.0
HardTimeout applies a per-request context deadline and sends a timeout response when the deadline expires before the handler returns. Handler writes after the deadline are discarded. Responses are buffered up to MaxCaptureBytes, which defaults to 1 MiB when unset.
func NewHard ¶ added in v2.1.0
func NewHard(opts Options) (*HardTimeout, error)
NewHard constructs a hard wall-clock timeout middleware. It keeps the cooperative request context deadline and also synthesizes a 504 Problem Details response when the wrapped handler does not return in time.
func (*HardTimeout) Handler ¶ added in v2.1.0
func (m *HardTimeout) Handler(next http.Handler) http.Handler
Handler wraps the next handler with a context deadline and a hard timeout response. It cannot stop CPU work in a handler that ignores ctx.Done, but it does stop that handler from writing the client response after the deadline. Panics from the wrapped handler are recovered inside the child goroutine. A panic before the timeout wins returns a deterministic 500 Problem Details response unless capture overflow already occurred. A panic after the timeout response has been sent is contained and dropped.
func (*HardTimeout) Middleware ¶ added in v2.1.0
func (m *HardTimeout) Middleware() func(http.Handler) http.Handler
Middleware implements ports.Middleware via Handler adapter.
type Middleware ¶
type Middleware = Propagator
Middleware is kept as a backward-compatible alias for Propagator.
type Propagator ¶ added in v2.1.0
Propagator applies a per-request context deadline without writing timeout responses. Handlers and downstream calls must observe ctx.Done for the deadline to take effect.
func New ¶
func New(opts Options) (*Propagator, error)
New constructs a cooperative request-deadline propagator. Deprecated: use NewPropagator to make the non-aborting behavior explicit.
func NewPropagator ¶ added in v2.1.0
func NewPropagator(opts Options) (*Propagator, error)
NewPropagator constructs a cooperative request-deadline propagator with the given duration.
func (*Propagator) Handler ¶ added in v2.1.0
func (m *Propagator) Handler(next http.Handler) http.Handler
Handler wraps the next handler with a context deadline. It does not abort writes or synthesize timeout responses.
func (*Propagator) Middleware ¶ added in v2.1.0
func (m *Propagator) Middleware() func(http.Handler) http.Handler
Middleware implements ports.Middleware via Handler adapter.
Source Files