interlock-cb 1.0.0__py3-none-any.whl

interlock/_windows.py

@@ -0,0 +1,118 @@
+"""Concrete sliding-window implementations injected into the core.
+
+Two strategies satisfy the ``SlidingWindow`` protocol: ``CountBasedSlidingWindow``
+keeps the last N calls in a ring buffer; ``TimeBasedSlidingWindow`` keeps calls
+from the last N seconds in per-second buckets. Both expose running aggregates so
+``snapshot`` stays cheap, and both are constructed by the core from a validated
+``Config`` — they trust their ``size`` and never validate it themselves.
+"""
+
+from dataclasses import dataclass
+
+from interlock.config import Config
+from interlock.outcome import Outcome
+from interlock.protocols import Clock, SlidingWindow
+from interlock.window import WindowSnapshot, WindowType
+
+__all__ = ('CountBasedSlidingWindow', 'TimeBasedSlidingWindow', 'build_window')
+
+
+def build_window(*, config: Config, clock: Clock) -> SlidingWindow:
+    """Construct the window implementation selected by ``config``.
+
+    Time-based windows need the clock; count-based ones ignore it. The core
+    calls this whenever it needs fresh metrics — on construction and whenever a
+    breaker returns to ``CLOSED``.
+    """
+    if config.window_type is WindowType.COUNT_BASED:
+        return CountBasedSlidingWindow(size=config.window_size)
+
+    return TimeBasedSlidingWindow(size=config.window_size, clock=clock)
+
+
+class CountBasedSlidingWindow:
+    """Aggregates the most recent ``size`` outcomes via a ring buffer.
+
+    Running counters are adjusted on each record — incremented for the new
+    outcome, decremented for the one it evicts — so ``snapshot`` is O(1).
+    """
+
+    def __init__(self, *, size: int) -> None:
+        self._buffer: list[Outcome | None] = [None] * size
+        self._head = 0
+        self._total = 0
+        self._failed = 0
+        self._slow = 0
+
+    def record(self, outcome: Outcome) -> None:
+        evicted = self._buffer[self._head]
+        if evicted is not None:
+            self._total -= 1
+            self._failed -= evicted.is_failure
+            self._slow -= evicted.is_slow
+
+        self._buffer[self._head] = outcome
+        self._total += 1
+        self._failed += outcome.is_failure
+        self._slow += outcome.is_slow
+
+        self._head = (self._head + 1) % len(self._buffer)
+
+    def snapshot(self) -> WindowSnapshot:
+        return WindowSnapshot(
+            total_calls=self._total,
+            failed_calls=self._failed,
+            slow_calls=self._slow,
+        )
+
+
+@dataclass(slots=True)
+class _Bucket:
+    """Per-second aggregate. ``epoch_second`` tags which second it holds."""
+
+    epoch_second: int
+    total: int = 0
+    failed: int = 0
+    slow: int = 0
+
+
+class TimeBasedSlidingWindow:
+    """Aggregates outcomes from the last ``size`` seconds in per-second buckets.
+
+    Bucket ``i`` holds the second ``epoch % size == i``; touching a bucket whose
+    tag no longer matches the current second resets it, so a wrapped index never
+    carries a stale count. ``snapshot`` sums only buckets whose tag still falls
+    inside the window, which also expires calls as time passes without records.
+    """
+
+    def __init__(self, *, size: int, clock: Clock) -> None:
+        self._size = size
+        self._clock = clock
+        self._buckets = [_Bucket(epoch_second=-1) for _ in range(size)]
+
+    def _now_second(self) -> int:
+        return int(self._clock.monotonic())
+
+    def record(self, outcome: Outcome) -> None:
+        now = self._now_second()
+        bucket = self._buckets[now % self._size]
+        if bucket.epoch_second != now:
+            bucket.epoch_second = now
+            bucket.total = bucket.failed = bucket.slow = 0
+
+        bucket.total += 1
+        bucket.failed += outcome.is_failure
+        bucket.slow += outcome.is_slow
+
+    def snapshot(self) -> WindowSnapshot:
+        now = self._now_second()
+        oldest = max(0, now - self._size + 1)
+
+        total = failed = slow = 0
+        for bucket in self._buckets:
+            if oldest <= bucket.epoch_second <= now:
+                total += bucket.total
+                failed += bucket.failed
+                slow += bucket.slow
+
+        return WindowSnapshot(total_calls=total, failed_calls=failed, slow_calls=slow)

