goBreaker

README

goBreaker

goBreaker is a simple circuitBreaker, you can use it directly, or you can read and reform it .

easy to start:

go get github.com/JeffreyDing11223/goBreaker

easy to use:

  var cmds = []int32{1, 2, 289, 55}
	var options = goBreaker.Options{
		BucketTime:        150 * time.Millisecond,
		BucketNums:        200,
		BreakerRate:       0.6,
		BreakerMinSamples: 300,
		CoolingTimeout:    3 * time.Second,
		DetectTimeout:     150 * time.Millisecond,
		HalfOpenSuccess:   3,
	}
	cb := goBreaker.InitCircuitBreakers(cmds, options)
	
  ...
  
	if cb.IsTriggerBreaker(289){
		// downStream service is broken
	}
  

Documentation

Index

• Constants
• Variables
• type Breaker
  • func NewBreaker(options Options) (*Breaker, error)
  • func (b *Breaker) Fail()
  • func (b *Breaker) FailWithTrip(trip TripFunc)
  • func (b *Breaker) IsAllowed() bool
  • func (b *Breaker) Reset()
  • func (b *Breaker) State() State
  • func (b *Breaker) Succeed()
  • func (b *Breaker) Timeout()
  • func (b *Breaker) TimeoutWithTrip(trip TripFunc)
• type CircuitBreaker
  • func InitCircuitBreakers(cmds []int32, options Options) (cb CircuitBreaker)
  • func (b *CircuitBreaker) AdjustBreakers(count int, options Options)
  • func (b *CircuitBreaker) GenBreaker(cmd int32, options Options) *Breaker
  • func (b *CircuitBreaker) GetAllBreakers() map[int32]*Breaker
  • func (b *CircuitBreaker) GetBreaker(cmd int32) *Breaker
  • func (b *CircuitBreaker) IsTriggerBreaker(cmd int32) bool
• type Container
  • func NewWindowWithOptions(bucketTime time.Duration, bucketNums int) (Container, error)
• type Options
• type State
  • func (s State) String() string
• type StateChangeHandler
• type TripFunc
  • func ConsecutiveTripFunc(threshold int64) TripFunc
  • func RateTripFunc(rate float64, minSamples int64) TripFunc
  • func ThresholdTripFunc(threshold int64) TripFunc

Constants

const (
	// COOLING_TIMEOUT is the time the breaker stay in OPEN before becoming HALFOPEN
	DEFAULT_COOLING_TIMEOUT = time.Second * 5

	// DETECT_TIMEOUT is the time interval between every detect in HALFOPEN
	DEFAULT_DETECT_TIMEOUT = time.Millisecond * 200

	// HALFOPEN_SUCCESSES is the threshold when the breaker is in HALFOPEN;
	// after secceeding consecutively this times, it will change its state from HALFOPEN to CLOSED;
	DEFAULT_HALFOPEN_SUCCESSES = 2

	// RateTrip Rate
	DEFAULT_BREAKER_RATE = 0.5

	// MinSamples for RateTrip (single instance)
	DEFAULT_BREAKER_MINSAMPLES = 200
)

const (
	// bucket time is the time each bucket holds
	DEFAULT_BUCKET_TIME = time.Millisecond * 100

	// bucket nums is the number of buckets the container has;
	DEFAULT_BUCKET_NUMS = 100
)

const (
	// MinQps determines the MinSamples when using AdjustBreakers func
	DEFAULT_BREAKER_MINQPS = 200
)

Variables

var BreakerWhitelist = map[int32]bool{}

Types

type Breaker

type Breaker struct {
	Container // contains all success, error and timeout
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewBreaker

func NewBreaker(options Options) (*Breaker, error)

NewBreaker creates a base breaker with a specified options

func (*Breaker) Fail

func (b *Breaker) Fail()

func (*Breaker) FailWithTrip

func (b *Breaker) FailWithTrip(trip TripFunc)

func (*Breaker) IsAllowed

func (b *Breaker) IsAllowed() bool

func (*Breaker) Reset

func (b *Breaker) Reset()

resets this breaker

func (*Breaker) State

func (b *Breaker) State() State

returns the breaker's state now

func (*Breaker) Succeed

func (b *Breaker) Succeed()

Succeed records a success and decreases the concurrency counter by one

func (*Breaker) Timeout

func (b *Breaker) Timeout()

func (*Breaker) TimeoutWithTrip

func (b *Breaker) TimeoutWithTrip(trip TripFunc)

type CircuitBreaker

type CircuitBreaker struct {
	Breakers map[int32]*Breaker
	Mutex    sync.RWMutex
}

func InitCircuitBreakers

func InitCircuitBreakers(cmds []int32, options Options) (cb CircuitBreaker)

func (*CircuitBreaker) AdjustBreakers

func (b *CircuitBreaker) AdjustBreakers(count int, options Options)

when instances >1, you can use AdjustBreakers count means how many instances you have

func (*CircuitBreaker) GenBreaker

func (b *CircuitBreaker) GenBreaker(cmd int32, options Options) *Breaker

func (*CircuitBreaker) GetAllBreakers

func (b *CircuitBreaker) GetAllBreakers() map[int32]*Breaker

func (*CircuitBreaker) GetBreaker

func (b *CircuitBreaker) GetBreaker(cmd int32) *Breaker

func (*CircuitBreaker) IsTriggerBreaker

func (b *CircuitBreaker) IsTriggerBreaker(cmd int32) bool

type Container

type Container interface {
	Fail()    // records a failure
	Succeed() // records a success
	Timeout() // records a timeout

	Failures() int64          // return the number of failures
	Successes() int64         // return the number of successes
	Timeouts() int64          // return the number of timeouts
	ConsecutiveErrors() int64 // return the consecutive errors recently
	ErrorRate() float64       // rate = (timeouts + failures) / (timeouts + failures + successes)
	Samples() int64           // (timeouts + failures + successes)
	Counts() (successes, failures, timeouts int64)

	Reset()
}

Container contains errors, timeouts and successes

func NewWindowWithOptions

func NewWindowWithOptions(bucketTime time.Duration, bucketNums int) (Container, error)

NewWindowWithOptions creates a new window

type Options

type Options struct {
	// parameters for container
	BucketTime time.Duration // the time each bucket holds
	BucketNums int           // the number of buckets the breaker have

	// parameters for breaker
	BreakerRate        float64
	BreakerMinQPS      int           // when instance > 1, if qps is over this value, the breaker trip will work
	BreakerMinSamples  int           // for RateTrip callback
	CoolingTimeout     time.Duration // fixed when create
	DetectTimeout      time.Duration // fixed when create
	HalfOpenSuccess    int
	ShouldTrip         TripFunc // trip callback, default is RateTrip func
	StateChangeHandler StateChangeHandler
	// contains filtered or unexported fields
}

Options for Breaker

type State

type State int

const (
	OPEN State = iota
	HALFOPEN
	CLOSED
)

func (State) String

func (s State) String() string

type StateChangeHandler

type StateChangeHandler func(oldState, newState State, m Container)

StateChangeHandler

type TripFunc

type TripFunc func(Container) bool

TripFunc is a function called by a Breaker when error appears and determines whether the breaker should trip

func ConsecutiveTripFunc

func ConsecutiveTripFunc(threshold int64) TripFunc

ConsecutiveTripFunc

func RateTripFunc

func RateTripFunc(rate float64, minSamples int64) TripFunc

RateTripFunc

func ThresholdTripFunc

func ThresholdTripFunc(threshold int64) TripFunc

ThresholdTripFunc