httpware 0.3.0__tar.gz → 0.4.0__tar.gz

{httpware-0.3.0 → httpware-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.3.0
+Version: 0.4.0
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -15,17 +15,14 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Framework :: AsyncIO
 Requires-Dist: httpx2>=2.0.0,<3.0
-Requires-Dist: httpware[pydantic,msgspec,otel] ; extra == 'all'
+Requires-Dist: httpware[pydantic,msgspec] ; extra == 'all'
 Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
-Requires-Dist: opentelemetry-api>=1.20 ; extra == 'otel'
-Requires-Dist: opentelemetry-sdk>=1.20 ; extra == 'otel'
 Requires-Dist: pydantic>=2.0,<3.0 ; extra == 'pydantic'
 Requires-Python: >=3.11, <4
 Project-URL: repository, https://github.com/modern-python/httpware
 Project-URL: docs, https://httpware.readthedocs.io
 Provides-Extra: all
 Provides-Extra: msgspec
-Provides-Extra: otel
 Provides-Extra: pydantic
 Description-Content-Type: text/markdown
 
@@ -38,9 +35,9 @@ Description-Content-Type: text/markdown
 
 **Async HTTP client framework for Python.**
 
-`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.
+`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 — `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
-> **Status:** Pre-1.0 (0.3.0). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
 
 ## Install
 
@@ -48,10 +45,10 @@ Description-Content-Type: text/markdown
 pip install httpware                # core only — no decoder
 pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
 pip install httpware[msgspec]       # + MsgspecDecoder
-pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
+pip install httpware[all]           # everything declared above (pydantic, msgspec)
 ```
 
-`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing. The `otel` extra is declared but the OpenTelemetry middleware (Epic 5) has not shipped yet.
+`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
 
 ## Quickstart
 
@@ -73,7 +70,30 @@ async def main() -> None:
         print(user.name)
 ```
 
-## 📚 [Documentation](https://httpware.readthedocs.io)
+### With resilience middleware
+
+Compose resilience middleware at construction; `Bulkhead` goes outside `Retry` so one slot covers all retry attempts.
+
+```python
+from httpware import AsyncClient, Bulkhead, Retry
+
+
+async def main() -> None:
+    async with AsyncClient(
+        base_url="https://api.example.com",
+        middleware=[
+            Bulkhead(max_concurrent=10),  # cap total in-flight
+            Retry(),                       # default: 3 attempts, full-jitter backoff
+        ],
+    ) as client:
+        user = await client.get("/users/1", response_model=User)
+```
+
+## 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`.
+
+## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)
 

{httpware-0.3.0 → httpware-0.4.0}/README.md

@@ -7,9 +7,9 @@
 
 **Async HTTP client framework for Python.**
 
-`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.
+`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 — `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
-> **Status:** Pre-1.0 (0.3.0). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
 
 ## Install
 
@@ -17,10 +17,10 @@
 pip install httpware                # core only — no decoder
 pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
 pip install httpware[msgspec]       # + MsgspecDecoder
-pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
+pip install httpware[all]           # everything declared above (pydantic, msgspec)
 ```
 
-`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing. The `otel` extra is declared but the OpenTelemetry middleware (Epic 5) has not shipped yet.
+`AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
 
 ## Quickstart
 
@@ -42,7 +42,30 @@ async def main() -> None:
         print(user.name)
 ```
 
-## 📚 [Documentation](https://httpware.readthedocs.io)
+### With resilience middleware
+
+Compose resilience middleware at construction; `Bulkhead` goes outside `Retry` so one slot covers all retry attempts.
+
+```python
+from httpware import AsyncClient, Bulkhead, Retry
+
+
+async def main() -> None:
+    async with AsyncClient(
+        base_url="https://api.example.com",
+        middleware=[
+            Bulkhead(max_concurrent=10),  # cap total in-flight
+            Retry(),                       # default: 3 attempts, full-jitter backoff
+        ],
+    ) as client:
+        user = await client.get("/users/1", response_model=User)
+```
+
+## 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`.
+
+## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)
 

{httpware-0.3.0 → httpware-0.4.0}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -34,11 +34,7 @@ dependencies = [
 [project.optional-dependencies]
 pydantic = ["pydantic>=2.0,<3.0"]
 msgspec = ["msgspec>=0.18"]
-otel = [
-    "opentelemetry-api>=1.20",
-    "opentelemetry-sdk>=1.20",
-]
-all = ["httpware[pydantic,msgspec,otel]"]
+all = ["httpware[pydantic,msgspec]"]
 
 [project.urls]
 repository = "https://github.com/modern-python/httpware"

{httpware-0.3.0 → httpware-0.4.0}/src/httpware/__init__.py

@@ -5,13 +5,16 @@ from httpware.decoders import ResponseDecoder
 from httpware.errors import (
     STATUS_TO_EXCEPTION,
     BadRequestError,
+    BulkheadFullError,
     ClientError,
     ClientStatusError,
     ConflictError,
     ForbiddenError,
     InternalServerError,
+    NetworkError,
     NotFoundError,
     RateLimitedError,
+    RetryBudgetExhaustedError,
     ServerStatusError,
     ServiceUnavailableError,
     StatusError,
@@ -21,22 +24,29 @@ from httpware.errors import (
     UnprocessableEntityError,
 )
 from httpware.middleware import Middleware, Next, after_response, before_request, on_error
+from httpware.middleware.resilience import Bulkhead, Retry, RetryBudget
 
 
 __all__ = [
     "STATUS_TO_EXCEPTION",
     "AsyncClient",
     "BadRequestError",
+    "Bulkhead",
+    "BulkheadFullError",
     "ClientError",
     "ClientStatusError",
     "ConflictError",
     "ForbiddenError",
     "InternalServerError",
     "Middleware",
+    "NetworkError",
     "Next",
     "NotFoundError",
     "RateLimitedError",
     "ResponseDecoder",
+    "Retry",
+    "RetryBudget",
+    "RetryBudgetExhaustedError",
     "ServerStatusError",
     "ServiceUnavailableError",
     "StatusError",

{httpware-0.3.0 → httpware-0.4.0}/src/httpware/client.py

@@ -11,6 +11,7 @@ from httpware.decoders import ResponseDecoder
 from httpware.errors import (
     STATUS_TO_EXCEPTION,
     ClientStatusError,
+    NetworkError,
     ServerStatusError,
     TimeoutError,  # noqa: A004
     TransportError,
@@ -110,6 +111,8 @@ class AsyncClient:
             raise TimeoutError(str(exc)) from exc
         except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
             raise TransportError(str(exc)) from exc
+        except httpx2.NetworkError as exc:
+            raise NetworkError(str(exc)) from exc
         except httpx2.HTTPError as exc:
             raise TransportError(str(exc)) from exc
         except RuntimeError as exc:

{httpware-0.3.0 → httpware-0.4.0}/src/httpware/errors.py

@@ -40,6 +40,14 @@ class TransportError(ClientError):
     """Connection / network / protocol failure raised before a response was received."""
 
 
+class NetworkError(TransportError):
+    """Transient network-layer failure (connect/read/write/close). Safe to retry.
+
+    Pool-acquisition timeouts are NOT under this class; they raise ``TimeoutError``
+    via ``httpx2.PoolTimeout`` (a ``TimeoutException`` subclass).
+    """
+
+
 class TimeoutError(ClientError, builtins.TimeoutError):  # noqa: A001
     """Client-side timeout (connect / read / write / pool).
 
@@ -136,3 +144,71 @@ STATUS_TO_EXCEPTION: Mapping[int, type[StatusError]] = {
     500: InternalServerError,
     503: ServiceUnavailableError,
 }
+
+
+def _reconstruct_budget_exhausted(
+    cls: "type[RetryBudgetExhaustedError]",
+    last_response: httpx2.Response | None,
+    last_exception: BaseException | None,
+    attempts: int,
+) -> "RetryBudgetExhaustedError":
+    return cls(last_response=last_response, last_exception=last_exception, attempts=attempts)
+
+
+class RetryBudgetExhaustedError(ClientError):
+    """Raised when a retry was needed but the RetryBudget refused to permit it.
+
+    Carries the last response and/or exception observed before the budget refused,
+    plus the number of attempts already completed.
+    """
+
+    last_response: httpx2.Response | None
+    last_exception: BaseException | None
+    attempts: int
+
+    def __init__(
+        self,
+        *,
+        last_response: httpx2.Response | None,
+        last_exception: BaseException | None,
+        attempts: int,
+    ) -> None:
+        self.last_response = last_response
+        self.last_exception = last_exception
+        self.attempts = attempts
+        super().__init__(f"retry budget exhausted after {attempts} attempt(s)")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (
+            _reconstruct_budget_exhausted,
+            (type(self), self.last_response, self.last_exception, self.attempts),
+        )
+
+
+def _reconstruct_bulkhead_full(
+    cls: "type[BulkheadFullError]",
+    max_concurrent: int,
+    acquire_timeout: float | None,
+) -> "BulkheadFullError":
+    return cls(max_concurrent=max_concurrent, acquire_timeout=acquire_timeout)
+
+
+class BulkheadFullError(ClientError):
+    """Raised when ``acquire_timeout`` elapses before a Bulkhead slot becomes available.
+
+    Carries the configured caps for caller logging/alerting.
+    """
+
+    max_concurrent: int
+    acquire_timeout: float | None
+
+    def __init__(self, *, max_concurrent: int, acquire_timeout: float | None) -> None:
+        self.max_concurrent = max_concurrent
+        self.acquire_timeout = acquire_timeout
+        super().__init__(f"bulkhead full (max_concurrent={max_concurrent}, acquire_timeout={acquire_timeout})")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (
+            _reconstruct_bulkhead_full,
+            (type(self), self.max_concurrent, self.acquire_timeout),
+        )

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

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

httpware-0.4.0/src/httpware/middleware/resilience/_backoff.py

@@ -0,0 +1,26 @@
+"""Full-jitter exponential backoff helper (private)."""
+
+import random
+from collections.abc import Callable
+
+
+def full_jitter_delay(
+    attempt_index: int,
+    *,
+    base_delay: float,
+    max_delay: float,
+    _random_uniform: Callable[[float, float], float] = random.uniform,
+) -> float:
+    """Return a backoff delay using AWS's "full jitter" formulation.
+
+    sleep = uniform(0, min(max_delay, base_delay * 2.0 ** attempt_index))
+
+    `attempt_index` is 0 for the first retry, 1 for the second, etc.
+
+    Uses ``2.0 **`` (float exponentiation) rather than ``2 **`` so that
+    ``attempt_index >= 1024`` saturates to ``math.inf`` and ``min`` clamps to
+    ``max_delay`` — ``2 ** 1024`` would raise ``OverflowError`` during the
+    int→float conversion.
+    """
+    ceiling = min(max_delay, base_delay * (2.0**attempt_index))
+    return _random_uniform(0.0, ceiling)

httpware-0.4.0/src/httpware/middleware/resilience/budget.py

@@ -0,0 +1,64 @@
+"""Finagle-style token-bucket retry budget.
+
+See planning/specs/2026-06-05-retry-and-retry-budget-design.md for the contract.
+No locking: asyncio runs coroutines cooperatively on a single thread, so deque
+mutations between await points are atomic with respect to other coroutines on
+the same event loop. Cross-thread use is out of scope.
+"""
+
+import time
+from collections import deque
+from collections.abc import Callable
+
+
+class RetryBudget:
+    """Token-bucket budget bounding retry rate to prevent retry storms.
+
+    Each request deposits a token; each retry attempts to withdraw one.
+    Available retries are bounded by `percent_can_retry` of recent deposits,
+    plus a `min_retries_per_sec * ttl` floor.
+    """
+
+    def __init__(
+        self,
+        *,
+        ttl: float = 10.0,
+        min_retries_per_sec: float = 10.0,
+        percent_can_retry: float = 0.2,
+        _now: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._ttl = ttl
+        self._min_retries_per_sec = min_retries_per_sec
+        self._percent_can_retry = percent_can_retry
+        self._now = _now
+        self._deposits: deque[float] = deque()
+        self._withdrawn: deque[float] = deque()
+
+    def _purge(self, now: float) -> None:
+        # Strict `< cutoff` keeps entries at exactly `now - ttl`: window is [now - ttl, now].
+        cutoff = now - self._ttl
+        while self._deposits and self._deposits[0] < cutoff:
+            self._deposits.popleft()
+        while self._withdrawn and self._withdrawn[0] < cutoff:
+            self._withdrawn.popleft()
+
+    def deposit(self) -> None:
+        """Record a request (success or failure attempt). Adds one token."""
+        now = self._now()
+        self._purge(now)
+        self._deposits.append(now)
+
+    def try_withdraw(self) -> bool:
+        """Atomically attempt to spend one retry token.
+
+        Returns True if a retry is permitted, False if the budget is exhausted.
+        Never blocks.
+        """
+        now = self._now()
+        self._purge(now)
+        floor = int(self._min_retries_per_sec * self._ttl)
+        ceiling = int(len(self._deposits) * self._percent_can_retry) + floor
+        if len(self._withdrawn) >= ceiling:
+            return False
+        self._withdrawn.append(now)
+        return True

httpware-0.4.0/src/httpware/middleware/resilience/bulkhead.py

@@ -0,0 +1,75 @@
+"""Bulkhead middleware — concurrency limiter via asyncio.Semaphore.
+
+See planning/specs/2026-06-05-bulkhead-design.md for the contract.
+
+The middleware owns an asyncio.Semaphore(max_concurrent). On each request,
+it acquires a slot (bounded by acquire_timeout via asyncio.timeout) and
+releases the slot in a try/finally so success, exceptions, and cancellation
+all release deterministically.
+
+Bulkhead is the sharable unit — pass the same instance to multiple
+AsyncClient(middleware=[shared]) calls to enforce a joint cap across clients.
+"""
+
+import asyncio
+
+import httpx2
+
+from httpware.errors import BulkheadFullError
+from httpware.middleware import Next
+
+
+_MAX_CONCURRENT_INVALID = "max_concurrent must be >= 1"
+_ACQUIRE_TIMEOUT_INVALID = "acquire_timeout must be >= 0"
+
+
+class Bulkhead:
+    """Concurrency limiter middleware backed by ``asyncio.Semaphore``.
+
+    Parameters
+    ----------
+    max_concurrent
+        Required. Maximum number of in-flight requests this Bulkhead permits.
+        Must be ``>= 1``. There is no default because no value is universally
+        correct — the right cap depends on downstream capacity and SLA.
+    acquire_timeout
+        Seconds to wait for a slot before raising ``BulkheadFullError``.
+        Defaults to ``1.0``. ``None`` waits forever; ``0`` fails fast. Must be
+        ``>= 0`` (or ``None``).
+
+    See the module docstring for the algorithm and middleware-ordering guidance.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        max_concurrent: int,
+        acquire_timeout: float | None = 1.0,
+    ) -> None:
+        if max_concurrent < 1:
+            raise ValueError(_MAX_CONCURRENT_INVALID)
+        if acquire_timeout is not None and acquire_timeout < 0:
+            raise ValueError(_ACQUIRE_TIMEOUT_INVALID)
+        self._max_concurrent = max_concurrent
+        self._acquire_timeout = acquire_timeout
+        self._sem = asyncio.Semaphore(max_concurrent)
+
+    async def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002
+        """Acquire a slot (bounded by acquire_timeout), invoke next, release."""
+        try:
+            if self._acquire_timeout is None:
+                await self._sem.acquire()
+            else:
+                async with asyncio.timeout(self._acquire_timeout):
+                    await self._sem.acquire()
+        except TimeoutError as exc:
+            raise BulkheadFullError(
+                max_concurrent=self._max_concurrent,
+                acquire_timeout=self._acquire_timeout,
+            ) from exc
+
+        try:
+            return await next(request)
+        finally:
+            self._sem.release()

httpware-0.4.0/src/httpware/middleware/resilience/retry.py

@@ -0,0 +1,158 @@
+"""Retry middleware — automatic retry of transient failures with budget control.
+
+See planning/specs/2026-06-05-retry-and-retry-budget-design.md for the full contract.
+
+Status-code retry: the AsyncClient terminal raises StatusError subclasses on 4xx/5xx,
+so Retry catches StatusError and inspects exc.response.status_code. The original
+StatusError subclass is re-raised unwrapped on exhaustion, with a PEP 678 note added.
+"""
+
+import asyncio
+import builtins
+import datetime
+import email.utils
+from collections.abc import Awaitable, Callable
+from http import HTTPStatus
+
+import httpx2
+
+from httpware.errors import NetworkError, RetryBudgetExhaustedError, StatusError, TimeoutError  # noqa: A004
+from httpware.middleware import Next
+from httpware.middleware.resilience._backoff import full_jitter_delay
+from httpware.middleware.resilience.budget import RetryBudget
+
+
+DEFAULT_RETRY_STATUS_CODES = frozenset(
+    {
+        int(HTTPStatus.REQUEST_TIMEOUT),
+        int(HTTPStatus.TOO_MANY_REQUESTS),
+        int(HTTPStatus.BAD_GATEWAY),
+        int(HTTPStatus.SERVICE_UNAVAILABLE),
+        int(HTTPStatus.GATEWAY_TIMEOUT),
+    }
+)
+
+DEFAULT_IDEMPOTENT_METHODS = frozenset(
+    {
+        "GET",
+        "HEAD",
+        "OPTIONS",
+        "PUT",
+        "DELETE",
+    }
+)
+
+_MAX_ATTEMPTS_INVALID = "max_attempts must be >= 1"
+
+
+def _parse_retry_after(value: str) -> float | None:
+    """Parse a Retry-After header value. Returns None on malformed input."""
+    try:
+        return max(0.0, float(int(value)))  # clamp: negative integers are malformed servers
+    except ValueError:
+        pass
+    try:
+        parsed = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed is None:  # pragma: no cover — parsedate_to_datetime raises rather than returning None in CPython 3.11+
+        return None
+    now = datetime.datetime.now(datetime.UTC)
+    delta = (parsed - now).total_seconds()
+    return max(0.0, delta)
+
+
+class Retry:
+    """Retry middleware. See module docstring for default policy."""
+
+    def __init__(  # noqa: PLR0913 — retry policy has many orthogonal knobs; a dataclass would be worse
+        self,
+        *,
+        max_attempts: int = 3,
+        base_delay: float = 0.1,
+        max_delay: float = 5.0,
+        attempt_timeout: float | None = None,
+        retry_status_codes: frozenset[int] = DEFAULT_RETRY_STATUS_CODES,
+        retry_methods: frozenset[str] = DEFAULT_IDEMPOTENT_METHODS,
+        respect_retry_after: bool = True,
+        budget: RetryBudget | None = None,
+        _sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        if max_attempts < 1:
+            raise ValueError(_MAX_ATTEMPTS_INVALID)
+        self.max_attempts = max_attempts
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.attempt_timeout = attempt_timeout
+        self.retry_status_codes = retry_status_codes
+        self.retry_methods = retry_methods
+        self.respect_retry_after = respect_retry_after
+        self.budget = budget if budget is not None else RetryBudget()
+        self._sleep = _sleep
+
+    async def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002, C901, PLR0912 — complexity budget: 3 error clauses + idempotency gate + budget gate + Retry-After branch + backoff
+        """Process a request through the retry loop. See module docstring."""
+        method_eligible = request.method.upper() in self.retry_methods
+        last_exc: BaseException | None = None
+        last_response: httpx2.Response | None = None
+
+        for attempt in range(self.max_attempts):
+            is_last = attempt + 1 >= self.max_attempts
+            self.budget.deposit()
+            try:
+                if self.attempt_timeout is not None:
+                    async with asyncio.timeout(self.attempt_timeout):
+                        return await next(request)
+                else:
+                    return await next(request)
+            except StatusError as exc:
+                if not method_eligible or exc.response.status_code not in self.retry_status_codes:
+                    raise
+                last_exc = exc
+                last_response = exc.response
+            except (NetworkError, TimeoutError) as exc:
+                if not method_eligible:
+                    raise
+                last_exc = exc
+                last_response = None
+            except builtins.TimeoutError as exc:
+                wrapped = TimeoutError("attempt timed out")
+                wrapped.__cause__ = exc  # set now; the retry path (last_exc = wrapped) has no `from` clause
+                if not method_eligible:
+                    raise wrapped from exc
+                last_exc = wrapped
+                last_response = None
+
+            # ---- retryable failure path
+            if is_last:
+                if last_exc is None:  # pragma: no cover — structural invariant from except branch
+                    msg = "Retry: last_exc unset on final attempt — unreachable"
+                    raise AssertionError(msg)
+                last_exc.add_note(f"httpware: gave up after {attempt + 1} attempts")
+                raise last_exc
+
+            if not self.budget.try_withdraw():
+                raise RetryBudgetExhaustedError(
+                    last_response=last_response,
+                    last_exception=last_exc,
+                    attempts=attempt + 1,
+                ) from last_exc
+
+            retry_after: float | None = None
+            if self.respect_retry_after and last_response is not None:
+                header = last_response.headers.get("Retry-After")
+                if header is not None:
+                    retry_after = _parse_retry_after(header)
+
+            if retry_after is not None:
+                delay = min(retry_after, self.max_delay)
+            else:
+                delay = full_jitter_delay(
+                    attempt,
+                    base_delay=self.base_delay,
+                    max_delay=self.max_delay,
+                )
+            await self._sleep(delay)
+
+        msg = "unreachable"  # pragma: no cover
+        raise AssertionError(msg)  # pragma: no cover