circuitbreaker

Documentation

Overview

Package circuitbreaker implements the Circuit-Breaker pattern.

The transformation of circuitbreaker's state is as follows:

1. Assuming the number of requests reachs the threshold(Config.TriggerThreshold), initial state is CLOSE.
2. After 1, if the error rate or the rate of high latency exceeds the threshold(Config.ErrorRate/HighLatencyRate), the circuitbreaker is OPEN.
3. Otherwise for 2, the circuitbreaker will be CLOSE.
4. After 2, the circuitbreaker remains OPEN until some amount of time(Config.SleepWindow) pass, then it's the HALF-OPEN which let a single request through, if the request fails, it returns to the OPEN. If the request succeeds, the circuitbreaker is CLOSE, and 1 takes over again.

Example

cb := New(DefaultConfig())

func() (err error) {
	c := cb.Circuit() // DO NOT reuse it, create a new one each time.
	if c.IsInterrupted() {
		err = ErrIsOpen
		return // System is not healthy, return immediately.
	}

	defer func() { c.Trace(err != nil) }()
	// err = doSth()
	fmt.Println(err)
	return
}()

func() { // Use Run for "convenience".
	err := cb.Run(func() error {
		time.Sleep(time.Millisecond)
		return fmt.Errorf("is ok")
	})
	fmt.Println(err)
}()

Output:

<nil>
is ok

Index

• Variables
• type Circuit
  • func (c Circuit) IsInterrupted() bool
  • func (c Circuit) Trace(haserr bool)
• type CircuitBreaker
  • func New(conf Config) *CircuitBreaker
  • func (cb *CircuitBreaker) Circuit() Circuit
  • func (cb *CircuitBreaker) Run(fn func() error) (err error)
• type Config
  • func DefaultConfig() Config

Examples

• Package

Variables

var ErrIsOpen = errors.New("circuitbreaker is open: not healthy")

ErrIsOpen means circuitbreaker is open, the system or API is not healthy.

Types

type Circuit

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

Circuit is used for every call.

func (Circuit) IsInterrupted

func (c Circuit) IsInterrupted() bool

IsInterrupted returns true if the circuit is interrupted, the caller should return immediately. Otherwise, returns false.

func (Circuit) Trace

func (c Circuit) Trace(haserr bool)

Trace records the stats, the caller shouldn't record the "tolerable" error. If IsInterrupted returns false, the caller must(use defer) Trace the result, otherwise, the circuitbreaker may be OPEN forever.

type CircuitBreaker

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

CircuitBreaker traces the failures then protects the system.

There is a lock inside, in case of you worry about the performance, use multiple CircuitBreaker for defferent kinds of API(request type),

func New

func New(conf Config) *CircuitBreaker

New creates a new CircuitBreaker. It doesn't check the Config for the caller.

func (*CircuitBreaker) Circuit

func (cb *CircuitBreaker) Circuit() Circuit

Circuit creates a Circuit, each request(API call) requires exactly one Circuit, DO NOT reuse it or ignore it. You can use Run for "convenience".

func (*CircuitBreaker) Run

func (cb *CircuitBreaker) Run(fn func() error) (err error)

Run is a shortcut for the workflow.

type Config

type Config struct {
	// TriggerThreshold is the threshold of total requests to trigger the circuitbreaker,
	// 0 means never trigger.
	TriggerThreshold int
	// CountWindow is the time window to keep stats, any stats before the window will be droped.
	CountWindow time.Duration
	// SleepWindow is the wait time before recovering.
	SleepWindow time.Duration
	// ErrorRate is the error rate to trigger the circuitbreaker.
	ErrorRate float64
	// HighLatencyValue is the max acceptable latency.
	HighLatencyValue time.Duration
	// HighLatencyRate is the rate for HighLatencyValue to trigger the circuitbreaker.
	HighLatencyRate float64
	// CoverPanic will recover the panic, only used in Run.
	CoverPanic bool
}

Config configures the CircuitBreaker.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig creates a default Config, it is just an example.