breaker

Documentation

Overview

Package breaker provides circuit breaker implementations for gofly services, including simple threshold-based and adaptive breakers.

Package breaker provides circuit breaker implementations for gofly services, including a standard state-machine breaker and a Google SRE adaptive throttle.

Index

• Variables
• type AdaptiveBreaker
  • func NewAdaptive(opts ...AdaptiveOption) *AdaptiveBreaker
  • func (b *AdaptiveBreaker) Allow() error
  • func (b *AdaptiveBreaker) Do(ctx context.Context, fn func() error) error
  • func (b *AdaptiveBreaker) MarkFailure()
  • func (b *AdaptiveBreaker) MarkSuccess()
  • func (b *AdaptiveBreaker) Snapshot() AdaptiveSnapshot
  • func (b *AdaptiveBreaker) State() State
• type AdaptiveOption
  • func WithAdaptiveBuckets(n int) AdaptiveOption
  • func WithAdaptiveFailureRatio(ratio float64) AdaptiveOption
  • func WithAdaptiveK(k float64) AdaptiveOption
  • func WithAdaptiveMinRequests(n int64) AdaptiveOption
  • func WithAdaptiveOpenTimeout(d time.Duration) AdaptiveOption
  • func WithAdaptiveWindow(d time.Duration) AdaptiveOption
• type AdaptiveSnapshot
• type Breaker
  • func New(opts ...Option) *Breaker
  • func (b *Breaker) Allow() error
  • func (b *Breaker) Do(ctx context.Context, fn func() error) error
  • func (b *Breaker) Snapshot() BreakerSnapshot
  • func (b *Breaker) State() State
• type BreakerSnapshot
• type GoogleBreaker
  • func NewGoogle(opts ...GoogleOption) *GoogleBreaker
  • func (b *GoogleBreaker) Allow() error
  • func (b *GoogleBreaker) Do(ctx context.Context, fn func() error) error
  • func (b *GoogleBreaker) MarkFailure()
  • func (b *GoogleBreaker) MarkSuccess()
  • func (b *GoogleBreaker) RejectProbability() float64
• type GoogleOption
  • func WithGoogleBuckets(n int) GoogleOption
  • func WithGoogleK(k float64) GoogleOption
  • func WithGoogleWindow(d time.Duration) GoogleOption
• type Option
  • func WithFailureThreshold(n int) Option
  • func WithOpenTimeout(d time.Duration) Option
• type State
  • func (s State) String() string

Variables

var ErrOpen = errors.New("breaker is open")

ErrOpen is returned when the circuit breaker is open.

Types

type AdaptiveBreaker

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

func NewAdaptive

func NewAdaptive(opts ...AdaptiveOption) *AdaptiveBreaker

func (*AdaptiveBreaker) Allow

func (b *AdaptiveBreaker) Allow() error

func (*AdaptiveBreaker) Do

func (b *AdaptiveBreaker) Do(ctx context.Context, fn func() error) error

func (*AdaptiveBreaker) MarkFailure

func (b *AdaptiveBreaker) MarkFailure()

func (*AdaptiveBreaker) MarkSuccess

func (b *AdaptiveBreaker) MarkSuccess()

func (*AdaptiveBreaker) Snapshot

func (b *AdaptiveBreaker) Snapshot() AdaptiveSnapshot

func (*AdaptiveBreaker) State

func (b *AdaptiveBreaker) State() State

type AdaptiveOption

type AdaptiveOption func(*AdaptiveBreaker)

func WithAdaptiveBuckets

func WithAdaptiveBuckets(n int) AdaptiveOption

func WithAdaptiveFailureRatio

func WithAdaptiveFailureRatio(ratio float64) AdaptiveOption

func WithAdaptiveK

func WithAdaptiveK(k float64) AdaptiveOption

func WithAdaptiveMinRequests

func WithAdaptiveMinRequests(n int64) AdaptiveOption

func WithAdaptiveOpenTimeout

func WithAdaptiveOpenTimeout(d time.Duration) AdaptiveOption

func WithAdaptiveWindow

func WithAdaptiveWindow(d time.Duration) AdaptiveOption

type AdaptiveSnapshot

