circuit

Documentation

Overview

Package circuit provides a circuit breaker pattern for resilience. When failures exceed a threshold, the circuit opens and fails fast. After a timeout, the circuit transitions to half-open to test recovery.

Index

• Variables
• func CallWithResult[T any](b *Breaker, fn func() (T, error)) (T, error)
• type Breaker
  • func New(cfg Config) *Breaker
  • func (b *Breaker) Allow() bool
  • func (b *Breaker) Call(fn func() error) error
  • func (b *Breaker) RecordFailure()
  • func (b *Breaker) RecordSuccess()
  • func (b *Breaker) State() State
  • func (b *Breaker) Stats() Stats
• type Config
  • func DefaultConfig() Config
• type Manager
  • func NewManager(cfg Config) *Manager
  • func (m *Manager) Get(name string) *Breaker
  • func (m *Manager) List() map[string]Stats
• type State
  • func (s State) String() string
• type Stats

Variables

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

ErrOpen is returned when the circuit is open.

Functions

func CallWithResult

func CallWithResult[T any](b *Breaker, fn func() (T, error)) (T, error)

CallWithResult executes fn if the circuit allows it.

Types

type Breaker

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

Breaker is a circuit breaker.

func New

func New(cfg Config) *Breaker

New creates a new circuit breaker.

func (*Breaker) Allow

func (b *Breaker) Allow() bool

Allow checks if a call should be allowed.

func (*Breaker) Call

func (b *Breaker) Call(fn func() error) error

Call executes fn if the circuit allows it.

func (*Breaker) RecordFailure

func (b *Breaker) RecordFailure()

RecordFailure records a failed call.

func (*Breaker) RecordSuccess

func (b *Breaker) RecordSuccess()

RecordSuccess records a successful call.

func (*Breaker) State

func (b *Breaker) State() State

State returns the current state.

func (*Breaker) Stats

func (b *Breaker) Stats() Stats

Stats returns current statistics.

type Config

type Config struct {
	MaxFailures      int
	Timeout          time.Duration
	HalfOpenMaxCalls int
}

Config configures a circuit breaker.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults.

type Manager

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

Manager manages multiple named circuit breakers.

func NewManager

func NewManager(cfg Config) *Manager

NewManager creates a new circuit breaker manager.

func (*Manager) Get

func (m *Manager) Get(name string) *Breaker

Get returns a breaker by name, creating it if needed.

func (*Manager) List

func (m *Manager) List() map[string]Stats

List returns all breaker names and their stats.

type State

type State int

State represents the circuit breaker state.

const (
	Closed   State = iota // Normal operation
	Open                  // Failing fast
	HalfOpen              // Testing recovery
)

func (State) String

func (s State) String() string

type Stats

type Stats struct {
	State       string    `json:"state"`
	Failures    int       `json:"failures"`
	LastFailure time.Time `json:"last_failure,omitempty"`
}

Stats returns breaker statistics.