Documentation
¶
Overview ¶
Package resilience provides failure-class-aware circuit breaking (design §5, ADR-0005).
Transport/connection failures are server-health signals and trip a breaker scoped to the downstream target. Individual tool-call timeouts are tool-specific: they are tracked per (downstream, tool) and never sink the target breaker, so a slow tool cannot down its siblings. The target breaker recovers through an external, single-flight MCP ping probe; a per-tool breaker recovers through a single-flight user call, since a ping cannot exercise a specific tool's timeout behavior.
Index ¶
- Constants
- Variables
- type Breakers
- func (m *Breakers) Allow(downstream, tool string) error
- func (m *Breakers) AllowProbe(downstream string) bool
- func (m *Breakers) RecordProbe(downstream string, success bool)
- func (m *Breakers) RecordSuccess(downstream, tool string)
- func (m *Breakers) RecordToolTimeout(downstream, tool string)
- func (m *Breakers) RecordTransportFailure(downstream string)
- type Config
Constants ¶
const ( DefaultFailureThreshold = 5 DefaultOpenDuration = 30 * time.Second )
Default breaker tuning, used when a Config field is left zero. Breaker tuning is not part of the V1 config surface; these constants are the policy.
Variables ¶
var ErrOpen = errors.New("circuit breaker open")
ErrOpen is returned by Allow when a call is shed because the relevant breaker (target or tool) is open. Callers match it with errors.Is.
Functions ¶
This section is empty.
Types ¶
type Breakers ¶
type Breakers struct {
// contains filtered or unexported fields
}
Breakers manages per-target and per-(downstream, tool) breakers and applies the failure-class rules. It is safe for concurrent use.
func (*Breakers) Allow ¶
Allow reports whether a call to (downstream, tool) may proceed. It fails with ErrOpen if the target breaker is open (the downstream is unhealthy) or if the tool's breaker is open (the tool is persistently timing out). User calls never probe the target — only AllowProbe does — but a user call may serve as the single-flight probe for a recovering tool breaker.
func (*Breakers) AllowProbe ¶
AllowProbe reports whether the caller may run the single-flight ping probe for a target breaker. It returns true at most once per open period, when the open duration has elapsed; the result must be reported with RecordProbe.
func (*Breakers) RecordProbe ¶
RecordProbe reports the outcome of a ping probe started via AllowProbe: success closes the target breaker, failure reopens it.
func (*Breakers) RecordSuccess ¶
RecordSuccess records a successful call, resetting both the target and the tool breakers (closing a tool breaker that was probing).
func (*Breakers) RecordToolTimeout ¶
RecordToolTimeout records a tool-call timeout, which counts against the (downstream, tool) breaker only and never against the target.
func (*Breakers) RecordTransportFailure ¶
RecordTransportFailure records a transport/connection failure, a server-health signal that counts against the target breaker only.
type Config ¶
type Config struct {
// FailureThreshold is the number of consecutive failures that trips a breaker.
FailureThreshold int
// OpenDuration is how long a breaker stays open before a probe is allowed.
OpenDuration time.Duration
}
Config tunes the breakers. Zero fields fall back to the package defaults.
Source Files