reflectapi-runtime 0.17.6__tar.gz → 0.18.0__tar.gz

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: reflectapi-runtime
-Version: 0.17.6
+Version: 0.18.0
 Summary: Runtime library for ReflectAPI Python clients
 Project-URL: Homepage, https://github.com/thepartly/reflectapi
 Project-URL: Repository, https://github.com/thepartly/reflectapi
@@ -14,12 +14,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.4.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'
@@ -50,8 +52,9 @@ directly.
 - `ApplicationError`, `NetworkError`, `TimeoutError`, `ValidationError` —
   exceptions raised by the generated methods on non-2xx, transport, and
   validation failures respectively.
-- `ReflectapiOption` — three-state Option used by the generated models
-  (`some` / `none` / `undefined`) so absent and explicit-null can round-trip.
+- `ReflectapiPartialModel` — base class for generated models with three-state
+  fields (value / explicit-null / absent) so absent and explicit-null can
+  round-trip, tracked via Pydantic's `model_fields_set`.
 - Authentication helpers (`BearerTokenAuth`, `APIKeyAuth`, `BasicAuth`,
   `OAuth2ClientCredentialsAuth`, `OAuth2AuthorizationCodeAuth`).
 - Middleware, batching, and testing utilities (`MockClient`,

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/README.md

@@ -15,8 +15,9 @@ directly.
 - `ApplicationError`, `NetworkError`, `TimeoutError`, `ValidationError` —
   exceptions raised by the generated methods on non-2xx, transport, and
   validation failures respectively.
-- `ReflectapiOption` — three-state Option used by the generated models
-  (`some` / `none` / `undefined`) so absent and explicit-null can round-trip.
+- `ReflectapiPartialModel` — base class for generated models with three-state
+  fields (value / explicit-null / absent) so absent and explicit-null can
+  round-trip, tracked via Pydantic's `model_fields_set`.
 - Authentication helpers (`BearerTokenAuth`, `APIKeyAuth`, `BasicAuth`,
   `OAuth2ClientCredentialsAuth`, `OAuth2AuthorizationCodeAuth`).
 - Middleware, batching, and testing utilities (`MockClient`,

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reflectapi-runtime"
-version = "0.17.6"
+version = "0.18.0"
 description = "Runtime library for ReflectAPI Python clients"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,6 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Internet :: WWW/HTTP",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
@@ -27,6 +28,7 @@ classifiers = [
 dependencies = [
     "pydantic>=2.0.0",
     "httpx>=0.25.0",
+    "typing-extensions>=4.4.0",
 ]
 
 [project.optional-dependencies]

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/src/reflectapi_runtime/__init__.py

@@ -50,7 +50,7 @@ from .testing import (
 )
 from .types import BatchResult, ReflectapiEmpty, ReflectapiInfallible
 
-__version__ = "0.17.6"
+__version__ = "0.18.0"
 
 __all__ = [
     # Authentication

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/src/reflectapi_runtime/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import datetime
 import json
 import time
@@ -50,6 +51,119 @@ def _json_serializer(obj: Any) -> Any:
 # Note: AsyncAuthWrapper removed - AuthHandler now inherits from httpx.Auth directly
 
 
+def _synthesize_raw_response(
+    status: int, headers: Any, body: bytes | str | None
+) -> httpx.Response:
+    """Build a stand-in ``httpx.Response`` for ``TransportMetadata.raw_response``.
+
+    Used only when a custom transport returns a structural :class:`Response`
+    without a wire-level ``raw`` object to surface. Response parsing never
+    goes through this synthetic object — it exists purely so
+    ``raw_response`` keeps its ``httpx.Response`` shape for callers.
+
+    The structural body is already decoded (``httpx.Response.content``
+    decompresses on read), but the headers may still advertise
+    ``Content-Encoding``. Passing both back into
+    ``httpx.Response(content=...)`` would make httpx decompress the decoded
+    bytes a second time and raise ``DecodingError``, so the compression
+    headers are stripped. ``Content-Length`` describes the wire body, which
+    the structural body (decoded, possibly middleware-rewritten) need not
+    match, so it is always dropped.
+    """
+    sanitized_headers = httpx.Headers(headers)
+    if "content-encoding" in sanitized_headers:
+        del sanitized_headers["content-encoding"]
+    if "content-length" in sanitized_headers:
+        del sanitized_headers["content-length"]
+    return httpx.Response(
+        status_code=status,
+        headers=sanitized_headers,
+        content=body,
+    )
+
+
+def _parse_json_body(body: bytes | str | None) -> Any:
+    """Parse a response body as JSON, raising ``ValidationError`` on failure."""
+    try:
+        return json.loads(body if body is not None else b"")
+    except Exception as e:
+        raise ValidationError(
+            f"Failed to parse JSON response: {e}",
+            cause=e,
+        )
+
+
+def _raise_for_error_status(
+    status: int,
+    body: bytes | str | None,
+    metadata: TransportMetadata,
+    error_model: type | None = None,
+) -> None:
+    """Raise ``ApplicationError`` for HTTP error responses (4xx, 5xx).
+
+    If ``error_model`` is provided, attempts to deserialize the error body
+    into a typed Pydantic model before raising.
+    """
+    if status < 400:
+        return
+
+    error_data = None
+    typed_error = None
+    with contextlib.suppress(Exception):
+        error_data = json.loads(body)
+
+    # Try typed error deserialization; fall back to raw error_data
+    if error_model is not None and error_data is not None:
+        with contextlib.suppress(Exception):
+            typed_error = TypeAdapter(error_model).validate_python(error_data)
+
+    message = f"API error {status}: {httpx.codes.get_reason_phrase(status)}"
+    if error_data:
+        message += f" - {error_data}"
+
+    raise ApplicationError(
+        message,
+        metadata=metadata,
+        error_data=error_data,
+        typed_error=typed_error,
+    )
+
+
+def _validate_body(
+    body: bytes | str | None,
+    response_model: type[T] | type[Any] | str | _NoValidation,
+    metadata: TransportMetadata,
+) -> ApiResponse[T] | ApiResponse[dict[str, Any]]:
+    """Validate a response body using Pydantic via TypeAdapter.
+
+    TypeAdapter handles all types: plain BaseModel, Generic types
+    (list[Model], dict[str, Model]), Union types, and primitives.
+    Uses validate_json for Pydantic's fast Rust-based JSON parsing when raw
+    bytes are available.
+    """
+    # Handle special cases where no validation is needed
+    if (
+        response_model == "Any"
+        or response_model is NO_VALIDATION
+        or response_model is Any
+    ):
+        return ApiResponse(_parse_json_body(body), metadata)
+
+    try:
+        ta = TypeAdapter(response_model)
+        if isinstance(body, (bytes, bytearray, str)):
+            validated_data = ta.validate_json(body)
+        else:
+            validated_data = ta.validate_python(_parse_json_body(body))
+        return ApiResponse(validated_data, metadata)
+    except PydanticValidationError as e:
+        raise ValidationError(
+            f"Response validation failed: {e}",
+            validation_errors=e.errors(),
+            cause=e,
+        )
+
+
 class ClientBase(ABC):
     """Base class for synchronous ReflectAPI clients."""
 
@@ -173,6 +287,7 @@ class ClientBase(ABC):
         json_model: None = None,
         headers_model: BaseModel | None = None,
         response_model: type[T],
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -186,6 +301,7 @@ class ClientBase(ABC):
         json_model: None = None,
         headers_model: BaseModel | None = None,
         response_model: None = None,
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -199,7 +315,8 @@ class ClientBase(ABC):
         json_model: None = None,
         headers_model: BaseModel | None = None,
         response_model: type[Any],
-    ) -> ApiResponse[dict[str, Any]]: ...
+        error_model: type[Any] | None = None,
+    ) -> ApiResponse[Any]: ...
 
     @overload
     def _make_request(
@@ -210,7 +327,9 @@ class ClientBase(ABC):
         params: dict[str, Any] | None = None,
         json_data: dict[str, Any] | None = None,
         json_model: None = None,
+        headers_model: BaseModel | None = None,
         response_model: str,
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -224,6 +343,7 @@ class ClientBase(ABC):
         json_model: BaseModel,
         headers_model: BaseModel | None = None,
         response_model: type[T],
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -237,6 +357,7 @@ class ClientBase(ABC):
         json_model: BaseModel,
         headers_model: BaseModel | None = None,
         response_model: None = None,
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     def _validate_request_params(
@@ -389,85 +510,6 @@ class ClientBase(ABC):
 
         return terminal
 
-    def _handle_error_response(
-        self,
-        response: httpx.Response,
-        metadata: TransportMetadata,
-        error_model: type | None = None,
-    ) -> None:
-        """Handle HTTP error responses (4xx, 5xx).
-
-        If error_model is provided, attempts to deserialize the error body
-        into a typed Pydantic model before raising ApplicationError.
-        """
-        if response.status_code >= 400:
-            error_data = None
-            typed_error = None
-            try:
-                error_data = response.json()
-            except Exception:
-                pass
-
-            # Try typed error deserialization
-            if error_model is not None and error_data is not None:
-                try:
-                    ta = TypeAdapter(error_model)
-                    typed_error = ta.validate_python(error_data)
-                except Exception:
-                    pass  # Fall back to raw error_data
-
-            raise ApplicationError.from_response(
-                response, metadata, error_data, typed_error=typed_error
-            )
-
-    def _parse_json_response(self, response: httpx.Response) -> dict[str, Any]:
-        """Parse JSON response with error handling."""
-        try:
-            return response.json()
-        except Exception as e:
-            raise ValidationError(
-                f"Failed to parse JSON response: {e}",
-                cause=e,
-            )
-
-    def _validate_response_model(
-        self,
-        response: httpx.Response,
-        response_model: type[T] | type[Any] | str | _NoValidation,
-        metadata: TransportMetadata,
-    ) -> ApiResponse[T] | ApiResponse[dict[str, Any]]:
-        """Validate response using Pydantic model via TypeAdapter.
-
-        TypeAdapter handles all types: plain BaseModel, Generic types
-        (list[Model], dict[str, Model]), Union types, and primitives.
-        Uses validate_json for performance when raw bytes are available.
-        """
-        # Handle special cases where no validation is needed
-        if response_model == "Any" or response_model is NO_VALIDATION:
-            json_response = self._parse_json_response(response)
-            return ApiResponse(json_response, metadata)
-
-        if response_model is Any:
-            json_response = self._parse_json_response(response)
-            return ApiResponse(json_response, metadata)
-
-        try:
-            ta = TypeAdapter(response_model)
-            # Prefer validate_json for Pydantic's fast Rust-based JSON parsing
-            content = response.content
-            if isinstance(content, (bytes, bytearray)):
-                validated_data = ta.validate_json(content)
-            else:
-                json_response = self._parse_json_response(response)
-                validated_data = ta.validate_python(json_response)
-            return ApiResponse(validated_data, metadata)
-        except PydanticValidationError as e:
-            raise ValidationError(
-                f"Response validation failed: {e}",
-                validation_errors=e.errors(),
-                cause=e,
-            )
-
     def _make_request(
         self,
 
@@ -501,33 +543,33 @@ class ClientBase(ABC):
             # response so any middleware transforms apply; `raw` is used
             # only as the metadata sidecar (preserves `.request` /
             # `.extensions` / `.history` from the real wire response when
-            # available, fallback to the synthetic for custom transports).
-            parsed_response = httpx.Response(
-                status_code=client_response.status,
-                headers=client_response.headers,
-                content=client_response.body,
-            )
+            # available, fallback to a synthetic for custom transports).
             metadata = TransportMetadata(
                 status_code=client_response.status,
                 headers=client_response.headers,
                 timing=time.time() - start_time,
-                raw_response=client_response.raw or parsed_response,
+                raw_response=client_response.raw
+                or _synthesize_raw_response(
+                    client_response.status,
+                    client_response.headers,
+                    client_response.body,
+                ),
             )
 
             # Handle error responses
-            self._handle_error_response(
-                parsed_response, metadata, error_model=error_model
+            _raise_for_error_status(
+                client_response.status,
+                client_response.body,
+                metadata,
+                error_model=error_model,
             )
 
             # Validate and return response
             if response_model is not None:
-                return self._validate_response_model(
-                    parsed_response, response_model, metadata
-                )
+                return _validate_body(client_response.body, response_model, metadata)
             else:
-                # No response_model provided - parse JSON into dict
-                json_response = self._parse_json_response(parsed_response)
-                return ApiResponse(json_response, metadata)
+                # No response_model provided - parse JSON as-is
+                return ApiResponse(_parse_json_body(client_response.body), metadata)
 
         except httpx.TimeoutException as e:
             raise TimeoutError.from_httpx_timeout(e)
@@ -581,7 +623,12 @@ class ClientBase(ABC):
             if response.status_code >= 400:
                 # read_full body so error parsing can see it
                 response.read()
-                self._handle_error_response(response, metadata, error_model=error_model)
+                _raise_for_error_status(
+                    response.status_code,
+                    response.content,
+                    metadata,
+                    error_model=error_model,
+                )
 
             adapter: TypeAdapter[Any] | None = None
             if (
@@ -734,7 +781,9 @@ class AsyncClientBase(ABC):
         params: dict[str, Any] | None = None,
         json_data: dict[str, Any] | None = None,
         json_model: None = None,
+        headers_model: BaseModel | None = None,
         response_model: type[T],
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -748,6 +797,7 @@ class AsyncClientBase(ABC):
         json_model: None = None,
         headers_model: BaseModel | None = None,
         response_model: None = None,
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -761,7 +811,8 @@ class AsyncClientBase(ABC):
         json_model: None = None,
         headers_model: BaseModel | None = None,
         response_model: type[Any],
-    ) -> ApiResponse[dict[str, Any]]: ...
+        error_model: type[Any] | None = None,
+    ) -> ApiResponse[Any]: ...
 
     @overload
     async def _make_request(
@@ -772,7 +823,9 @@ class AsyncClientBase(ABC):
         params: dict[str, Any] | None = None,
         json_data: dict[str, Any] | None = None,
         json_model: None = None,
+        headers_model: BaseModel | None = None,
         response_model: str,
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     @overload
@@ -786,6 +839,7 @@ class AsyncClientBase(ABC):
         json_model: BaseModel,
         headers_model: BaseModel | None = None,
         response_model: type[T],
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[T]: ...
 
     @overload
@@ -799,6 +853,7 @@ class AsyncClientBase(ABC):
         json_model: BaseModel,
         headers_model: BaseModel | None = None,
         response_model: None = None,
+        error_model: type[Any] | None = None,
     ) -> ApiResponse[dict[str, Any]]: ...
 
     def _validate_request_params(
@@ -947,73 +1002,6 @@ class AsyncClientBase(ABC):
 
         return terminal
 
-    def _handle_error_response(
-        self,
-        response: httpx.Response,
-        metadata: TransportMetadata,
-        error_model: type | None = None,
-    ) -> None:
-        """Handle HTTP error responses (4xx, 5xx)."""
-        if response.status_code >= 400:
-            error_data = None
-            typed_error = None
-            try:
-                error_data = response.json()
-            except Exception:
-                pass
-
-            if error_model is not None and error_data is not None:
-                try:
-                    ta = TypeAdapter(error_model)
-                    typed_error = ta.validate_python(error_data)
-                except Exception:
-                    pass
-
-            raise ApplicationError.from_response(
-                response, metadata, error_data, typed_error=typed_error
-            )
-
-    def _parse_json_response(self, response: httpx.Response) -> dict[str, Any]:
-        """Parse JSON response with error handling."""
-        try:
-            return response.json()
-        except Exception as e:
-            raise ValidationError(
-                f"Failed to parse JSON response: {e}",
-                cause=e,
-            )
-
-    def _validate_response_model(
-        self,
-        response: httpx.Response,
-        response_model: type[T] | type[Any] | str | _NoValidation,
-        metadata: TransportMetadata,
-    ) -> ApiResponse[T] | ApiResponse[dict[str, Any]]:
-        """Validate response using Pydantic model via TypeAdapter."""
-        if response_model == "Any" or response_model is NO_VALIDATION:
-            json_response = self._parse_json_response(response)
-            return ApiResponse(json_response, metadata)
-
-        if response_model is Any:
-            json_response = self._parse_json_response(response)
-            return ApiResponse(json_response, metadata)
-
-        try:
-            ta = TypeAdapter(response_model)
-            content = response.content
-            if isinstance(content, (bytes, bytearray)):
-                validated_data = ta.validate_json(content)
-            else:
-                json_response = self._parse_json_response(response)
-                validated_data = ta.validate_python(json_response)
-            return ApiResponse(validated_data, metadata)
-        except PydanticValidationError as e:
-            raise ValidationError(
-                f"Response validation failed: {e}",
-                validation_errors=e.errors(),
-                cause=e,
-            )
-
     async def _make_request(
         self,
 
@@ -1047,32 +1035,32 @@ class AsyncClientBase(ABC):
             # response so any middleware transforms apply; `raw` is used
             # only as the metadata sidecar (preserves `.request` /
             # `.extensions` / `.history` from the real wire response when
-            # available, fallback to the synthetic for custom transports).
-            parsed_response = httpx.Response(
-                status_code=client_response.status,
-                headers=client_response.headers,
-                content=client_response.body,
-            )
+            # available, fallback to a synthetic for custom transports).
             metadata = TransportMetadata(
                 status_code=client_response.status,
                 headers=client_response.headers,
                 timing=time.time() - start_time,
-                raw_response=client_response.raw or parsed_response,
+                raw_response=client_response.raw
+                or _synthesize_raw_response(
+                    client_response.status,
+                    client_response.headers,
+                    client_response.body,
+                ),
             )
 
             # Handle error responses
-            self._handle_error_response(
-                parsed_response, metadata, error_model=error_model
+            _raise_for_error_status(
+                client_response.status,
+                client_response.body,
+                metadata,
+                error_model=error_model,
             )
 
             # Validate and return response
             if response_model is not None:
-                return self._validate_response_model(
-                    parsed_response, response_model, metadata
-                )
+                return _validate_body(client_response.body, response_model, metadata)
             else:
-                json_response = self._parse_json_response(parsed_response)
-                return ApiResponse(json_response, metadata)
+                return ApiResponse(_parse_json_body(client_response.body), metadata)
 
         except httpx.TimeoutException as e:
             raise TimeoutError.from_httpx_timeout(e)
@@ -1090,7 +1078,7 @@ class AsyncClientBase(ABC):
         headers_model: BaseModel | None = None,
         item_model: type[T] | type[Any] | str | _NoValidation | None = None,
         error_model: type | None = None,
-    ) -> AsyncIterator[T] | AsyncIterator[Any]:
+    ) -> AsyncIterator[Any]:
         """Open an SSE stream and yield items validated against ``item_model``.
 
         Errors raised when the server returns a non-2xx response are
@@ -1125,7 +1113,12 @@ class AsyncClientBase(ABC):
             metadata = TransportMetadata.from_response(response, start_time)
             if response.status_code >= 400:
                 await response.aread()
-                self._handle_error_response(response, metadata, error_model=error_model)
+                _raise_for_error_status(
+                    response.status_code,
+                    response.content,
+                    metadata,
+                    error_model=error_model,
+                )
 
             adapter: TypeAdapter[Any] | None = None
             if (

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/src/reflectapi_runtime/response.py

@@ -4,12 +4,13 @@ from __future__ import annotations
 
 import time
 from dataclasses import dataclass
-from typing import Any, Generic, TypeVar
+from typing import Any, Generic
 
 import httpx  # noqa: TC002
+from typing_extensions import TypeVar
 
-T = TypeVar("T")
-E = TypeVar("E")
+T = TypeVar("T", covariant=True)
+E = TypeVar("E", covariant=True, default=Any)
 
 
 @dataclass(frozen=True)

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/src/reflectapi_runtime/transport.py

@@ -26,7 +26,12 @@ class Request:
 
 @dataclass(frozen=True)
 class Response:
-    """Transport response returned by custom ReflectAPI Python clients."""
+    """Transport response returned by custom ReflectAPI Python clients.
+
+    ``body`` must already be decoded (any ``Content-Encoding`` reversed), as
+    ``httpx.Response.content`` is. ``headers`` may still carry the wire
+    headers; the runtime never re-applies them to ``body``.
+    """
 
     status: int
     # Permissive headers type so adapters wrapping httpx.Headers (which is

{reflectapi_runtime-0.17.6 → reflectapi_runtime-0.18.0}/tests/test_client.py

@@ -907,3 +907,269 @@ class TestMiddlewareTransformsAreParsed:
 
         assert result.value.name == "healed"
         assert result.metadata.status_code == 200
+
+
+class TestCompressedResponseNotDoubleDecoded:
+    """A transport that has already decompressed the body (httpx does this
+    when reading ``.content``) may still surface ``Content-Encoding: gzip``
+    in the headers. Rebuilding an ``httpx.Response`` from that pair must not
+    attempt a second decompression of the already-decoded bytes.
+
+    Regression test: previously this raised
+    ``NetworkError: Error -3 while decompressing data: incorrect header check``.
+    """
+
+    @staticmethod
+    def _gzip_handler(request: httpx.Request) -> httpx.Response:
+        import gzip
+
+        return httpx.Response(
+            200,
+            headers={
+                "content-type": "application/json",
+                "content-encoding": "gzip",
+            },
+            content=gzip.compress(b'{"name":"zipped","age":3}'),
+        )
+
+    def test_sync_gzip_response(self):
+        with httpx.Client(transport=httpx.MockTransport(self._gzip_handler)) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            result = client._make_request("/test", response_model=SampleModel)
+
+        assert result.value.name == "zipped"
+        # Metadata still reflects the original wire headers.
+        assert result.metadata.headers.get("content-encoding") == "gzip"
+
+    @pytest.mark.asyncio
+    async def test_async_gzip_response(self):
+        async with httpx.AsyncClient(
+            transport=httpx.MockTransport(self._gzip_handler)
+        ) as raw:
+            client = AsyncClientBase("http://example.com", client=raw)
+            result = await client._make_request("/test", response_model=SampleModel)
+
+        assert result.value.name == "zipped"
+        assert result.metadata.headers.get("content-encoding") == "gzip"
+
+    def test_sync_custom_transport_decoded_body_with_encoding_header(self):
+        """A custom structural transport returning a decoded body while
+        keeping the compression header must also parse cleanly."""
+
+        class _DecodedButLabelled:
+            def request(self, request: Request) -> Response:
+                return Response(
+                    status=200,
+                    headers=httpx.Headers(
+                        {
+                            "content-type": "application/json",
+                            "content-encoding": "gzip",
+                            "content-length": "17",
+                        }
+                    ),
+                    body=b'{"name":"raw","age":9}',
+                )
+
+        client = ClientBase("http://example.com", client=_DecodedButLabelled())
+        result = client._make_request("/test", response_model=SampleModel)
+        assert result.value.name == "raw"
+
+
+class TestParsingBypassesSyntheticHttpxResponse:
+    """Response parsing operates on the structural body directly — it never
+    round-trips through a rebuilt ``httpx.Response``, so stale wire headers
+    (compression, content-length) can't corrupt parsing on any path.
+    """
+
+    @staticmethod
+    def _gzip_error_handler(request: httpx.Request) -> httpx.Response:
+        import gzip
+
+        return httpx.Response(
+            404,
+            headers={
+                "content-type": "application/json",
+                "content-encoding": "gzip",
+            },
+            content=gzip.compress(b'{"reason":"missing"}'),
+        )
+
+    def test_sync_compressed_error_response_parses_error_body(self):
+        with httpx.Client(
+            transport=httpx.MockTransport(self._gzip_error_handler)
+        ) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            with pytest.raises(ApplicationError) as exc_info:
+                client._make_request("/test", response_model=SampleModel)
+
+        assert exc_info.value.status_code == 404
+        assert exc_info.value.error_data == {"reason": "missing"}
+        assert "API error 404: Not Found" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_async_compressed_error_response_parses_error_body(self):
+        async with httpx.AsyncClient(
+            transport=httpx.MockTransport(self._gzip_error_handler)
+        ) as raw:
+            client = AsyncClientBase("http://example.com", client=raw)
+            with pytest.raises(ApplicationError) as exc_info:
+                await client._make_request("/test", response_model=SampleModel)
+
+        assert exc_info.value.status_code == 404
+        assert exc_info.value.error_data == {"reason": "missing"}
+
+    def test_sync_typed_error_from_compressed_response(self):
+        class ErrorModel(BaseModel):
+            reason: str
+
+        with httpx.Client(
+            transport=httpx.MockTransport(self._gzip_error_handler)
+        ) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            with pytest.raises(ApplicationError) as exc_info:
+                client._make_request(
+                    "/test", response_model=SampleModel, error_model=ErrorModel
+                )
+
+        assert exc_info.value.typed_error == ErrorModel(reason="missing")
+
+    def test_middleware_rewritten_body_ignores_stale_wire_headers(self):
+        """Middleware can replace the body entirely; the original wire
+        headers (content-length, content-encoding) must not be applied to
+        the new body during parsing."""
+        import gzip
+        from dataclasses import replace
+
+        from reflectapi_runtime.middleware import SyncMiddleware
+
+        class _Rewrite(SyncMiddleware):
+            def handle(self, request, next_call):
+                resp = next_call(request)
+                return replace(resp, body=b'{"name":"rewritten","age":7}')
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                200,
+                headers={
+                    "content-type": "application/json",
+                    "content-encoding": "gzip",
+                },
+                content=gzip.compress(b'{"name":"wire","age":1}'),
+            )
+
+        with httpx.Client(transport=httpx.MockTransport(handler)) as raw:
+            client = ClientBase(
+                "http://example.com", client=raw, middleware=[_Rewrite()]
+            )
+            result = client._make_request("/test", response_model=SampleModel)
+
+        assert result.value.name == "rewritten"
+
+    def test_no_response_model_parses_json_directly(self):
+        import gzip
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                200,
+                headers={
+                    "content-type": "application/json",
+                    "content-encoding": "gzip",
+                },
+                content=gzip.compress(b'{"free": "form"}'),
+            )
+
+        with httpx.Client(transport=httpx.MockTransport(handler)) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            result = client._make_request("/test")
+
+        assert result.value == {"free": "form"}
+
+    def test_invalid_json_error_body_still_raises_application_error(self):
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(500, content=b"not json at all")
+
+        with httpx.Client(transport=httpx.MockTransport(handler)) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            with pytest.raises(ApplicationError) as exc_info:
+                client._make_request("/test", response_model=SampleModel)
+
+        assert exc_info.value.status_code == 500
+        assert exc_info.value.error_data is None
+        assert "API error 500: Internal Server Error" in str(exc_info.value)
+
+    def test_invalid_json_success_body_raises_validation_error(self):
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, content=b"not json")
+
+        with httpx.Client(transport=httpx.MockTransport(handler)) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            with pytest.raises(ValidationError):
+                client._make_request("/test")
+
+    def test_synthetic_raw_response_fallback_is_sanitized(self):
+        """Custom transports without a wire-level `raw` get a synthetic
+        raw_response whose compression headers are stripped so it is
+        readable, while metadata.headers keeps the original wire view."""
+
+        class _DecodedButLabelled:
+            def request(self, request: Request) -> Response:
+                return Response(
+                    status=200,
+                    headers=httpx.Headers(
+                        {
+                            "content-type": "application/json",
+                            "content-encoding": "gzip",
+                            "content-length": "17",
+                        }
+                    ),
+                    body=b'{"name":"raw","age":9}',
+                )
+
+        client = ClientBase("http://example.com", client=_DecodedButLabelled())
+        result = client._make_request("/test", response_model=SampleModel)
+
+        assert result.value.name == "raw"
+        assert result.metadata.headers.get("content-encoding") == "gzip"
+        raw = result.metadata.raw_response
+        assert isinstance(raw, httpx.Response)
+        assert "content-encoding" not in raw.headers
+        assert raw.json() == {"name": "raw", "age": 9}
+
+    def test_wire_raw_response_still_preferred_over_synthetic(self):
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, content=b'{"name":"x","age":1}')
+
+        with httpx.Client(transport=httpx.MockTransport(handler)) as raw:
+            client = ClientBase("http://example.com", client=raw)
+            result = client._make_request("/test", response_model=SampleModel)
+
+        # The real wire response carries .request; a synthetic would not.
+        assert result.metadata.raw_response.request is not None
+
+    def test_synthetic_raw_response_recomputes_stale_content_length(self):
+        """Even without Content-Encoding, the wire Content-Length may not
+        describe the structural body (e.g. after middleware rewrites it).
+        The stale value is dropped and httpx re-derives it from the actual
+        body when constructing the synthetic."""
+
+        class _StaleLength:
+            def request(self, request: Request) -> Response:
+                return Response(
+                    status=200,
+                    headers=httpx.Headers(
+                        {
+                            "content-type": "application/json",
+                            "content-length": "9999",
+                        }
+                    ),
+                    body=b'{"name":"raw","age":9}',
+                )
+
+        client = ClientBase("http://example.com", client=_StaleLength())
+        result = client._make_request("/test", response_model=SampleModel)
+
+        body = b'{"name":"raw","age":9}'
+        assert result.metadata.raw_response.headers.get("content-length") == str(
+            len(body)
+        )
+        assert result.metadata.headers.get("content-length") == "9999"