feat(errors): add MissingDecoderError raised by future multi-decoder dispatch

Author: lesnik512

src/httpware/__init__.py

@@ -12,6 +12,7 @@
     DecodeError,
     ForbiddenError,
     InternalServerError,
+    MissingDecoderError,
     NetworkError,
     NotFoundError,
     RateLimitedError,
@@ -57,6 +58,7 @@
     "ForbiddenError",
     "InternalServerError",
     "Middleware",
+    "MissingDecoderError",
     "NetworkError",
     "Next",
     "NotFoundError",

src/httpware/errors.py

@@ -254,3 +254,43 @@ def __reduce__(self) -> tuple[Any, ...]:
             _reconstruct_decode_error,
             (type(self), self.response, self.model, self.original),
         )
+
+
+def _missing_decoder_summary(model: type, registered_names: tuple[str, ...]) -> str:
+    if not registered_names:
+        hint = (
+            "no decoders registered. Install `pip install httpware[pydantic]` "
+            "or `pip install httpware[msgspec]`, or pass decoders=[...] explicitly."
+        )
+    else:
+        joined = " + ".join(registered_names)
+        hint = f"registered decoders ({joined}) all rejected it. Pass a custom decoder via decoders=[...]."
+    return f"no decoder for response_model={model!r}: {hint}"
+
+
+def _reconstruct_missing_decoder(
+    cls: "type[MissingDecoderError]",
+    model: type,
+    registered_names: tuple[str, ...],
+) -> "MissingDecoderError":
+    return cls(model=model, registered_names=registered_names)
+
+
+class MissingDecoderError(ClientError):
+    """Raised when response_model= is set but no registered decoder claims the model.
+
+    Fires at .send() entry, BEFORE the HTTP call — no point sending a request
+    whose response cannot be decoded. Distinct from DecodeError, which means
+    the decoder ran and the payload was malformed.
+    """
+
+    model: type
+    registered_names: tuple[str, ...]
+
+    def __init__(self, *, model: type, registered_names: tuple[str, ...]) -> None:
+        self.model = model
+        self.registered_names = registered_names
+        super().__init__(_missing_decoder_summary(model, registered_names))
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (_reconstruct_missing_decoder, (type(self), self.model, self.registered_names))

tests/test_errors.py

@@ -18,6 +18,7 @@
     DecodeError,
     ForbiddenError,
     InternalServerError,
+    MissingDecoderError,
     NetworkError,
     NotFoundError,
     RateLimitedError,
@@ -305,3 +306,54 @@ def test_decode_error_pickleable() -> None:
     assert isinstance(restored.original, ValueError)
     assert str(restored.original) == "bad payload"
     assert restored.response.status_code == HTTPStatus.OK
+
+
+class _Foo:
+    pass
+
+
+def test_missing_decoder_error_carries_model() -> None:
+    exc = MissingDecoderError(model=_Foo, registered_names=())
+    assert exc.model is _Foo
+
+
+def test_missing_decoder_error_carries_registered_names() -> None:
+    exc = MissingDecoderError(model=_Foo, registered_names=("PydanticDecoder",))
+    assert exc.registered_names == ("PydanticDecoder",)
+
+
+def test_missing_decoder_error_no_registered_message() -> None:
+    exc = MissingDecoderError(model=_Foo, registered_names=())
+    msg = str(exc)
+    assert "no decoders registered" in msg
+    assert "httpware[pydantic]" in msg
+    assert "httpware[msgspec]" in msg
+
+
+def test_missing_decoder_error_single_registered_message() -> None:
+    exc = MissingDecoderError(model=_Foo, registered_names=("PydanticDecoder",))
+    assert "registered decoders (PydanticDecoder) all rejected" in str(exc)
+
+
+def test_missing_decoder_error_two_registered_message() -> None:
+    exc = MissingDecoderError(
+        model=_Foo,
+        registered_names=("PydanticDecoder", "MsgspecDecoder"),
+    )
+    assert "registered decoders (PydanticDecoder + MsgspecDecoder) all rejected" in str(exc)
+
+
+def test_missing_decoder_error_is_client_error() -> None:
+    exc = MissingDecoderError(model=_Foo, registered_names=())
+    assert isinstance(exc, ClientError)
+
+
+def test_missing_decoder_error_pickle_roundtrip() -> None:
+    exc = MissingDecoderError(
+        model=_Foo,
+        registered_names=("PydanticDecoder", "MsgspecDecoder"),
+    )
+    revived = pickle.loads(pickle.dumps(exc))  # noqa: S301
+    assert isinstance(revived, MissingDecoderError)
+    assert revived.model is _Foo
+    assert revived.registered_names == ("PydanticDecoder", "MsgspecDecoder")

tests/test_public_api.py

@@ -44,6 +44,7 @@ def test_expected_exports() -> None:
         "ForbiddenError",
         "InternalServerError",
         "Middleware",
+        "MissingDecoderError",
         "NetworkError",
         "Next",
         "NotFoundError",
@@ -71,3 +72,8 @@ def test_expected_exports() -> None:
     assert expected == actual, (
         f"__all__ mismatch:\n  missing from __all__: {expected - actual}\n  unexpected in __all__: {actual - expected}"
     )
+
+
+def test_missing_decoder_error_exported() -> None:
+    assert "MissingDecoderError" in httpware.__all__
+    assert httpware.MissingDecoderError.__module__ == "httpware.errors"