httpware 0.9.0__tar.gz → 0.10.0__tar.gz

{httpware-0.9.0 → httpware-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.9.0
+Version: 0.10.0
 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.
 
@@ -80,7 +80,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
+Typed decoding via `response_model=` works in both worlds — install either `pip install httpware[pydantic]` or `pip install httpware[msgspec]` (or both; pydantic is tried first when both are present). Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient
@@ -146,16 +146,18 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## 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.WARNING)
+logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
 ```
 
 For OTel attribute enrichment on the active span — install the extra:

{httpware-0.9.0 → httpware-0.10.0}/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.
 
@@ -50,7 +50,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
+Typed decoding via `response_model=` works in both worlds — install either `pip install httpware[pydantic]` or `pip install httpware[msgspec]` (or both; pydantic is tried first when both are present). Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient
@@ -116,16 +116,18 @@ All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `Se
 
 ## 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.WARNING)
+logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
 ```
 
 For OTel attribute enrichment on the active span — install the extra:

{httpware-0.9.0 → httpware-0.10.0}/pyproject.toml

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

{httpware-0.9.0 → httpware-0.10.0}/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.0 → httpware-0.10.0}/src/httpware/decoders/__init__.py

@@ -19,6 +19,13 @@ class ResponseDecoder(Protocol):
         list ordering encodes the caller's preference for shared shapes.
         Native types of another library (e.g. `PydanticDecoder` vs
         `msgspec.Struct`) MUST be rejected.
+
+        `can_decode` MUST NOT raise. It runs at dispatch time — before the HTTP
+        call and outside the `DecodeError` wrap that protects `decode` — so an
+        exception here escapes the `ClientError` contract rather than being
+        translated. A decoder that cannot determine support for `model` must
+        return False (decline), not raise; the built-in decoders treat any
+        probe failure as False.
         """
         ...
 

httpware-0.10.0/src/httpware/decoders/msgspec.py

@@ -0,0 +1,116 @@
+"""MsgspecDecoder — opt-in ResponseDecoder backed by a per-instance msgspec.json.Decoder cache."""
+
+import typing
+from typing import TypeVar
+
+from httpware._internal import import_checker
+
+
+if import_checker.is_msgspec_installed:
+    import msgspec
+
+
+MISSING_DEPENDENCY_MESSAGE = "MsgspecDecoder requires the 'msgspec' extra. Install with: pip install httpware[msgspec]"
+
+T = TypeVar("T")
+
+
+def _contains_custom_type(info: "msgspec.inspect.Type") -> bool:
+    """Return True if `info` is a CustomType or nests one in its parameters.
+
+    Walks generic-container parameterization (list/dict/set/tuple/union element
+    types) by visiting any attribute that is itself a `msgspec.inspect.Type` or a
+    tuple of them. It deliberately does NOT descend into `StructType`/dataclass
+    fields: those expose `fields` as `Field` objects (not `Type`), so the walk
+    stops at the boundary of a type msgspec natively owns. That boundary is what
+    makes the walk both correct (a Struct is a valid target) and safe against
+    infinite recursion on self-referential struct definitions.
+    """
+    if isinstance(info, msgspec.inspect.CustomType):
+        return True
+    for name in dir(info):
+        if name.startswith("_"):
+            continue
+        value = getattr(info, name, None)
+        if isinstance(value, msgspec.inspect.Type):
+            if _contains_custom_type(value):
+                return True
+        elif (
+            isinstance(value, tuple)
+            and value
+            and all(isinstance(item, msgspec.inspect.Type) for item in value)
+            and any(_contains_custom_type(item) for item in value)
+        ):
+            return True
+    return False
+
+
+class MsgspecDecoder:
+    """Decode raw response bytes via a per-instance cached `msgspec.json.Decoder(model)`.
+
+    Requires the `msgspec` extra: `pip install httpware[msgspec]`. Importing
+    this module without the extra works (the `msgspec` import is guarded by a
+    `find_spec` check), but instantiating the decoder raises `ImportError`.
+    """
+
+    _msgspec_decoders: dict[type, "msgspec.json.Decoder[typing.Any]"]
+    _can_decode_results: dict[type, bool]
+
+    def __init__(self) -> None:
+        if not import_checker.is_msgspec_installed:
+            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
+        self._msgspec_decoders = {}
+        self._can_decode_results = {}
+
+    def _get_msgspec_decoder(self, model: type[T]) -> "msgspec.json.Decoder[T]":
+        decoder = self._msgspec_decoders.get(model)
+        if decoder is None:
+            decoder = msgspec.json.Decoder(model)
+            self._msgspec_decoders[model] = decoder
+        return decoder
+
+    def can_decode(self, model: type) -> bool:
+        """Return True iff msgspec natively understands `model` end-to-end.
+
+        The verdict is memoized per `model`: the probe below (an uncached
+        `type_info` call plus a recursive tree walk) runs once per type, not on
+        every dispatch. Unhashable models skip the cache and probe fresh.
+        """
+        try:
+            cached = self._can_decode_results.get(model)
+        except TypeError:  # unhashable model — can't memoize, probe fresh
+            return self._probe_can_decode(model)
+        if cached is not None:
+            return cached
+        result = self._probe_can_decode(model)
+        self._can_decode_results[model] = result
+        return result
+
+    def _probe_can_decode(self, model: type) -> bool:
+        """Decide whether msgspec natively decodes `model` (the uncached path).
+
+        msgspec builds a Decoder for almost any class via a generic CustomType
+        fallback; the Decoder constructor does NOT raise on unsupported types
+        (e.g. pydantic.BaseModel, or a container parameterized by one). We walk
+        msgspec.inspect.type_info and reject if a CustomType appears anywhere in
+        the type tree, so MissingDecoderError fires before a request is sent.
+        """
+        try:
+            info = msgspec.inspect.type_info(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        if _contains_custom_type(info):
+            return False
+        try:
+            self._get_msgspec_decoder(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        return True
+
+    def decode(self, content: bytes, model: type[T]) -> T:
+        """Validate `content` as JSON against `model` in a single parse pass."""
+        try:
+            decoder = self._get_msgspec_decoder(model)
+        except TypeError:
+            decoder = msgspec.json.Decoder(model)
+        return decoder.decode(content)

{httpware-0.9.0 → httpware-0.10.0}/src/httpware/decoders/pydantic.py

@@ -26,11 +26,13 @@ class PydanticDecoder:
     """Decode raw response bytes into `model` via a per-instance cached `pydantic.TypeAdapter`."""
 
     _adapters: dict[type, TypeAdapter[typing.Any]]
+    _can_decode_results: dict[type, bool]
 
     def __init__(self) -> None:
         if not import_checker.is_pydantic_installed:
             raise ImportError(MISSING_DEPENDENCY_MESSAGE)
         self._adapters = {}
+        self._can_decode_results = {}
 
     def _get_adapter(self, model: type[T]) -> "TypeAdapter[T]":
         adapter = self._adapters.get(model)
@@ -42,6 +44,23 @@ class PydanticDecoder:
     def can_decode(self, model: type) -> bool:
         """Return True iff pydantic can build a schema for `model`.
 
+        The verdict is memoized per `model` so a rejection (which costs a
+        `PydanticSchemaGenerationError` round-trip) is not re-probed on every
+        dispatch. Unhashable models skip the cache and probe fresh.
+        """
+        try:
+            cached = self._can_decode_results.get(model)
+        except TypeError:  # unhashable model — can't memoize, probe fresh
+            return self._probe_can_decode(model)
+        if cached is not None:
+            return cached
+        result = self._probe_can_decode(model)
+        self._can_decode_results[model] = result
+        return result
+
+    def _probe_can_decode(self, model: type) -> bool:
+        """Decide whether pydantic can build a schema for `model` (uncached).
+
         Probes via `_get_adapter`; subsequent calls (including `decode`) reuse
         the cached `TypeAdapter`. Rejects `msgspec.Struct` subclasses —
         pydantic raises `PydanticSchemaGenerationError` (a `TypeError`) when

{httpware-0.9.0 → httpware-0.10.0}/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.0/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.0/src/httpware/middleware/resilience/circuit_breaker.py

@@ -0,0 +1,302 @@
+"""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.
+
+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.0/src/httpware/middleware/resilience/timeout.py

@@ -0,0 +1,75 @@
+"""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 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 > 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 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.0/src/httpware/decoders/msgspec.py

@@ -1,66 +0,0 @@
-"""MsgspecDecoder — opt-in ResponseDecoder backed by a per-instance msgspec.json.Decoder cache."""
-
-import typing
-from typing import TypeVar
-
-from httpware._internal import import_checker
-
-
-if import_checker.is_msgspec_installed:
-    import msgspec
-
-
-MISSING_DEPENDENCY_MESSAGE = "MsgspecDecoder requires the 'msgspec' extra. Install with: pip install httpware[msgspec]"
-
-T = TypeVar("T")
-
-
-class MsgspecDecoder:
-    """Decode raw response bytes via a per-instance cached `msgspec.json.Decoder(model)`.
-
-    Requires the `msgspec` extra: `pip install httpware[msgspec]`. Importing
-    this module without the extra works (the `msgspec` import is guarded by a
-    `find_spec` check), but instantiating the decoder raises `ImportError`.
-    """
-
-    _msgspec_decoders: dict[type, "msgspec.json.Decoder[typing.Any]"]
-
-    def __init__(self) -> None:
-        if not import_checker.is_msgspec_installed:
-            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
-        self._msgspec_decoders = {}
-
-    def _get_msgspec_decoder(self, model: type[T]) -> "msgspec.json.Decoder[T]":
-        decoder = self._msgspec_decoders.get(model)
-        if decoder is None:
-            decoder = msgspec.json.Decoder(model)
-            self._msgspec_decoders[model] = decoder
-        return decoder
-
-    def can_decode(self, model: type) -> bool:
-        """Return True iff msgspec natively understands `model`.
-
-        msgspec builds a Decoder for almost any class via a generic CustomType
-        fallback; the Decoder constructor itself does NOT raise on unsupported
-        types (e.g. pydantic.BaseModel). We use msgspec.inspect.type_info
-        to detect the fallback and reject CustomType results explicitly.
-        """
-        try:
-            info = msgspec.inspect.type_info(model)
-        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
-            return False
-        if isinstance(info, msgspec.inspect.CustomType):
-            return False
-        try:
-            self._get_msgspec_decoder(model)
-        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
-            return False
-        return True
-
-    def decode(self, content: bytes, model: type[T]) -> T:
-        """Validate `content` as JSON against `model` in a single parse pass."""
-        try:
-            decoder = self._get_msgspec_decoder(model)
-        except TypeError:
-            decoder = msgspec.json.Decoder(model)
-        return decoder.decode(content)

httpware-0.9.0/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"]