feat!: replace max_error_body_bytes with max_response_body_bytes

Status-agnostic, decoded-byte cap enforced at the non-streaming terminal via a
streaming capped-accumulator (send(stream=True) + _read_capped). Branches on
cap is None so the default path keeps plain send() and .elapsed. Construction
validates >= 1. The old error-only param is removed (pre-1.0, no shim).

BREAKING CHANGE: max_error_body_bytes is replaced by max_response_body_bytes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lesnik512

src/httpware/client.py

@@ -32,6 +32,15 @@
 )
 
 
+_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:
@@ -179,7 +188,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,
@@ -194,8 +203,9 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
         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,
@@ -233,12 +243,20 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
         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
+        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
@@ -1100,12 +1118,12 @@ async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signature
 
         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:
+                if self._max_response_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:
+                    if content_length is not None and content_length > self._max_response_body_bytes:
                         raise ResponseTooLargeError(
                             status_code=response.status_code,
-                            limit=self._max_error_body_bytes,
+                            limit=self._max_response_body_bytes,
                             content_length=content_length,
                             reason="declared",
                         )
@@ -1146,7 +1164,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,
@@ -1161,8 +1179,9 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
         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,
@@ -1200,12 +1219,20 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
         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
+        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
@@ -2089,12 +2116,12 @@ def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwa
 
         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:
+                if self._max_response_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:
+                    if content_length is not None and content_length > self._max_response_body_bytes:
                         raise ResponseTooLargeError(
                             status_code=response.status_code,
-                            limit=self._max_error_body_bytes,
+                            limit=self._max_response_body_bytes,
                             content_length=content_length,
                             reason="declared",
                         )

tests/test_client_body_cap.py

@@ -0,0 +1,158 @@
+"""max_response_body_bytes — non-streaming send() cap + construction validation.
+
+Covers both clients: the terminal buffers under the cap and fails fast with
+ResponseTooLargeError when a response body (any status) exceeds it. stream()
+coverage lives in tests/test_client_stream*.py.
+"""
+
+import gzip
+from collections.abc import AsyncIterator
+
+import httpx2
+import pytest
+
+from httpware import AsyncClient, Client
+from httpware.errors import ResponseTooLargeError
+
+
+def _sync(handler: object, cap: int | None) -> Client:
+    return Client(
+        httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler)),  # ty: ignore[invalid-argument-type]
+        max_response_body_bytes=cap,
+    )
+
+
+def _async(handler: object, cap: int | None) -> AsyncClient:
+    return AsyncClient(
+        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)),  # ty: ignore[invalid-argument-type]
+        max_response_body_bytes=cap,
+    )
+
+
+# ---- construction validation ----
+
+
+@pytest.mark.parametrize("bad", [0, -1])
+def test_async_rejects_cap_below_one(bad: int) -> None:
+    with pytest.raises(ValueError, match="max_response_body_bytes must be >= 1"):
+        AsyncClient(max_response_body_bytes=bad)
+
+
+@pytest.mark.parametrize("bad", [0, -1])
+def test_sync_rejects_cap_below_one(bad: int) -> None:
+    with pytest.raises(ValueError, match="max_response_body_bytes must be >= 1"):
+        Client(max_response_body_bytes=bad)
+
+
+# ---- sync send() ----
+
+
+def test_sync_send_within_cap_returns_response() -> None:
+    body = b"hello world"
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body)
+
+    client = _sync(handler, 1000)
+    request = client.build_request("GET", "https://example.test/x")
+    assert client.send(request).content == body
+    client.close()
+
+
+def test_sync_send_over_cap_declared_on_success() -> None:
+    body = b"x" * 200
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body)
+
+    client = _sync(handler, 10)
+    request = client.build_request("GET", "https://example.test/x")
+    with pytest.raises(ResponseTooLargeError) as caught:
+        client.send(request)
+    assert caught.value.reason == "declared"
+    assert caught.value.status_code == 200  # noqa: PLR2004 — status-agnostic: a 200 trips
+    client.close()
+
+
+def test_sync_send_over_cap_streamed_gzip_bomb() -> None:
+    raw = gzip.compress(b"A" * 100_000)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-encoding": "gzip"}, content=raw)
+
+    client = _sync(handler, 1000)
+    request = client.build_request("GET", "https://example.test/x")
+    with pytest.raises(ResponseTooLargeError) as caught:
+        client.send(request)
+    assert caught.value.reason == "streamed"
+    client.close()
+
+
+def test_sync_send_none_cap_unbounded() -> None:
+    body = b"x" * 10_000
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body)
+
+    client = _sync(handler, None)
+    request = client.build_request("GET", "https://example.test/x")
+    assert client.send(request).content == body
+    client.close()
+
+
+# ---- async send() ----
+
+
+async def test_async_send_within_cap_returns_response() -> None:
+    body = b"hello world"
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body)
+
+    client = _async(handler, 1000)
+    request = client.build_request("GET", "https://example.test/x")
+    assert (await client.send(request)).content == body
+    await client.aclose()
+
+
+async def test_async_send_over_cap_declared() -> None:
+    body = b"x" * 200
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body)
+
+    client = _async(handler, 10)
+    request = client.build_request("GET", "https://example.test/x")
+    with pytest.raises(ResponseTooLargeError) as caught:
+        await client.send(request)
+    assert caught.value.reason == "declared"
+    await client.aclose()
+
+
+async def test_async_send_over_cap_streamed_chunked() -> None:
+    async def body() -> AsyncIterator[bytes]:
+        yield b"a" * 50
+        yield b"b" * 50
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body())
+
+    client = _async(handler, 70)
+    request = client.build_request("GET", "https://example.test/x")
+    with pytest.raises(ResponseTooLargeError) as caught:
+        await client.send(request)
+    assert caught.value.reason == "streamed"
+    assert caught.value.content_length is None
+    await client.aclose()
+
+
+async def test_async_send_none_cap_unbounded() -> None:
+    body = b"x" * 10_000
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, content=body)
+
+    client = _async(handler, None)
+    request = client.build_request("GET", "https://example.test/x")
+    assert (await client.send(request)).content == body
+    await client.aclose()

