httpware 0.14.0__tar.gz → 0.15.1__tar.gz

{httpware-0.14.0 → httpware-0.15.1}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.14.0
-Summary: Resilience-first async HTTP client framework for Python
-Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
+Version: 0.15.1
+Summary: Python HTTP client framework with sync & async clients and built-in resilience
+Keywords: http-client,httpx,async,asyncio,resilience,retry,circuit-breaker,bulkhead,middleware,pydantic,msgspec,python
 Author: Artur Shiriev
 Author-email: Artur Shiriev <me@shiriev.ru>
 License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -20,19 +22,28 @@ 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
+Project-URL: Homepage, https://httpware.modern-python.org
+Project-URL: Documentation, https://httpware.modern-python.org
+Project-URL: Repository, https://github.com/modern-python/httpware
+Project-URL: Issues, https://github.com/modern-python/httpware/issues
+Project-URL: Changelog, https://github.com/modern-python/httpware/releases
 Provides-Extra: all
 Provides-Extra: msgspec
 Provides-Extra: otel
 Provides-Extra: pydantic
 Description-Content-Type: text/markdown
 
-# httpware
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-light.svg">
+    <img alt="httpware" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup.png" width="420">
+  </picture>
+</p>
 
 [![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)
+[![Downloads](https://static.pepy.tech/badge/httpware/month)](https://pepy.tech/projects/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)
@@ -42,7 +53,7 @@ Description-Content-Type: text/markdown
 [![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.**
+**Typed, resilient HTTP clients for Python — typed errors, typed response bodies, and composable resilience (retry, bulkhead, circuit breaker), sync or async.**
 
 ## Why httpware
 

{httpware-0.14.0 → httpware-0.15.1}/README.md

@@ -1,8 +1,14 @@
-# httpware
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup-light.svg">
+    <img alt="httpware" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/httpware/lockup.png" width="420">
+  </picture>
+</p>
 
 [![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)
+[![Downloads](https://static.pepy.tech/badge/httpware/month)](https://pepy.tech/projects/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)
@@ -12,7 +18,7 @@
 [![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.**
+**Typed, resilient HTTP clients for Python — typed errors, typed response bodies, and composable resilience (retry, bulkhead, circuit breaker), sync or async.**
 
 ## Why httpware
 

{httpware-0.14.0 → httpware-0.15.1}/pyproject.toml

@@ -1,22 +1,27 @@
 [project]
 name = "httpware"
-description = "Resilience-first async HTTP client framework for Python"
+description = "Python HTTP client framework with sync & async clients and built-in resilience"
 authors = [{ name = "Artur Shiriev", email = "me@shiriev.ru" }]
 requires-python = ">=3.11,<4"
 license = "MIT"
 readme = "README.md"
 keywords = [
-    "http",
+    "http-client",
+    "httpx",
     "async",
-    "client",
+    "asyncio",
     "resilience",
     "retry",
     "circuit-breaker",
+    "bulkhead",
     "middleware",
-    "httpx",
     "pydantic",
+    "msgspec",
+    "python",
 ]
 classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -26,7 +31,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.14.0"
+version = "0.15.1"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -38,8 +43,11 @@ otel = ["opentelemetry-api>=1.20"]
 all = ["httpware[pydantic,msgspec,otel]"]
 
 [project.urls]
-repository = "https://github.com/modern-python/httpware"
-docs = "https://httpware.modern-python.org"
+Homepage = "https://httpware.modern-python.org"
+Documentation = "https://httpware.modern-python.org"
+Repository = "https://github.com/modern-python/httpware"
+Issues = "https://github.com/modern-python/httpware/issues"
+Changelog = "https://github.com/modern-python/httpware/releases"
 
 [build-system]
 requires = ["uv_build>=0.11,<1.0"]

{httpware-0.14.0 → httpware-0.15.1}/src/httpware/client.py

@@ -2,7 +2,7 @@
 
 import contextlib
 import typing
-from collections.abc import AsyncIterator, Iterator, Sequence
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
 from http import HTTPStatus
 
 import httpx2
@@ -16,7 +16,8 @@ from httpware._internal.status import (
     _raise_on_status_error,
 )
 from httpware.decoders import ResponseDecoder
-from httpware.errors import DecodeError, MissingDecoderError, ResponseTooLargeError, TransportError
+from httpware.decoders._resolver import _DecoderResolver
+from httpware.errors import ResponseTooLargeError, TransportError
 from httpware.middleware import AsyncMiddleware, AsyncNext, Middleware, Next
 from httpware.middleware.chain import compose, compose_async
 
@@ -31,6 +32,15 @@ _HTTPX2_CLIENT_CONFLICT_MESSAGE = (
 )
 
 
+_MAX_RESPONSE_BODY_BYTES_INVALID = "max_response_body_bytes must be >= 1"
+
+
+def _validate_max_response_body_bytes(cap: int | None) -> None:
+    """Reject a non-None cap below 1. None means unbounded (the default)."""
+    if cap is not None and cap < 1:
+        raise ValueError(_MAX_RESPONSE_BODY_BYTES_INVALID)
+
+
 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:
@@ -42,6 +52,123 @@ def _parse_content_length(raw: str | None) -> int | None:
     return value if value >= 0 else None
 
 
+class _CapExceeded(Exception):  # noqa: N818 — internal control-flow signal, not a user-facing error
+    """Internal signal: decoded bytes crossed the cap mid-read. Carries bytes read so far."""
+
+    def __init__(self, *, read: int) -> None:
+        self.read = read
+        super().__init__(f"decoded body exceeded cap after {read} bytes")
+
+
+def _accumulate_capped(chunks: typing.Iterable[bytes], cap: int) -> bytes:
+    """Concatenate `chunks`, raising `_CapExceeded` the moment the running total exceeds `cap`.
+
+    Counts decoded bytes (the in-memory footprint). Grown in a single bytearray
+    so there is no transient list-plus-join double allocation.
+    """
+    buf = bytearray()
+    for chunk in chunks:
+        buf += chunk
+        if len(buf) > cap:
+            raise _CapExceeded(read=len(buf))
+    return bytes(buf)
+
+
+def _safe_extensions(extensions: Mapping[str, typing.Any]) -> dict[str, typing.Any]:
+    """Copy response extensions, dropping the now-stale `network_stream`.
+
+    The rebuilt buffered Response never touches its network stream, so carrying a
+    consumed/closed one wholesale is sloppy. `http_version`/`reason_phrase` and
+    any other keys are preserved.
+    """
+    return {key: value for key, value in extensions.items() if key != "network_stream"}
+
+
+# Headers describing the wire encoding of the body. The accumulator yields the
+# DECODED body, so these no longer apply; httpx2 recomputes content-length from
+# the buffered content. Carrying content-encoding forward makes httpx2 try to
+# re-decode already-decoded bytes and raise.
+_WIRE_BODY_HEADERS = ("content-encoding", "content-length", "transfer-encoding")
+_BODILESS_STATUS = frozenset({HTTPStatus.NO_CONTENT, HTTPStatus.NOT_MODIFIED})  # 204, 304
+
+
+def _buffered_headers(headers: httpx2.Headers) -> httpx2.Headers:
+    """Copy `headers`, stripping wire-encoding headers stale after decoding+buffering."""
+    out = httpx2.Headers(headers)
+    for name in _WIRE_BODY_HEADERS:
+        if name in out:
+            del out[name]
+    return out
+
+
+def _response_has_body(method: str, status_code: int) -> bool:
+    """Whether a response carries a message body (RFC 9110 §6.4.1).
+
+    HEAD responses and 204/304 never have a body regardless of a declared
+    Content-Length, so they must never trip the cap.
+    """
+    return method.upper() != "HEAD" and status_code not in _BODILESS_STATUS
+
+
+def _read_capped(response: httpx2.Response, cap: int, request: httpx2.Request) -> httpx2.Response:
+    """Buffer a streaming sync `response` under `cap` decoded bytes; return a buffered Response.
+
+    Raises `ResponseTooLargeError` (reason="declared") if the declared
+    Content-Length already exceeds `cap` — before any byte is read — and
+    (reason="streamed") if the decoded body crosses `cap` mid-read. Does not
+    close `response`; the caller owns the stream lifecycle.
+    """
+    if not _response_has_body(request.method, response.status_code):
+        response.read()  # empty body; preserve the original response (and its headers)
+        return response
+    content_length = _parse_content_length(response.headers.get("content-length"))
+    if content_length is not None and content_length > cap:
+        raise ResponseTooLargeError(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="declared"
+        )
+    try:
+        content = _accumulate_capped(response.iter_bytes(), cap)
+    except _CapExceeded:
+        raise ResponseTooLargeError(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="streamed"
+        ) from None
+    return httpx2.Response(
+        status_code=response.status_code,
+        headers=_buffered_headers(response.headers),
+        content=content,
+        request=request,
+        extensions=_safe_extensions(response.extensions),
+        history=response.history,
+    )
+
+
+async def _read_capped_async(response: httpx2.Response, cap: int, request: httpx2.Request) -> httpx2.Response:
+    """Async mirror of `_read_capped` (counts decoded bytes from `aiter_bytes`)."""
+    if not _response_has_body(request.method, response.status_code):
+        await response.aread()  # empty body; preserve the original response (and its headers)
+        return response
+    content_length = _parse_content_length(response.headers.get("content-length"))
+    if content_length is not None and content_length > cap:
+        raise ResponseTooLargeError(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="declared"
+        )
+    buf = bytearray()
+    async for chunk in response.aiter_bytes():
+        buf += chunk
+        if len(buf) > cap:
+            raise ResponseTooLargeError(
+                status_code=response.status_code, limit=cap, content_length=content_length, reason="streamed"
+            )
+    return httpx2.Response(
+        status_code=response.status_code,
+        headers=_buffered_headers(response.headers),
+        content=bytes(buf),
+        request=request,
+        extensions=_safe_extensions(response.extensions),
+        history=response.history,
+    )
+
+
 def _build_default_decoders() -> tuple[ResponseDecoder, ...]:
     """Construct the default decoder tuple based on installed extras.
 
@@ -93,7 +220,7 @@ class AsyncClient:
     _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[AsyncMiddleware, ...]
     _dispatch: AsyncNext
-    _max_error_body_bytes: int | None
+    _max_response_body_bytes: int | None
 
     def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call API
         self,
@@ -108,8 +235,9 @@ class AsyncClient:
         httpx2_client: httpx2.AsyncClient | None = None,
         decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[AsyncMiddleware] = (),
-        max_error_body_bytes: int | None = None,
+        max_response_body_bytes: int | None = None,
     ) -> None:
+        _validate_max_response_body_bytes(max_response_body_bytes)
         if httpx2_client is not None:
             forwarded = {
                 "base_url": base_url,
@@ -144,21 +272,23 @@ class AsyncClient:
             self._owns_client = True
 
         self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
+        self._decoder_resolver = _DecoderResolver(self._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."""
-        for decoder in self._decoders:
-            if decoder.can_decode(model):
-                return decoder
-        return None
+        self._max_response_body_bytes = max_response_body_bytes
 
     async def _terminal(self, request: httpx2.Request) -> httpx2.Response:
+        cap = self._max_response_body_bytes
         try:
             async with _httpx2_exception_mapper():
-                response = await self._httpx2_client.send(request)
+                if cap is None:
+                    response = await self._httpx2_client.send(request)
+                else:
+                    streaming = await self._httpx2_client.send(request, stream=True)
+                    try:
+                        response = await _read_capped_async(streaming, cap, request)
+                    finally:
+                        await streaming.aclose()
         except RuntimeError as exc:
             if self._httpx2_client.is_closed:
                 raise TransportError(str(exc)) from exc
@@ -182,18 +312,9 @@ class AsyncClient:
         if response_model is None:
             return await self._dispatch(request)
 
-        decoder = self._dispatch_decoder(response_model)
-        if decoder is None:
-            raise MissingDecoderError(
-                model=response_model,
-                registered_names=tuple(type(d).__name__ for d in self._decoders),
-            )
-
+        bound = self._decoder_resolver.resolve(response_model)
         response = await self._dispatch(request)
-        try:
-            return decoder.decode(response.content, response_model)
-        except Exception as exc:
-            raise DecodeError(response=response, model=response_model, original=exc) from exc
+        return bound.decode(response)
 
     async def send_with_response(
         self,
@@ -210,19 +331,9 @@ class AsyncClient:
         Not for streaming responses — decodes ``response.content``, which
         requires the body to be fully read. Use ``stream()`` for streaming.
         """
-        decoder = self._dispatch_decoder(response_model)
-        if decoder is None:
-            raise MissingDecoderError(
-                model=response_model,
-                registered_names=tuple(type(d).__name__ for d in self._decoders),
-            )
-
+        bound = self._decoder_resolver.resolve(response_model)
         response = await self._dispatch(request)
-        try:
-            decoded = decoder.decode(response.content, response_model)
-        except Exception as exc:
-            raise DecodeError(response=response, model=response_model, original=exc) from exc
-        return response, decoded
+        return response, bound.decode(response)
 
     def build_request(self, method: str, url: str, **kwargs: typing.Any) -> httpx2.Request:
         """Delegate request construction to the wrapped httpx2.AsyncClient."""
@@ -1039,16 +1150,13 @@ 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)
+                cap = self._max_response_body_bytes
+                if cap is None:
+                    await response.aread()  # pre-read body so exc.response.content works
+                    _raise_on_status_error(response)
+                else:
+                    # Bound the error pre-read; raises ResponseTooLargeError when over cap.
+                    _raise_on_status_error(await _read_capped_async(response, cap, response.request))
             yield response
 
     async def __aenter__(self) -> typing.Self:
@@ -1084,7 +1192,7 @@ class Client:
     _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[Middleware, ...]
     _dispatch: Next
-    _max_error_body_bytes: int | None
+    _max_response_body_bytes: int | None
 
     def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call API
         self,
@@ -1099,8 +1207,9 @@ class Client:
         httpx2_client: httpx2.Client | None = None,
         decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[Middleware] = (),
-        max_error_body_bytes: int | None = None,
+        max_response_body_bytes: int | None = None,
     ) -> None:
+        _validate_max_response_body_bytes(max_response_body_bytes)
         if httpx2_client is not None:
             forwarded = {
                 "base_url": base_url,
@@ -1135,21 +1244,23 @@ class Client:
             self._owns_client = True
 
         self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
+        self._decoder_resolver = _DecoderResolver(self._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."""
-        for decoder in self._decoders:
-            if decoder.can_decode(model):
-                return decoder
-        return None
+        self._max_response_body_bytes = max_response_body_bytes
 
     def _terminal(self, request: httpx2.Request) -> httpx2.Response:
+        cap = self._max_response_body_bytes
         try:
             with _httpx2_exception_mapper_sync():
-                response = self._httpx2_client.send(request)
+                if cap is None:
+                    response = self._httpx2_client.send(request)
+                else:
+                    streaming = self._httpx2_client.send(request, stream=True)
+                    try:
+                        response = _read_capped(streaming, cap, request)
+                    finally:
+                        streaming.close()
         except RuntimeError as exc:
             if self._httpx2_client.is_closed:
                 raise TransportError(str(exc)) from exc
@@ -1197,18 +1308,9 @@ class Client:
         if response_model is None:
             return self._dispatch(request)
 
-        decoder = self._dispatch_decoder(response_model)
-        if decoder is None:
-            raise MissingDecoderError(
-                model=response_model,
-                registered_names=tuple(type(d).__name__ for d in self._decoders),
-            )
-
+        bound = self._decoder_resolver.resolve(response_model)
         response = self._dispatch(request)
-        try:
-            return decoder.decode(response.content, response_model)
-        except Exception as exc:
-            raise DecodeError(response=response, model=response_model, original=exc) from exc
+        return bound.decode(response)
 
     def send_with_response(
         self,
@@ -1225,19 +1327,9 @@ class Client:
         Not for streaming responses — decodes ``response.content``, which
         requires the body to be fully read. Use ``stream()`` for streaming.
         """
-        decoder = self._dispatch_decoder(response_model)
-        if decoder is None:
-            raise MissingDecoderError(
-                model=response_model,
-                registered_names=tuple(type(d).__name__ for d in self._decoders),
-            )
-
+        bound = self._decoder_resolver.resolve(response_model)
         response = self._dispatch(request)
-        try:
-            decoded = decoder.decode(response.content, response_model)
-        except Exception as exc:
-            raise DecodeError(response=response, model=response_model, original=exc) from exc
-        return response, decoded
+        return response, bound.decode(response)
 
     def build_request(self, method: str, url: str, **kwargs: typing.Any) -> httpx2.Request:
         """Delegate request construction to the wrapped httpx2.Client."""
@@ -2052,14 +2144,11 @@ 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)
+                cap = self._max_response_body_bytes
+                if cap is None:
+                    response.read()  # pre-read body so exc.response.content works
+                    _raise_on_status_error(response)
+                else:
+                    # Bound the error pre-read; raises ResponseTooLargeError when over cap.
+                    _raise_on_status_error(_read_capped(response, cap, response.request))
             yield response

httpware-0.15.1/src/httpware/decoders/_resolver.py

@@ -0,0 +1,64 @@
+"""The Seam B orchestrator: resolve a response_model to a claiming decoder, then decode.
+
+`_DecoderResolver` walks the client's frozen `_decoders` tuple and returns the
+first decoder whose `can_decode` claims the model, bound to that model as a
+`_BoundDecoder`. Resolution (and the pre-flight `MissingDecoderError`) is a
+separate step from decoding because the HTTP call happens between them: the
+client calls `resolve` before `_dispatch` — so a missing decoder fails before
+the request goes out — and `_BoundDecoder.decode` after the response arrives.
+
+Both clients hold one `_DecoderResolver`; it is fully synchronous, so there is
+no sync/async split. See architecture/decoders.md for the full Seam B contract.
+"""
+
+from typing import Generic, TypeVar
+
+import httpx2
+
+from httpware.decoders import ResponseDecoder
+from httpware.errors import DecodeError, MissingDecoderError
+
+
+T = TypeVar("T")
+
+
+class _BoundDecoder(Generic[T]):
+    """A `ResponseDecoder` sealed to the `model` it will decode into.
+
+    Binding the decoder and model together at resolve time makes a
+    decoder/model mismatch unrepresentable: the caller supplies only the
+    response. Decode failures are wrapped as `DecodeError` (the Seam B
+    contract — implementers never raise it directly).
+    """
+
+    def __init__(self, decoder: ResponseDecoder, model: type[T]) -> None:
+        self._decoder = decoder
+        self._model = model
+
+    def decode(self, response: httpx2.Response) -> T:
+        """Decode `response.content` into `model`, wrapping any failure as `DecodeError`."""
+        try:
+            return self._decoder.decode(response.content, self._model)
+        except Exception as exc:
+            raise DecodeError(response=response, model=self._model, original=exc) from exc
+
+
+class _DecoderResolver:
+    """Resolves a `response_model` to the first claiming decoder in a frozen list."""
+
+    def __init__(self, decoders: tuple[ResponseDecoder, ...]) -> None:
+        self._decoders = decoders
+
+    def resolve(self, model: type[T]) -> _BoundDecoder[T]:
+        """Return the first decoder claiming `model`, bound to it.
+
+        Raises `MissingDecoderError` when no registered decoder claims `model`.
+        Called before the HTTP call, so the failure is pre-flight.
+        """
+        for decoder in self._decoders:
+            if decoder.can_decode(model):
+                return _BoundDecoder(decoder, model)
+        raise MissingDecoderError(
+            model=model,
+            registered_names=tuple(type(d).__name__ for d in self._decoders),
+        )