Safe Haskell	None
Language	GHC2021

Ecluse.Core.Breaker

Contents

Observing transitions

Description

The circuit-breaker state machine fronting a call that can fail or hang: minting an outbound credential, or consulting an effectful rule source.

Every transition takes the caller's now, so no wall clock is read here. The two policy knobs, the trip threshold and the cooldown, are the caller's and reach recordFailure per call, and so are storage and concurrency. These functions only fold one state into the next.

Synopsis

data Breaker
- = Closed Int
- | Open UTCTime
- | HalfOpen
initialBreaker :: Breaker
admit :: UTCTime -> Breaker -> (Bool, Breaker)
recordSuccess :: Breaker -> Breaker
recordFailure :: Int -> NominalDiffTime -> UTCTime -> Breaker -> Breaker
newtype BreakerReporter = BreakerReporter (Breaker -> IO ())
noBreakerReporter :: BreakerReporter
reportBreakerChange :: BreakerReporter -> Breaker -> Breaker -> IO ()
breakerState :: Breaker -> BreakerState

Documentation

data Breaker Source #

The breaker's state, gating whether the guarded operation may be attempted.

Constructors

Closed Int	Healthy: the consecutive-failure count so far, up to the trip threshold.
Open UTCTime	Tripped until the given instant: attempts fast-fail until then.
HalfOpen	Cooldown elapsed: `admit` lets one probe attempt through to test recovery.

Instances

Instances details

Show Breaker Source #
Instance details Defined in Ecluse.Core.Breaker Methods showsPrec :: Int -> Breaker -> ShowS # show :: Breaker -> String # showList :: [Breaker] -> ShowS #
Eq Breaker Source #
Instance details Defined in Ecluse.Core.Breaker Methods (==) :: Breaker -> Breaker -> Bool # (/=) :: Breaker -> Breaker -> Bool #

initialBreaker :: Breaker Source #

A fresh, healthy breaker with no failures recorded.

admit :: UTCTime -> Breaker -> (Bool, Breaker) Source #

Decide whether the guarded operation may be attempted at now. The caller must commit the returned breaker state, or the move from Open to HalfOpen never takes effect.

recordSuccess :: Breaker -> Breaker Source #

Fold a successful attempt into the breaker: reset it to healthy from any state.

recordFailure :: Int -> NominalDiffTime -> UTCTime -> Breaker -> Breaker Source #

Fold a failed attempt into the breaker, given the caller's trip threshold and cooldown. A Closed breaker counts up and trips at the threshold, and any other state opens a fresh cooldown.

Observing transitions

newtype BreakerReporter Source #

An observer of breaker state changes. The callback takes the breaker itself, so no instrument handle reaches here, and the composition root installs the live observer.

Constructors

BreakerReporter (Breaker -> IO ())

noBreakerReporter :: BreakerReporter Source #

The inert reporter: discards the state, recording nothing.

reportBreakerChange :: BreakerReporter -> Breaker -> Breaker -> IO () Source #

Report a transition through the observer, but only when old and new differ observably. The failure tally inside Closed is not observable, so advancing it alone fires nothing.

breakerState :: Breaker -> BreakerState Source #

The breaker's coarse observable state, the bounded value the ecluse.rule.breaker.state gauge records. It drops the failure tally, so two Closed breakers project alike.