Quick start

If you already use gobreaker, you only change the import.

Install

go get github.com/deaprima/fluxgo@v0.2.2

Wrap a call

Create one breaker per downstream dependency. DefaultConfig() is tuned for typical HTTP services.

breaker.go

import "github.com/deaprima/fluxgo"

cb := fluxgo.NewCircuitBreaker(fluxgo.Settings{
    Name:   "payment-service",
    Config: fluxgo.DefaultConfig(),
    OnStateChange: func(name string, from, to fluxgo.State) {
        log.Printf("[%s] %s -> %s", name, from, to)
    },
})

result, err := cb.Execute(func() (interface{}, error) {
    return callDownstream()
})

NewCircuitBreaker panics if the config is invalid, for example when W1 + W2 is not 1.

Handle the open state

switch {
case errors.Is(err, fluxgo.ErrOpenState):
    // circuit is open: serve a fallback
case errors.Is(err, fluxgo.ErrTooManyRequests):
    // half-open and the probe quota is used up
}

Note

For the first 30 seconds fluxgo learns a healthy baseline and behaves like a static breaker. Send representative traffic during warmup; a warmup with more than WarmupMaxFailRate failures is not accepted as a baseline.

Configure

Field	Default	Description
Alpha	0.3	EWMA smoothing factor (0 < α ≤ 1)
W1 / W2	0.4 / 0.6	Weights of the EWMA and percentile signals; must sum to 1
ThetaBase	0.6	Baseline failure-rate threshold
ThetaMin / ThetaMax	0.05 / 0.9	Clamp range for the adaptive threshold
WarmupDuration	30s	Observation period before the threshold adapts
RecoveryTimeout	60s	Time spent Open before moving to Half-Open
MinDwellTime	5s	Minimum time between state transitions
MinRequests	20	Requests in the window before the failure rate is evaluated

Inspect the breaker

snap := cb.Snapshot()
fmt.Println(snap.State, snap.ThetaT, snap.FailureRate, snap.IsWarmingUp)

Snapshot() is the one addition to the gobreaker API. It exposes every internal signal (Sₜ, Pₜ, θₜ, degraded requests) for dashboards and debugging.