httpware 0.2.0__tar.gz → 0.4.0__tar.gz

httpware-0.4.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: httpware
+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
+Author-email: Artur Shiriev <me@shiriev.ru>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+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] ; extra == 'all'
+Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
+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: pydantic
+Description-Content-Type: text/markdown
+
+# 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)
+```
+
+## 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.4.0/README.md

@@ -0,0 +1,76 @@
+# 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)
+```
+
+## 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.2.0 → httpware-0.4.0}/pyproject.toml

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

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

@@ -2,17 +2,19 @@
 
 from httpware.client import AsyncClient
 from httpware.decoders import ResponseDecoder
-from httpware.decoders.pydantic import PydanticDecoder
 from httpware.errors import (
     STATUS_TO_EXCEPTION,
     BadRequestError,
+    BulkheadFullError,
     ClientError,
     ClientStatusError,
     ConflictError,
     ForbiddenError,
     InternalServerError,
+    NetworkError,
     NotFoundError,
     RateLimitedError,
+    RetryBudgetExhaustedError,
     ServerStatusError,
     ServiceUnavailableError,
     StatusError,
@@ -22,23 +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",
-    "PydanticDecoder",
     "RateLimitedError",
     "ResponseDecoder",
+    "Retry",
+    "RetryBudget",
+    "RetryBudgetExhaustedError",
     "ServerStatusError",
     "ServiceUnavailableError",
     "StatusError",

{httpware-0.2.0 → httpware-0.4.0}/src/httpware/_internal/import_checker.py

@@ -4,3 +4,4 @@ from importlib.util import find_spec
 
 
 is_msgspec_installed = find_spec("msgspec") is not None
+is_pydantic_installed = find_spec("pydantic") is not None

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

@@ -6,11 +6,12 @@ from http import HTTPStatus
 
 import httpx2
 
+from httpware._internal import import_checker
 from httpware.decoders import ResponseDecoder
-from httpware.decoders.pydantic import PydanticDecoder
 from httpware.errors import (
     STATUS_TO_EXCEPTION,
     ClientStatusError,
+    NetworkError,
     ServerStatusError,
     TimeoutError,  # noqa: A004
     TransportError,
@@ -28,6 +29,20 @@ _HTTPX2_CLIENT_CONFLICT_MESSAGE = (
     f"{_FORWARDED_KWARG_NAMES}; configure the httpx2.AsyncClient you pass instead."
 )
 
+_DEFAULT_DECODER_MISSING_MESSAGE = (
+    "AsyncClient(decoder=None) defaults to PydanticDecoder, which requires the "
+    "'pydantic' extra. Either install it (`pip install httpware[pydantic]`) or "
+    "pass an explicit decoder=..."
+)
+
+
+def _default_pydantic_decoder() -> ResponseDecoder:
+    if not import_checker.is_pydantic_installed:
+        raise ImportError(_DEFAULT_DECODER_MISSING_MESSAGE)
+    from httpware.decoders.pydantic import PydanticDecoder  # noqa: PLC0415 — lazy by design
+
+    return PydanticDecoder()
+
 
 class AsyncClient:
     """Async HTTP client: thin wrapper around httpx2 with typed decoding and middleware."""
@@ -85,7 +100,7 @@ class AsyncClient:
             self._httpx2_client = httpx2.AsyncClient(**kwargs)
             self._owns_client = True
 
-        self._decoder = decoder if decoder is not None else PydanticDecoder()
+        self._decoder = decoder if decoder is not None else _default_pydantic_decoder()
         self._user_middleware = tuple(middleware)
         self._dispatch = compose(self._user_middleware, self._terminal)
 
@@ -96,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.4.0/src/httpware/decoders/pydantic.py

@@ -0,0 +1,44 @@
+"""PydanticDecoder — module-level cached TypeAdapter adapter for ResponseDecoder.
+
+Requires the `pydantic` extra: `pip install httpware[pydantic]`. Importing this
+module without the extra works (the `pydantic` import is guarded by a
+`find_spec` check), but instantiating the decoder raises `ImportError` with the
+install hint.
+"""
+
+import functools
+from typing import TypeVar
+
+from httpware._internal import import_checker
+
+
+if import_checker.is_pydantic_installed:
+    from pydantic import TypeAdapter
+
+
+MISSING_DEPENDENCY_MESSAGE = (
+    "PydanticDecoder requires the 'pydantic' extra. Install with: pip install httpware[pydantic]"
+)
+
+T = TypeVar("T")
+
+
+@functools.lru_cache(maxsize=1024)
+def _get_adapter(model: type[T]) -> "TypeAdapter[T]":
+    return TypeAdapter(model)
+
+
+class PydanticDecoder:
+    """Decode raw response bytes into `model` via a cached `pydantic.TypeAdapter`."""
+
+    def __init__(self) -> None:
+        if not import_checker.is_pydantic_installed:
+            raise ImportError(MISSING_DEPENDENCY_MESSAGE)
+
+    def decode(self, content: bytes, model: type[T]) -> T:
+        """Validate `content` as JSON against `model` in a single parse pass."""
+        try:
+            adapter = _get_adapter(model)
+        except TypeError:
+            adapter = TypeAdapter(model)
+        return adapter.validate_json(content)

{httpware-0.2.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

httpware-0.2.0/PKG-INFO

@@ -1,84 +0,0 @@
-Metadata-Version: 2.4
-Name: httpware
-Version: 0.2.0
-Summary: Resilience-first async HTTP client framework for Python
-Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
-Author: Artur Shiriev
-Author-email: Artur Shiriev <me@shiriev.ru>
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Typing :: Typed
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Internet :: WWW/HTTP
-Classifier: Framework :: AsyncIO
-Requires-Dist: httpx2>=2.0.0,<3.0
-Requires-Dist: pydantic>=2.0,<3.0
-Requires-Dist: httpware[msgspec,otel] ; 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-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
-Description-Content-Type: text/markdown
-
-# 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 typed, async HTTP client library with a protocol-based seam so the transport is swappable (`httpx2` ships as the default). Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces `respx` for transport-level tests.
-
-> **Status:** Pre-1.0 (0.1.0 alpha). 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
-```
-
-Optional extras:
-
-```bash
-pip install httpware[msgspec]    # MsgspecDecoder
-```
-
-(`otel`, `niquests`, and `all` extras are declared; integrations have not shipped yet.)
-
-## Quickstart
-
-```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.

httpware-0.2.0/README.md

@@ -1,54 +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 typed, async HTTP client library with a protocol-based seam so the transport is swappable (`httpx2` ships as the default). Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces `respx` for transport-level tests.
-
-> **Status:** Pre-1.0 (0.1.0 alpha). 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
-```
-
-Optional extras:
-
-```bash
-pip install httpware[msgspec]    # MsgspecDecoder
-```
-
-(`otel`, `niquests`, and `all` extras are declared; integrations have not shipped yet.)
-
-## Quickstart
-
-```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.

httpware-0.2.0/src/httpware/decoders/pydantic.py

@@ -1,29 +0,0 @@
-"""PydanticDecoder — module-level cached TypeAdapter adapter for ResponseDecoder."""
-
-import functools
-from typing import TypeVar
-
-from pydantic import TypeAdapter
-
-
-T = TypeVar("T")
-
-
-@functools.lru_cache(maxsize=1024)
-def _get_adapter(model: type[T]) -> TypeAdapter[T]:
-    return TypeAdapter(model)
-
-
-class PydanticDecoder:
-    """Decode raw response bytes into `model` via a cached `pydantic.TypeAdapter`."""
-
-    def decode(self, content: bytes, model: type[T]) -> T:
-        """Validate `content` as JSON against `model` in a single parse pass."""
-        try:
-            adapter = _get_adapter(model)
-        except TypeError:
-            adapter = TypeAdapter(model)
-        return adapter.validate_json(content)
-
-
-__all__ = ["PydanticDecoder"]