breaker

Documentation

Overview

Package breaker implements a per-provider circuit breaker so a single failing upstream never gets hammered with retries and never blocks requests from reaching healthy providers.

Index

• type Config
• type Registry
  • func NewRegistry() *Registry
  • func NewRegistryWithConfig(cfg Config) *Registry
  • func (r *Registry) Allow(id string) bool
  • func (r *Registry) IsHalfOpen(id string) bool
  • func (r *Registry) IsOpen(id string) bool
  • func (r *Registry) ReportFailure(id string)
  • func (r *Registry) ReportSuccess(id string)

Types

type Config

type Config struct {
	// FailureThreshold is consecutive failures before a provider trips open.
	FailureThreshold int
	// Cooldown is how long a provider stays open before a half-open trial.
	Cooldown time.Duration
}

Config tunes a Registry's breaker behavior. Zero values fall back to the defaults, so NewRegistryWithConfig(Config{}) == NewRegistry(). Fed from config.Tunables so slow local hardware can loosen the thresholds without a recompile.

type Registry

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

Registry tracks circuit breaker state for every known provider ID.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty breaker registry with the default thresholds; providers register lazily on first use.

func NewRegistryWithConfig

func NewRegistryWithConfig(cfg Config) *Registry

NewRegistryWithConfig is NewRegistry with tunable thresholds; a zero field in cfg falls back to that field's default.

func (*Registry) Allow

func (r *Registry) Allow(id string) bool

Allow reports whether a request may currently be attempted against the given provider. A provider in "open" state is allowed exactly once per cooldown window (the half-open trial) — and, once that trial is admitted, no further request is allowed until the trial's outcome is reported (or the trial timeout, which equals cooldown, elapses without one), so concurrent callers can never all pile onto an upstream that's still recovering.

func (*Registry) IsHalfOpen

func (r *Registry) IsHalfOpen(id string) bool

IsHalfOpen reports whether a provider is currently in its half-open trial window — allowed through by Allow(), but not yet proven healthy again. Scoring strategies use this to treat a half-open candidate more cautiously than a fully closed one, without excluding it outright.

func (*Registry) IsOpen

func (r *Registry) IsOpen(id string) bool

IsOpen reports whether a provider is currently tripped (for status/telemetry).

func (*Registry) ReportFailure

func (r *Registry) ReportFailure(id string)

ReportFailure records a failed attempt, tripping the breaker open once the consecutive-failure threshold is reached (or immediately, if the failing attempt was itself a half-open trial).

func (*Registry) ReportSuccess

func (r *Registry) ReportSuccess(id string)

ReportSuccess resets a provider back to a healthy, closed state.