interlock/breaker.py

@@ -0,0 +1,169 @@
+"""The public circuit breaker.
+
+``CircuitBreaker`` is a single class serving both sync and async code. It offers
+three ways to protect work over the one ``call()`` primitive:
+
+- **decorator** — ``@breaker`` wraps a function, preserving its signature *and*
+  its sync/async nature via ``@overload`` + ``ParamSpec``;
+- **context manager** — the same instance is both a sync (``with``) and async
+  (``async with``) context manager guarding a block;
+- **``breaker.call(fn, ...)``** — the breaker executes the callable.
+
+A documented contract difference: the decorator and ``call`` see a callable, so
+result-based classification and slow-call detection both apply. The context
+manager sees only the block — its exception and duration — so result-based
+classification is unavailable there.
+"""
+
+import functools
+from collections.abc import Awaitable
+from types import TracebackType
+from typing import Literal, Self, cast, overload
+
+from interlock._clock import SystemClock
+from interlock._detect import is_async_callable
+from interlock._engine import Engine
+from interlock._typing import AsyncCallable, P, R, SyncCallable
+from interlock.config import Config
+from interlock.protocols import Clock, EventListener, FailureClassifier
+from interlock.state import State
+from interlock.window import WindowSnapshot
+
+__all__ = ('CircuitBreaker',)
+
+
+class CircuitBreaker:
+    """A named circuit breaker for sync and async callables.
+
+    Args:
+        name: Identifies the breaker; surfaced on ``CircuitOpenError``.
+        config: Thresholds, window and timing. Defaults to ``Config()``.
+        clock: Time source. Defaults to ``SystemClock`` (real monotonic time);
+            inject a fake for deterministic tests.
+        classifier: Decides which outcomes count as failures. Defaults to any
+            raised exception being a failure.
+        listener: Observability hooks (state changes, calls, rejections,
+            resets). Defaults to no observation.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        config: Config | None = None,
+        clock: Clock | None = None,
+        classifier: FailureClassifier | None = None,
+        listener: EventListener | None = None,
+    ) -> None:
+        self._name = name
+        self._engine = Engine(
+            name=name,
+            config=config if config is not None else Config(),
+            clock=clock if clock is not None else SystemClock(),
+            classifier=classifier,
+            listener=listener,
+        )
+        self._block_starts: list[float] = []
+
+    @property
+    def name(self) -> str:
+        """The breaker's name."""
+        return self._name
+
+    @property
+    def state(self) -> State:
+        """The breaker's current lifecycle state."""
+        return self._engine.state
+
+    def snapshot(self) -> WindowSnapshot:
+        """An immutable view of the current window aggregates."""
+        return self._engine.snapshot()
+
+    def reset(self) -> None:
+        """Return the breaker to ``CLOSED`` with a fresh window."""
+        self._engine.reset()
+
+    def force_open(self) -> None:
+        """Force the breaker ``FORCED_OPEN``: reject all traffic until reset."""
+        self._engine.force_open()
+
+    def disable(self) -> None:
+        """Disable the breaker: admit all traffic and record nothing."""
+        self._engine.disable()
+
+    def metrics_only(self) -> None:
+        """Put the breaker in shadow mode: admit all traffic, record, never trip."""
+        self._engine.metrics_only()
+
+    def call(
+        self,
+        fn: AsyncCallable[P, R] | SyncCallable[P, R],
+        /,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Awaitable[R] | R:
+        """Execute ``fn`` under protection, dispatching on its sync/async nature.
+
+        Returns an awaitable for a coroutine function and the plain result for a
+        synchronous one.
+
+        Raises:
+            CircuitOpenError: If the breaker rejects the call.
+        """
+        return self._engine.call(fn, *args, **kwargs)
+
+    @overload
+    def __call__(self, fn: AsyncCallable[P, R]) -> AsyncCallable[P, R]: ...
+
+    @overload
+    def __call__(self, fn: SyncCallable[P, R]) -> SyncCallable[P, R]: ...
+
+    # mypy cannot reconcile this union implementation with the ParamSpec
+    # overloads above (a known limitation of overloaded decorators); pyright
+    # accepts it, and the overloads are what callers see.
+    def __call__(  # type: ignore[misc]
+        self, fn: AsyncCallable[P, R] | SyncCallable[P, R]
+    ) -> AsyncCallable[P, R] | SyncCallable[P, R]:
+        """Decorate ``fn``, preserving its signature and sync/async nature."""
+        if is_async_callable(fn):
+            async_fn = cast('AsyncCallable[P, R]', fn)
+
+            @functools.wraps(async_fn)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                return await self._engine.call_async(async_fn, *args, **kwargs)
+
+            return async_wrapper
+
+        sync_fn = cast('SyncCallable[P, R]', fn)
+
+        @functools.wraps(sync_fn)
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            return self._engine.call_sync(sync_fn, *args, **kwargs)
+
+        return sync_wrapper
+
+    def __enter__(self) -> Self:
+        self._block_starts.append(self._engine.enter_block())
+        return self
+
+    def __exit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        _traceback: TracebackType | None,
+    ) -> Literal[False]:
+        self._engine.exit_block(start=self._block_starts.pop(), exception=exc)
+        return False
+
+    async def __aenter__(self) -> Self:
+        self._block_starts.append(self._engine.enter_block())
+        return self
+
+    async def __aexit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        _traceback: TracebackType | None,
+    ) -> Literal[False]:
+        self._engine.exit_block(start=self._block_starts.pop(), exception=exc)
+        return False

