feat(decoders): add can_decode predicate to ResponseDecoder protocol

Author: lesnik512

src/httpware/decoders/__init__.py

@@ -10,6 +10,18 @@
 class ResponseDecoder(Protocol):
     """Structural protocol every response-body decoder satisfies."""
 
+    def can_decode(self, model: type) -> bool:
+        """Return True iff this decoder claims responsibility for `model`.
+
+        The client walks its `_decoders` tuple in order and picks the first
+        decoder whose `can_decode` returns True. Implementations should claim
+        every model type they can actually handle — broad is correct, because
+        list ordering encodes the caller's preference for shared shapes.
+        Native types of another library (e.g. `PydanticDecoder` vs
+        `msgspec.Struct`) MUST be rejected.
+        """
+        ...
+
     def decode(self, content: bytes, model: type[T]) -> T:
         """Decode `content` (raw response bytes) into an instance of `model`.
 

src/httpware/decoders/msgspec.py

@@ -1,5 +1,6 @@
-"""MsgspecDecoder — opt-in ResponseDecoder backed by msgspec.json.decode."""
+"""MsgspecDecoder — opt-in ResponseDecoder backed by a cached msgspec.json.Decoder."""
 
+import functools
 from typing import TypeVar
 
 from httpware._internal import import_checker
@@ -14,19 +15,49 @@
 T = TypeVar("T")
 
 
+@functools.lru_cache(maxsize=1024)
+def _get_msgspec_decoder(model: type[T]) -> "msgspec.json.Decoder[T]":
+    return msgspec.json.Decoder(model)
+
+
 class MsgspecDecoder:
-    """Decode raw response bytes via `msgspec.json.decode(content, type=model)`.
+    """Decode raw response bytes via a cached `msgspec.json.Decoder(model)`.
 
     Requires the `msgspec` extra: `pip install httpware[msgspec]`. Importing
     this module without the extra works (the `msgspec` import is guarded by a
-    `find_spec` check), but instantiating the decoder raises `ImportError` with
-    the install hint.
+    `find_spec` check), but instantiating the decoder raises `ImportError`.
     """
 
     def __init__(self) -> None:
         if not import_checker.is_msgspec_installed:
             raise ImportError(MISSING_DEPENDENCY_MESSAGE)
 
