gobreaker

Documentation

Overview

Package gobreaker implements the Circuit Breaker pattern. See https://msdn.microsoft.com/en-us/library/dn589784.aspx.

Index

• Variables
• type CircuitBreaker
  • func NewCircuitBreaker[T any](st Settings) *CircuitBreaker[T]
  • func (cb *CircuitBreaker[T]) Counts() Counts
  • func (cb *CircuitBreaker[T]) Execute(req func() (T, error)) (T, error)
  • func (cb *CircuitBreaker[T]) Name() string
  • func (cb *CircuitBreaker[T]) State() State
• type Counts
• type DistributedCircuitBreaker
  • func NewDistributedCircuitBreaker[T any](store SharedDataStore, settings Settings) (dcb *DistributedCircuitBreaker[T], err error)
  • func (dcb *DistributedCircuitBreaker[T]) Execute(req func() (T, error)) (t T, err error)
  • func (dcb *DistributedCircuitBreaker[T]) State() (state State, err error)
• type RedisStore
  • func NewRedisStore(addr string) *RedisStore
  • func (rs *RedisStore) Close()
  • func (rs *RedisStore) GetData(name string) ([]byte, error)
  • func (rs *RedisStore) Lock(name string) error
  • func (rs *RedisStore) SetData(name string, data []byte) error
  • func (rs *RedisStore) Unlock(name string) error
• type Settings
• type SharedDataStore
• type SharedState
• type State
  • func (s State) String() string
• type TwoStepCircuitBreaker
  • func NewTwoStepCircuitBreaker[T any](st Settings) *TwoStepCircuitBreaker[T]
  • func (tscb *TwoStepCircuitBreaker[T]) Allow() (done func(success bool), err error)
  • func (tscb *TwoStepCircuitBreaker[T]) Counts() Counts
  • func (tscb *TwoStepCircuitBreaker[T]) Name() string
  • func (tscb *TwoStepCircuitBreaker[T]) State() State

Variables

var (
	// ErrNoSharedStore is returned when there is no shared store.
	ErrNoSharedStore = errors.New("no shared store")
	// ErrNoSharedState is returned when there is no shared state.
	ErrNoSharedState = errors.New("no shared state")
)

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

Types

type CircuitBreaker

type CircuitBreaker[T any] struct {
	// contains filtered or unexported fields
}

CircuitBreaker is a state machine to prevent sending requests that are likely to fail.

func NewCircuitBreaker

func NewCircuitBreaker[T any](st Settings) *CircuitBreaker[T]

NewCircuitBreaker returns a new CircuitBreaker configured with the given Settings.

func (*CircuitBreaker[T]) Counts

func (cb *CircuitBreaker[T]) Counts() Counts

Counts returns internal counters

func (*CircuitBreaker[T]) Execute

func (cb *CircuitBreaker[T]) Execute(req func() (T, error)) (T, error)

Execute runs the given request if the CircuitBreaker accepts it. Execute returns an error instantly if the CircuitBreaker rejects the request. Otherwise, Execute returns the result of the request. If a panic occurs in the request, the CircuitBreaker handles it as an error and causes the same panic again.

func (*CircuitBreaker[T]) Name

func (cb *CircuitBreaker[T]) Name() string

Name returns the name of the CircuitBreaker.

func (*CircuitBreaker[T]) State

func (cb *CircuitBreaker[T]) State() State

State returns the current state of the CircuitBreaker.

type Counts

type Counts struct {
	Requests             uint32
	TotalSuccesses       uint32
	TotalFailures        uint32
	ConsecutiveSuccesses uint32
	ConsecutiveFailures  uint32
}

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 DistributedCircuitBreaker

type DistributedCircuitBreaker[T any] struct {
	*CircuitBreaker[T]
	// contains filtered or unexported fields
}

DistributedCircuitBreaker extends CircuitBreaker with SharedDataStore.

func NewDistributedCircuitBreaker

func NewDistributedCircuitBreaker[T any](store SharedDataStore, settings Settings) (dcb *DistributedCircuitBreaker[T], err error)

NewDistributedCircuitBreaker returns a new DistributedCircuitBreaker.

func (*DistributedCircuitBreaker[T]) Execute

func (dcb *DistributedCircuitBreaker[T]) Execute(req func() (T, error)) (t T, err error)

