interlock-cb 1.0.0__py3-none-any.whl

interlock/__init__.py

@@ -0,0 +1,53 @@
+"""interlock — a modern circuit breaker for Python."""
+
+from interlock._typing import AsyncCallable, Call, SyncCallable
+from interlock.breaker import CircuitBreaker
+from interlock.config import Config
+from interlock.errors import (
+    CallTimeoutError,
+    CircuitOpenError,
+    InterlockDeprecationWarning,
+    InterlockError,
+)
+from interlock.listeners import LoggingEventListener
+from interlock.outcome import Outcome
+from interlock.protocols import (
+    Clock,
+    EventListener,
+    FailureClassifier,
+    SlidingWindow,
+    Storage,
+)
+from interlock.registry import Registry
+from interlock.state import State
+from interlock.timeout import timeout
+from interlock.version import VERSION
+from interlock.window import WindowSnapshot, WindowType
+
+__version__ = VERSION
+
+__all__ = (
+    'VERSION',
+    'AsyncCallable',
+    'Call',
+    'CallTimeoutError',
+    'CircuitBreaker',
+    'CircuitOpenError',
+    'Clock',
+    'Config',
+    'EventListener',
+    'FailureClassifier',
+    'InterlockDeprecationWarning',
+    'InterlockError',
+    'LoggingEventListener',
+    'Outcome',
+    'Registry',
+    'SlidingWindow',
+    'State',
+    'Storage',
+    'SyncCallable',
+    'WindowSnapshot',
+    'WindowType',
+    '__version__',
+    'timeout',
+)

interlock/_classify.py

@@ -0,0 +1,24 @@
+"""Default failure classification policy.
+
+Implements ``FailureClassifier``: the baseline treats any raised exception as a
+failure and any returned value as a success. Result-based predicates and
+exception allow/ignore lists layer on top in the public API (M5).
+"""
+
+__all__ = ('DefaultFailureClassifier',)
+
+
+class DefaultFailureClassifier:
+    """Counts a call as a failure exactly when it raised."""
+
+    def is_failure(self, *, result: object, exception: BaseException | None) -> bool:  # noqa: ARG002
+        """Return whether a completed call counts as a failure.
+
+        Args:
+            result: The call's return value; ignored by this policy.
+            exception: The exception the call raised, or ``None`` if it returned.
+
+        Returns:
+            ``True`` if the call raised, ``False`` otherwise.
+        """
+        return exception is not None

interlock/_clock.py

@@ -0,0 +1,18 @@
+"""The default production clock.
+
+Breakers read time only through a ``Clock``, so tests can inject a fake one.
+In production the default is this thin wrapper over ``time.monotonic`` — a
+monotonic source unaffected by wall-clock adjustments.
+"""
+
+import time
+
+__all__ = ('SystemClock',)
+
+
+class SystemClock:
+    """A ``Clock`` backed by ``time.monotonic``."""
+
+    def monotonic(self) -> float:
+        """Return ``time.monotonic()`` in fractional seconds."""
+        return time.monotonic()

interlock/_detect.py

@@ -0,0 +1,34 @@
+"""Detect whether a callable runs synchronously or returns an awaitable.
+
+The public surface accepts any callable and must dispatch to the right path.
+A naive ``inspect.iscoroutinefunction(fn)`` misses two common shapes: callables
+wrapped in ``functools.partial`` and objects whose ``__call__`` is a coroutine
+function. This unwraps partials and inspects ``__call__`` so both are handled.
+"""
+
+import functools
+import inspect
+
+__all__ = ('is_async_callable',)
+
+
+def is_async_callable(fn: object) -> bool:
+    """Return whether calling ``fn`` produces an awaitable.
+
+    Args:
+        fn: Any callable — a function, bound method, ``functools.partial``, or an
+            instance with a ``__call__`` method.
+
+    Returns:
+        ``True`` if ``fn`` is (or wraps, or is an object whose ``__call__`` is) a
+        coroutine function; ``False`` otherwise.
+    """
+    while isinstance(fn, functools.partial):
+        fn = fn.func
+
+    if inspect.iscoroutinefunction(fn):
+        return True
+
+    # The __call__ attribute itself is needed to test its async-ness, which
+    # callable() cannot report — so B004's suggestion does not apply here.
+    return inspect.iscoroutinefunction(getattr(type(fn), '__call__', None))  # noqa: B004

