httpware 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.3.0
+Version: 0.5.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,49 @@ 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)
+```
+
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
+## 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.5.0/README.md

@@ -0,0 +1,95 @@
+# httpware
+
+[![Test](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/httpware.svg)](https://pypi.org/project/httpware/)
+[![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**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. 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. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
+
+## Install
+
+```bash
+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)
+```
+
+`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
+
+> Requires: `pip install httpware[pydantic]`
+
+```python
+from httpware import AsyncClient
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)
+```
+
+### 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)
+```
+
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
+## 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)
+
+## 📝 [License](./LICENSE)
+
+## Part of `modern-python`
+
+Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.

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

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.3.0"
+version = "0.5.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.5.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.5.0}/src/httpware/client.py

@@ -1,7 +1,8 @@
 """AsyncClient — the thin httpx2 wrapper."""
 
+import contextlib
 import typing
-from collections.abc import Sequence
+from collections.abc import AsyncIterator, Sequence
 from http import HTTPStatus
 
 import httpx2
@@ -11,6 +12,7 @@ from httpware.decoders import ResponseDecoder
 from httpware.errors import (
     STATUS_TO_EXCEPTION,
     ClientStatusError,
+    NetworkError,
     ServerStatusError,
     TimeoutError,  # noqa: A004
     TransportError,
@@ -43,6 +45,48 @@ def _default_pydantic_decoder() -> ResponseDecoder:
     return PydanticDecoder()
 
 
+@contextlib.asynccontextmanager
+async def _httpx2_exception_mapper() -> AsyncIterator[None]:
+    """Map httpx2 exceptions to httpware exceptions. Shared by AsyncClient._terminal and stream()."""
+    try:
+        yield
+    except httpx2.TimeoutException as exc:
+        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
+
+
+def _raise_on_status_error(response: httpx2.Response) -> None:
+    """Raise the appropriate StatusError subclass for a 4xx/5xx response. No-op for 2xx/3xx."""
+    status = response.status_code
+    if HTTPStatus.BAD_REQUEST <= status < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+        exc_class = STATUS_TO_EXCEPTION.get(
+            status,
+            ClientStatusError if status < HTTPStatus.INTERNAL_SERVER_ERROR else ServerStatusError,
+        )
+        raise exc_class(response)
+
+
+STREAMING_BODY_MARKER = "httpware.streaming_body"
+"""Key set on ``httpx2.Request.extensions`` by ``_request_with_body`` when content/data/files is an async-iterable.
+
+``Retry.__call__`` reads this marker to refuse retrying a streamed-body request
+(the consumed iterator cannot replay across attempts)."""
+
+
+def _is_streaming_body(value: typing.Any) -> bool:
+    """Return True if value is an async-iterable that cannot be safely replayed for retry."""
+    if value is None:
+        return False
+    if isinstance(value, (bytes, bytearray, memoryview, str, dict)):
+        return False
+    return hasattr(value, "__aiter__")
+
+
 class AsyncClient:
     """Async HTTP client: thin wrapper around httpx2 with typed decoding and middleware."""
 
@@ -105,24 +149,13 @@ class AsyncClient:
 
     async def _terminal(self, request: httpx2.Request) -> httpx2.Response:
         try:
-            response = await self._httpx2_client.send(request)
-        except httpx2.TimeoutException as exc:
-            raise TimeoutError(str(exc)) from exc
-        except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
-            raise TransportError(str(exc)) from exc
-        except httpx2.HTTPError as exc:
-            raise TransportError(str(exc)) from exc
+            async with _httpx2_exception_mapper():
+                response = await self._httpx2_client.send(request)
         except RuntimeError as exc:
             if "closed" in str(exc):
                 raise TransportError(str(exc)) from exc
             raise
-        status = response.status_code
-        if HTTPStatus.BAD_REQUEST <= status < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
-            exc_class = STATUS_TO_EXCEPTION.get(
-                status,
-                ClientStatusError if status < HTTPStatus.INTERNAL_SERVER_ERROR else ServerStatusError,
-            )
-            raise exc_class(response)
+        _raise_on_status_error(response)
         return response
 
     @typing.overload
@@ -147,7 +180,7 @@ class AsyncClient:
         """Delegate request construction to the wrapped httpx2.AsyncClient."""
         return self._httpx2_client.build_request(method, url, **kwargs)
 
-    async def _request_with_body(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+    async def _request_with_body(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,
         method: str,
         url: str,
@@ -183,6 +216,8 @@ class AsyncClient:
         if files is not None:
             kwargs["files"] = files
         request = self._httpx2_client.build_request(method, url, **kwargs)
+        if _is_streaming_body(content) or _is_streaming_body(data) or _is_streaming_body(files):
+            request.extensions[STREAMING_BODY_MARKER] = True
         return await self.send(request, response_model=response_model)
 
     @typing.overload
@@ -660,6 +695,66 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    @contextlib.asynccontextmanager
+    async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+    ) -> AsyncIterator[httpx2.Response]:
+        """Stream an HTTP response. Bypasses the middleware chain.
+
+        Yields an httpx2.Response; consume the body via response.aiter_bytes(),
+        response.aiter_text(), response.aiter_lines(), or response.aiter_raw().
+        The body is NOT pre-read for 2xx/3xx (streaming preserved); the response
+        is closed when the context exits.
+
+        Bypasses the middleware chain (no Retry, no Bulkhead, no user-installed
+        middleware) for v1 — see planning/specs/2026-06-05-streaming-design.md.
+
+        Auto-raises StatusError subclasses on 4xx/5xx (NotFoundError,
+        ServiceUnavailableError, etc.) — consistent with client.get()/post()/etc.
+        On error the response body is pre-read so exc.response.content is
+        accessible. You lose the streaming property on errors; rare in practice.
+
+        Maps httpx2 exceptions raised during the request OR body consumption to
+        httpware exceptions via _httpx2_exception_mapper.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if params is not None:
+            kwargs["params"] = params
+        if headers is not None:
+            kwargs["headers"] = headers
+        if cookies is not None:
+            kwargs["cookies"] = cookies
+        if timeout is not httpx2.USE_CLIENT_DEFAULT:
+            kwargs["timeout"] = timeout
+        if extensions is not None:
+            kwargs["extensions"] = extensions
+        if json is not None:
+            kwargs["json"] = json
+        if content is not None:
+            kwargs["content"] = content
+        if data is not None:
+            kwargs["data"] = data
+        if files is not None:
+            kwargs["files"] = files
+
+        async with _httpx2_exception_mapper(), self._httpx2_client.stream(method, url, **kwargs) as response:
+            if HTTPStatus.BAD_REQUEST <= response.status_code < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+                await response.aread()  # pre-read body so exc.response.content works
+                _raise_on_status_error(response)
+            yield response
+
     async def __aenter__(self) -> typing.Self:
         """Enter the async context manager; return self."""
         return self

{httpware-0.3.0 → httpware-0.5.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.5.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.5.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.5.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.5.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.5.0/src/httpware/middleware/resilience/retry.py

@@ -0,0 +1,174 @@
+"""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.client import STREAMING_BODY_MARKER
+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"
+_STREAMING_BODY_REFUSAL_NOTE = "httpware: not retrying — request body is a stream that cannot replay across attempts"
+
+
+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, PLR0915 — complexity budget: 3 error clauses + idempotency gate + streaming-body refusal + 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:
+                retryable_status = exc.response.status_code in self.retry_status_codes
+                if not method_eligible or not retryable_status:
+                    if retryable_status and request.extensions.get(STREAMING_BODY_MARKER):
+                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                    raise
+                last_exc = exc
+                last_response = exc.response
+            except (NetworkError, TimeoutError) as exc:
+                if not method_eligible:
+                    if request.extensions.get(STREAMING_BODY_MARKER):
+                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                    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:
+                    if request.extensions.get(STREAMING_BODY_MARKER):
+                        wrapped.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                    raise wrapped from exc
+                last_exc = wrapped
+                last_response = None
+
+            # ---- retryable failure path
+            if request.extensions.get(STREAMING_BODY_MARKER):
+                if last_exc is None:  # pragma: no cover — invariant from except branch
+                    msg = "Retry: streaming-body refusal reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                raise last_exc
+
+            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

httpware-0.3.0/README.md

@@ -1,53 +0,0 @@
-# httpware
-
-[![Test](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
-[![PyPI version](https://badge.fury.io/py/httpware.svg)](https://pypi.org/project/httpware/)
-[![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**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.
-
-> **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.
-
-## Install
-
-```bash
-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)
-```
-
-`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.
-
-## Quickstart
-
-> Requires: `pip install httpware[pydantic]`
-
-```python
-from httpware import AsyncClient
-from pydantic import BaseModel
-
-
-class User(BaseModel):
-    id: int
-    name: str
-
-
-async def main() -> None:
-    async with AsyncClient(base_url="https://api.example.com") as client:
-        user = await client.get("/users/1", response_model=User)
-        print(user.name)
-```
-
-## 📚 [Documentation](https://httpware.readthedocs.io)
-
-## 📦 [PyPI](https://pypi.org/project/httpware)
-
-## 📝 [License](./LICENSE)
-
-## Part of `modern-python`
-
-Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.