type AdaptiveSnapshot struct {
	State        string        `json:"state"`
	OpenTimeout  time.Duration `json:"openTimeout"`
	OpenedAt     time.Time     `json:"openedAt,omitempty"`
	Window       time.Duration `json:"window"`
	BucketSize   time.Duration `json:"bucketSize"`
	Buckets      int           `json:"buckets"`
	MinRequests  int64         `json:"minRequests"`
	FailureRatio float64       `json:"failureRatio"`
	K            float64       `json:"k"`
	Requests     int64         `json:"requests"`
	Success      int64         `json:"success"`
	Failures     int64         `json:"failures"`
	ErrorRatio   float64       `json:"errorRatio"`
}

type Breaker

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

Breaker is a simple threshold-based circuit breaker.

func New

func New(opts ...Option) *Breaker

New creates a Breaker with the given options.

func (*Breaker) Allow

func (b *Breaker) Allow() error

func (*Breaker) Do

func (b *Breaker) Do(ctx context.Context, fn func() error) error

func (*Breaker) Snapshot

func (b *Breaker) Snapshot() BreakerSnapshot

func (*Breaker) State

func (b *Breaker) State() State

type BreakerSnapshot

type BreakerSnapshot struct {
	State            string        `json:"state"`
	Failures         int           `json:"failures"`
	FailureThreshold int           `json:"failureThreshold"`
	OpenTimeout      time.Duration `json:"openTimeout"`
	OpenedAt         time.Time     `json:"openedAt,omitempty"`
}

type GoogleBreaker

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

GoogleBreaker implements the client-side adaptive throttling algorithm from the Google SRE book ("Handling Overload"). Instead of a hard open/closed switch it probabilistically rejects requests based on the ratio of recent requests to accepted responses:

rejectProbability = max(0, (requests - K*accepts) / (requests + 1))

As the backend recovers and accepts climb, the probability decays smoothly back to zero, avoiding the thundering-herd retry storms a binary breaker can cause when it flips back to closed.

func NewGoogle

func NewGoogle(opts ...GoogleOption) *GoogleBreaker

NewGoogle creates a Google SRE adaptive breaker.

func (*GoogleBreaker) Allow

func (b *GoogleBreaker) Allow() error

Allow reports whether a request should be admitted. It returns ErrOpen when the request is probabilistically rejected. A rejected request is still counted so that sustained overload keeps the rejection probability high.

func (*GoogleBreaker) Do

func (b *GoogleBreaker) Do(ctx context.Context, fn func() error) error

Do admits the call through Allow, executes fn, and records the outcome.

func (*GoogleBreaker) MarkFailure

func (b *GoogleBreaker) MarkFailure()

MarkFailure records a rejected response (no accept increment).

func (*GoogleBreaker) MarkSuccess

func (b *GoogleBreaker) MarkSuccess()

MarkSuccess records an accepted response.

func (*GoogleBreaker) RejectProbability

func (b *GoogleBreaker) RejectProbability() float64

RejectProbability returns the current drop probability in [0,1).

type GoogleOption

type GoogleOption func(*GoogleBreaker)

GoogleOption configures a GoogleBreaker.

func WithGoogleBuckets

func WithGoogleBuckets(n int) GoogleOption

WithGoogleBuckets sets the number of sub-buckets the window is divided into.

func WithGoogleK

func WithGoogleK(k float64) GoogleOption

WithGoogleK sets the aggressiveness multiplier K. Larger K accepts more requests (less aggressive throttling); the SRE book default is 2.0.

func WithGoogleWindow

func WithGoogleWindow(d time.Duration) GoogleOption

WithGoogleWindow sets the rolling statistics window.

type Option

type Option func(*Breaker)

Option configures a Breaker.

func WithFailureThreshold

func WithFailureThreshold(n int) Option

WithFailureThreshold sets the number of consecutive failures before opening.

func WithOpenTimeout

func WithOpenTimeout(d time.Duration) Option

WithOpenTimeout sets the duration before attempting to half-open.

type State

type State int

State represents the circuit breaker state.

const (
	Closed State = iota
	Open
	HalfOpen
)

func (State) String

func (s State) String() string