fastbreaker

README

fastbreaker

fastbreaker implements the Circuit Breaker pattern in Go.

Installation

go get github.com/bluekiri/fastbreaker

Usage

The interface fastbreaker.FastBreaker is a state machine to prevent sending requests that are likely to fail. The function fastbreaker.New creates a new fastbreaker.FastBreaker.

func fastbreaker.New(configuration fastbreaker.Configuration) fastbreaker.FastBreaker

You can configure fastbreaker.FastBreaker by the struct fastbreaker.Configuration:

type Configuration struct {
    NumBuckets      int
    BucketDuration  time.Duration
    DurationOfBreak time.Duration
    ShouldTrip      ShouldTripFunc
}

• NumBuckets is the number of buckets of the rolling window. If NumBuckets is less than 1, the fastbreaker.DefaultNumBuckets is used.

• BucketDuration is the duration (truncated to the second) of every bucket. If BucketDuration is less than 1s, the fastbreaker.DefaultBucketDuration is used.

• DurationOfBreak is the time (truncated to the second) of the open state, after which the state becomes half-open. If DurationOfBreak is less than 1s, the fastbreaker.DefaultDurationOfBreak is used.

• ShouldTrip is called whenever a request fails in the closed state with the number of executions and the number of failures. If ShouldTrip returns true, fastbreaker.FastBreaker state becomes open. If ShouldTrip is nil, fastbreaker.DefaultShouldTrip is used. fastbreaker.DefaultShouldTrip returns true when the number of executions is greater than or equal to 10 and at least half the number of executions have failed.

Example

var cb fastbreaker.FastBreaker

func Get(url string) ([]byte, error) {
	feedback, err := cb.Allow()
	if err != nil {
		return nil, err
	}

	resp, err := http.Get(url)
	if err != nil {
		feedback(false)
		return nil, err
	}

	defer resp.Body.Close()
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		feedback(false)
		return nil, err
	}

	feedback(true)
	return body, nil
}

License

The MIT License (MIT)

See LICENSE for details.

Documentation

Index

• Constants
• Variables
• func DefaultShouldTrip(executions uint64, failures uint64) bool
• type Configuration
• type FastBreaker
  • func New(configuration Configuration) FastBreaker
• type ShouldTripFunc
• type State
  • func (state State) String() string

Constants

const (
	// DefaultNumBuckets is the default number of buckets of a circuit breaker. Value = 10.
	DefaultNumBuckets = 10
	// DefaultBucketDuration is the default duration of a bucket. Value = 1s.
	DefaultBucketDuration = 1 * time.Second
	// DefaultDurationOfBreak is the default duration of a circuit breaker break. Value = 5s
	DefaultDurationOfBreak = 5 * time.Second
)

Variables

var ErrCircuitOpen = errors.New("circuit breaker is open")

ErrCircuitOpen is the error returned by FastCircuitBreaker.Allow() when the circuit is open.

var ErrCircuitStopped = errors.New("circuit breaker is stopped")

ErrCircuitStopped is the error returned by FastCircuitBreaker.Allow() when the circuit is stopped.

Functions

func DefaultShouldTrip

func DefaultShouldTrip(executions uint64, failures uint64) bool

DefaultShouldTrip is the default implementation of the ShouldTrip function. If will trip the circuit when there has been at least 20 executions and at least 50% of the executions failed.

Types

type Configuration

type Configuration struct {
	NumBuckets      int
	BucketDuration  time.Duration
	DurationOfBreak time.Duration
	ShouldTrip      ShouldTripFunc
}

Configuration is a struct used to configure a circuit breaker.

type FastBreaker

type FastBreaker interface {
	// Configuration returns the actual configuration used to create the circuit breaker.
	Configuration() Configuration

	// Stop releases the circuit breaker resources.
	Stop()

	// Allow checks if the circuit breaker should allow the execution to proceed.
	// Returns a function to report if the execution was successful when the execution is allowed or an
	// error when it is not.
	Allow() (func(bool), error)

	// State returns the current State of the circuit breaker.
	State() State

	// Executions returns the number of executions the circuit breaker has allowed.
	Executions() uint64

	// Failures returns the number of executions reported as failed.
	Failures() uint64

	// Rejected returns the number of executions the circuit breaker has rejected.
	Rejected() uint64

	// RollingCounters returns the rolling executions and failures.
	RollingCounters() (uint64, uint64)
}

FastBreaker is the interface implemented by the circuit breakers.

func New

func New(configuration Configuration) FastBreaker

New creates a new CircuitBreaker with the passed Configuration.

type ShouldTripFunc

type ShouldTripFunc func(executions uint64, failures uint64) bool

A ShouldTripFunc tells the circuit breaker to trip when it returns true. If it returns false, the circuit breaker will remain closed.

type State

type State uint32

State represents the state of a circuit breaker.

const (
	// StateStopped is the circuit breaker state when it is stopped.
	StateStopped State = iota
	// StateClosed is the circuit breaker state when it is allowing executions.
	StateClosed
	// StateHalfOpen is the circuit breaker state when it tests if it should remain open
	// or reset to the closed state.
	StateHalfOpen
	// StateOpen is the circuit breaker state when it is rejecting executions.
	StateOpen
)

func (State) String

func (state State) String() string