Documentation
¶
Overview ¶
Package recovery provides panic recovery middleware for HTTP handlers.
The middleware recovers from panics in HTTP handlers and returns a 500 Internal Server Error response to the client. This prevents a single panicking request from crashing the entire server.
Basic Usage ¶
mux := http.NewServeMux()
mux.HandleFunc("/", handler)
wrappedMux := recovery.Middleware(mux)
http.ListenAndServe(":8080", wrappedMux)
Logging ¶
By default panics are recovered silently. Use WithLogger to log panic details (value, stack trace, request method and path) at ERROR level:
logger := logging.New() wrappedMux := recovery.Middleware(mux, recovery.WithLogger(logger))
Panic reporting ¶
Use WithPanicHandler to forward recovered panics to observability backends. RecordError receives a sanitized, value-free error suitable for tracing spans; ReportPanic receives the raw panic value for operator-configured error trackers.
Abort-handler passthrough ¶
A panic of http.ErrAbortHandler (or an error wrapping it) is re-panicked rather than recovered, preserving net/http and httputil.ReverseProxy streaming-abort semantics.
Stability ¶
This package is Beta stability. The API may have minor changes before reaching stable status in v1.0.0.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Middleware ¶
Middleware is an HTTP middleware that recovers from panics. When a panic occurs, it returns a 500 Internal Server Error response to the client, preventing the panic from crashing the server.
A panic of http.ErrAbortHandler (or an error wrapping it) is re-panicked instead of recovered: net/http and httputil.ReverseProxy use that sentinel to abort in-flight streaming responses, and recovering it would corrupt the response and log noisy stack traces for a normal disconnect.
Options can be provided to configure logging and panic reporting. By default, panics are recovered silently. Use WithLogger to enable logging and WithPanicHandler to report panics to observability backends.
Types ¶
type Option ¶ added in v0.0.5
type Option func(*config)
Option configures the recovery middleware.
func WithLogger ¶ added in v0.0.5
WithLogger sets the logger used to report recovered panics. When a panic is recovered and a logger is configured, the middleware logs the panic value, stack trace, and request context at ERROR level.
func WithPanicHandler ¶ added in v0.0.36
func WithPanicHandler(h PanicHandler) Option
WithPanicHandler sets the handler invoked when a panic is recovered. Typical implementations record the panic on a tracing span and/or report it to an error-tracking backend such as Sentry. The handler runs after logging and before the 500 response is written.
The handler must not panic itself; a panicking handler crashes the serving goroutine just as an unrecovered panic would.
type PanicHandler ¶ added in v0.0.36
type PanicHandler interface {
// RecordError records a sanitized error for the request's panic.
// The error message is always generic ("panic recovered") and contains
// no panic value.
RecordError(r *http.Request, err error)
// ReportPanic reports the raw recovered panic value for the request.
ReportPanic(r *http.Request, panicValue any)
}
PanicHandler receives recovered panics for observability backends. Implementations must be safe for concurrent use and must not panic.
The two methods exist because backends have different data-safety contracts:
- RecordError is for telemetry that ships to shared/external systems (tracing spans, metrics). It receives a generic error whose message never contains the panic value, so implementations can safely attach it to spans or error records.
- ReportPanic is for error-tracking backends the operator explicitly configured (e.g. Sentry Issues). It receives the raw recovered panic value, which such backends need to group and triage the failure.
type PanicHandlerFunc ¶ added in v0.0.36
PanicHandlerFunc adapts a single function to PanicHandler, calling it from both RecordError and ReportPanic. The function receives the panic value on ReportPanic and nil on RecordError. Prefer implementing PanicHandler directly when the two channels need different treatment.
func (PanicHandlerFunc) RecordError ¶ added in v0.0.36
func (f PanicHandlerFunc) RecordError(r *http.Request, _ error)
RecordError calls f(r, nil).
func (PanicHandlerFunc) ReportPanic ¶ added in v0.0.36
func (f PanicHandlerFunc) ReportPanic(r *http.Request, panicValue any)
ReportPanic calls f(r, panicValue).
Source Files