feat(client)!: AsyncClient takes decoders=[...] with type-dispatched routing

Author: lesnik512

src/httpware/client.py

@@ -16,7 +16,7 @@
     _raise_on_status_error,
 )
 from httpware.decoders import ResponseDecoder
-from httpware.errors import DecodeError, TransportError
+from httpware.errors import DecodeError, MissingDecoderError, TransportError
 from httpware.middleware import AsyncMiddleware, AsyncNext, Middleware, Next
 from httpware.middleware.chain import compose, compose_async
 
@@ -93,7 +93,7 @@ class AsyncClient:
 
     _httpx2_client: httpx2.AsyncClient
     _owns_client: bool
-    _decoder: ResponseDecoder
+    _decoders: tuple[ResponseDecoder, ...]
     _user_middleware: tuple[AsyncMiddleware, ...]
     _dispatch: AsyncNext
 
@@ -108,7 +108,7 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
         limits: httpx2.Limits | None = None,
         auth: httpx2.Auth | None = None,
         httpx2_client: httpx2.AsyncClient | None = None,
-        decoder: ResponseDecoder | None = None,
+        decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[AsyncMiddleware] = (),
     ) -> None:
         if httpx2_client is not None:
@@ -144,10 +144,17 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
             self._httpx2_client = httpx2.AsyncClient(**kwargs)
             self._owns_client = True
 
-        self._decoder = decoder if decoder is not None else _default_pydantic_decoder()
+        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)
 
+    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
+
     async def _terminal(self, request: httpx2.Request) -> httpx2.Response:
         try:
             async with _httpx2_exception_mapper():
@@ -172,11 +179,19 @@ async def send(
         response_model: type[T] | None = None,
     ) -> httpx2.Response | T:
         """Send `request` through the middleware chain. Decode if `response_model` is set."""
-        response = await self._dispatch(request)
         if response_model is None:
-            return response
+            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),
+            )
+
+        response = await self._dispatch(request)
         try:
-            return self._decoder.decode(response.content, response_model)
+            return decoder.decode(response.content, response_model)
         except Exception as exc:
             raise DecodeError(response=response, model=response_model, original=exc) from exc
 
@@ -195,9 +210,16 @@ async def send_with_response(
         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),
+            )
+
         response = await self._dispatch(request)
         try:
-            decoded = self._decoder.decode(response.content, response_model)
+            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

tests/test_client_construction.py

@@ -5,7 +5,7 @@
 import httpx2
 import pytest
 
-from httpware import AsyncClient
+from httpware import AsyncClient, MissingDecoderError
 from httpware.client import _build_default_decoders
 from httpware.decoders.msgspec import MsgspecDecoder
 from httpware.decoders.pydantic import PydanticDecoder
@@ -52,21 +52,48 @@ def test_caller_owned_client_with_forwarded_kwargs_is_typeerror(kwargs: dict) ->
         AsyncClient(httpx2_client=caller, **kwargs)
 
 
-def test_default_decoder_is_pydantic_decoder() -> None:
+def test_default_decoders_includes_pydantic_when_installed() -> None:
     client = AsyncClient()
-    assert isinstance(client._decoder, PydanticDecoder)  # noqa: SLF001
+    assert any(isinstance(d, PydanticDecoder) for d in client._decoders)  # noqa: SLF001
 
 
-def test_explicit_decoder_is_honored() -> None:
+def test_explicit_decoders_is_honored() -> None:
     class _Stub:
         def can_decode(self, model: type) -> bool:  # noqa: ARG002  # pragma: no cover
             return True
 
         def decode(self, content: bytes, model: type) -> object:  # noqa: ARG002  # pragma: no cover
             return None
 
