breaker

Documentation

Overview

Package breaker implements a circuit breaker with configurable failure thresholds. It provides a Handler, to circuit break in HTTP servers, and a Transport, to circuit break in HTTP clients.

Index

• Constants
• Variables
• func DefaultResponseValidator(resp *http.Response) bool
• func DefaultStatusCodeValidator(code int) bool
• func Handler(breaker Breaker, validator StatusCodeValidator, next http.Handler) http.Handler
• func Middleware(breaker Breaker, validator StatusCodeValidator) func(http.Handler) http.Handler
• func NewBreaker(ops ...BreakerOption) *breaker
• func Transport(breaker Breaker, validator ResponseValidator, next http.RoundTripper) http.RoundTripper
• type Breaker
• type BreakerOption
  • func WithCooldown(d time.Duration) BreakerOption
  • func WithFailureRatio(ratio float64) BreakerOption
  • func WithMinObservation(min uint) BreakerOption
  • func WithWindow(w time.Duration) BreakerOption
• type ResponseValidator
• type StatusCodeValidator

Constants

const (
	// DefaultWindow is the default number of per-second buckets that will be
	// considered when calculating metrics on the circuit breaker.
	DefaultWindow = 5 * time.Second

	// DefaultCooldown is the default period a circuit will remain in the open
	// state before allowing a single sentinel request through.
	DefaultCooldown = 1 * time.Second

	// DefaultMinObservations is the default number of observations that must
	// be made before the circuit breaker
	DefaultMinObservations = 10
)

Variables

var (
	// ErrCircuitOpen is returned by the transport when the downstream is
	// unavailable due to a broken circuit.
	ErrCircuitOpen = errors.New("circuit open")
)

Functions

func DefaultResponseValidator

func DefaultResponseValidator(resp *http.Response) bool

DefaultResponseValidator considers any status code less than 400 to be a success, from the perspective of a client. All other codes are failures.

func DefaultStatusCodeValidator

func DefaultStatusCodeValidator(code int) bool

DefaultStatusCodeValidator considers any status code less than 500 to be a success, from the perspective of a server. All other codes are failures.

func Handler

func Handler(breaker Breaker, validator StatusCodeValidator, next http.Handler) http.Handler

Handler produces an http.Handler that's governed by the passed Breaker and StatusCodeValidator. Responses written by the next http.Handler whose status codes fail the validator signal failures to the breaker. Once the breaker opens, incoming requests are terminated before being forwarded with HTTP 503.

func Middleware

func Middleware(breaker Breaker, validator StatusCodeValidator) func(http.Handler) http.Handler

Middleware produces an http.Handler factory like Handler to be composed.

func NewBreaker

func NewBreaker(ops ...BreakerOption) *breaker

NewBreaker constructs a new circuit breaker, initially closed. The breaker opens after failureRatio failures per success, and only after DefaultMinObservations have been made.

func Transport

func Transport(breaker Breaker, validator ResponseValidator, next http.RoundTripper) http.RoundTripper

Transport produces an http.RoundTripper that's governed by the passed Breaker and ResponseValidator. Responses that fail the validator signal failures to the breaker. Once the breaker opens, outgoing requests are terminated before being forwarded with ErrCircuitOpen.

Types

type Breaker

type Breaker interface {
	Allow() bool
	Success(time.Duration)
	Failure(time.Duration)
}

Breaker is an interface representing the ability to conditionally allow requests to pass, and to report on the result of passed requests.

type BreakerOption

type BreakerOption func(c *breakerConfig)

func WithCooldown

func WithCooldown(d time.Duration) BreakerOption

WithCooldown sets the cooldown time

func WithFailureRatio

func WithFailureRatio(ratio float64) BreakerOption

WithFailureRatio sets the failure ratio

func WithMinObservation

func WithMinObservation(min uint) BreakerOption

WithMinObservation sets the mininum observation value

func WithWindow

func WithWindow(w time.Duration) BreakerOption

WithWindow sets the observation window

type ResponseValidator

type ResponseValidator func(*http.Response) bool

ResponseValidator is a function that determines if an http.Response received by a circuit breaking Transport should count as a success or a failure. The DefaultResponseValidator can be used in most situations.

type StatusCodeValidator

type StatusCodeValidator func(int) bool

StatusCodeValidator is a function that determines if a status code written to a client by a circuit breaking Handler should count as a success or failure. The DefaultStatusCodeValidator can be used in most situations.