circuit

README

circuit

Go package providing an implementation of the circuit-breaker pattern as described by Martin Fowler

Overview

The circuit breaker can be in one of three states: closed (requests will be executed normally), open (requests will be rejected immediately) or half-open (a single request will be used to determine whether to move to the open or closed states)

During normal operation the breaker is in the closed state. When a request fails a counter is incremented. A successful request will reset the counter. When the failure counter reaches a threshold, indicating a consecutive series of failures, the breaker will trip and move to the open state.

In the open state all requests will fail immediately, returning the ErrCircuitOpen error.

A timer is started and after the reset timeout, the breaker will move into the half-open state. In the half-open state the first call is used to trial the system. During this trial all other requests will fail as though the breaker were in the open state. If the trialing request succeeds the breaker is moved to the closed (normal) state. Otherwise the breaker moves back to the open state and the reset timer is restarted.

In the closed and half-open states, a count of the number of concurrent requests is maintained. This number rises above the configured maximum then the breaker will trip into the open state.

This implementation has run in a high volume production real time bidding environment for over a year and has no currently known bugs.

Installation

Simply run

go get -u github.com/iand/circuit

Documentation is at https://pkg.go.dev/github.com/iand/circuit

Author

• Ian Davis - http://iandavis.com/

Note that this package was initially developed for Avocet and is released here with their permission.

License

This is free and unencumbered software released into the public domain. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

Documentation

Overview

Package circuit provides an implementation of the circuit-breaker pattern which can be used to improve stability in distributed systems.

Index

• Variables
• type Breaker
  • func (b *Breaker) Do(ctx context.Context, fn func() error) error
  • func (b *Breaker) Inflight() uint32
  • func (b *Breaker) IsClosed() bool
  • func (b *Breaker) IsHalfOpen() bool
  • func (b *Breaker) IsOpen() bool
• type OpenReason

Variables

var (
	// ErrCircuitOpen is returned when a request is made while the circuit is open
	ErrCircuitOpen = errors.New("circuit is open")

	// ErrTooManyConcurrent is returned when a request would exceed the concurrency level of the breaker.
	ErrTooManyConcurrent = errors.New("too many concurrent requests")
)

Types

type Breaker

type Breaker struct {
	// Threshold controls the number of consecutive errors that are allowed before the
	// circuit breaker trips open. If zero a default of 20 will be assumed.
	Threshold uint32

	// Concurrency controls the number of concurrent requests that are allowed before
	// the circuit breaker trips open.  If zero a default of 10 will be assumed.
	Concurrency uint32

	// Reset timeout is the time to wait once the circuit breaker trips open until it
	// should be put into the half-open state.  If zero a default of 10 seconds will be assumed.
	ResetTimeout time.Duration

	// OnOpen is a function that will be called when the circuit breaker trips open. If it
	// is nil then it will be ignored.
	OnOpen func(OpenReason)

	// OnClose is a function that will be called when the circuit breaker closes. If it
	// is nil then it will be ignored.
	OnClose func()

	// OnReset is a function that will be called just before the circuit breaker enters the
	// half-open state. This will be before any trial calls are made. If it is nil then it
	// will be ignored.
	OnReset func()
	// contains filtered or unexported fields
}

Breaker is a circuit breaker. The circuit breaker can be in one of three states: closed (requests will be executed normally), open (requests will be rejected immediately) or half-open (a single request will be used to determine whether to move to the open or closed states) During normal operation the breaker is in the closed state. When a request fails a counter is incremented. A successful request will reset the counter. When the failure counter reaches a threshold, indicating a consecutive series of failures, the breaker will trip and move to the open state. In the open state all requests will fail immediately, returning the ErrCircuitOpen error. A timer is started and after the reset timeout, the breaker will move into the half-open state. In the half-open state the first call is used to trial the system. During this trial all other requests will fail as though the breaker were in the open state. If the trialing request succeeds the breaker is moved to the closed (normal) state. Otherwise the breaker moves back to the open state and the reset timer is restarted. In the closed and half-open states, a count of the number of concurrent requests is maintained. This number rises above the configured maximum then the breaker will trip into the open state.

func (*Breaker) Do

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

Do attempts to execute the supplied function. If the function is executed any error it produces is treated as a failure, incrementing the breaker's counter. The error, if any, is returned from Do. If there are too many concurrent requests then fn will not be executed and ErrTooManyConcurrent will be returned. When the breaker is in the open state then fn will not be executed and ErrCircuitOpen error will be returned.

func (*Breaker) Inflight

func (b *Breaker) Inflight() uint32

Inflight returns the number of requests currently in flight

func (*Breaker) IsClosed

func (b *Breaker) IsClosed() bool

IsClosed reports whether the circuit breaker is in the closed state

func (*Breaker) IsHalfOpen

func (b *Breaker) IsHalfOpen() bool

IsHalfOpen reports whether the circuit breaker is in the half-open state

func (*Breaker) IsOpen

func (b *Breaker) IsOpen() bool

IsOpen reports whether the circuit breaker is in the open state

type OpenReason

type OpenReason int

An OpenReason indicates why the circuit breaker opened.

const (
	// OpenReasonThreshold means the circuit opened because the failure threshold was reached
	OpenReasonThreshold OpenReason = 0 //

	// OpenReasonConcurrency means the circuit opened because the concurrency limit was reached
	OpenReasonConcurrency OpenReason = 1

	// OpenReasonTrial means the circuit opened because the trial request failed
	OpenReasonTrial OpenReason = 2
)