gobreaker

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[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 Counts struct {
	Requests             uint32
	TotalSuccesses       uint32
	TotalFailures        uint32
	TotalExclusions      uint32
	ConsecutiveSuccesses uint32
	ConsecutiveFailures  uint32
}

Counts holds the numbers of requests and their successes/failures/exclusions. 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 ¶ added in v2.1.0

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

DistributedCircuitBreaker extends CircuitBreaker with SharedDataStore.

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 Settings ¶

type Settings struct {
	Name          string
	MaxRequests   uint32
	Interval      time.Duration
	BucketPeriod  time.Duration
	Timeout       time.Duration
	ReadyToTrip   func(counts Counts) bool
	OnStateChange func(name string, from State, to State)
	IsSuccessful  func(err error) bool
	IsExcluded    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 does not clear internal Counts during the closed state.

BucketPeriod defines the time duration for each bucket in the rolling window strategy. The internal Counts will be updated and reset gradually for each bucket. Interval will be automatically adjusted to be a multiple of BucketPeriod. If BucketPeriod is less than or equal to 0, the CircuitBreaker will use a fixed window strategy instead.

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.

IsExcluded determines whether a request error should be ignored for the purposes of updating the circuit breaker metrics. If IsExcluded returns true for a given error, the request is neither counted as a success nor as a failure. This can be used, for example, to ignore context cancellations or other errors that should not affect the circuit breaker state. If IsExcluded is nil, no requests are excluded.

type SharedDataStore ¶ added in v2.1.0

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 ¶ added in v2.1.0

type SharedState struct {
	State      State     `json:"state"`
	Generation uint64    `json:"generation"`
	Age        uint64    `json:"age"`
	Counts     Counts    `json:"counts"`
	Buckets    []Counts  `json:"buckets"`
	Start      time.Time `json:"start"`
	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
)

func (s State) String() string

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[T any](st Settings) *TwoStepCircuitBreaker[T]

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

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

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

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