GitHub

circuit_breaker

API reference for circuit_breaker.

Circuit breakers per key (Effect's effect/persistence/CircuitBreaker)::

breaker = yield from circuit_breaker.make(
    trip_policy=circuit_breaker.consecutive(5), open_duration=30
)
yield from call_api.pipe(breaker.execute(key="api"))

A key's circuit is Closed (calls run and are counted), Open (calls fail with CircuitOpen for the open time) or HalfOpen (one probe runs; its success closes the circuit, its failure reopens it). The trip policy is consecutive failures or a failure rate; classify decides how a call counts (success, ignored, failure()), and on_rejection="allow" runs a call the circuit refuses, unrecorded.

States live in a CircuitBreakerStore: layer_store_memory, or layer_store_redis (shared by every process using that Redis).

Values

AttributeTypeDescription
CIRCUIT_BREAKER_ERROR_REASONUnionSchema[CircuitOpen | CircuitHalfOpen | CircuitBreakerStoreError, Mapping[str, object], Never, Never]

The schema of every reason.

ignoredFinal[Outcome]
successFinal[Outcome]

Types

TypeDefinitionDescription
Classifiertype Classifier[A, E, R = Never] = Callable[[Exit[A, E], ClassifyContext], Outcome | Effect[Outcome, Never, R]]

How an admitted call's exit counts; without it a success is a success and a failure a failure(). An interrupt-only exit is always ignored.

OnRejectiontype OnRejection = Literal['allow', 'fail']

When the circuit refuses a call: "fail" fails it with CircuitOpen or CircuitHalfOpen, "allow" runs it unrecorded. An admitted call, the probe included, is recorded either way.

OnStoreErrortype OnStoreError = Literal['allow', 'fail']

When the store cannot admit a call: "allow" runs it unrecorded (reporting the cause at the UnhandledLogLevel), "fail" fails with the CircuitBreakerStoreError.

OpenDurationtype OpenDuration = DurationInput | Schedule[object, int]

How long an opening lasts: a duration, or a schedule replayed with the number of consecutive openings (its delays measured from the opening).

CircuitBreakerErrorReasontype CircuitBreakerErrorReason = CircuitOpen | CircuitHalfOpen | CircuitBreakerStoreError
Outcometype Outcome = SuccessOutcome | IgnoredOutcome | FailureOutcome

How a call counts (what classify gives).

OutcomeKindtype OutcomeKind = Literal['Success', 'Failure', 'Ignored']
Statetype State = Closed | Open | HalfOpen
Transitiontype Transition = OpenTransition | HalfOpenTransition | CloseTransition

A change of a key's state, published on transitions.

TripPolicytype TripPolicy = Consecutive | Rate

When a closed circuit opens.

Classes

Functions

layer

layer(*, trip_policy, open_duration, max_open_duration='1 hour', on_store_error='allow') -> Layer[CircuitBreaker, Never, CircuitBreakerStore]

Provides CircuitBreaker (see make).

ParameterTypeDescription
trip_policyTripPolicy
open_durationOpenDuration
max_open_durationDurationInput = '1 hour'
on_store_errorOnStoreError = 'allow'

Returns Layer[CircuitBreaker, Never, CircuitBreakerStore]

def layer(
    *,
    trip_policy: TripPolicy,
    open_duration: OpenDuration,
    max_open_duration: DurationInput = "1 hour",
    on_store_error: OnStoreError = "allow",
) -> Layer[CircuitBreaker, Never, CircuitBreakerStore]:
    """Provides ``CircuitBreaker`` (see ``make``)."""
    return layer_effect(
        CircuitBreaker,
        make(
            trip_policy=trip_policy,
            open_duration=open_duration,
            max_open_duration=max_open_duration,
            on_store_error=on_store_error,
        ),
    )

make

make(*, trip_policy, open_duration, max_open_duration='1 hour', on_store_error='allow') -> Effect[CircuitBreakerService, Never, CircuitBreakerStore | Scope]

A breaker on the CircuitBreakerStore. A closed key opens when trip_policy says; an opening lasts open_duration (a schedule gives longer ones as openings repeat), or a failure's retry_after up to max_open_duration (default an hour). After it, one probe runs: its success closes the key, its failure reopens it. A key closed as long as its last opening starts counting openings afresh. transitions ends when the scope closes.

ParameterTypeDescription
trip_policyTripPolicy
open_durationOpenDuration
max_open_durationDurationInput = '1 hour'
on_store_errorOnStoreError = 'allow'

Returns Effect[CircuitBreakerService, Never, CircuitBreakerStore | Scope]

def make(
    *,
    trip_policy: TripPolicy,
    open_duration: OpenDuration,
    max_open_duration: DurationInput = "1 hour",
    on_store_error: OnStoreError = "allow",
) -> Effect[CircuitBreakerService, Never, CircuitBreakerStore | Scope]:
    """A breaker on the ``CircuitBreakerStore``. A closed key opens when
    ``trip_policy`` says; an opening lasts ``open_duration`` (a schedule
    gives longer ones as openings repeat), or a failure's ``retry_after``
    up to ``max_open_duration`` (default an hour). After it, one probe
    runs: its success closes the key, its failure reopens it. A key closed
    as long as its last opening starts counting openings afresh.
    ``transitions`` ends when the scope closes."""
    max_open = from_input_unsafe(max_open_duration)

    def build() -> Generator[Effect[Any, Never, Any], Any, CircuitBreakerService]:
        store = yield from CircuitBreakerStore()
        pubsub: PubSub[Take[Transition]] = yield from PubSub[Take[Transition]].sliding(128)
        yield from add_finalizer(lambda _: pubsub.end(exit_succeed(None)))
        return CircuitBreakerService(
            store, pubsub, trip_policy, open_duration, max_open, on_store_error
        )

    return gen(build)

layer_store_memory

layer_store_memory(*, idle_time_to_live='1 hour') -> Layer[CircuitBreakerStore]

Circuit states in memory, fresh each time the layer is built.

ParameterTypeDescription
idle_time_to_liveDurationInput = '1 hour'

Returns Layer[CircuitBreakerStore]

def layer_store_memory(
    *, idle_time_to_live: DurationInput = "1 hour"
) -> Layer[CircuitBreakerStore]:
    """Circuit states in memory, fresh each time the layer is built."""
    return layer_sync(
        CircuitBreakerStore, lambda: make_store_memory(idle_time_to_live=idle_time_to_live)
    )

make_store_memory

make_store_memory(*, idle_time_to_live='1 hour') -> CircuitBreakerStoreService

A store in memory, dropping keys idle for idle_time_to_live (default an hour).

ParameterTypeDescription
idle_time_to_liveDurationInput = '1 hour'

Returns CircuitBreakerStoreService

def make_store_memory(*, idle_time_to_live: DurationInput = "1 hour") -> CircuitBreakerStoreService:
    """A store in memory, dropping keys idle for ``idle_time_to_live``
    (default an hour)."""
    store = MemoryCircuitBreakerStore(to_millis(idle_time_to_live))
    return CircuitBreakerStoreService(admit=store.admit, record=store.record, state=store.state)

layer_store_redis

layer_store_redis(*, prefix='circuitbreaker:', probe_lease='10 seconds', idle_time_to_live='1 hour') -> Layer[CircuitBreakerStore, Never, Redis]

Circuit states in Redis (see make_store_redis).

ParameterTypeDescription
prefixstr = 'circuitbreaker:'
probe_leaseDurationInput = '10 seconds'
idle_time_to_liveDurationInput = '1 hour'

Returns Layer[CircuitBreakerStore, Never, Redis]

def layer_store_redis(
    *,
    prefix: str = "circuitbreaker:",
    probe_lease: DurationInput = "10 seconds",
    idle_time_to_live: DurationInput = "1 hour",
) -> Layer[CircuitBreakerStore, Never, Redis]:
    """Circuit states in Redis (see ``make_store_redis``)."""
    return layer_effect(
        CircuitBreakerStore,
        make_store_redis(
            prefix=prefix, probe_lease=probe_lease, idle_time_to_live=idle_time_to_live
        ),
    )

layer_store_redis_config

layer_store_redis_config(options) -> Layer[CircuitBreakerStore, ConfigError, Redis]

layer_store_redis with its options read from the ConfigProvider: a Config of them, or a mapping from option names to their Config (Effect's Config.Wrap).

ParameterTypeDescription
optionsConfig[Mapping[str, Any]] | Mapping[str, Any]

Returns Layer[CircuitBreakerStore, ConfigError, Redis]

def layer_store_redis_config(
    options: Config[Mapping[str, Any]] | Mapping[str, Any],
) -> Layer[CircuitBreakerStore, ConfigError, Redis]:
    """``layer_store_redis`` with its options read from the
    ``ConfigProvider``: a ``Config`` of them, or a mapping from option names
    to their ``Config`` (Effect's ``Config.Wrap``)."""
    read: Effect[Mapping[str, Any], ConfigError] = unwrap(options)
    return layer_effect(
        CircuitBreakerStore, read.flat_map(lambda fields: make_store_redis(**fields))
    )

make_store_redis

make_store_redis(*, prefix='circuitbreaker:', probe_lease='10 seconds', idle_time_to_live='1 hour') -> Effect[CircuitBreakerStoreService, Never, Redis]

A store in the Redis service, its keys under prefix. A probe's lease lasts probe_lease (renewed while it runs, so a probe whose process died frees its slot), and a key idle for idle_time_to_live expires (an open one only after its open time).

ParameterTypeDescription
prefixstr = 'circuitbreaker:'
probe_leaseDurationInput = '10 seconds'
idle_time_to_liveDurationInput = '1 hour'

Returns Effect[CircuitBreakerStoreService, Never, Redis]

def make_store_redis(
    *,
    prefix: str = "circuitbreaker:",
    probe_lease: DurationInput = "10 seconds",
    idle_time_to_live: DurationInput = "1 hour",
) -> Effect[CircuitBreakerStoreService, Never, Redis]:
    """A store in the ``Redis`` service, its keys under ``prefix``. A
    probe's lease lasts ``probe_lease`` (renewed while it runs, so a probe
    whose process died frees its slot), and a key idle for
    ``idle_time_to_live`` expires (an open one only after its open time)."""
    lease_millis = _redis_millis(probe_lease)
    idle_millis = _redis_millis(idle_time_to_live)

    def build() -> Generator[Effect[Any, Never, Any], Any, CircuitBreakerStoreService]:
        redis = yield from Redis()
        store = RedisCircuitBreakerStore(
            redis, prefix=prefix, lease_millis=lease_millis, idle_millis=idle_millis
        )
        return CircuitBreakerStoreService(admit=store.admit, record=store.record, state=store.state)

    return gen(build)

consecutive

consecutive(failures) -> TripPolicy

Open after failures failures in a row.

ParameterTypeDescription
failuresint

Returns TripPolicy

def consecutive(failures: int) -> TripPolicy:
    """Open after ``failures`` failures in a row."""
    return Consecutive(failures)

failure

failure(*, retry_after=None) -> Outcome

A failure, opening for at least retry_after if it opens.

ParameterTypeDescription
retry_afterDurationInput | None = None

Returns Outcome

def failure(*, retry_after: DurationInput | None = None) -> Outcome:
    """A failure, opening for at least ``retry_after`` if it opens."""
    return FailureOutcome(None if retry_after is None else from_input_unsafe(retry_after))

rate

rate(*, threshold=0.5, size=100, minimum_calls=None) -> TripPolicy

Open once threshold (default half) of the last size (default 100) recorded calls failed, counting only once minimum_calls (default size) are in.

ParameterTypeDescription
thresholdfloat = 0.5
sizeint = 100
minimum_callsint | None = None

Returns TripPolicy

def rate(
    *, threshold: float = 0.5, size: int = 100, minimum_calls: int | None = None
) -> TripPolicy:
    """Open once ``threshold`` (default half) of the last ``size`` (default
    100) recorded calls failed, counting only once ``minimum_calls``
    (default ``size``) are in."""
    return Rate(threshold, size if minimum_calls is None else minimum_calls, size)