Documentation
¶
Overview ¶
Package circuitbreaker provides circuit breaker middleware for celeris.
The breaker monitors downstream error rates using a sliding window and automatically stops sending requests when failure thresholds are exceeded, giving the failing service time to recover. It operates as a three-state machine: Closed (normal), Open (rejecting all requests with 503), and HalfOpen (allowing limited probe requests to test recovery).
Use New to create middleware with default settings (50% threshold, minimum 10 requests, 10 s window, 30 s cooldown). Pass a Config to tune Config.Threshold, Config.MinRequests, Config.WindowSize, Config.CooldownPeriod, Config.HalfOpenMax, Config.IsError, and Config.OnStateChange.
Use NewWithBreaker to obtain a *Breaker reference for programmatic state inspection (Breaker.State), sliding-window counter export (Breaker.Counts), and forced reset (Breaker.Reset) from health-check or admin handlers.
ErrServiceUnavailable is the sentinel error (503) returned when the breaker is open; use errors.Is to match it in upstream middleware.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware-traffic
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
ErrServiceUnavailable aliases celeris.ErrServiceUnavailable so callers can match across timeout/circuitbreaker/ratelimit with errors.Is.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a circuit breaker middleware with the given config.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/circuitbreaker"
)
func main() {
// Zero-config: 50% threshold, 10 min requests, 10s window, 30s cooldown.
_ = circuitbreaker.New()
}
Output:
Example (Custom) ¶
package main
import (
"time"
"github.com/goceleris/celeris/middleware/circuitbreaker"
)
func main() {
// Custom threshold and cooldown period.
_ = circuitbreaker.New(circuitbreaker.Config{
Threshold: 0.3,
MinRequests: 20,
CooldownPeriod: time.Minute,
})
}
Output:
Example (PerGroup) ¶
package main
import (
"github.com/goceleris/celeris/middleware/circuitbreaker"
)
func main() {
// Separate circuit breakers for different upstream services.
// s := celeris.New()
// payments := s.Group("/api/payments")
// payments.Use(circuitbreaker.New(circuitbreaker.Config{Threshold: 0.3}))
// internal := s.Group("/internal")
// internal.Use(circuitbreaker.New(circuitbreaker.Config{Threshold: 0.7}))
_ = circuitbreaker.New(circuitbreaker.Config{Threshold: 0.3})
}
Output:
Types ¶
type Breaker ¶
type Breaker struct {
// contains filtered or unexported fields
}
Breaker holds the circuit breaker state. Use NewWithBreaker to obtain a reference for programmatic state inspection and reset.
func NewWithBreaker ¶
func NewWithBreaker(config ...Config) (celeris.HandlerFunc, *Breaker)
NewWithBreaker creates a circuit breaker middleware and returns both the handler and the underlying Breaker for programmatic access.
Example ¶
package main
import (
"fmt"
"github.com/goceleris/celeris/middleware/circuitbreaker"
)
func main() {
// Obtain a Breaker reference for programmatic state inspection.
mw, breaker := circuitbreaker.NewWithBreaker(circuitbreaker.Config{
Threshold: 0.5,
MinRequests: 10,
OnStateChange: func(from, to circuitbreaker.State) {
fmt.Printf("circuit breaker: %s -> %s\n", from, to)
},
})
_ = mw
// Use the breaker for health checks or admin endpoints.
fmt.Println(breaker.State())
}
Output: closed
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// SkipPaths lists paths to skip (exact match).
SkipPaths []string
// Threshold is the failure ratio (failures/total) that trips the breaker.
// Must be in (0, 1] — greater than 0 and at most 1. Default: 0.5.
Threshold float64
// MinRequests is the minimum number of requests in the current window
// before the breaker can trip. Prevents premature tripping on small
// sample sizes. Default: 10.
MinRequests int
// WindowSize is the duration of the sliding observation window.
// Default: 10s.
WindowSize time.Duration
// CooldownPeriod is how long the breaker stays open before transitioning
// to half-open. Default: 30s.
CooldownPeriod time.Duration
// HalfOpenMax is the maximum number of probe requests allowed through
// in the half-open state. Default: 1.
HalfOpenMax int
// IsError determines whether a response should be counted as a failure.
// Receives the error returned by the handler and the response status code.
// Default: status >= 500.
IsError func(err error, statusCode int) bool
// OnStateChange is called when the breaker transitions between states.
// Called under a mutex; keep the callback fast.
OnStateChange func(from, to State)
// ErrorHandler is called to produce a response when the breaker is open.
// Default: returns ErrServiceUnavailable (503).
ErrorHandler func(c *celeris.Context, err error) error
}
Config defines the circuit breaker middleware configuration.
Source Files