httpware 0.9.1__tar.gz → 0.10.1__tar.gz

{httpware-0.9.1 → httpware-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.9.1
+Version: 0.10.1
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 **A Python HTTP client framework with sync and async clients for building resilient service clients.**
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry`/`Retry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead`/`Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a resilience suite under `httpware.middleware.resilience` — `AsyncRetry`/`Retry` with a Finagle-style `RetryBudget`, `AsyncBulkhead`/`Bulkhead` concurrency limiter, `AsyncCircuitBreaker`/`CircuitBreaker` consecutive-failure breaker, and `AsyncTimeout` for overall-operation wall-clock bounds.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -142,20 +142,22 @@ It does NOT pass through the middleware chain: `AsyncRetry`, `AsyncBulkhead`, an
 
 ## Errors
 
-All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.
+All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError`, `BulkheadFullError`, and `CircuitOpenError`. Everything inherits `httpware.ClientError`.
 
 ## Observability
 
-`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
+All resilience middleware emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
-Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
+Logger names and event names are the stable public contract: `httpware.retry` (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`), `httpware.bulkhead` (`bulkhead.rejected`), `httpware.circuit_breaker` (`circuit.opened`, `circuit.rejected`, `circuit.half_open`, `circuit.closed`), and `httpware.timeout` (`timeout.exceeded`).
 
 ```python
 import logging
 
-# Enable visibility into retry / bulkhead operational events
+# Enable visibility into resilience operational events
 logging.getLogger("httpware.retry").setLevel(logging.WARNING)
 logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+logging.getLogger("httpware.circuit_breaker").setLevel(logging.INFO)   # INFO: includes recovery events (half_open, closed)
+logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
 ```
 
 For OTel attribute enrichment on the active span — install the extra:

{httpware-0.9.1 → httpware-0.10.1}/README.md

@@ -7,7 +7,7 @@
 
 **A Python HTTP client framework with sync and async clients for building resilient service clients.**
 
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `AsyncRetry`/`Retry` middleware with a Finagle-style `RetryBudget`, plus an `AsyncBulkhead`/`Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
+`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a resilience suite under `httpware.middleware.resilience` — `AsyncRetry`/`Retry` with a Finagle-style `RetryBudget`, `AsyncBulkhead`/`Bulkhead` concurrency limiter, `AsyncCircuitBreaker`/`CircuitBreaker` consecutive-failure breaker, and `AsyncTimeout` for overall-operation wall-clock bounds.
 
 > **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
@@ -112,20 +112,22 @@ It does NOT pass through the middleware chain: `AsyncRetry`, `AsyncBulkhead`, an
 
 ## Errors
 
-All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.
+All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError`, `BulkheadFullError`, and `CircuitOpenError`. Everything inherits `httpware.ClientError`.
 
 ## Observability
 
-`AsyncRetry`/`Retry` and `AsyncBulkhead`/`Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
+All resilience middleware emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
 
-Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
+Logger names and event names are the stable public contract: `httpware.retry` (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`), `httpware.bulkhead` (`bulkhead.rejected`), `httpware.circuit_breaker` (`circuit.opened`, `circuit.rejected`, `circuit.half_open`, `circuit.closed`), and `httpware.timeout` (`timeout.exceeded`).
 
 ```python
 import logging
 
-# Enable visibility into retry / bulkhead operational events
+# Enable visibility into resilience operational events
 logging.getLogger("httpware.retry").setLevel(logging.WARNING)
 logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+logging.getLogger("httpware.circuit_breaker").setLevel(logging.INFO)   # INFO: includes recovery events (half_open, closed)
+logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
 ```
 
 For OTel attribute enrichment on the active span — install the extra:

{httpware-0.9.1 → httpware-0.10.1}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.9.1"
+version = "0.10.1"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]

{httpware-0.9.1 → httpware-0.10.1}/src/httpware/__init__.py

