Documentation
¶
Overview ¶
Package breaker implements a circuit breaker.
Circuit breaker watches the error from executed functions and according to the configured TripFn will allow requests for a period of time before slowly allowing a few.
Circuit breakers start in StateStandby first, observing errors and watching Metrics.
Once the Circuit breaker TripFn returns true, it enters the StateTripped, where it blocks all traffic and returns ErrStateTripped for the configured Config.TrippedPeriod.
After the Config.TrippedPeriod passes, Circuit breaker enters StateRecovering, during that state it will either transition to StateStandby after the Config.RecoveryLimit is met or StateTripped if the Config.Recover TripFn is satisfied.
It is possible to define actions on transitions between states:
* Config.OnTripped is called on transition (StateStandby -> StateTripped) * Config.OnStandBy is called on transition (StateRecovering -> StateStandby)
Index ¶
- Variables
- func IsResponseSuccessful(v interface{}, err error) bool
- func NonNilErrorIsSuccess(_ interface{}, err error) bool
- func StreamClientInterceptor(cb *CircuitBreaker) grpc.StreamClientInterceptor
- func UnaryClientInterceptor(cb *CircuitBreaker) grpc.UnaryClientInterceptor
- type CircuitBreaker
- type Config
- type Metrics
- type RoundTripper
- type State
- type TripFn
Constants ¶
This section is empty.
Variables ¶
var ErrStateTripped = &trace.ConnectionProblemError{Message: "breaker is tripped"}
ErrStateTripped will be returned from executions performed while the CircuitBreaker is in StateTripped
Functions ¶
func IsResponseSuccessful ¶
IsResponseSuccessful determines whether the error provided should be ignored by the circuit breaker. This checks for http status codes < 500 and a few unsuccessful gRPC status codes.
func NonNilErrorIsSuccess ¶
NonNilErrorIsSuccess returns true if the provided error is non nil. This is the default value for Config.IsSuccessful if not provided.
func StreamClientInterceptor ¶
func StreamClientInterceptor(cb *CircuitBreaker) grpc.StreamClientInterceptor
StreamClientInterceptor is a stream gRPC client interceptor that uses the provided CircuitBreaker to track errors returned from the outgoing calls.
func UnaryClientInterceptor ¶
func UnaryClientInterceptor(cb *CircuitBreaker) grpc.UnaryClientInterceptor
UnaryClientInterceptor is a unary gRPC client interceptor that uses the provided CircuitBreaker to track errors returned from the outgoing calls.
Types ¶
type CircuitBreaker ¶
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker implements the circuit breaker pattern
func New ¶
func New(cfg Config) (*CircuitBreaker, error)
New returns a CircuitBreaker configured with the provided Config
func NewNoop ¶
func NewNoop() *CircuitBreaker
func (*CircuitBreaker) Execute ¶
func (c *CircuitBreaker) Execute(f func() (interface{}, error)) (interface{}, error)
Execute calls the provided function depending on the CircuitBreaker state.
- StateStandby: all functions are executed.
- StateTripped: no functions are executed and ErrStateTripped is returned.
- StateRecovering: some functions are executed, some functions are not, when not executed ErrLimitExceeded is returned.
The CircuitBreaker state is updated according to the outcome of executing the provided function and the current state. See package docs for a more detailed explanation of state transitions.
type Config ¶
type Config struct {
// Clock is used to control time - mainly used for testing
Clock clockwork.Clock
// Interval is the period of time that execution metrics will be collected for within StateStandby before
// transitioning to the next generation.
Interval time.Duration
// TrippedPeriod is the amount of time to remain in StateTripped before transitioning
// into StateRecovering
TrippedPeriod time.Duration
// Recover specifies the TripFn that will be used to determine if the CircuitBreaker should transition from
// StateRecovering to StateTripped. This is required to be supplied, failure to do so will result in an error
// creating the CircuitBreaker.
Recover TripFn
// RecoveryLimit is the number on consecutive successful executions required to transition from
// StateRecovering to StateStandby
RecoveryLimit uint32
// Trip specifies the TripFn that will be used to determine if the CircuitBreaker should transition from
// StateStandby to StateTripped. This is required to be supplied, failure to do so will result in an error
// creating the CircuitBreaker.
Trip TripFn
// OnTripped will be called when the CircuitBreaker enters the StateTripped
// state; this callback is called while holding a lock, so it should return
// quickly.
OnTripped func()
// OnStandby will be called when the CircuitBreaker returns to the
// StateStandby state; this callback is called while holding a lock, so it
// should return quickly.
OnStandBy func()
// OnExecute will be called once for each execution, and given the result
// and the current state of the breaker state; this callback is called while
// holding a lock, so it should return quickly.
OnExecute func(success bool, state State)
// IsSuccessful is used by the CircuitBreaker to determine if the executed function was successful or not
IsSuccessful func(v interface{}, err error) bool
// TrippedErrorMessage is an optional message to use as the error message when the CircuitBreaker
// is tripped. Defaults to ErrStateTripped if not provided.
TrippedErrorMessage string
}
Config contains configuration of the CircuitBreaker
func DefaultBreakerConfig ¶
func NoopBreakerConfig ¶
func NoopBreakerConfig() Config
func (*Config) CheckAndSetDefaults ¶
CheckAndSetDefaults checks and sets default config values.
type Metrics ¶
type Metrics struct {
// Executions the total number of times the breaker has executed within the interval
Executions uint32
// Successes the number of successful executions
Successes uint32
// Failures the total number of failed executions
Failures uint32
// ConsecutiveSuccesses the number of consecutive successful executions
ConsecutiveSuccesses uint32
// ConsecutiveFailures the number of consecutive failed executions
ConsecutiveFailures uint32
}
Metrics tallies success and failure counts for all executions performed by a CircuitBreaker
type RoundTripper ¶
type RoundTripper struct {
// contains filtered or unexported fields
}
RoundTripper wraps a http.RoundTripper with a CircuitBreaker
func NewRoundTripper ¶
func NewRoundTripper(cb *CircuitBreaker, tripper http.RoundTripper) *RoundTripper
NewRoundTripper returns a RoundTripper
func (*RoundTripper) CloseIdleConnections ¶
func (t *RoundTripper) CloseIdleConnections()
CloseIdleConnections ensures idle connections of the wrapped http.RoundTripper are closed.
func (*RoundTripper) RoundTrip ¶
RoundTrip forwards the request on to the provided http.RoundTripper if the CircuitBreaker allows it
func (*RoundTripper) Unwrap ¶
func (t *RoundTripper) Unwrap() http.RoundTripper
Unwrap returns the inner round tripper.
type State ¶
type State int
State represents an operating state that a CircuitBreaker may be in.
const ( // StateStandby indicates the breaker is passing all requests and watching stats StateStandby State = iota // StateTripped indicates too many errors have occurred and requests are actively being rejected StateTripped // StateRecovering indicates the breaker is allowing some requests to go through and rejecting others StateRecovering )
type TripFn ¶
TripFn determines if the CircuitBreaker should be tripped based on the state of the provided Metrics. A return value of true will cause the CircuitBreaker to transition into the StateTripped state
func ConsecutiveFailureTripper ¶
ConsecutiveFailureTripper is a TripFn that will return true if Metrics.ConsecutiveFailures is greater than the provided value.
func RatioTripper ¶
RatioTripper is a TripFn that returns true it the error ratio is greater than the provided ratio and there have been at least minExecutions performed.
func StaticTripper ¶
StaticTripper is a TripFn that always returns the provided value regardless of the Metrics. Useful for testing.
Source Files