breaker

Documentation

Overview

Package breaker provides a circuitbraker mechanism for dealing with flaky or unreliable counterparties.

The algorithm used for the state machine is described by Microsoft https://docs.microsoft.com/en-us/previous-versions/msp-n-p/dn589784(v=pandp.10)

Index

• Constants
• Variables
• func ErrIsOpen(err error) bool
• func ErrIsTooManyRequests(err error) bool
• type Action
• type Breaker
  • func MustNew(options ...Option) *Breaker
  • func New(options ...Option) (*Breaker, error)
  • func (b *Breaker) Do(ctx context.Context, action Action) (interface{}, error)
  • func (b *Breaker) EvaluateState(ctx context.Context) State
• type Config
• type Counts
• type NowProvider
• type OnStateChangeHandler
• type Option
  • func OptClosedExpiryInterval(interval time.Duration) Option
  • func OptConfig(cfg Config) Option
  • func OptHalfOpenMaxActions(maxActions int64) Option
  • func OptNowProvider(provider NowProvider) Option
  • func OptOnStateChange(handler OnStateChangeHandler) Option
  • func OptOpenAction(action Action) Option
  • func OptOpenExpiryInterval(interval time.Duration) Option
  • func OptShouldOpenProvider(provider ShouldOpenProvider) Option
• type ShouldOpenProvider
• type State
  • func (s State) String() string

Constants

const (
	DefaultClosedExpiryInterval = 5 * time.Second
	DefaultOpenExpiryInterval   = 60 * time.Second
	DefaultHalfOpenMaxActions   = 1
	DefaultConsecutiveFailures  = 5
)

Constants

Variables

var (
	// ErrTooManyRequests is returned when the CB state is half open and the requests count is over the cb maxRequests
	ErrTooManyRequests ex.Class = "too many requests"
	// ErrOpenState is returned when the CB state is open
	ErrOpenState ex.Class = "circuit breaker is open"
)

Functions

func ErrIsOpen

func ErrIsOpen(err error) bool

ErrIsOpen returns if the error is an ErrOpenState.

func ErrIsTooManyRequests

func ErrIsTooManyRequests(err error) bool

ErrIsTooManyRequests returns if the error is an ErrTooManyRequests.

Types

type Action

type Action func(context.Context) (interface{}, error)

Action is a piece of code to run.

type Breaker

type Breaker struct {
	sync.Mutex

	// OpenAction is an optional action to be called when the breaker is open (i.e. preventing calls
	// to the main action handler.)
	OpenAction Action

	// OnStateChange is an optional handler called when the breaker transitions state.
	OnStateChange OnStateChangeHandler
	// ShouldOpenProvider is called optionally to determine if we should open the breaker.
	ShouldOpenProvider ShouldOpenProvider
	// NowProvider lets you optionally inject the current time for testing.
	NowProvider NowProvider

	// HalfOpenMaxActions is the maximum number of requests
	// we can make when the state is HalfOpen.
	HalfOpenMaxActions int64
	// ClosedExpiryInterval is the cyclic period of the closed state for the CircuitBreaker to clear the internal Counts.
	// If Interval is 0, the CircuitBreaker doesn't clear internal Counts during the closed state.
	ClosedExpiryInterval time.Duration
	// OpenExpiryInterval is the period of the open state,
	// after which the state of the CircuitBreaker becomes half-open.
	// If Timeout is 0, the timeout value of the CircuitBreaker is set to 60 seconds.
	OpenExpiryInterval time.Duration
	// Counts are stats for the breaker.
	Counts Counts
	// contains filtered or unexported fields
}

Breaker is a state machine to prevent performing actions that are likely to fail.

func MustNew

func MustNew(options ...Option) *Breaker

MustNew returns a new breaker and panics if there is a construction error.

func New

func New(options ...Option) (*Breaker, error)

New creates a new breaker with the given options.

func (*Breaker) Do

func (b *Breaker) Do(ctx context.Context, action Action) (interface{}, error)

Do runs the given action if the Breaker accepts it. Do returns an error instantly if the Breaker rejects the request. Otherwise, Do returns the result of the request. If a panic occurs in the request, the Breaker handles it as an error.

func (*Breaker) EvaluateState

func (b *Breaker) EvaluateState(ctx context.Context) State

EvaluateState returns the current state of the CircuitBreaker.

type Config

type Config struct {
	HalfOpenMaxActions   int64         `json:"halfOpenMaxActions" yaml:"halfOpenMaxActions"`
	ClosedExpiryInterval time.Duration `json:"closedExpiryInterval" yaml:"closedExpiryInterval"`
	OpenExpiryInterval   time.Duration `json:"openExpiryInterval" yaml:"openExpiryInterval"`
}

Config is the breaker config.

type Counts

type Counts struct {
	Requests             int64 `json:"requests"`
	TotalSuccesses       int64 `json:"totalSuccesses"`
	TotalFailures        int64 `json:"totalFailures"`
	ConsecutiveSuccesses int64 `json:"consecutiveSuccesses"`
	ConsecutiveFailures  int64 `json:"consecutiveFailures"`
}

Counts holds the numbers of requests and their successes/failures. CircuitBreaker clears the internal Counts either on the change of the state or at the closed-state intervals. Counts ignores the results of the requests sent before clearing.

type NowProvider

type NowProvider func() time.Time

NowProvider returns the current time.

type OnStateChangeHandler

type OnStateChangeHandler func(ctx context.Context, from, to State, generation int64)

OnStateChangeHandler is called when the state changes.

type Option

type Option func(*Breaker) error

Option is a mutator for a breaker.

func OptClosedExpiryInterval

func OptClosedExpiryInterval(interval time.Duration) Option

OptClosedExpiryInterval sets the ClosedExpiryInterval.

func OptConfig

func OptConfig(cfg Config) Option

OptConfig sets the breaker based on a config.

func OptHalfOpenMaxActions

func OptHalfOpenMaxActions(maxActions int64) Option

OptHalfOpenMaxActions sets the HalfOpenMaxActions.

func OptNowProvider

func OptNowProvider(provider NowProvider) Option

OptNowProvider sets the now provider on the breaker.

func OptOnStateChange

func OptOnStateChange(handler OnStateChangeHandler) Option

OptOnStateChange sets the OnStateChange handler on the breaker.

func OptOpenAction

func OptOpenAction(action Action) Option

OptOpenAction sets the open action on the breaker.

func OptOpenExpiryInterval

func OptOpenExpiryInterval(interval time.Duration) Option

OptOpenExpiryInterval sets the OpenExpiryInterval.

func OptShouldOpenProvider

func OptShouldOpenProvider(provider ShouldOpenProvider) Option

OptShouldOpenProvider sets the ShouldCloseProvider provider on the breaker.

type ShouldOpenProvider

type ShouldOpenProvider func(ctx context.Context, counts Counts) bool

ShouldOpenProvider returns if the breaker should open.

type State

type State int

State is a type that represents a state of CircuitBreaker.

const (
	StateClosed State = iota
	StateHalfOpen
	StateOpen
)

These constants are states of CircuitBreaker.

func (State) String

func (s State) String() string

String implements stringer interface.