interlock/_engine.py

@@ -0,0 +1,232 @@
+"""The ``call()`` primitive: detect, dispatch, time, classify, record.
+
+This is the I/O-aware layer wrapping the I/O-free ``StateMachine``. It owns a
+single ``threading.Lock`` and holds it only around the two await-free critical
+sections — admitting a call (``acquire``) and recording its outcome
+(``record``). The protected callable runs *outside* the lock, so a slow
+downstream never serialises throughput and a re-entrant call cannot deadlock.
+
+A single instance serves both sync and async callers: ``call`` detects the
+callable's nature via ``is_async_callable`` and dispatches to ``call_sync`` or
+``call_async``. The lock is a ``threading.Lock`` because the critical sections
+never ``await``; it is correct for threads and for a single event loop alike.
+"""
+
+import threading
+from collections.abc import Awaitable, Callable
+from typing import cast
+
+from interlock._classify import DefaultFailureClassifier
+from interlock._detect import is_async_callable
+from interlock._state_machine import StateMachine
+from interlock._typing import AsyncCallable, P, R, SyncCallable
+from interlock.config import Config
+from interlock.errors import CircuitOpenError
+from interlock.outcome import Outcome
+from interlock.protocols import Clock, EventListener, FailureClassifier
+from interlock.state import State
+from interlock.window import WindowSnapshot
+
+__all__ = ('Engine',)
+
+_OUTCOME_BY_FLAGS = {
+    (False, False): Outcome.SUCCESS,
+    (True, False): Outcome.FAILURE,
+    (False, True): Outcome.SLOW_SUCCESS,
+    (True, True): Outcome.SLOW_FAILURE,
+}
+
+
+class _NoopListener:
+    """Null EventListener used when none is configured.
+
+    Lets the engine always call ``self._listener.<hook>(...)`` without a None
+    check; every hook is a no-op.
+    """
+
+    def on_state_change(self, *, name: str, old: State, new: State) -> None: ...
+    def on_call(self, *, name: str, outcome: Outcome, duration: float) -> None: ...
+    def on_rejected(self, *, name: str) -> None: ...
+    def on_reset(self, *, name: str) -> None: ...
+
+
+_NOOP_LISTENER: EventListener = _NoopListener()
+
+
+class Engine:
+    """Runs callables under one breaker, mediating the state machine.
+
+    Args:
+        name: Breaker name, surfaced on ``CircuitOpenError``.
+        config: Thresholds, window and timing.
+        clock: Time source; injected for deterministic tests.
+        classifier: Decides which outcomes count as failures. Defaults to
+            ``DefaultFailureClassifier`` (any raised exception is a failure).
+        listener: Observability hooks. Defaults to a no-op listener.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        config: Config,
+        clock: Clock,
+        classifier: FailureClassifier | None = None,
+        listener: EventListener | None = None,
+    ) -> None:
+        self._name = name
+        self._config = config
+        self._clock = clock
+        self._classifier = classifier if classifier is not None else DefaultFailureClassifier()
+        self._listener = listener if listener is not None else _NOOP_LISTENER
+        self._machine = StateMachine(config=config, clock=clock)
+        self._lock = threading.Lock()
+        self._last_failure: BaseException | None = None
+
+    @property
+    def state(self) -> State:
+        """The breaker's current lifecycle state."""
+        return self._machine.state
+
+    def snapshot(self) -> WindowSnapshot:
+        """An immutable view of the current window aggregates."""
+        return self._machine.snapshot()
+
+    def call(
+        self,
+        fn: AsyncCallable[P, R] | SyncCallable[P, R],
+        /,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Awaitable[R] | R:
+        """Run ``fn`` under protection, dispatching on its sync/async nature.
+
+        Returns an awaitable for a coroutine function and the plain result for a
+        synchronous one; the precise sync/async-preserving typing is supplied by
+        the public ``CircuitBreaker`` surface (M5) over this primitive.
+        """
+        if is_async_callable(fn):
+            return self.call_async(cast('AsyncCallable[P, R]', fn), *args, **kwargs)
+
+        return self.call_sync(cast('SyncCallable[P, R]', fn), *args, **kwargs)
+
+    def call_sync(self, fn: SyncCallable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Run a synchronous ``fn`` under protection.
+
+        Raises:
+            CircuitOpenError: If the breaker rejects the call.
+        """
+        self._admit()
+        start = self._clock.monotonic()
+
+        try:
+            result = fn(*args, **kwargs)
+        except Exception as exc:
+            self._settle(result=None, exception=exc, start=start)
+            raise
+        else:
+            self._settle(result=result, exception=None, start=start)
+            return result
+
+    async def call_async(self, fn: AsyncCallable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Run an asynchronous ``fn`` under protection.
+
+        Raises:
+            CircuitOpenError: If the breaker rejects the call.
+        """
+        self._admit()
+        start = self._clock.monotonic()
+
+        try:
+            result = await fn(*args, **kwargs)
+        except Exception as exc:
+            self._settle(result=None, exception=exc, start=start)
+            raise
+        else:
+            self._settle(result=result, exception=None, start=start)
+            return result
+
+    def enter_block(self) -> float:
+        """Admit a guarded block and return its start time.
+
+        Backs the context-manager surface, where there is no callable to run —
+        only a block whose exception and duration are observed.
+
+        Raises:
+            CircuitOpenError: If the breaker rejects the block.
+        """
+        self._admit()
+        return self._clock.monotonic()
+
+    def exit_block(self, *, start: float, exception: BaseException | None) -> None:
+        """Record a guarded block's outcome from its exception and duration."""
+        if exception is not None and not isinstance(exception, Exception):
+            return  # mirror call(): cancellation/shutdown are not downstream failures
+        self._settle(result=None, exception=exception, start=start)
+
+    def reset(self) -> None:
+        """Return to ``CLOSED`` with a fresh window, discarding past metrics."""
+        with self._lock:
+            before = self._machine.state
+            self._machine.reset()
+            after = self._machine.state
+
+        self._emit_state_change(before, after)
+        self._listener.on_reset(name=self._name)
+
+    def force_open(self) -> None:
+        """Override to ``FORCED_OPEN``: reject all traffic until reset."""
+        self._override(self._machine.force_open)
+
+    def disable(self) -> None:
+        """Override to ``DISABLED``: admit all traffic, record nothing."""
+        self._override(self._machine.disable)
+
+    def metrics_only(self) -> None:
+        """Override to ``METRICS_ONLY``: admit all traffic, record but never trip."""
+        self._override(self._machine.metrics_only)
+
+    def _override(self, mutate: Callable[[], None]) -> None:
+        with self._lock:
+            before = self._machine.state
+            mutate()
+            after = self._machine.state
+
+        self._emit_state_change(before, after)
+
+    def _admit(self) -> None:
+        with self._lock:
+            before = self._machine.state
+            admitted = self._machine.acquire()
+            after = self._machine.state
+            retry_after = None if admitted else self._machine.retry_after()
+            last_failure = self._last_failure
+
+        self._emit_state_change(before, after)
+        if not admitted:
+            self._listener.on_rejected(name=self._name)
+            raise CircuitOpenError(
+                self._name,
+                retry_after=retry_after,
+                last_failure=last_failure,
+            )
+
+    def _settle(self, *, result: object, exception: Exception | None, start: float) -> None:
+        duration = self._clock.monotonic() - start
+        failure = self._classifier.is_failure(result=result, exception=exception)
+        slow = duration >= self._config.slow_call_duration_threshold
+        outcome = _OUTCOME_BY_FLAGS[failure, slow]
+
+        with self._lock:
+            before = self._machine.state
+            self._machine.record(outcome)
+            after = self._machine.state
+            if failure and exception is not None:
+                self._last_failure = exception
+
+        self._listener.on_call(name=self._name, outcome=outcome, duration=duration)
+        self._emit_state_change(before, after)
+
+    def _emit_state_change(self, before: State, after: State) -> None:
+        if after != before:
+            self._listener.on_state_change(name=self._name, old=before, new=after)

interlock/_state_machine.py

@@ -0,0 +1,197 @@
+"""The I/O-free circuit breaker state machine.
+
+This is the core: it owns the current ``State``, the sliding window of recent
+outcomes, and every transition between them. It performs no I/O and knows
+nothing about sync vs async — the call layer wraps it in a lock and feeds it
+admission requests (``acquire``) and results (``record``). All time comes from
+the injected ``Clock``, so transitions are fully deterministic under test.
+
+Three core states cycle on downstream health:
+
+- ``CLOSED`` admits everything and trips to ``OPEN`` once the window holds at
+  least ``minimum_number_of_calls`` and the failure *or* slow-call rate reaches
+  its threshold.
+- ``OPEN`` rejects everything until ``wait_duration_in_open`` has elapsed, then
+  lazily (on the next ``acquire``) moves to ``HALF_OPEN``.
+- ``HALF_OPEN`` admits a bounded number of probes — at most
+  ``permitted_calls_in_half_open`` total and ``max_concurrent_probes`` at once —
+  then closes or reopens based on the probes' rates.
+
+Three special states are operator overrides: ``FORCED_OPEN`` (reject all),
+``DISABLED`` (admit all, no metrics), ``METRICS_ONLY`` (admit all, record
+metrics, never trip).
+"""
+
+from interlock._windows import build_window
+from interlock.config import Config
+from interlock.outcome import Outcome
+from interlock.protocols import Clock
+from interlock.state import State
+from interlock.window import WindowSnapshot
+
+__all__ = ('StateMachine',)
+
+_PERMIT_ALL = frozenset({State.CLOSED, State.DISABLED, State.METRICS_ONLY})
+
+
+class StateMachine:
+    """Owns breaker state and drives transitions from recorded outcomes.
+
+    Not thread-safe on its own: the call layer serialises ``acquire`` and
+    ``record`` under a single lock. Time is read only through the injected
+    ``Clock``.
+    """
+
+    def __init__(self, *, config: Config, clock: Clock) -> None:
+        self._config = config
+        self._clock = clock
+        self._window = build_window(config=config, clock=clock)
+        self._state = State.CLOSED
+        self._opened_at = 0.0
+        self._reset_probes()
+
+    @property
+    def state(self) -> State:
+        """The current lifecycle state."""
+        return self._state
+
+    def snapshot(self) -> WindowSnapshot:
+        """An immutable view of the current window aggregates."""
+        return self._window.snapshot()
+
+    def retry_after(self) -> float | None:
+        """Seconds until the next probe is admitted, when the breaker can estimate it.
+
+        Estimable only in ``OPEN`` — the remainder of ``wait_duration_in_open``.
+        ``HALF_OPEN`` rejections come from probe caps rather than time, and
+        ``FORCED_OPEN`` waits for an operator; neither has a time estimate, so
+        both (like the admitting states) return ``None``.
+        """
+        if self._state is not State.OPEN:
+            return None
+
+        elapsed = self._clock.monotonic() - self._opened_at
+        return max(0.0, self._config.wait_duration_in_open - elapsed)
+
+    def acquire(self) -> bool:
+        """Decide whether one call may proceed, mutating state lazily.
+
+        ``OPEN`` becomes ``HALF_OPEN`` here once its wait has elapsed, and the
+        triggering call is admitted as the first probe. The caller raises
+        ``CircuitOpenError`` on a ``False`` result; this method never raises.
+        """
+        if self._state in _PERMIT_ALL:
+            return True
+
+        if self._state is State.OPEN:
+            return self._begin_probing_if_elapsed()
+
+        if self._state is State.HALF_OPEN:
+            return self._admit_probe()
+
+        return False  # FORCED_OPEN
+
+    def record(self, outcome: Outcome) -> None:
+        """Record one completed call's outcome and evaluate any transition."""
+        if self._state is State.CLOSED:
+            self._window.record(outcome)
+            self._evaluate_closed()
+        elif self._state is State.HALF_OPEN:
+            self._record_probe(outcome)
+        elif self._state is State.METRICS_ONLY:
+            self._window.record(outcome)
+
+    def force_open(self) -> None:
+        """Override to ``FORCED_OPEN``: reject all traffic until reset."""
+        self._state = State.FORCED_OPEN
+        self._reset_probes()
+
+    def disable(self) -> None:
+        """Override to ``DISABLED``: admit all traffic, record nothing."""
+        self._state = State.DISABLED
+        self._reset_probes()
+
+    def metrics_only(self) -> None:
+        """Override to ``METRICS_ONLY``: admit all traffic, record but never trip."""
+        self._state = State.METRICS_ONLY
+        self._reset_probes()
+
+    def reset(self) -> None:
+        """Return to ``CLOSED`` with a fresh window, discarding past metrics."""
+        self._close()
+
+    def _begin_probing_if_elapsed(self) -> bool:
+        if self._clock.monotonic() - self._opened_at < self._config.wait_duration_in_open:
+            return False
+
+        self._to_half_open()
+        return self._admit_probe()
+
+    def _admit_probe(self) -> bool:
+        # Cap total probes (don't hammer a barely-recovered dependency) and how
+        # many run at once (else the whole parallel load floods in as probes).
+        if (
+            self._probes_in_flight >= self._config.max_concurrent_probes
+            or self._probes_admitted >= self._config.permitted_calls_in_half_open
+        ):
+            return False
+
+        self._probes_admitted += 1
+        self._probes_in_flight += 1
+        return True
+
+    def _evaluate_closed(self) -> None:
+        snapshot = self._window.snapshot()
+        if snapshot.total_calls < self._config.minimum_number_of_calls:
+            return
+
+        if self._exceeds_threshold(
+            failure_rate=snapshot.failure_rate,
+            slow_call_rate=snapshot.slow_call_rate,
+        ):
+            self._open()
+
+    def _record_probe(self, outcome: Outcome) -> None:
+        self._probes_in_flight -= 1
+        self._probes_completed += 1
+        self._probe_failures += outcome.is_failure
+        self._probe_slows += outcome.is_slow
+
+        if self._probes_completed >= self._config.permitted_calls_in_half_open:
+            self._evaluate_probes()
+
+    def _evaluate_probes(self) -> None:
+        completed = self._probes_completed
+        if self._exceeds_threshold(
+            failure_rate=self._probe_failures / completed,
+            slow_call_rate=self._probe_slows / completed,
+        ):
+            self._open()
+        else:
+            self._close()
+
+    def _exceeds_threshold(self, *, failure_rate: float, slow_call_rate: float) -> bool:
+        return (
+            failure_rate >= self._config.failure_rate_threshold
+            or slow_call_rate >= self._config.slow_call_rate_threshold
+        )
+
+    def _open(self) -> None:
+        self._state = State.OPEN
+        self._opened_at = self._clock.monotonic()
+
+    def _to_half_open(self) -> None:
+        self._state = State.HALF_OPEN
+        self._reset_probes()
+
+    def _close(self) -> None:
+        self._state = State.CLOSED
+        self._window = build_window(config=self._config, clock=self._clock)
+        self._reset_probes()
+
+    def _reset_probes(self) -> None:
+        self._probes_admitted = 0
+        self._probes_in_flight = 0
+        self._probes_completed = 0
+        self._probe_failures = 0
+        self._probe_slows = 0

interlock/_typing.py

@@ -0,0 +1,35 @@
+"""Typing primitives for the call() contract and type-safe decorators.
+
+These aliases let the public API preserve a wrapped callable's signature and
+its sync/async nature instead of collapsing to ``Callable[..., Any]``.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import ParamSpec, Protocol, TypeVar, overload, runtime_checkable
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+SyncCallable = Callable[P, R]
+AsyncCallable = Callable[P, Awaitable[R]]
+
+__all__ = ('AsyncCallable', 'Call', 'SyncCallable')
+
+
+@runtime_checkable
+class Call(Protocol):
+    """The call() primitive: run a callable under the breaker's protection.
+
+    The return type tracks the callable's nature — a coroutine function yields
+    an awaitable, a plain function yields its result — so static typing never
+    loses the sync/async distinction. The detect-and-dispatch implementation
+    lives in the core (M4); this protocol fixes the contract.
+    """
+
+    @overload
+    def __call__(
+        self, fn: AsyncCallable[P, R], /, *args: P.args, **kwargs: P.kwargs
+    ) -> Awaitable[R]: ...
+
+    @overload
+    def __call__(self, fn: SyncCallable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R: ...