interlock/config.py

@@ -0,0 +1,69 @@
+"""Immutable circuit breaker configuration with eager validation."""
+
+from dataclasses import dataclass
+
+from interlock.window import WindowType
+
+__all__ = ('Config',)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class Config:
+    """Thresholds, window and timing for a circuit breaker.
+
+    Reusable across breakers: the registry shares one config and overrides per
+    name. Failure classification (which exceptions/results count) is a separate
+    concern, handled by the ``FailureClassifier``, not here.
+
+    Defaults follow resilience4j: trip at 50% failures over at least 10 calls,
+    treat calls slower than 60s as slow (but never trip on slowness alone until
+    tuned), stay open 60s before a single probe is allowed.
+
+    Raises:
+        ValueError: If any value is out of range or inconsistent.
+    """
+
+    failure_rate_threshold: float = 0.5
+    minimum_number_of_calls: int = 10
+    slow_call_duration_threshold: float = 60.0
+    slow_call_rate_threshold: float = 1.0
+    permitted_calls_in_half_open: int = 10
+    max_concurrent_probes: int = 1
+    wait_duration_in_open: float = 60.0
+    window_type: WindowType = WindowType.COUNT_BASED
+    window_size: int = 100
+
+    def __post_init__(self) -> None:
+        if not 0.0 < self.failure_rate_threshold <= 1.0:
+            raise ValueError(
+                f'failure_rate_threshold must be in (0, 1], got {self.failure_rate_threshold!r}'
+            )
+        if not 0.0 < self.slow_call_rate_threshold <= 1.0:
+            raise ValueError(
+                f'slow_call_rate_threshold must be in (0, 1], got {self.slow_call_rate_threshold!r}'
+            )
+        if self.minimum_number_of_calls < 1:
+            raise ValueError(
+                f'minimum_number_of_calls must be >= 1, got {self.minimum_number_of_calls!r}'
+            )
+        if self.slow_call_duration_threshold <= 0.0:
+            raise ValueError(
+                f'slow_call_duration_threshold must be > 0, '
+                f'got {self.slow_call_duration_threshold!r}'
+            )
+        if self.wait_duration_in_open <= 0.0:
+            raise ValueError(
+                f'wait_duration_in_open must be > 0, got {self.wait_duration_in_open!r}'
+            )
+        if self.permitted_calls_in_half_open < 1:
+            raise ValueError(
+                f'permitted_calls_in_half_open must be >= 1, '
+                f'got {self.permitted_calls_in_half_open!r}'
+            )
+        if not 1 <= self.max_concurrent_probes <= self.permitted_calls_in_half_open:
+            raise ValueError(
+                f'max_concurrent_probes must be in [1, {self.permitted_calls_in_half_open}], '
+                f'got {self.max_concurrent_probes!r}'
+            )
+        if self.window_size < 1:
+            raise ValueError(f'window_size must be >= 1, got {self.window_size!r}')