Execute runs the given request if the DistributedCircuitBreaker accepts it.

func (*DistributedCircuitBreaker[T]) State

func (dcb *DistributedCircuitBreaker[T]) State() (state State, err error)

State returns the State of DistributedCircuitBreaker.

type RedisStore

type RedisStore struct {
	// contains filtered or unexported fields
}

func NewRedisStore

func NewRedisStore(addr string) *RedisStore

func (*RedisStore) Close

func (rs *RedisStore) Close()

func (*RedisStore) GetData

func (rs *RedisStore) GetData(name string) ([]byte, error)

func (*RedisStore) Lock

func (rs *RedisStore) Lock(name string) error

func (*RedisStore) SetData

func (rs *RedisStore) SetData(name string, data []byte) error

func (*RedisStore) Unlock

func (rs *RedisStore) Unlock(name string) error

type Settings

type Settings struct {
	Name          string
	MaxRequests   uint32
	Interval      time.Duration
	Timeout       time.Duration
	ReadyToTrip   func(counts Counts) bool
	OnStateChange func(name string, from State, to State)
	IsSuccessful  func(err error) bool
}

Settings configures CircuitBreaker:

Name is the name of the CircuitBreaker.

MaxRequests is the maximum number of requests allowed to pass through when the CircuitBreaker is half-open. If MaxRequests is 0, the CircuitBreaker allows only 1 request.

Interval is the cyclic period of the closed state for the CircuitBreaker to clear the internal Counts. If Interval is less than or equal to 0, the CircuitBreaker doesn't clear internal Counts during the closed state.

Timeout is the period of the open state, after which the state of the CircuitBreaker becomes half-open. If Timeout is less than or equal to 0, the timeout value of the CircuitBreaker is set to 60 seconds.

ReadyToTrip is called with a copy of Counts whenever a request fails in the closed state. If ReadyToTrip returns true, the CircuitBreaker will be placed into the open state. If ReadyToTrip is nil, default ReadyToTrip is used. Default ReadyToTrip returns true when the number of consecutive failures is more than 5.

OnStateChange is called whenever the state of the CircuitBreaker changes.

IsSuccessful is called with the error returned from a request. If IsSuccessful returns true, the error is counted as a success. Otherwise the error is counted as a failure. If IsSuccessful is nil, default IsSuccessful is used, which returns false for all non-nil errors.

type SharedDataStore

type SharedDataStore interface {
	Lock(name string) error
	Unlock(name string) error
	GetData(name string) ([]byte, error)
	SetData(name string, data []byte) error
}

SharedDataStore stores the shared state of DistributedCircuitBreaker.

type SharedState

type SharedState struct {
	State      State     `json:"state"`
	Generation uint64    `json:"generation"`
	Counts     Counts    `json:"counts"`
	Expiry     time.Time `json:"expiry"`
}

SharedState represents the shared state of DistributedCircuitBreaker.

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.

type TwoStepCircuitBreaker

type TwoStepCircuitBreaker[T any] struct {
	// contains filtered or unexported fields
}

TwoStepCircuitBreaker is like CircuitBreaker but instead of surrounding a function with the breaker functionality, it only checks whether a request can proceed and expects the caller to report the outcome in a separate step using a callback.

func NewTwoStepCircuitBreaker

func NewTwoStepCircuitBreaker[T any](st Settings) *TwoStepCircuitBreaker[T]

NewTwoStepCircuitBreaker returns a new TwoStepCircuitBreaker configured with the given Settings.

func (*TwoStepCircuitBreaker[T]) Allow

func (tscb *TwoStepCircuitBreaker[T]) Allow() (done func(success bool), err error)

Allow checks if a new request can proceed. It returns a callback that should be used to register the success or failure in a separate step. If the circuit breaker doesn't allow requests, it returns an error.

func (*TwoStepCircuitBreaker[T]) Counts

func (tscb *TwoStepCircuitBreaker[T]) Counts() Counts

Counts returns internal counters

func (*TwoStepCircuitBreaker[T]) Name

func (tscb *TwoStepCircuitBreaker[T]) Name() string

Name returns the name of the TwoStepCircuitBreaker.

func (*TwoStepCircuitBreaker[T]) State

func (tscb *TwoStepCircuitBreaker[T]) State() State

State returns the current state of the TwoStepCircuitBreaker.