+    def can_decode(self, model: type) -> bool:
+        """Return True iff msgspec natively understands `model`.
+
+        Cached via `_get_msgspec_decoder`; subsequent calls reuse the same
+        Decoder instance. Rejects `pydantic.BaseModel` subclasses — msgspec
+        will *build* a Decoder for them (falling back to a generic
+        `CustomType`) but cannot actually decode them without a `dec_hook`,
+        so we use `msgspec.inspect.type_info` to detect the fallback and
+        refuse to claim the model.
+        """
+        try:
+            info = msgspec.inspect.type_info(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        if isinstance(info, msgspec.inspect.CustomType):
+            return False
+        try:
+            _get_msgspec_decoder(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        return True
+
     def decode(self, content: bytes, model: type[T]) -> T:
         """Validate `content` as JSON against `model` in a single parse pass."""
-        return msgspec.json.decode(content, type=model)
+        try:
+            decoder = _get_msgspec_decoder(model)
+        except TypeError:
+            decoder = msgspec.json.Decoder(model)
+        return decoder.decode(content)

src/httpware/decoders/pydantic.py

@@ -36,6 +36,20 @@ def __init__(self) -> None:
         if not import_checker.is_pydantic_installed:
             raise ImportError(MISSING_DEPENDENCY_MESSAGE)
 
+    def can_decode(self, model: type) -> bool:
+        """Return True iff pydantic can build a schema for `model`.
+
+        Cached via `_get_adapter`; subsequent calls (including `decode`) reuse
+        the same `TypeAdapter` instance. Rejects `msgspec.Struct` subclasses —
+        pydantic raises `PydanticSchemaGenerationError` (a `TypeError`) when
+        building a schema for them.
+        """
+        try:
+            _get_adapter(model)
+        except Exception:  # noqa: BLE001 — can_decode is a probe; any failure means no
+            return False
+        return True
+
     def decode(self, content: bytes, model: type[T]) -> T:
         """Validate `content` as JSON against `model` in a single parse pass."""
         try:

tests/test_client_construction.py

@@ -55,6 +55,9 @@ def test_default_decoder_is_pydantic_decoder() -> None:
 
 def test_explicit_decoder_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
 

tests/test_client_sync.py

@@ -67,6 +67,9 @@ def test_default_decoder_is_pydantic_decoder() -> None:
 
 def test_explicit_decoder_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
 

tests/test_decoders_msgspec.py

@@ -1,15 +1,18 @@
 """Unit tests for httpware.decoders.msgspec.MsgspecDecoder."""
 
+import dataclasses
 from http import HTTPStatus
+from unittest.mock import patch
 
 import httpx2
 import msgspec
+import pydantic
 import pytest
 
 from httpware import AsyncClient, DecodeError
 from httpware._internal import import_checker
 from httpware.decoders import ResponseDecoder
-from httpware.decoders.msgspec import MsgspecDecoder
+from httpware.decoders.msgspec import MsgspecDecoder, _get_msgspec_decoder
 
 
 class _Item(msgspec.Struct):
@@ -70,3 +73,88 @@ def handler(request: httpx2.Request) -> httpx2.Response:
     exc = exc_info.value
     assert exc.model is _Item
     assert isinstance(exc.original, (msgspec.DecodeError, msgspec.ValidationError))
+
+
+class _PydanticUser(pydantic.BaseModel):
+    id: int
+    name: str
+
+
+@dataclasses.dataclass
+class _DC:
+    id: int
+    name: str
+
+
+@pytest.fixture(autouse=True)
+def _clear_msgspec_cache() -> None:
+    _get_msgspec_decoder.cache_clear()
+
+
+def test_msgspec_can_decode_struct() -> None:
+    assert MsgspecDecoder().can_decode(_Item) is True
+
+
+def test_msgspec_can_decode_dataclass() -> None:
+    assert MsgspecDecoder().can_decode(_DC) is True
+
+
+def test_msgspec_can_decode_dict() -> None:
+    assert MsgspecDecoder().can_decode(dict) is True
+
+
+def test_msgspec_can_decode_list_of_structs() -> None:
+    assert MsgspecDecoder().can_decode(list[_Item]) is True
+
+
+def test_msgspec_can_decode_primitive_int() -> None:
+    assert MsgspecDecoder().can_decode(int) is True
+
+
+def test_msgspec_rejects_pydantic_basemodel() -> None:
+    assert MsgspecDecoder().can_decode(_PydanticUser) is False
+
+
+def test_msgspec_can_decode_uses_cache() -> None:
+    _get_msgspec_decoder.cache_clear()
+    decoder = MsgspecDecoder()
+    decoder.can_decode(_Item)
+    decoder.can_decode(_Item)
+    info = _get_msgspec_decoder.cache_info()
+    assert info.hits >= 1
+    assert info.misses == 1
+
+
+def test_can_decode_returns_false_when_type_info_raises() -> None:
+    """`type_info` failures (unrecognized type) are treated as a soft 'no'."""
+    with patch(
+        "httpware.decoders.msgspec.msgspec.inspect.type_info",
+        side_effect=TypeError("unknown"),
+    ):
+        assert MsgspecDecoder().can_decode(_Item) is False
+
+
+def test_can_decode_returns_false_when_decoder_build_raises() -> None:
+    """A `_get_msgspec_decoder` failure after type_info-classification is a soft 'no'."""
+    _get_msgspec_decoder.cache_clear()
+    with patch(
+        "httpware.decoders.msgspec._get_msgspec_decoder",
+        side_effect=TypeError("cannot build decoder"),
+    ):
+        assert MsgspecDecoder().can_decode(_Item) is False
+
+
+def test_unhashable_model_falls_back_to_uncached_decoder() -> None:
+    """Unhashable `model` falls back to a direct uncached `msgspec.json.Decoder`.
+
+    Mirrors `PydanticDecoder`'s unhashable-fallback test: when `_get_msgspec_decoder`
+    raises `TypeError` (e.g., an unhashable parameterized type), `decode` bypasses
+    the cache so the user-visible error is `msgspec`'s own decode error, not a
+    `functools`-internal `TypeError`.
+    """
+    with patch(
+        "httpware.decoders.msgspec._get_msgspec_decoder",
+        side_effect=TypeError("unhashable type"),
+    ):
+        result = MsgspecDecoder().decode(b"42", int)
+        assert result == 42  # noqa: PLR2004

tests/test_decoders_pydantic.py

@@ -5,6 +5,7 @@
 import dataclasses
 from unittest.mock import patch
 
+import msgspec
 import pydantic
 import pytest
 
@@ -176,3 +177,46 @@ def test_malformed_payload_raises_validation_error(payload: bytes, model: type)
     """
     with pytest.raises(pydantic.ValidationError):
         PydanticDecoder().decode(payload, model)
+
+
+class _Struct(msgspec.Struct):
+    id: int
+    name: str
+
+
+def test_pydantic_can_decode_basemodel() -> None:
+    assert PydanticDecoder().can_decode(User) is True
+
+
+def test_pydantic_can_decode_dataclass() -> None:
+    assert PydanticDecoder().can_decode(UserDC) is True
+
+
+def test_pydantic_can_decode_dict() -> None:
+    assert PydanticDecoder().can_decode(dict) is True
+
+
+def test_pydantic_can_decode_list_of_models() -> None:
+    assert PydanticDecoder().can_decode(list[User]) is True
+
+
+def test_pydantic_can_decode_primitive_int() -> None:
+    assert PydanticDecoder().can_decode(int) is True
+
+
+def test_pydantic_can_decode_optional_int() -> None:
+    assert PydanticDecoder().can_decode(int | None) is True  # ty: ignore[invalid-argument-type]
+
+
+def test_pydantic_rejects_msgspec_struct() -> None:
+    assert PydanticDecoder().can_decode(_Struct) is False
+
+
+def test_pydantic_can_decode_uses_cache() -> None:
+    _get_adapter.cache_clear()
+    decoder = PydanticDecoder()
+    decoder.can_decode(User)
+    decoder.can_decode(User)
+    info = _get_adapter.cache_info()
+    assert info.hits >= 1
+    assert info.misses == 1

tests/test_optional_extras_pydantic_missing.py

@@ -17,6 +17,9 @@
 class _FakeDecoder:
     """Test stand-in for ResponseDecoder; never called at runtime."""
 
+    def can_decode(self, model: type) -> bool:  # noqa: ARG002 — name pinned by ResponseDecoder protocol
+        return True  # pragma: no cover
+
     def decode(self, content: bytes, model: type) -> object:  # noqa: ARG002 — name pinned by ResponseDecoder protocol
         return model()  # pragma: no cover