-    client = AsyncClient(decoder=_Stub())
-    assert isinstance(client._decoder, _Stub)  # noqa: SLF001
+    stub = _Stub()
+    client = AsyncClient(decoders=[stub])
+    assert client._decoders == (stub,)  # noqa: SLF001
+
+
+def test_empty_decoders_is_honored() -> None:
+    client = AsyncClient(decoders=[])
+    assert client._decoders == ()  # noqa: SLF001
+
+
+async def test_missing_decoder_raised_before_http_call() -> None:
+    """response_model with no claiming decoder raises before the transport is invoked."""
+
+    def handler(_: httpx2.Request) -> httpx2.Response:  # pragma: no cover
+        pytest.fail("transport should not be invoked when MissingDecoderError fires")
+
+    transport = httpx2.MockTransport(handler)
+    client = AsyncClient(
+        httpx2_client=httpx2.AsyncClient(transport=transport),
+        decoders=[],
+    )
+
+    class _Foo:
+        pass
+
+    with pytest.raises(MissingDecoderError) as exc_info:
+        await client.get("https://example.test/x", response_model=_Foo)
+    assert exc_info.value.model is _Foo
+    assert exc_info.value.registered_names == ()
 
 
 @pytest.mark.parametrize(

tests/test_client_send_with_response.py

@@ -6,7 +6,7 @@
 import pydantic
 import pytest
 
-from httpware import AsyncClient, ClientError, DecodeError, NotFoundError
+from httpware import AsyncClient, ClientError, DecodeError, MissingDecoderError, NotFoundError
 from httpware.middleware import async_before_request
 
 
@@ -128,3 +128,21 @@ def handler(request: httpx2.Request) -> httpx2.Response:
     response, _ = await client.send_with_response(request, response_model=_User)
     assert recorded[0].headers.get("x-test") == "ok"
     assert response.request.headers.get("x-test") == "ok"
+
+
+async def test_send_with_response_raises_missing_decoder_before_http_call() -> None:
+    def handler(_: httpx2.Request) -> httpx2.Response:  # pragma: no cover
+        pytest.fail("transport should not be invoked when MissingDecoderError fires")
+
+    transport = httpx2.MockTransport(handler)
+    client = AsyncClient(
+        httpx2_client=httpx2.AsyncClient(transport=transport),
+        decoders=[],
+    )
+
+    class _Foo:
+        pass
+
+    request = client.build_request("GET", "https://example.test/x")
+    with pytest.raises(MissingDecoderError):
+        await client.send_with_response(request, response_model=_Foo)

tests/test_decoders_msgspec.py

@@ -66,7 +66,7 @@ def handler(request: httpx2.Request) -> httpx2.Response:
     transport = httpx2.MockTransport(handler)
     client = AsyncClient(
         httpx2_client=httpx2.AsyncClient(transport=transport),
-        decoder=MsgspecDecoder(),
+        decoders=[MsgspecDecoder()],
     )
     with pytest.raises(DecodeError) as exc_info:
         await client.get("https://example.test/x", response_model=_Item)

tests/test_optional_extras_pydantic_missing.py

@@ -32,12 +32,11 @@ def test_pydantic_decoder_init_raises_when_pydantic_missing() -> None:
         PydanticDecoder()
 
 
-def test_async_client_default_decoder_raises_when_pydantic_missing() -> None:
-    with (
-        patch("httpware._internal.import_checker.is_pydantic_installed", False),
-        pytest.raises(ImportError, match=r"httpware\[pydantic\]"),
-    ):
-        AsyncClient()
+def test_async_client_no_pydantic_constructs_without_raising() -> None:
+    """AsyncClient() with pydantic missing must not raise — lazy default policy."""
+    with patch("httpware._internal.import_checker.is_pydantic_installed", False):
+        client = AsyncClient()
+    assert all(not isinstance(d, PydanticDecoder) for d in client._decoders)  # noqa: SLF001
 
 
 def test_sync_client_default_decoder_raises_when_pydantic_missing() -> None:
@@ -48,12 +47,12 @@ def test_sync_client_default_decoder_raises_when_pydantic_missing() -> None:
         Client()
 
 
-def test_async_client_accepts_explicit_decoder_without_pydantic() -> None:
-    """An explicit decoder= escapes the fail-fast AND is actually wired to the client."""
+def test_async_client_accepts_explicit_decoders_without_pydantic() -> None:
+    """An explicit decoders= list is honored regardless of pydantic install state."""
     fake = _FakeDecoder()
     with patch("httpware._internal.import_checker.is_pydantic_installed", False):
-        client = AsyncClient(decoder=fake)
-    assert client._decoder is fake  # noqa: SLF001 — wired the explicit decoder, not a default
+        client = AsyncClient(decoders=[fake])
+    assert client._decoders == (fake,)  # noqa: SLF001
 
 
 def test_sync_client_accepts_explicit_decoder_without_pydantic() -> None: