README
¶
Ideas Explored and Rejected (EARs): * Rev Provide Queue/Stack as middleware arrangement functions Present in v0.2.0; removed in v0.3.0 on 2025-07-25 While these convenience functions for chaining middleware seem helpful, they obscure execution order and introduce ambiguity in naming. For example, does Queue imply middleware is applied in first-in-first-out order, or executed that way - which is arrangement in precisely the reverse order? Such abstractions sacrifice clarity for superficially cleaner code. * Prop Include 'common' header-setting middleware Rejected on 2025-07-25 Middleware that sets common headers - e.g., CORS or OWASP secure headers - can simplify security configuration. However, when additional headers are set within handlers, reasoning about the final response requires checking multiple places. This breaks locality of behavior and reduces clarity, expecially in light of the Response representation in package messsages.
Documentation
¶
Overview ¶
Package middleware provides composable HTTP middleware for use with net/http. It includes utilities like panic recovery, access logging, request logging, and response inspection.
Index ¶
- func AccessLogger(logger *slog.Logger, prefix string) func(h http.Handler) http.Handler
- func RecoverAndHandle(logger *slog.Logger, fallback http.Handler) func(h http.Handler) http.Handler
- func RequestLogger(logger *slog.Logger, prefix string) func(http.RoundTripper) http.RoundTripper
- func RetryAndObserve(tries uint, delayBase time.Duration, delayMax time.Duration, ...) func(http.RoundTripper) http.RoundTripper
- type BreakerState
- type CircuitBreaker
- type NopRetryObserver
- type RetryObserver
- type RoundTripperFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AccessLogger ¶
AccessLogger returns middleware that logs request and server response details. Logged fields include remote address, method, URL, protocol, response status, user agent, and time to response (here as ttr).
If logger is nil, slog.Default() is used.
func RecoverAndHandle ¶
RecoverAndHandle returns middleware that recovers from panics in downstream handlers. If a panic occurs, it logs the error and stack trace using logger, then delegates to the fallback handler.
If logger is nil, slog.Default() is used.
func RequestLogger ¶ added in v0.5.0
func RequestLogger(logger *slog.Logger, prefix string) func(http.RoundTripper) http.RoundTripper
RequestLogger returns middleware that logs request and response round trips. Logged fields include remote address, method, URL, protocol, response status, user agent, and time to return (here as ttr).
If logger is nil, slog.Default() is used.
func RetryAndObserve ¶ added in v0.5.0
func RetryAndObserve(tries uint, delayBase time.Duration, delayMax time.Duration, breaker *CircuitBreaker, observer RetryObserver) func(http.RoundTripper) http.RoundTripper
Types ¶
type BreakerState ¶ added in v0.5.0
type BreakerState int
BreakerState represents a CircuitBreaker state
const ( BreakerStateClosed BreakerState = iota BreakerStateOpen )
type CircuitBreaker ¶ added in v0.5.0
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker represents a simple two-state circuit. After threshold+1 failures, the breaker breaks open and forces a cooldown period.
func NewCircuitBreaker ¶ added in v0.5.0
func NewCircuitBreaker(threshold uint, cooldown time.Duration) *CircuitBreaker
NewCircuitBreaker returns a new CircuitBreaker. It is initialized with a threshold and open cooldown time that cannot be changed. By default, the breaker is in the closed state and showtime is set to the current time.
func (*CircuitBreaker) OK ¶ added in v0.5.0
func (breaker *CircuitBreaker) OK() bool
OK returns whether the circuit is closed and therefore ok.
func (*CircuitBreaker) OnFailure ¶ added in v0.5.0
func (breaker *CircuitBreaker) OnFailure()
OnFailure increments failures. If failures exceeds threshold, the breaker breaks open, sets showtime to now + cooldown, and resets failures to 0.
func (*CircuitBreaker) OnSuccess ¶ added in v0.5.0
func (breaker *CircuitBreaker) OnSuccess()
OnSuccess resets failures to zero.
func (*CircuitBreaker) State ¶ added in v0.5.0
func (breaker *CircuitBreaker) State() BreakerState
State returns the current breaker's state. If open and past showtime, the breaker flips closed again.
type NopRetryObserver ¶ added in v0.5.0
type NopRetryObserver struct{}
NopRetryObserver is a no operation retry observer. It is used if no observer is supplied in RetryAndObserve
func (*NopRetryObserver) OnFailure ¶ added in v0.5.0
func (o *NopRetryObserver) OnFailure(*http.Request, uint, error)
type RetryObserver ¶ added in v0.5.0
type RetryObserver interface {
OnTry(*http.Request, uint)
OnSuccess(*http.Request, uint)
OnFailure(*http.Request, uint, error)
}
RetryObserver is the interface implemented by an object that can observe retry behavior in a RetryAndObserve RoundTripper.
type RoundTripperFunc ¶ added in v0.5.0
RoundTripperFunc implements RoundTripper. It may be used it to wrap another RoundTripper and act as middleware.
Source Files