interlock/errors.py

@@ -0,0 +1,72 @@
+"""Exception and warning hierarchy for interlock."""
+
+__all__ = (
+    'CallTimeoutError',
+    'CircuitOpenError',
+    'InterlockDeprecationWarning',
+    'InterlockError',
+)
+
+
+class InterlockError(Exception):
+    """Base class for all errors raised by interlock."""
+
+
+class CircuitOpenError(InterlockError):
+    """Raised when a call is rejected because the circuit is not closed.
+
+    Carries enough context to act on the rejection without inspecting the
+    breaker: which breaker rejected the call, roughly how long until the next
+    probe is allowed, and the most recent recorded failure (if any).
+
+    Args:
+        breaker_name: Name of the breaker that rejected the call.
+        retry_after: Seconds until the next probe is allowed, or ``None`` when
+            the breaker cannot estimate it (e.g. ``FORCED_OPEN``).
+        last_failure: The most recent recorded failure, if any.
+    """
+
+    def __init__(
+        self,
+        breaker_name: str,
+        *,
+        retry_after: float | None = None,
+        last_failure: BaseException | None = None,
+    ) -> None:
+        self.breaker_name = breaker_name
+        self.retry_after = retry_after
+        self.last_failure = last_failure
+
+        super().__init__(self._build_message())
+
+    def _build_message(self) -> str:
+        message = f'Circuit {self.breaker_name!r} is open'
+        if self.retry_after is not None:
+            message = f'{message}; retry in ~{self.retry_after:.3f}s'
+
+        return message
+
+
+class CallTimeoutError(InterlockError):
+    """Raised when a guarded operation exceeds its timeout deadline.
+
+    A call that hangs forever would never be counted as slow or failed — it just
+    holds a resource; the timeout converts it into a failure a surrounding
+    breaker can observe.
+
+    Args:
+        timeout: The deadline, in seconds, that was exceeded.
+    """
+
+    def __init__(self, timeout: float) -> None:
+        self.timeout = timeout
+        message = f'Operation exceeded its {timeout:.3f}s timeout'
+        super().__init__(message)
+
+
+class InterlockDeprecationWarning(UserWarning):
+    """Deprecation warning that is visible by default.
+
+    Subclasses ``UserWarning`` rather than ``DeprecationWarning`` so it is
+    shown to end users without enabling the deprecation filter.
+    """

interlock/httpx2.py