@@ -6,6 +6,7 @@ from httpware.errors import (
     STATUS_TO_EXCEPTION,
     BadRequestError,
     BulkheadFullError,
+    CircuitOpenError,
     ClientError,
     ClientStatusError,
     ConflictError,
@@ -37,19 +38,32 @@ from httpware.middleware import (
     before_request,
     on_error,
 )
-from httpware.middleware.resilience import AsyncBulkhead, AsyncRetry, Bulkhead, Retry, RetryBudget
+from httpware.middleware.resilience import (
+    AsyncBulkhead,
+    AsyncCircuitBreaker,
+    AsyncRetry,
+    AsyncTimeout,
+    Bulkhead,
+    CircuitBreaker,
+    Retry,
+    RetryBudget,
+)
 
 
 __all__ = [
     "STATUS_TO_EXCEPTION",
     "AsyncBulkhead",
+    "AsyncCircuitBreaker",
     "AsyncClient",
     "AsyncMiddleware",
     "AsyncNext",
     "AsyncRetry",
+    "AsyncTimeout",
     "BadRequestError",
     "Bulkhead",
     "BulkheadFullError",
+    "CircuitBreaker",
+    "CircuitOpenError",
     "Client",
     "ClientError",
     "ClientStatusError",

{httpware-0.9.1 → httpware-0.10.1}/src/httpware/_internal/observability.py

@@ -2,11 +2,13 @@
 
 See planning/specs/2026-06-05-observability-design.md for the contract.
 
-Logger names (``httpware.retry``, ``httpware.bulkhead``) and event names
-(``retry.giving_up``, ``bulkhead.rejected``, etc.) are the public observability
+Logger names (``httpware.retry``, ``httpware.bulkhead``, ``httpware.circuit_breaker``,
+``httpware.timeout``) and event names (``retry.giving_up``, ``bulkhead.rejected``,
+``circuit.opened``, ``timeout.exceeded``, etc.) are the public observability
 surface. They are stable: renames are breaking changes.
 """
 
+import contextlib
 import logging
 import typing
 
@@ -37,7 +39,7 @@ def _emit_event(
     the optional-extras isolation invariant: ``import httpware`` must not pull
     ``opentelemetry`` into ``sys.modules`` when the extra is absent.
     """
-    logger.log(level, message, extra=attributes)
+    logger.log(level, message, extra={**attributes, "event": event_name})
     if import_checker.is_otel_installed:
         try:
             from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
@@ -45,4 +47,9 @@ def _emit_event(
             # opentelemetry namespace exists but the api package is broken or missing —
             # degrade to log-only emission. The structured log record above has already fired.
             return
-        trace.get_current_span().add_event(event_name, attributes=attributes)
+        # Observability must never break the request path — suppress any failure from
+        # add_event (e.g. a recording span with a broken exporter or attribute validation).
+        # The structured log record above has already fired; CancelledError/KeyboardInterrupt
+        # are not Exception subclasses and will still propagate.
+        with contextlib.suppress(Exception):
+            trace.get_current_span().add_event(event_name, attributes=attributes)

{httpware-0.9.1 → httpware-0.10.1}/src/httpware/errors.py

@@ -214,6 +214,35 @@ class BulkheadFullError(ClientError):
         )
 
 
+def _reconstruct_circuit_open(
+    cls: "type[CircuitOpenError]",
+    retry_after: float | None,
+) -> "CircuitOpenError":
+    return cls(retry_after=retry_after)
+
+
+class CircuitOpenError(ClientError):
+    """Raised when a CircuitBreaker refuses a request because the circuit is not closed.
+
+    Fires when the circuit is OPEN, or when it is HALF_OPEN and the single probe
+    slot is already taken. The request is never forwarded to ``next``. ``retry_after``
+    carries the seconds until the circuit will next admit a probe, when known
+    (``None`` when a concurrent probe is already in flight).
+    """
+
+    retry_after: float | None
+
+    def __init__(self, *, retry_after: float | None) -> None:
+        self.retry_after = retry_after
+        if retry_after is None:
+            super().__init__("circuit open (a probe request is already in flight)")
+        else:
+            super().__init__(f"circuit open (retry_after={retry_after:.3f}s)")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (_reconstruct_circuit_open, (type(self), self.retry_after))
+
+
 def _reconstruct_decode_error(
     cls: "type[DecodeError]",
     response: httpx2.Response,

httpware-0.10.1/src/httpware/middleware/resilience/__init__.py

@@ -0,0 +1,19 @@
+"""Resilience middleware: Bulkhead, CircuitBreaker, Retry, RetryBudget, and their Async counterparts + AsyncTimeout."""
+
+from httpware.middleware.resilience.budget import RetryBudget
+from httpware.middleware.resilience.bulkhead import AsyncBulkhead, Bulkhead
+from httpware.middleware.resilience.circuit_breaker import AsyncCircuitBreaker, CircuitBreaker
+from httpware.middleware.resilience.retry import AsyncRetry, Retry
+from httpware.middleware.resilience.timeout import AsyncTimeout
+
+
+__all__ = [
+    "AsyncBulkhead",
+    "AsyncCircuitBreaker",
+    "AsyncRetry",
+    "AsyncTimeout",
+    "Bulkhead",
+    "CircuitBreaker",
+    "Retry",
+    "RetryBudget",
+]

httpware-0.10.1/src/httpware/middleware/resilience/circuit_breaker.py

@@ -0,0 +1,305 @@
+"""CircuitBreaker + AsyncCircuitBreaker — classic consecutive-failure circuit breaker.
+
+See planning/specs/2026-06-13-circuit-breaker-and-timeout-design.md for the contract.
+
+A counted failure is a NetworkError, an httpware TimeoutError, or a StatusError whose
+status_code is in the effective failure set (default: all 5xx). 4xx — including 429 —
+count as successes: 429 means healthy-but-throttling, and tripping on it amplifies
+incidents. Any other exception propagates without affecting circuit state. In
+particular, non-NetworkError transport problems — e.g. httpx2.InvalidURL from a
+malformed URL — are foreign: they propagate unchanged and do not increment the
+failure counter, so programming errors cannot trip the breaker.
+
+State machine (classic / consecutive-failure):
+    CLOSED    — forward; count consecutive counted-failures; open at failure_threshold.
+    OPEN      — fast-fail with CircuitOpenError; after reset_timeout the next request
+                becomes the half-open probe.
+    HALF_OPEN — admit exactly one probe at a time; success_threshold consecutive probe
+                successes close the circuit; one probe failure re-opens it.
+
+The lock-free _CircuitBreakerState holds the transition logic, shared by both wrappers.
+AsyncCircuitBreaker relies on asyncio atomicity (no await inside a transition) plus a
+single-event-loop guard; CircuitBreaker (sync) serializes transitions with a
+threading.Lock. Both are sharable across clients (one shared circuit); a sync instance
+cannot be shared with an async one.
+"""
+
+import asyncio
+import enum
+import logging
+import threading
+import time
+import typing
+from collections.abc import Callable, Collection
+
+import httpx2
+
+from httpware._internal.observability import _emit_event
+from httpware.errors import CircuitOpenError, NetworkError, StatusError, TimeoutError  # noqa: A004
+from httpware.middleware import AsyncNext, Next
+
+
+_FAILURE_THRESHOLD_INVALID = "failure_threshold must be >= 1"
+_RESET_TIMEOUT_INVALID = "reset_timeout must be >= 0"
+_SUCCESS_THRESHOLD_INVALID = "success_threshold must be >= 1"
+_CROSS_LOOP_MSG = (
+    "AsyncCircuitBreaker is bound to a single event loop. First seen on {first!r}; "
+    "current request is on {current!r}. Use one AsyncCircuitBreaker per loop; "
+    "cross-thread sharing requires the sync CircuitBreaker primitive."
+)
+
+_DEFAULT_FAILURE_STATUS_CODES = frozenset(range(500, 600))
+
+_ROLE_CLOSED = "closed"
+_ROLE_PROBE = "probe"
+
+_LOGGER = logging.getLogger("httpware.circuit_breaker")
+
+
+class _CircuitState(enum.Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class _CircuitBreakerState:
+    """Lock-free circuit-breaker state machine shared by the sync + async wrappers.
+
+    Every method is synchronous and performs no I/O beyond logging. The async wrapper
+    calls these directly (atomic under a single event loop because no await occurs
+    inside a transition); the sync wrapper wraps each call in a threading.Lock.
+    """
+
+    def __init__(
+        self,
+        *,
+        failure_threshold: int,
+        reset_timeout: float,
+        success_threshold: int,
+        failure_status_codes: Collection[int] | None,
+        now: Callable[[], float],
+    ) -> None:
+        if failure_threshold < 1:
+            raise ValueError(_FAILURE_THRESHOLD_INVALID)
+        if reset_timeout < 0:
+            raise ValueError(_RESET_TIMEOUT_INVALID)
+        if success_threshold < 1:
+            raise ValueError(_SUCCESS_THRESHOLD_INVALID)
+        self._failure_threshold = failure_threshold
+        self._reset_timeout = reset_timeout
+        self._success_threshold = success_threshold
+        # Accept any Collection (set, frozenset, list, ...) and freeze it so callers
+        # aren't forced to construct a frozenset just to satisfy the type checker.
+        self._failure_status_codes = (
+            frozenset(failure_status_codes) if failure_status_codes is not None else _DEFAULT_FAILURE_STATUS_CODES
+        )
+        self._now = now
+        self._state = _CircuitState.CLOSED
+        self._consecutive_failures = 0
+        self._consecutive_successes = 0
+        self._opened_at = 0.0
+        self._probe_in_flight = False
+
+    def is_failure_status(self, status_code: int) -> bool:
+        return status_code in self._failure_status_codes
+
+    def admit(self, request: httpx2.Request) -> str:
+        """Decide the request's role, or raise CircuitOpenError. No await inside."""
+        if self._state is _CircuitState.CLOSED:
+            return _ROLE_CLOSED
+        if self._state is _CircuitState.OPEN:
+            elapsed = self._now() - self._opened_at
+            if elapsed >= self._reset_timeout:
+                self._state = _CircuitState.HALF_OPEN
+                self._probe_in_flight = True
+                self._emit(request, "circuit.half_open", logging.INFO, "circuit half-open — admitting probe", {})
+                return _ROLE_PROBE
+            retry_after = max(0.0, self._reset_timeout - elapsed)
+            self._emit(
+                request,
+                "circuit.rejected",
+                logging.WARNING,
+                "circuit open — rejecting request",
+                {"retry_after": retry_after},
+            )
+            raise CircuitOpenError(retry_after=retry_after)
+        # HALF_OPEN
+        if self._probe_in_flight:
+            self._emit(
+                request,
+                "circuit.rejected",
+                logging.WARNING,
+                "circuit half-open — rejecting request (probe in flight)",
+                {"retry_after": None},
+            )
+            raise CircuitOpenError(retry_after=None)
+        self._probe_in_flight = True
+        return _ROLE_PROBE
+
+    def on_success(self, role: str, request: httpx2.Request) -> None:
+        if role == _ROLE_PROBE:
+            self._probe_in_flight = False
+        if self._state is _CircuitState.CLOSED:
+            self._consecutive_failures = 0
+        elif self._state is _CircuitState.HALF_OPEN:
+            self._consecutive_successes += 1
+            if self._consecutive_successes >= self._success_threshold:
+                self._state = _CircuitState.CLOSED
+                self._consecutive_failures = 0
+                self._consecutive_successes = 0
+                self._emit(request, "circuit.closed", logging.INFO, "circuit closed — service recovered", {})
+
+    def on_failure(self, role: str, request: httpx2.Request) -> None:
+        if role == _ROLE_PROBE:
+            self._probe_in_flight = False
+        if self._state is _CircuitState.CLOSED:
+            self._consecutive_failures += 1
+            if self._consecutive_failures >= self._failure_threshold:
+                self._open(request, failures=self._consecutive_failures)
+        elif self._state is _CircuitState.HALF_OPEN:
+            self._open(request, failures=1)  # 1 = the single probe failure that re-opened the circuit
+
+    def release_probe(self, role: str) -> None:
+        """Release the probe slot without recording success or failure (non-counted exc)."""
+        if role == _ROLE_PROBE:
+            self._probe_in_flight = False
+
+    def _open(self, request: httpx2.Request, *, failures: int) -> None:
+        self._state = _CircuitState.OPEN
+        self._opened_at = self._now()
+        self._consecutive_failures = 0
+        self._consecutive_successes = 0
+        self._emit(
+            request,
+            "circuit.opened",
+            logging.WARNING,
+            "circuit opened — failure threshold reached",
+            {"failure_threshold": self._failure_threshold, "failures": failures},
+        )
+
+    def _emit(
+        self,
+        request: httpx2.Request,
+        event_name: str,
+        level: int,
+        message: str,
+        attributes: dict[str, typing.Any],
+    ) -> None:
+        _emit_event(
+            _LOGGER,
+            event_name,
+            level=level,
+            message=message,
+            attributes={**attributes, "method": request.method, "url": str(request.url)},
+        )
+
+
+class AsyncCircuitBreaker:
+    """Async classic circuit breaker middleware. See the module docstring for the contract."""
+
+    def __init__(
+        self,
+        *,
+        failure_threshold: int = 5,
+        reset_timeout: float = 30.0,
+        success_threshold: int = 1,
+        failure_status_codes: Collection[int] | None = None,
+        _now: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._state = _CircuitBreakerState(
+            failure_threshold=failure_threshold,
+            reset_timeout=reset_timeout,
+            success_threshold=success_threshold,
+            failure_status_codes=failure_status_codes,
+            now=_now,
+        )
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._loop_lock = threading.Lock()
+
+    def _check_loop(self) -> None:
+        current = asyncio.get_running_loop()
+        cached = self._loop
+        if cached is current:
+            return
+        if cached is not None:
+            raise RuntimeError(_CROSS_LOOP_MSG.format(first=cached, current=current))
+        with self._loop_lock:
+            if self._loop is None:
+                self._loop = current
+            # pragma below: inner double-check-with-lock race arm; only reachable when
+            # two threads simultaneously pass the outer check, which single-threaded
+            # tests can't trigger.
+            elif self._loop is not current:  # pragma: no cover
+                raise RuntimeError(_CROSS_LOOP_MSG.format(first=self._loop, current=current))
+
+    async def __call__(self, request: httpx2.Request, next: AsyncNext) -> httpx2.Response:  # noqa: A002
+        """Admit, forward, then record the outcome. Fast-fail when the circuit is not closed."""
+        self._check_loop()
+        role = self._state.admit(request)
+        try:
+            response = await next(request)
+        except StatusError as exc:
+            if self._state.is_failure_status(exc.response.status_code):
+                self._state.on_failure(role, request)
+            else:
+                self._state.on_success(role, request)
+            raise
+        except (NetworkError, TimeoutError):
+            self._state.on_failure(role, request)
+            raise
+        except BaseException:
+            self._state.release_probe(role)
+            raise
+        self._state.on_success(role, request)
+        return response
+
+
+class CircuitBreaker:
+    """Sync classic circuit breaker middleware. Mirror of AsyncCircuitBreaker.
+
+    Serializes every state transition with a threading.Lock. Sharable across Clients
+    (one shared circuit); a sync instance cannot be shared with an AsyncClient.
+    """
+
+    def __init__(
+        self,
+        *,
+        failure_threshold: int = 5,
+        reset_timeout: float = 30.0,
+        success_threshold: int = 1,
+        failure_status_codes: Collection[int] | None = None,
+        _now: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._state = _CircuitBreakerState(
+            failure_threshold=failure_threshold,
+            reset_timeout=reset_timeout,
+            success_threshold=success_threshold,
+            failure_status_codes=failure_status_codes,
+            now=_now,
+        )
+        self._lock = threading.Lock()
+
+    def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002
+        """Admit, forward, then record the outcome. Fast-fail when the circuit is not closed."""
+        with self._lock:
+            role = self._state.admit(request)
+        try:
+            response = next(request)
+        except StatusError as exc:
+            with self._lock:
+                if self._state.is_failure_status(exc.response.status_code):
+                    self._state.on_failure(role, request)
+                else:
+                    self._state.on_success(role, request)
+            raise
+        except (NetworkError, TimeoutError):
+            with self._lock:
+                self._state.on_failure(role, request)
+            raise
+        except BaseException:
+            with self._lock:
+                self._state.release_probe(role)
+            raise
+        with self._lock:
+            self._state.on_success(role, request)
+        return response

httpware-0.10.1/src/httpware/middleware/resilience/timeout.py

@@ -0,0 +1,76 @@
+"""AsyncTimeout middleware — overall wall-clock deadline across the inner pipeline.
+
+This is NOT a per-call timeout — httpx2's connect/read/write/pool timeouts are the
+right tool for bounding a single outbound call, and AsyncTimeout does not duplicate
+them. What httpx2 cannot bound is the total wall-clock across the whole middleware
+pipeline (most importantly across an AsyncRetry loop, whose attempts and backoff
+sleeps it knows nothing about). Place AsyncTimeout outermost to enforce
+"this whole operation must finish within `timeout` seconds, even across retries."
+
+Async-only by design: a sync total-deadline cannot interrupt a blocking httpx2 call
+mid-flight (sync Python has no cancellation), and httpx2 already covers sync per-call
+timeouts. Sync callers configure httpx2's timeouts directly; there is no sync Timeout.
+"""
+
+import asyncio
+import logging
+import math
+
+import httpx2
+
+from httpware._internal.observability import _emit_event
+from httpware.errors import TimeoutError as HttpwareTimeoutError
+from httpware.middleware import AsyncNext
+
+
+_TIMEOUT_INVALID = "timeout must be a finite number > 0"
+
+_LOGGER = logging.getLogger("httpware.timeout")
+
+
+class AsyncTimeout:
+    """Bounds total wall-clock time spent in the inner pipeline.
+
+    Parameters
+    ----------
+    timeout
+        Required. Overall deadline in seconds for ``next(request)`` to complete,
+        including everything it wraps (retries, backoff sleeps, the call itself).
+        Must be ``> 0``. On expiry the middleware raises ``httpware.TimeoutError``.
+
+    Place outermost in the chain for an overall-operation deadline. For bounding a
+    single outbound call (connect/read/write/pool), configure ``httpx2`` instead.
+
+    """
+
+    def __init__(self, *, timeout: float) -> None:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError(_TIMEOUT_INVALID)
+        self._timeout = timeout
+
+    async def __call__(self, request: httpx2.Request, next: AsyncNext) -> httpx2.Response:  # noqa: A002
+        """Invoke next under an asyncio.timeout; raise httpware.TimeoutError on expiry.
+
+        Only a deadline THIS middleware imposed is re-wrapped: ``cm.expired()``
+        distinguishes our own expiry from an inner ``TimeoutError`` (e.g. an httpx2
+        per-call timeout surfacing through a retry), which propagates unchanged.
+        """
+        try:
+            async with asyncio.timeout(self._timeout) as cm:
+                return await next(request)
+        except TimeoutError as exc:
+            if not cm.expired():
+                raise  # inner TimeoutError, not our deadline — leave it untouched
+            _emit_event(
+                _LOGGER,
+                "timeout.exceeded",
+                level=logging.WARNING,
+                message="overall timeout exceeded",
+                attributes={
+                    "timeout": self._timeout,
+                    "method": request.method,
+                    "url": str(request.url),
+                },
+            )
+            msg = f"overall timeout of {self._timeout}s exceeded"
+            raise HttpwareTimeoutError(msg) from exc

httpware-0.9.1/src/httpware/middleware/resilience/__init__.py

@@ -1,8 +0,0 @@
-"""Resilience primitives: Bulkhead/AsyncBulkhead, Retry/AsyncRetry, RetryBudget."""
-
-from httpware.middleware.resilience.budget import RetryBudget
-from httpware.middleware.resilience.bulkhead import AsyncBulkhead, Bulkhead
-from httpware.middleware.resilience.retry import AsyncRetry, Retry
-
-
-__all__ = ["AsyncBulkhead", "AsyncRetry", "Bulkhead", "Retry", "RetryBudget"]