httpware 0.10.0__tar.gz → 0.11.0__tar.gz

httpware-0.11.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: httpware
+Version: 0.11.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,otel] ; extra == 'all'
+Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
+Requires-Dist: opentelemetry-api>=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.modern-python.org
+Provides-Extra: all
+Provides-Extra: msgspec
+Provides-Extra: otel
+Provides-Extra: pydantic
+Description-Content-Type: text/markdown
+
+# httpware
+
+[![PyPI version](https://img.shields.io/pypi/v/httpware.svg)](https://pypi.org/project/httpware/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![Downloads](https://img.shields.io/pypi/dm/httpware.svg)](https://pypistats.org/packages/httpware)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![CI](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/modern-python/httpware.svg)](https://github.com/modern-python/httpware/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/modern-python/httpware)](https://github.com/modern-python/httpware/stargazers)
+[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/httpware)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
+
+## Why httpware
+
+- **Typed errors, no `raise_for_status()`** — 4xx/5xx automatically raise a status-keyed exception tree (`NotFoundError`, `RateLimitedError`, …), all under `httpware.StatusError`.
+- **Typed response bodies** — `response_model=YourType` decodes the body straight to your pydantic or msgspec model; a missing decoder fails fast, *before* the request goes out.
+- **Production resilience as composable middleware** — retry + retry-budget, bulkhead, circuit breaker, and timeout, composed at construction — all over standard `httpx2`.
+
+Built on `httpx2`: httpware re-exports `httpx2.Request`/`httpx2.Response` and stays a thin wrapper, not a new HTTP abstraction.
+
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
+
+## Install
+
+```bash
+pip install httpware                # core only — no decoder
+pip install httpware[pydantic]      # + PydanticDecoder — BaseModel, dataclasses, primitives, generics
+pip install httpware[msgspec]       # + MsgspecDecoder — Struct, dataclasses, primitives, generics
+pip install httpware[pydantic,msgspec]   # both — BaseModel routes to pydantic, Struct to msgspec
+pip install httpware[all]           # everything (pydantic, msgspec, otel)
+```
+
+## Quickstart
+
+A typed GET against a live API (needs `pip install httpware[pydantic]`):
+
+```python
+import asyncio
+
+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://jsonplaceholder.typicode.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)  # Leanne Graham
+
+
+asyncio.run(main())
+```
+
+The sync `Client` is identical — swap `AsyncClient` → `Client` and drop the `await` / `async with`. A 4xx/5xx response raises a typed `StatusError`; a malformed body raises `DecodeError`. Both subclass `httpware.ClientError`.
+
+## Documentation
+
+Full guides live at **[httpware.modern-python.org](https://httpware.modern-python.org)**:
+
+- **[Quickstart & observability](https://httpware.modern-python.org/)** — resilience middleware, streaming, and the stable logger/event contract.
+- **[Middleware](https://httpware.modern-python.org/middleware/)** — write your own (auth, tracing, request-ID propagation).
+- **[Resilience](https://httpware.modern-python.org/resilience/)** — retry + retry-budget, bulkhead, circuit breaker, timeout.
+- **[Errors](https://httpware.modern-python.org/errors/)** — the exception tree and catching strategies.
+- **[Testing](https://httpware.modern-python.org/testing/)** — `httpx2.MockTransport` injection.
+- **[Recipes](https://httpware.modern-python.org/recipes/modern-di/)** — DI wiring, phase-decorator patterns, link-header pagination.
+
+## 🗒️ [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.11.0/README.md

@@ -0,0 +1,80 @@
+# httpware
+
+[![PyPI version](https://img.shields.io/pypi/v/httpware.svg)](https://pypi.org/project/httpware/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![Downloads](https://img.shields.io/pypi/dm/httpware.svg)](https://pypistats.org/packages/httpware)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![CI](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/modern-python/httpware.svg)](https://github.com/modern-python/httpware/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/modern-python/httpware)](https://github.com/modern-python/httpware/stargazers)
+[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/httpware)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
+
+## Why httpware
+
+- **Typed errors, no `raise_for_status()`** — 4xx/5xx automatically raise a status-keyed exception tree (`NotFoundError`, `RateLimitedError`, …), all under `httpware.StatusError`.
+- **Typed response bodies** — `response_model=YourType` decodes the body straight to your pydantic or msgspec model; a missing decoder fails fast, *before* the request goes out.
+- **Production resilience as composable middleware** — retry + retry-budget, bulkhead, circuit breaker, and timeout, composed at construction — all over standard `httpx2`.
+
+Built on `httpx2`: httpware re-exports `httpx2.Request`/`httpx2.Response` and stays a thin wrapper, not a new HTTP abstraction.
+
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
+
+## Install
+
+```bash
+pip install httpware                # core only — no decoder
+pip install httpware[pydantic]      # + PydanticDecoder — BaseModel, dataclasses, primitives, generics
+pip install httpware[msgspec]       # + MsgspecDecoder — Struct, dataclasses, primitives, generics
+pip install httpware[pydantic,msgspec]   # both — BaseModel routes to pydantic, Struct to msgspec
+pip install httpware[all]           # everything (pydantic, msgspec, otel)
+```
+
+## Quickstart
+
+A typed GET against a live API (needs `pip install httpware[pydantic]`):
+
+```python
+import asyncio
+
+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://jsonplaceholder.typicode.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)  # Leanne Graham
+
+
+asyncio.run(main())
+```
+
+The sync `Client` is identical — swap `AsyncClient` → `Client` and drop the `await` / `async with`. A 4xx/5xx response raises a typed `StatusError`; a malformed body raises `DecodeError`. Both subclass `httpware.ClientError`.
+
+## Documentation
+
+Full guides live at **[httpware.modern-python.org](https://httpware.modern-python.org)**:
+
+- **[Quickstart & observability](https://httpware.modern-python.org/)** — resilience middleware, streaming, and the stable logger/event contract.
+- **[Middleware](https://httpware.modern-python.org/middleware/)** — write your own (auth, tracing, request-ID propagation).
+- **[Resilience](https://httpware.modern-python.org/resilience/)** — retry + retry-budget, bulkhead, circuit breaker, timeout.
+- **[Errors](https://httpware.modern-python.org/errors/)** — the exception tree and catching strategies.
+- **[Testing](https://httpware.modern-python.org/testing/)** — `httpx2.MockTransport` injection.
+- **[Recipes](https://httpware.modern-python.org/recipes/modern-di/)** — DI wiring, phase-decorator patterns, link-header pagination.
+
+## 🗒️ [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.10.0 → httpware-0.11.0}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.10.0"
+version = "0.11.0"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -97,4 +97,4 @@ asyncio_default_fixture_loop_scope = "function"
 
 [tool.coverage]
 run.concurrency = ["thread"]
-report.exclude_also = ["if typing.TYPE_CHECKING:"]
+report.exclude_also = ["if typing.TYPE_CHECKING:", 'pytest\.fail\(']

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/__init__.py

@@ -17,6 +17,7 @@ from httpware.errors import (
     NetworkError,
     NotFoundError,
     RateLimitedError,
+    ResponseTooLargeError,
     RetryBudgetExhaustedError,
     ServerStatusError,
     ServiceUnavailableError,
@@ -78,6 +79,7 @@ __all__ = [
     "NotFoundError",
     "RateLimitedError",
     "ResponseDecoder",
+    "ResponseTooLargeError",
     "Retry",
     "RetryBudget",
     "RetryBudgetExhaustedError",

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/_internal/observability.py

@@ -2,15 +2,18 @@
 
 See planning/specs/2026-06-05-observability-design.md for the contract.
 
-Logger names (``httpware.retry``, ``httpware.bulkhead``) and event names
-(``retry.giving_up``, ``bulkhead.rejected``, etc.) are the public observability
+Logger names (``httpware.retry``, ``httpware.bulkhead``, ``httpware.circuit_breaker``,
+``httpware.timeout``) and event names (``retry.giving_up``, ``bulkhead.rejected``,
+``circuit.opened``, ``timeout.exceeded``, etc.) are the public observability
 surface. They are stable: renames are breaking changes.
 """
 
+import contextlib
 import logging
 import typing
 
 from httpware._internal import import_checker
+from httpware._internal.redaction import redact_url
 
 
 def _emit_event(
@@ -23,6 +26,12 @@ def _emit_event(
 ) -> None:
     """Emit one observability event to both channels.
 
+    The ``url`` attribute, when present, is run through
+    ``redaction.redact_url`` here — at the single emission boundary — so a
+    request URL's userinfo and known-sensitive query/fragment secrets never
+    reach a log record or span event, regardless of how a caller built the
+    attributes dict.
+
     1. Always emits a structured log record at ``level`` with ``extra=attributes``
        (so log aggregators that index ``extra`` see structured fields).
     2. If ``opentelemetry-api`` is installed, calls
@@ -37,7 +46,9 @@ def _emit_event(
     the optional-extras isolation invariant: ``import httpware`` must not pull
     ``opentelemetry`` into ``sys.modules`` when the extra is absent.
     """
-    logger.log(level, message, extra=attributes)
+    raw_url = attributes.get("url")
+    safe_attributes = {**attributes, "url": redact_url(raw_url)} if isinstance(raw_url, str) else attributes
+    logger.log(level, message, extra={**safe_attributes, "event": event_name})
     if import_checker.is_otel_installed:
         try:
             from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
@@ -45,4 +56,9 @@ def _emit_event(
             # opentelemetry namespace exists but the api package is broken or missing —
             # degrade to log-only emission. The structured log record above has already fired.
             return
-        trace.get_current_span().add_event(event_name, attributes=attributes)
+        # Observability must never break the request path — suppress any failure from
+        # add_event (e.g. a recording span with a broken exporter or attribute validation).
+        # The structured log record above has already fired; CancelledError/KeyboardInterrupt
+        # are not Exception subclasses and will still propagate.
+        with contextlib.suppress(Exception):
+            trace.get_current_span().add_event(event_name, attributes=safe_attributes)

httpware-0.11.0/src/httpware/_internal/redaction.py

@@ -0,0 +1,116 @@
+"""URL sanitation for logs, telemetry, and error messages.
+
+Strips ``user:pass@`` userinfo and masks the values of known-sensitive query
+parameters so secrets embedded in URLs do not leak into observability output.
+Shared by ``errors.py`` (StatusError messages) and the resilience middleware
+(event attributes).
+"""
+
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+
+SENSITIVE_QUERY_KEYS = frozenset(
+    {
+        "api_key",
+        "apikey",
+        "access_token",
+        "refresh_token",
+        "token",
+        "secret",
+        "client_secret",
+        "password",
+        "passwd",
+        "pwd",
+        "auth",
+        "authorization",
+        "sig",
+        "signature",
+        "key",
+        "private_key",
+        "session",
+        "sessionid",
+        "x-api-key",
+    }
+)
+
+_REDACTED = "REDACTED"
+
+
+def _reassemble(scheme: str, netloc: str, path: str, query: str, fragment: str) -> str:
+    """Like ``urlunsplit``, but avoid the spurious triple-slash for an empty authority.
+
+    ``urlunsplit(("http", "", "/path", ...))`` yields ``http:///path`` for a
+    netloc-using scheme. When userinfo stripping leaves no host (e.g.
+    ``http://user:pass@/path``) we want ``http:/path`` (scheme + path), not a
+    triple-slash. With a non-empty netloc this delegates to ``urlunsplit``, so
+    normal URLs are byte-identical.
+    """
+    if netloc:
+        return urlunsplit((scheme, netloc, path, query, fragment))
+    tail = path
+    if query:
+        tail += "?" + query
+    if fragment:
+        tail += "#" + fragment
+    return f"{scheme}:{tail}" if scheme else tail
+
+
+def _strip_userinfo(url: str) -> str:
+    if "@" not in url or "://" not in url:
+        return url
+    parts = urlsplit(url)
+    if parts.username is None and parts.password is None:
+        return url
+    # Strip the "user:pass@" prefix from the raw netloc to preserve host:port
+    # exactly (including IPv6 brackets), rather than reconstructing from parts.
+    netloc = parts.netloc.split("@", 1)[1] if "@" in parts.netloc else parts.netloc
+    return _reassemble(parts.scheme, netloc, parts.path, parts.query, parts.fragment)
+
+
+def _mask_component(component: str) -> tuple[str, bool]:
+    """Mask sensitive key=value pairs in a query or fragment string.
+
+    Returns ``(masked_component, was_changed)``; when no sensitive key is
+    found the original string is returned unchanged (``was_changed=False``).
+    """
+    pairs = parse_qsl(component, keep_blank_values=True)
+    if not any(key.strip().lower() in SENSITIVE_QUERY_KEYS for key, _ in pairs):
+        return component, False
+    masked = [(key, _REDACTED if key.strip().lower() in SENSITIVE_QUERY_KEYS else value) for key, value in pairs]
+    return urlencode(masked), True
+
+
+def _mask_query(url: str) -> str:
+    parts = urlsplit(url)
+    has_query = bool(parts.query)
+    has_fragment = bool(parts.fragment)
+
+    if not has_query and not has_fragment:
+        return url
+
+    new_query = parts.query
+    new_fragment = parts.fragment
+    changed = False
+
+    if has_query:
+        new_query, q_changed = _mask_component(parts.query)
+        changed = changed or q_changed
+
+    if has_fragment:
+        new_fragment, f_changed = _mask_component(parts.fragment)
+        changed = changed or f_changed
+
+    if not changed:
+        return url  # common-path guard: nothing sensitive, leave bytes untouched
+
+    return _reassemble(parts.scheme, parts.netloc, parts.path, new_query, new_fragment)
+
+
+def redact_url(url: str) -> str:
+    """Return ``url`` safe for logs/telemetry/errors.
+
+    Userinfo is stripped and the values of known-sensitive query parameters are
+    replaced with ``REDACTED`` (keys preserved). URLs with no sensitive query
+    key are returned byte-identical to the userinfo-stripped input.
+    """
+    return _mask_query(_strip_userinfo(url))

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/_internal/status.py

@@ -29,19 +29,24 @@ def _raise_on_status_error(response: httpx2.Response) -> None:
         raise exc_class(response)
 
 
+def _is_replayable_type(value: object) -> bool:
+    """Return True if value is a replayable type (safe to replay across retry attempts)."""
+    return isinstance(value, (bytes, bytearray, memoryview, str, dict, list, tuple))
+
+
 def _is_streaming_body_async(value: object) -> bool:
-    """Return True if value is an async-iterable that cannot be safely replayed for retry."""
+    """Return True if value is a non-replayable body (async-iterable or sync non-replayable iterable)."""
     if value is None:
         return False
-    if isinstance(value, (bytes, bytearray, memoryview, str, dict)):
+    if _is_replayable_type(value):
         return False
-    return hasattr(value, "__aiter__")
+    return hasattr(value, "__aiter__") or hasattr(value, "__iter__")
 
 
 def _is_streaming_body_sync(value: object) -> bool:
     """Return True if value is a sync iterable body that cannot be safely replayed for retry."""
     if value is None:
         return False
-    if isinstance(value, (bytes, bytearray, memoryview, str, dict, list, tuple)):
+    if _is_replayable_type(value):
         return False
     return hasattr(value, "__iter__")

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/client.py

@@ -16,7 +16,7 @@ from httpware._internal.status import (
     _raise_on_status_error,
 )
 from httpware.decoders import ResponseDecoder
-from httpware.errors import DecodeError, MissingDecoderError, TransportError
+from httpware.errors import DecodeError, MissingDecoderError, ResponseTooLargeError, TransportError
 from httpware.middleware import AsyncMiddleware, AsyncNext, Middleware, Next
 from httpware.middleware.chain import compose, compose_async
 
@@ -31,6 +31,17 @@ _HTTPX2_CLIENT_CONFLICT_MESSAGE = (
 )
 
 
+def _parse_content_length(raw: str | None) -> int | None:
+    """Return a non-negative int Content-Length, or None for missing/garbage. Never raises."""
+    if raw is None:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value >= 0 else None
+
+
 def _build_default_decoders() -> tuple[ResponseDecoder, ...]:
     """Construct the default decoder tuple based on installed extras.
 
@@ -82,6 +93,7 @@ class AsyncClient:
     _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[AsyncMiddleware, ...]
     _dispatch: AsyncNext
+    _max_error_body_bytes: int | None
 
     def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call API
         self,
@@ -96,6 +108,7 @@ class AsyncClient:
         httpx2_client: httpx2.AsyncClient | None = None,
         decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[AsyncMiddleware] = (),
+        max_error_body_bytes: int | None = None,
     ) -> None:
         if httpx2_client is not None:
             forwarded = {
@@ -133,6 +146,7 @@ class AsyncClient:
         self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
         self._user_middleware = tuple(middleware)
         self._dispatch = compose_async(self._user_middleware, self._terminal)
+        self._max_error_body_bytes = max_error_body_bytes
 
     def _dispatch_decoder(self, model: type) -> ResponseDecoder | None:
         """Walk `_decoders` and return the first decoder claiming `model`, or None."""
@@ -785,6 +799,14 @@ class AsyncClient:
 
         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
+                if self._max_error_body_bytes is not None:
+                    content_length = _parse_content_length(response.headers.get("content-length"))
+                    if content_length is not None and content_length > self._max_error_body_bytes:
+                        raise ResponseTooLargeError(
+                            status_code=response.status_code,
+                            limit=self._max_error_body_bytes,
+                            content_length=content_length,
+                        )
                 await response.aread()  # pre-read body so exc.response.content works
                 _raise_on_status_error(response)
             yield response
@@ -822,6 +844,7 @@ class Client:
     _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[Middleware, ...]
     _dispatch: Next
+    _max_error_body_bytes: int | None
 
     def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call API
         self,
@@ -836,6 +859,7 @@ class Client:
         httpx2_client: httpx2.Client | None = None,
         decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[Middleware] = (),
+        max_error_body_bytes: int | None = None,
     ) -> None:
         if httpx2_client is not None:
             forwarded = {
@@ -873,6 +897,7 @@ class Client:
         self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
         self._user_middleware = tuple(middleware)
         self._dispatch = compose(self._user_middleware, self._terminal)
+        self._max_error_body_bytes = max_error_body_bytes
 
     def _dispatch_decoder(self, model: type) -> ResponseDecoder | None:
         """Walk `_decoders` and return the first decoder claiming `model`, or None."""
@@ -1547,6 +1572,14 @@ class Client:
 
         with _httpx2_exception_mapper_sync(), 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
+                if self._max_error_body_bytes is not None:
+                    content_length = _parse_content_length(response.headers.get("content-length"))
+                    if content_length is not None and content_length > self._max_error_body_bytes:
+                        raise ResponseTooLargeError(
+                            status_code=response.status_code,
+                            limit=self._max_error_body_bytes,
+                            content_length=content_length,
+                        )
                 response.read()  # pre-read body so exc.response.content works
                 _raise_on_status_error(response)
             yield response

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/decoders/msgspec.py

@@ -26,6 +26,8 @@ def _contains_custom_type(info: "msgspec.inspect.Type") -> bool:
     makes the walk both correct (a Struct is a valid target) and safe against
     infinite recursion on self-referential struct definitions.
     """
+    if not import_checker.is_msgspec_installed:
+        raise ImportError(MISSING_DEPENDENCY_MESSAGE)
     if isinstance(info, msgspec.inspect.CustomType):
         return True
     for name in dir(info):

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

@@ -10,11 +10,13 @@ not trip the ImportError when the user is not using `response_model=`.
 import typing
 from typing import TypeVar
 
-from pydantic import TypeAdapter
-
 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]"
 )
@@ -23,9 +25,15 @@ T = TypeVar("T")
 
 
 class PydanticDecoder:
-    """Decode raw response bytes into `model` via a per-instance cached `pydantic.TypeAdapter`."""
+    """Decode raw response bytes into `model` via a per-instance cached `pydantic.TypeAdapter`.
+
+    Requires the `pydantic` extra: `pip install httpware[pydantic]`. Importing
+    this module without the extra works (the `pydantic` import is guarded by an
+    `is_pydantic_installed` check), but instantiating the decoder raises
+    `ImportError`.
+    """
 
-    _adapters: dict[type, TypeAdapter[typing.Any]]
+    _adapters: dict[type, "TypeAdapter[typing.Any]"]
     _can_decode_results: dict[type, bool]
 
     def __init__(self) -> None:

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/errors.py

@@ -1,35 +1,25 @@
 """Status-keyed exception hierarchy.
 
-Auto-raise rule lives at AsyncClient's internal terminal (see client.py).
+Auto-raise fires at four sites (all in client.py): both clients' internal
+terminals (Client._terminal / AsyncClient._terminal) and both stream() methods
+(Client.stream / AsyncClient.stream).
 Unknown 4xx falls back to ClientStatusError; unknown 5xx to ServerStatusError.
 The fallback assumes 400 <= status < 600.
 
-__repr__ and the summary message strip user:pass@ userinfo from
-response.request.url to avoid leaking credentials in tracebacks.
-Query-string secrets are NOT stripped here.
+__repr__ and the summary message run response.request.url through
+_internal.redaction.redact_url, which strips user:pass@ userinfo and masks the
+values of known-sensitive query parameters. NOTE: the full request headers
+(Authorization, Cookie, ...) remain reachable via exc.response.request — handler
+authors must redact those before logging.
 """
 
 import builtins
 from collections.abc import Mapping
 from typing import Any
-from urllib.parse import urlsplit, urlunsplit
 
 import httpx2
 
-
-def _strip_userinfo(url: str) -> str:
-    if "@" not in url or "://" not in url:
-        return url
-    parts = urlsplit(url)
-    if parts.username is None and parts.password is None:
-        return url
-    hostname = parts.hostname or ""
-    if ":" in hostname:  # IPv6 literal — re-wrap in brackets
-        hostname = f"[{hostname}]"
-    netloc = hostname
-    if parts.port is not None:
-        netloc = f"{netloc}:{parts.port}"
-    return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))
+from httpware._internal.redaction import redact_url
 
 
 class ClientError(Exception):
@@ -76,13 +66,13 @@ class StatusError(ClientError):
 
     def _summary(self) -> str:
         method = self.response.request.method
-        url = _strip_userinfo(str(self.response.request.url))
+        url = redact_url(str(self.response.request.url))
         return f"{self.response.status_code} {method} {url}"
 
     def __repr__(self) -> str:
         cls_name = type(self).__name__
         method = self.response.request.method
-        url = _strip_userinfo(str(self.response.request.url))
+        url = redact_url(str(self.response.request.url))
         return f"<{cls_name} status={self.response.status_code} method={method} url={url}>"
 
     def __reduce__(self) -> tuple[Any, ...]:
@@ -323,3 +313,40 @@ class MissingDecoderError(ClientError):
 
     def __reduce__(self) -> tuple[Any, ...]:
         return (_reconstruct_missing_decoder, (type(self), self.model, self.registered_names))
+
+
+def _reconstruct_response_too_large(
+    cls: "type[ResponseTooLargeError]",
+    status_code: int,
+    limit: int,
+    content_length: int | None,
+) -> "ResponseTooLargeError":
+    return cls(status_code=status_code, limit=limit, content_length=content_length)
+
+
+class ResponseTooLargeError(ClientError):
+    """Raised when an error response body exceeds the client's max_error_body_bytes cap.
+
+    Fires from stream() on a 4xx/5xx whose declared Content-Length exceeds the
+    configured cap, BEFORE the body is read — so the oversized body is never
+    buffered. Only raised when max_error_body_bytes is set (opt-in).
+    """
+
+    status_code: int
+    limit: int
+    content_length: int | None
+
+    def __init__(self, *, status_code: int, limit: int, content_length: int | None) -> None:
+        self.status_code = status_code
+        self.limit = limit
+        self.content_length = content_length
+        super().__init__(
+            f"error response body too large: status={status_code} "
+            f"content_length={content_length} exceeds max_error_body_bytes={limit}"
+        )
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (
+            _reconstruct_response_too_large,
+            (type(self), self.status_code, self.limit, self.content_length),
+        )

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/middleware/__init__.py

@@ -11,6 +11,19 @@ from typing import Protocol, TypeAlias, runtime_checkable
 import httpx2
 
 
+__all__ = [
+    "AsyncMiddleware",
+    "AsyncNext",
+    "Middleware",
+    "Next",
+    "after_response",
+    "async_after_response",
+    "async_before_request",
+    "async_on_error",
+    "before_request",
+    "on_error",
+]
+
 AsyncNext: TypeAlias = Callable[[httpx2.Request], Awaitable[httpx2.Response]]
 
 

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/middleware/resilience/_backoff.py

@@ -17,10 +17,13 @@ def full_jitter_delay(
 
     `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.
+    For large ``attempt_index`` (>= 1024), ``2.0 ** attempt_index`` raises
+    ``OverflowError``. That is caught and the ceiling is clamped directly to
+    ``max_delay``, which is exactly what ``min`` would produce for an infinite
+    exponentiation result.
     """
-    ceiling = min(max_delay, base_delay * (2.0**attempt_index))
+    try:
+        ceiling = min(max_delay, base_delay * (2.0**attempt_index))
+    except OverflowError:
+        ceiling = max_delay
     return _random_uniform(0.0, ceiling)

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/middleware/resilience/budget.py

@@ -2,10 +2,14 @@
 
 See planning/specs/2026-06-05-retry-and-retry-budget-design.md for the contract.
 
-Thread-safe and asyncio-safe: all mutations go through a threading.Lock.
-A single RetryBudget instance is safe to share across threads, across
-coroutines on one event loop, and across (sync Client, AsyncClient) pairs
-in the same process.
+Thread-safe and asyncio-safe: all mutations go through a threading.Lock,
+which ensures no torn state across concurrent accesses. When a RetryBudget
+is shared between a sync Client (pool thread) and an AsyncClient (event-loop
+thread), a sync thread holding the lock can briefly block the loop thread's
+acquisition; the critical section (purge + append/compare) is intentionally
+tiny to bound this latency. Safe to share across threads, across coroutines
+on one event loop, and across (sync Client, AsyncClient) pairs in the same
+process.
 """
 
 import math

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/middleware/resilience/circuit_breaker.py

@@ -5,7 +5,10 @@ See planning/specs/2026-06-13-circuit-breaker-and-timeout-design.md for the cont
 A counted failure is a NetworkError, an httpware TimeoutError, or a StatusError whose
 status_code is in the effective failure set (default: all 5xx). 4xx — including 429 —
 count as successes: 429 means healthy-but-throttling, and tripping on it amplifies
-incidents. Any other exception propagates without affecting circuit state.
+incidents. Any other exception propagates without affecting circuit state. In
+particular, non-NetworkError transport problems — e.g. httpx2.InvalidURL from a
+malformed URL — are foreign: they propagate unchanged and do not increment the
+failure counter, so programming errors cannot trip the breaker.
 
 State machine (classic / consecutive-failure):
     CLOSED    — forward; count consecutive counted-failures; open at failure_threshold.

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/middleware/resilience/retry.py

@@ -58,7 +58,7 @@ 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:
+    except (ValueError, OverflowError):
         pass
     try:
         parsed = email.utils.parsedate_to_datetime(value)
@@ -159,6 +159,24 @@ class AsyncRetry:
                 )
                 raise 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 and retry_after > self.max_delay:
+                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
+                    msg = "AsyncRetry: retry_after path reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(
+                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
+                        retry_after=retry_after,
+                        max_delay=self.max_delay,
+                    ),
+                )
+                raise last_exc
+
             if not self.budget.try_withdraw():
                 _emit_event(
                     _LOGGER,
@@ -178,23 +196,6 @@ class AsyncRetry:
                     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 and retry_after > self.max_delay:
-                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
-                    msg = "AsyncRetry: retry_after path reached with no last_exc"
-                    raise AssertionError(msg)
-                last_exc.add_note(
-                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
-                        retry_after=retry_after,
-                        max_delay=self.max_delay,
-                    ),
-                )
-                raise last_exc
             if retry_after is not None:
                 delay = retry_after
             else:
@@ -297,6 +298,24 @@ class Retry:
                 )
                 raise 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 and retry_after > self.max_delay:
+                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
+                    msg = "Retry: retry_after path reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(
+                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
+                        retry_after=retry_after,
+                        max_delay=self.max_delay,
+                    ),
+                )
+                raise last_exc
+
             if not self.budget.try_withdraw():
                 _emit_event(
                     _LOGGER,
@@ -316,23 +335,6 @@ class Retry:
                     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 and retry_after > self.max_delay:
-                if last_exc is None:  # pragma: no cover — retry_after requires last_response which requires last_exc
-                    msg = "Retry: retry_after path reached with no last_exc"
-                    raise AssertionError(msg)
-                last_exc.add_note(
-                    _RETRY_AFTER_EXCEEDS_MAX_DELAY_NOTE.format(
-                        retry_after=retry_after,
-                        max_delay=self.max_delay,
-                    ),
-                )
-                raise last_exc
             if retry_after is not None:
                 delay = retry_after
             else:

{httpware-0.10.0 → httpware-0.11.0}/src/httpware/middleware/resilience/timeout.py

@@ -14,6 +14,7 @@ timeouts. Sync callers configure httpx2's timeouts directly; there is no sync Ti
 
 import asyncio
 import logging
+import math
 
 import httpx2
 
@@ -22,7 +23,7 @@ from httpware.errors import TimeoutError as HttpwareTimeoutError
 from httpware.middleware import AsyncNext
 
 
-_TIMEOUT_INVALID = "timeout must be > 0"
+_TIMEOUT_INVALID = "timeout must be a finite number > 0"
 
 _LOGGER = logging.getLogger("httpware.timeout")
 
@@ -43,7 +44,7 @@ class AsyncTimeout:
     """
 
     def __init__(self, *, timeout: float) -> None:
-        if timeout <= 0:
+        if not math.isfinite(timeout) or timeout <= 0:
             raise ValueError(_TIMEOUT_INVALID)
         self._timeout = timeout
 

httpware-0.10.0/PKG-INFO

@@ -1,181 +0,0 @@
-Metadata-Version: 2.4
-Name: httpware
-Version: 0.10.0
-Summary: Resilience-first async HTTP client framework for Python
-Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
-Author: Artur Shiriev
-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,otel] ; extra == 'all'
-Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
-Requires-Dist: opentelemetry-api>=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.modern-python.org
-Provides-Extra: all
-Provides-Extra: msgspec
-Provides-Extra: otel
-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)
-
-**A Python HTTP client framework with sync and async clients for building resilient service clients.**
-
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a resilience suite under `httpware.middleware.resilience` — `AsyncRetry`/`Retry` with a Finagle-style `RetryBudget`, `AsyncBulkhead`/`Bulkhead` concurrency limiter, `AsyncCircuitBreaker`/`CircuitBreaker` consecutive-failure breaker, and `AsyncTimeout` for overall-operation wall-clock bounds.
-
-> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
-
-## Install
-
-```bash
-pip install httpware                # core only — no decoder
-pip install httpware[pydantic]      # + PydanticDecoder — handles BaseModel + dataclasses + primitives + generics
-pip install httpware[msgspec]       # + MsgspecDecoder — handles Struct + dataclasses + primitives + generics
-pip install httpware[pydantic,msgspec]   # both extras — both decoders register; BaseModel routes to pydantic, Struct to msgspec
-pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
-```
-
-`AsyncClient()` resolves `decoders=None` against installed extras: pydantic if installed (first), msgspec if installed (second), or an empty tuple if neither. `AsyncClient()` never raises on missing extras — failure is deferred to the first `response_model=` call, where `MissingDecoderError` fires *before* the HTTP request if no registered decoder claims the model.
-
-## Quickstart
-
-**Async usage:**
-
-```python
-import asyncio
-
-from httpware import AsyncClient
-
-async def main() -> None:
-    async with AsyncClient(base_url="https://example.test") as client:
-        response = await client.get("/users/42")
-        print(response.json())
-
-asyncio.run(main())
-```
-
-**Sync usage:**
-
-```python
-from httpware import Client
-
-with Client(base_url="https://example.test") as client:
-    response = client.get("/users/42")
-    print(response.json())
-```
-
-Typed decoding via `response_model=` works in both worlds — install either `pip install httpware[pydantic]` or `pip install httpware[msgspec]` (or both; pydantic is tried first when both are present). Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
-
-```python
-from httpware import AsyncClient
-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; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
-
-The sync `Client` accepts identical `middleware=[...]`; swap `AsyncClient` → `Client` and `AsyncRetry` → `Retry` for the sync version.
-
-```python
-from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
-
-
-async def main() -> None:
-    async with AsyncClient(
-        base_url="https://api.example.com",
-        middleware=[
-            AsyncBulkhead(max_concurrent=10),  # cap total in-flight
-            AsyncRetry(),                       # default: 3 attempts, full-jitter backoff
-        ],
-    ) as client:
-        user = await client.get("/users/1", response_model=User)
-```
-
-Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](https://httpware.modern-python.org/middleware/).
-
-### 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: `AsyncRetry`, `AsyncBulkhead`, and any custom middleware are bypassed. (AsyncRetry 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`.
-
-## Observability
-
-All resilience middleware emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
-
-Logger names and event names are the stable public contract: `httpware.retry` (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`), `httpware.bulkhead` (`bulkhead.rejected`), `httpware.circuit_breaker` (`circuit.opened`, `circuit.rejected`, `circuit.half_open`, `circuit.closed`), and `httpware.timeout` (`timeout.exceeded`).
-
-```python
-import logging
-
-# Enable visibility into resilience operational events
-logging.getLogger("httpware.retry").setLevel(logging.WARNING)
-logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
-logging.getLogger("httpware.circuit_breaker").setLevel(logging.WARNING)
-logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
-```
-
-For OTel attribute enrichment on the active span — install the extra:
-
-```bash
-pip install httpware[otel]
-```
-
-When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
-
-## 📚 [Documentation](https://httpware.modern-python.org)
-
-## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
-
-## 📦 [PyPI](https://pypi.org/project/httpware)
-
-## 📝 [License](https://github.com/modern-python/httpware/blob/main/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.10.0/README.md

@@ -1,151 +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)
-
-**A Python HTTP client framework with sync and async clients for building resilient service clients.**
-
-`httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a resilience suite under `httpware.middleware.resilience` — `AsyncRetry`/`Retry` with a Finagle-style `RetryBudget`, `AsyncBulkhead`/`Bulkhead` concurrency limiter, `AsyncCircuitBreaker`/`CircuitBreaker` consecutive-failure breaker, and `AsyncTimeout` for overall-operation wall-clock bounds.
-
-> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
-
-## Install
-
-```bash
-pip install httpware                # core only — no decoder
-pip install httpware[pydantic]      # + PydanticDecoder — handles BaseModel + dataclasses + primitives + generics
-pip install httpware[msgspec]       # + MsgspecDecoder — handles Struct + dataclasses + primitives + generics
-pip install httpware[pydantic,msgspec]   # both extras — both decoders register; BaseModel routes to pydantic, Struct to msgspec
-pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
-```
-
-`AsyncClient()` resolves `decoders=None` against installed extras: pydantic if installed (first), msgspec if installed (second), or an empty tuple if neither. `AsyncClient()` never raises on missing extras — failure is deferred to the first `response_model=` call, where `MissingDecoderError` fires *before* the HTTP request if no registered decoder claims the model.
-
-## Quickstart
-
-**Async usage:**
-
-```python
-import asyncio
-
-from httpware import AsyncClient
-
-async def main() -> None:
-    async with AsyncClient(base_url="https://example.test") as client:
-        response = await client.get("/users/42")
-        print(response.json())
-
-asyncio.run(main())
-```
-
-**Sync usage:**
-
-```python
-from httpware import Client
-
-with Client(base_url="https://example.test") as client:
-    response = client.get("/users/42")
-    print(response.json())
-```
-
-Typed decoding via `response_model=` works in both worlds — install either `pip install httpware[pydantic]` or `pip install httpware[msgspec]` (or both; pydantic is tried first when both are present). Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
-
-```python
-from httpware import AsyncClient
-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; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
-
-The sync `Client` accepts identical `middleware=[...]`; swap `AsyncClient` → `Client` and `AsyncRetry` → `Retry` for the sync version.
-
-```python
-from httpware import AsyncClient, AsyncBulkhead, AsyncRetry
-
-
-async def main() -> None:
-    async with AsyncClient(
-        base_url="https://api.example.com",
-        middleware=[
-            AsyncBulkhead(max_concurrent=10),  # cap total in-flight
-            AsyncRetry(),                       # default: 3 attempts, full-jitter backoff
-        ],
-    ) as client:
-        user = await client.get("/users/1", response_model=User)
-```
-
-Need a custom middleware (auth, tracing, request-ID propagation, etc.)? See the [Middleware guide](https://httpware.modern-python.org/middleware/).
-
-### 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: `AsyncRetry`, `AsyncBulkhead`, and any custom middleware are bypassed. (AsyncRetry 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`.
-
-## Observability
-
-All resilience middleware emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.
-
-Logger names and event names are the stable public contract: `httpware.retry` (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`), `httpware.bulkhead` (`bulkhead.rejected`), `httpware.circuit_breaker` (`circuit.opened`, `circuit.rejected`, `circuit.half_open`, `circuit.closed`), and `httpware.timeout` (`timeout.exceeded`).
-
-```python
-import logging
-
-# Enable visibility into resilience operational events
-logging.getLogger("httpware.retry").setLevel(logging.WARNING)
-logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
-logging.getLogger("httpware.circuit_breaker").setLevel(logging.WARNING)
-logging.getLogger("httpware.timeout").setLevel(logging.WARNING)
-```
-
-For OTel attribute enrichment on the active span — install the extra:
-
-```bash
-pip install httpware[otel]
-```
-
-When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
-
-## 📚 [Documentation](https://httpware.modern-python.org)
-
-## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
-
-## 📦 [PyPI](https://pypi.org/project/httpware)
-
-## 📝 [License](https://github.com/modern-python/httpware/blob/main/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.