@@ -0,0 +1,158 @@
+"""httpx2 transport integration — requires the ``httpx2`` extra.
+
+This module imports ``httpx2`` and is deliberately *not* re-exported from
+``interlock`` so the core stays zero-dependency. Install with
+``pip install interlock[httpx2]`` and wrap your transport explicitly::
+
+    import httpx2
+    from interlock.httpx2 import CircuitBreakerTransport
+
+    transport = CircuitBreakerTransport(httpx2.HTTPTransport())
+    client = httpx2.Client(transport=transport)
+
+The wrapper applies one circuit breaker **per host** transparently: no
+decorators in user code. Each host gets its own breaker (a slow or failing
+``api.a`` must not trip ``api.b``), created lazily and shared across requests.
+
+By default a response counts as a failure when its status is one of
+``HttpStatusClassifier``'s — the canonical retryable set ``429, 500, 502, 503,
+504`` — and any transport exception (connect/read errors) is a failure. Supply
+a custom ``classifier`` to change that policy.
+"""
+
+import http
+from typing import cast
+
+from httpx2 import AsyncBaseTransport, BaseTransport, Request, Response
+from interlock.config import Config
+from interlock.protocols import Clock, EventListener, FailureClassifier
+from interlock.registry import Registry
+
+__all__ = (
+    'AsyncCircuitBreakerTransport',
+    'CircuitBreakerTransport',
+    'HttpStatusClassifier',
+)
+
+# Mirrors urllib3's recommended ``status_forcelist`` (also used by AWS/Google):
+# transient server-side conditions where the dependency is unhealthy or
+# overloaded. Permanent 5xx (501 Not Implemented, 505) are excluded — retrying
+# or tripping the breaker cannot help a contract/protocol error.
+_FAILURE_STATUSES = frozenset(
+    {
+        http.HTTPStatus.TOO_MANY_REQUESTS,  # 429
+        http.HTTPStatus.INTERNAL_SERVER_ERROR,  # 500
+        http.HTTPStatus.BAD_GATEWAY,  # 502
+        http.HTTPStatus.SERVICE_UNAVAILABLE,  # 503
+        http.HTTPStatus.GATEWAY_TIMEOUT,  # 504
+    }
+)
+
+
+class HttpStatusClassifier:
+    """Counts transport exceptions and unhealthy-status responses as failures.
+
+    A returned response is a failure when its status is in the canonical
+    retryable set (``429, 500, 502, 503, 504``); any raised exception is a
+    failure. Other responses — including ``4xx`` client mistakes like ``404`` —
+    are successes, so they never trip the breaker.
+    """
+
+    def is_failure(self, *, result: object, exception: BaseException | None) -> bool:
+        """Return whether a completed request counts as a failure."""
+        if exception is not None:
+            return True
+
+        return cast('Response', result).status_code in _FAILURE_STATUSES
+
+
+def _build_registry(
+    config: Config | None,
+    clock: Clock | None,
+    classifier: FailureClassifier | None,
+    listener: EventListener | None,
+) -> Registry:
+    return Registry(
+        config=config,
+        clock=clock,
+        classifier=classifier if classifier is not None else HttpStatusClassifier(),
+        listener=listener,
+    )
+
+
+class CircuitBreakerTransport(BaseTransport):
+    """A synchronous transport that guards each host with a circuit breaker.
+
+    Args:
+        transport: The wrapped transport that performs the actual request.
+        config: Thresholds, window and timing for every host's breaker.
+        clock: Time source for the breakers; inject a fake for deterministic
+            tests.
+        classifier: Failure policy. Defaults to ``HttpStatusClassifier``.
+        listener: Observability hooks shared by every host's breaker.
+    """
+
+    def __init__(
+        self,
+        transport: BaseTransport,
+        *,
+        config: Config | None = None,
+        clock: Clock | None = None,
+        classifier: FailureClassifier | None = None,
+        listener: EventListener | None = None,
+    ) -> None:
+        self._transport = transport
+        self._registry = _build_registry(config, clock, classifier, listener)
+
+    def handle_request(self, request: Request) -> Response:
+        """Run the request under its host's breaker.
+
+        Raises:
+            CircuitOpenError: If the host's breaker is open.
+        """
+        breaker = self._registry.get(request.url.host)
+        guarded = breaker(self._transport.handle_request)
+        return guarded(request)
+
+    def close(self) -> None:
+        """Close the wrapped transport, releasing its connection pool."""
+        self._transport.close()
+
+
+class AsyncCircuitBreakerTransport(AsyncBaseTransport):
+    """An asynchronous transport that guards each host with a circuit breaker.
+
+    Args:
+        transport: The wrapped async transport that performs the request.
+        config: Thresholds, window and timing for every host's breaker.
+        clock: Time source for the breakers; inject a fake for deterministic
+            tests.
+        classifier: Failure policy. Defaults to ``HttpStatusClassifier``.
+        listener: Observability hooks shared by every host's breaker.
+    """
+
+    def __init__(
+        self,
+        transport: AsyncBaseTransport,
+        *,
+        config: Config | None = None,
+        clock: Clock | None = None,
+        classifier: FailureClassifier | None = None,
+        listener: EventListener | None = None,
+    ) -> None:
+        self._transport = transport
+        self._registry = _build_registry(config, clock, classifier, listener)
+
+    async def handle_async_request(self, request: Request) -> Response:
+        """Run the request under its host's breaker.
+
+        Raises:
+            CircuitOpenError: If the host's breaker is open.
+        """
+        breaker = self._registry.get(request.url.host)
+        guarded = breaker(self._transport.handle_async_request)
+        return await guarded(request)
+
+    async def aclose(self) -> None:
+        """Close the wrapped transport, releasing its connection pool."""
+        await self._transport.aclose()