tests/test_client_stream.py

@@ -347,12 +347,12 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
         return httpx2.Response(500, content=body)
 
     client = AsyncClient(
-        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)), max_error_body_bytes=10
+        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)), max_response_body_bytes=10
     )
     with pytest.raises(ResponseTooLargeError) as caught:
         async with client.stream("GET", "https://example.test/x"):
             pytest.fail("unreachable")
-    assert caught.value.limit == 10  # noqa: PLR2004 — mirrors max_error_body_bytes above
+    assert caught.value.limit == 10  # noqa: PLR2004 — mirrors max_response_body_bytes above
     assert caught.value.content_length == 200  # noqa: PLR2004 — len(body) above
     await client.aclose()
 
@@ -364,7 +364,7 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
         return httpx2.Response(404, content=body)
 
     client = AsyncClient(
-        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)), max_error_body_bytes=1000
+        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)), max_response_body_bytes=1000
     )
     with pytest.raises(NotFoundError) as caught:
         async with client.stream("GET", "https://example.test/x"):

tests/test_client_stream_sync.py

@@ -314,10 +314,10 @@ def test_stream_raises_response_too_large_when_over_cap_sync() -> None:
     def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
         return httpx2.Response(500, content=body)
 
-    client = Client(httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler)), max_error_body_bytes=10)
+    client = Client(httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler)), max_response_body_bytes=10)
     with pytest.raises(ResponseTooLargeError) as caught, client.stream("GET", "https://example.test/x"):
         pytest.fail("unreachable")
-    assert caught.value.limit == 10  # noqa: PLR2004 — mirrors max_error_body_bytes above
+    assert caught.value.limit == 10  # noqa: PLR2004 — mirrors max_response_body_bytes above
     assert caught.value.content_length == 200  # noqa: PLR2004 — len(body) above
     client.close()
 
@@ -328,7 +328,7 @@ def test_stream_reads_error_body_when_under_cap_sync() -> None:
     def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
         return httpx2.Response(404, content=body)
 
-    client = Client(httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler)), max_error_body_bytes=1000)
+    client = Client(httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler)), max_response_body_bytes=1000)
     with pytest.raises(NotFoundError) as caught, client.stream("GET", "https://example.test/x"):
         pytest.fail("unreachable")
     assert caught.value.response.content == body