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#
| Attribute | Type | Description |
|---|---|---|
CIRCUIT_BREAKER_ERROR_REASON | UnionSchema[CircuitOpen | CircuitHalfOpen | CircuitBreakerStoreError, Mapping[str, object], Never, Never] | The schema of every reason. |
ignored | Final[Outcome] | |
success | Final[Outcome] |
Types#
| Type | Definition | Description |
|---|---|---|
Classifier | type 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
|
OnRejection | type OnRejection = Literal['allow', 'fail'] | When the circuit refuses a call: |
OnStoreError | type OnStoreError = Literal['allow', 'fail'] | When the store cannot admit a call: |
OpenDuration | type 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). |
CircuitBreakerErrorReason | type CircuitBreakerErrorReason = CircuitOpen | CircuitHalfOpen | CircuitBreakerStoreError | |
Outcome | type Outcome = SuccessOutcome | IgnoredOutcome | FailureOutcome | How a call counts (what |
OutcomeKind | type OutcomeKind = Literal['Success', 'Failure', 'Ignored'] | |
State | type State = Closed | Open | HalfOpen | |
Transition | type Transition = OpenTransition | HalfOpenTransition | CloseTransition | A change of a key's state, published on |
TripPolicy | type 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).
| Parameter | Type | Description |
|---|---|---|
trip_policy | TripPolicy | |
open_duration | OpenDuration | |
max_open_duration | DurationInput = '1 hour' | |
on_store_error | OnStoreError = '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.
| Parameter | Type | Description |
|---|---|---|
trip_policy | TripPolicy | |
open_duration | OpenDuration | |
max_open_duration | DurationInput = '1 hour' | |
on_store_error | OnStoreError = '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.
| Parameter | Type | Description |
|---|---|---|
idle_time_to_live | DurationInput = '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') -> CircuitBreakerStoreServiceA store in memory, dropping keys idle for idle_time_to_live
(default an hour).
| Parameter | Type | Description |
|---|---|---|
idle_time_to_live | DurationInput = '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).
| Parameter | Type | Description |
|---|---|---|
prefix | str = 'circuitbreaker:' | |
probe_lease | DurationInput = '10 seconds' | |
idle_time_to_live | DurationInput = '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).
| Parameter | Type | Description |
|---|---|---|
options | Config[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).
| Parameter | Type | Description |
|---|---|---|
prefix | str = 'circuitbreaker:' | |
probe_lease | DurationInput = '10 seconds' | |
idle_time_to_live | DurationInput = '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) -> TripPolicyOpen after failures failures in a row.
| Parameter | Type | Description |
|---|---|---|
failures | int |
Returns TripPolicy
def consecutive(failures: int) -> TripPolicy:
"""Open after ``failures`` failures in a row."""
return Consecutive(failures)failure#
failure(*, retry_after=None) -> OutcomeA failure, opening for at least retry_after if it opens.
| Parameter | Type | Description |
|---|---|---|
retry_after | DurationInput | 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) -> TripPolicyOpen once threshold (default half) of the last size (default
100) recorded calls failed, counting only once minimum_calls
(default size) are in.
| Parameter | Type | Description |
|---|---|---|
threshold | float = 0.5 | |
size | int = 100 | |
minimum_calls | int | 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)