interlock/listeners.py

@@ -0,0 +1,38 @@
+"""Built-in ``EventListener`` implementations (zero-dependency)."""
+
+import logging
+
+from interlock.outcome import Outcome
+from interlock.state import State
+
+__all__ = ('LoggingEventListener',)
+
+
+class LoggingEventListener:
+    """An ``EventListener`` that logs every breaker event via stdlib logging.
+
+    State changes and rejections log at ``WARNING`` (operationally significant),
+    resets at ``INFO``, and individual calls at ``DEBUG`` (high volume).
+
+    Args:
+        logger: Logger to write to. Defaults to ``logging.getLogger('interlock')``.
+    """
+
+    def __init__(self, logger: logging.Logger | None = None) -> None:
+        self._log = logger if logger is not None else logging.getLogger('interlock')
+
+    def on_state_change(self, *, name: str, old: State, new: State) -> None:
+        """Log a state transition at WARNING."""
+        self._log.warning('circuit %r: state %s -> %s', name, old, new)
+
+    def on_call(self, *, name: str, outcome: Outcome, duration: float) -> None:
+        """Log a completed call at DEBUG."""
+        self._log.debug('circuit %r: call %s in %.3fs', name, outcome, duration)
+
+    def on_rejected(self, *, name: str) -> None:
+        """Log a rejected call at WARNING."""
+        self._log.warning('circuit %r: call rejected (open)', name)
+
+    def on_reset(self, *, name: str) -> None:
+        """Log a manual reset at INFO."""
+        self._log.info('circuit %r: reset', name)

interlock/otel.py

@@ -0,0 +1,64 @@
+"""OpenTelemetry metrics adapter — requires the ``otel`` extra.
+
+This module imports ``opentelemetry`` and is deliberately *not* re-exported from
+``interlock`` so the core stays zero-dependency. Install with
+``pip install interlock[otel]`` and import explicitly::
+
+    from interlock.otel import OTelEventListener
+
+It maps breaker events onto three instruments: a duration histogram per call, a
+counter of rejected calls, and a counter of state transitions (plus resets).
+"""
+
+from opentelemetry import metrics
+from opentelemetry.metrics import Meter
+
+from interlock.outcome import Outcome
+from interlock.state import State
+
+__all__ = ('OTelEventListener',)
+
+
+class OTelEventListener:
+    """Records breaker events as OpenTelemetry metrics.
+
+    Args:
+        meter: Meter to create instruments on. Defaults to
+            ``opentelemetry.metrics.get_meter('interlock')``.
+    """
+
+    def __init__(self, meter: Meter | None = None) -> None:
+        meter = meter if meter is not None else metrics.get_meter('interlock')
+        self._calls = meter.create_histogram(
+            'interlock.call.duration',
+            unit='s',
+            description='Duration of protected calls.',
+        )
+        self._rejected = meter.create_counter(
+            'interlock.call.rejected',
+            description='Calls rejected because the circuit was open.',
+        )
+        self._state_changes = meter.create_counter(
+            'interlock.state.changes',
+            description='Circuit breaker state transitions.',
+        )
+        self._resets = meter.create_counter(
+            'interlock.reset',
+            description='Manual breaker resets.',
+        )
+
+    def on_state_change(self, *, name: str, old: State, new: State) -> None:
+        """Count a state transition, labelled with the breaker and direction."""
+        self._state_changes.add(1, {'breaker': name, 'from': str(old), 'to': str(new)})
+
+    def on_call(self, *, name: str, outcome: Outcome, duration: float) -> None:
+        """Record the call's duration, labelled with the breaker and outcome."""
+        self._calls.record(duration, {'breaker': name, 'outcome': str(outcome)})
+
+    def on_rejected(self, *, name: str) -> None:
+        """Count a rejected call, labelled with the breaker."""
+        self._rejected.add(1, {'breaker': name})
+
+    def on_reset(self, *, name: str) -> None:
+        """Count a manual reset, labelled with the breaker."""
+        self._resets.add(1, {'breaker': name})