fix: correct capped-rebuild header handling + skip bodiless responses

Two bugs in the capped read path found in review of #78:

- The rebuilt Response kept content-encoding while holding already-decoded
  content, so httpx2 re-decompressed and crashed on every compressed body under
  the cap. Strip content-encoding / transfer-encoding / (compressed)
  content-length via _buffered_headers; httpx2 recomputes content-length.
- A bodiless response (HEAD / 204 / 304) with a large declared Content-Length
  was falsely rejected. _response_has_body short-circuits these: read the empty
  body and return the original response unchanged, preserving its headers (HEAD
  legitimately echoes the entity length).

Adds within-cap compressed-body and bodiless regression tests at the
_read_capped, send(), and stream() levels.

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

Author: lesnik512

architecture/client.md

@@ -42,4 +42,8 @@ The cap bounds memory that httpware buffers on your behalf, at two sites:
 
 The declared `Content-Length` is used only as an *early reject* (if even the compressed size already exceeds the cap, fail before reading a byte); it is never an early accept, so the accumulator always runs — chunked and bomb bodies are caught, not waved through. `ResponseTooLargeError.reason` is `"declared"` or `"streamed"` accordingly. Entirely public httpx2 API — no private access.
 
+**Bodiless responses bypass the cap.** Responses that carry no message body — to a `HEAD` request, or with status `204`/`304` — buffer nothing, so the cap never applies to them even when they declare a large `Content-Length` (`HEAD` legitimately echoes the entity length). These are returned unchanged, preserving their original headers.
+
+**Rebuilt headers.** The accumulator yields the *decoded* body, so the rebuilt Response drops the wire-encoding headers (`Content-Encoding`, `Transfer-Encoding`, and the now-incorrect compressed `Content-Length`); httpx2 recomputes `Content-Length` from the buffered content. Carrying `Content-Encoding` forward would make httpx2 re-decode already-decoded bytes and raise.
+
 **Caveat:** on the capped path the buffered response is rebuilt via the public `httpx2.Response(content=...)` constructor, which does not carry `.elapsed` (httpx2 only sets it on its own buffered `send()`). Clients that set a cap and read `response.elapsed` will find it absent; the `None`-cap fast path preserves it.

src/httpware/client.py

@@ -84,6 +84,32 @@ def _safe_extensions(extensions: Mapping[str, typing.Any]) -> dict[str, typing.A
     return {key: value for key, value in extensions.items() if key != "network_stream"}
 
 
+# Headers describing the wire encoding of the body. The accumulator yields the
+# DECODED body, so these no longer apply; httpx2 recomputes content-length from
+# the buffered content. Carrying content-encoding forward makes httpx2 try to
+# re-decode already-decoded bytes and raise.
+_WIRE_BODY_HEADERS = ("content-encoding", "content-length", "transfer-encoding")
+_BODILESS_STATUS = frozenset({HTTPStatus.NO_CONTENT, HTTPStatus.NOT_MODIFIED})  # 204, 304
+
+
+def _buffered_headers(headers: httpx2.Headers) -> httpx2.Headers:
+    """Copy `headers`, stripping wire-encoding headers stale after decoding+buffering."""
+    out = httpx2.Headers(headers)
+    for name in _WIRE_BODY_HEADERS:
+        if name in out:
+            del out[name]
+    return out
+
+
+def _response_has_body(method: str, status_code: int) -> bool:
+    """Whether a response carries a message body (RFC 9110 §6.4.1).
+
+    HEAD responses and 204/304 never have a body regardless of a declared
+    Content-Length, so they must never trip the cap.
+    """
+    return method.upper() != "HEAD" and status_code not in _BODILESS_STATUS
+
+
 def _read_capped(response: httpx2.Response, cap: int, request: httpx2.Request) -> httpx2.Response:
     """Buffer a streaming sync `response` under `cap` decoded bytes; return a buffered Response.
 
@@ -92,6 +118,9 @@ def _read_capped(response: httpx2.Response, cap: int, request: httpx2.Request) -
     (reason="streamed") if the decoded body crosses `cap` mid-read. Does not
     close `response`; the caller owns the stream lifecycle.
     """
+    if not _response_has_body(request.method, response.status_code):
+        response.read()  # empty body; preserve the original response (and its headers)
+        return response
     content_length = _parse_content_length(response.headers.get("content-length"))
     if content_length is not None and content_length > cap:
         raise ResponseTooLargeError(
@@ -105,7 +134,7 @@ def _read_capped(response: httpx2.Response, cap: int, request: httpx2.Request) -
         ) from None
     return httpx2.Response(
         status_code=response.status_code,
-        headers=response.headers,
+        headers=_buffered_headers(response.headers),
         content=content,
         request=request,
         extensions=_safe_extensions(response.extensions),
@@ -115,6 +144,9 @@ def _read_capped(response: httpx2.Response, cap: int, request: httpx2.Request) -
 
 async def _read_capped_async(response: httpx2.Response, cap: int, request: httpx2.Request) -> httpx2.Response:
     """Async mirror of `_read_capped` (counts decoded bytes from `aiter_bytes`)."""
+    if not _response_has_body(request.method, response.status_code):
+        await response.aread()  # empty body; preserve the original response (and its headers)
+        return response
     content_length = _parse_content_length(response.headers.get("content-length"))
     if content_length is not None and content_length > cap:
         raise ResponseTooLargeError(
@@ -129,7 +161,7 @@ async def _read_capped_async(response: httpx2.Response, cap: int, request: httpx
             )
     return httpx2.Response(
         status_code=response.status_code,
-        headers=response.headers,
+        headers=_buffered_headers(response.headers),
         content=bytes(buf),
         request=request,
         extensions=_safe_extensions(response.extensions),

tests/test_capped_read.py

@@ -16,15 +16,15 @@
 from httpware.errors import ResponseTooLargeError
 
 
-def _sync_stream(handler: object) -> tuple[httpx2.Client, httpx2.Response]:
+def _sync_stream(handler: object, method: str = "GET") -> tuple[httpx2.Client, httpx2.Response]:
     client = httpx2.Client(transport=httpx2.MockTransport(handler))  # ty: ignore[invalid-argument-type]
-    request = client.build_request("GET", "https://example.test/x")
+    request = client.build_request(method, "https://example.test/x")
     return client, client.send(request, stream=True)
 
 
-async def _async_stream(handler: object) -> tuple[httpx2.AsyncClient, httpx2.Response]:
+async def _async_stream(handler: object, method: str = "GET") -> tuple[httpx2.AsyncClient, httpx2.Response]:
     client = httpx2.AsyncClient(transport=httpx2.MockTransport(handler))  # ty: ignore[invalid-argument-type]
-    request = client.build_request("GET", "https://example.test/x")
+    request = client.build_request(method, "https://example.test/x")
     return client, await client.send(request, stream=True)
 
 
@@ -81,6 +81,39 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
         client.close()
 
 
+def test_read_capped_within_cap_gzip_returns_decoded_content() -> None:
+    # Regression: rebuilt Response must not re-decompress already-decoded content.
+    raw = gzip.compress(b"A" * 500)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-encoding": "gzip"}, content=raw)
+
+    client, resp = _sync_stream(handler)
+    try:
+        out = _read_capped(resp, 1_000_000, resp.request)
+        assert out.content == b"A" * 500  # decoded, not re-gzipped/crashed
+        assert "content-encoding" not in out.headers  # stale wire header dropped
+        assert out.headers["content-length"] == "500"  # recomputed from decoded content
+    finally:
+        resp.close()
+        client.close()
+
+
+def test_read_capped_head_with_large_declared_length_not_rejected() -> None:
+    # Regression: a bodiless HEAD response buffers nothing and must not trip the cap.
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-length": "50000000"})
+
+    client, resp = _sync_stream(handler, method="HEAD")
+    try:
+        out = _read_capped(resp, 1000, resp.request)
+        assert out.content == b""
+        assert out.headers["content-length"] == "50000000"  # entity length preserved for HEAD
+    finally:
+        resp.close()
+        client.close()
+
+
 def test_read_capped_gzip_bomb_trips_on_decoded_bytes() -> None:
     raw = gzip.compress(b"A" * 100_000)
 
@@ -142,6 +175,37 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
         await client.aclose()
 
 
+async def test_read_capped_async_within_cap_gzip_returns_decoded_content() -> None:
+    raw = gzip.compress(b"A" * 500)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-encoding": "gzip"}, content=raw)
+
+    client, resp = await _async_stream(handler)
+    try:
+        out = await _read_capped_async(resp, 1_000_000, resp.request)
+        assert out.content == b"A" * 500
+        assert "content-encoding" not in out.headers
+        assert out.headers["content-length"] == "500"
+    finally:
+        await resp.aclose()
+        await client.aclose()
+
+
+async def test_read_capped_async_head_with_large_declared_length_not_rejected() -> None:
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-length": "50000000"})
+
+    client, resp = await _async_stream(handler, method="HEAD")
+    try:
+        out = await _read_capped_async(resp, 1000, resp.request)
+        assert out.content == b""
+        assert out.headers["content-length"] == "50000000"
+    finally:
+        await resp.aclose()
+        await client.aclose()
+
+
 async def test_read_capped_async_declared_over_cap() -> None:
     body = b"x" * 200
 

tests/test_client_body_cap.py

@@ -88,6 +88,30 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
     client.close()
 
 
+def test_sync_send_within_cap_gzip_returns_decoded() -> None:
+    raw = gzip.compress(b"A" * 500)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-encoding": "gzip"}, content=raw)
+
+    client = _sync(handler, 1_000_000)
+    request = client.build_request("GET", "https://example.test/x")
+    assert client.send(request).content == b"A" * 500  # not re-decompressed/crashed
+    client.close()
+
+
+def test_sync_head_large_declared_length_not_rejected() -> None:
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-length": "50000000"})
+
+    client = _sync(handler, 1000)
+    request = client.build_request("HEAD", "https://example.test/x")
+    response = client.send(request)
+    assert response.content == b""
+    assert response.headers["content-length"] == "50000000"
+    client.close()
+
+
 def test_sync_send_none_cap_unbounded() -> None:
     body = b"x" * 10_000
 
@@ -146,6 +170,30 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
     await client.aclose()
 
 
+async def test_async_send_within_cap_gzip_returns_decoded() -> None:
+    raw = gzip.compress(b"A" * 500)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-encoding": "gzip"}, content=raw)
+
+    client = _async(handler, 1_000_000)
+    request = client.build_request("GET", "https://example.test/x")
+    assert (await client.send(request)).content == b"A" * 500
+    await client.aclose()
+
+
+async def test_async_head_large_declared_length_not_rejected() -> None:
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(200, headers={"content-length": "50000000"})
+
+    client = _async(handler, 1000)
+    request = client.build_request("HEAD", "https://example.test/x")
+    response = await client.send(request)
+    assert response.content == b""
+    assert response.headers["content-length"] == "50000000"
+    await client.aclose()
+
+
 async def test_async_send_none_cap_unbounded() -> None:
     body = b"x" * 10_000
 

tests/test_client_stream.py

@@ -406,6 +406,24 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
     await client.aclose()
 
 
+async def test_stream_error_pre_read_within_cap_gzip_decoded() -> None:
+    import gzip  # noqa: PLC0415 — local to this regression test
+
+    raw = gzip.compress(b"boom" * 50)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(500, headers={"content-encoding": "gzip"}, content=raw)
+
+    client = AsyncClient(
+        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)), max_response_body_bytes=1_000_000
+    )
+    with pytest.raises(InternalServerError) as caught:
+        async with client.stream("GET", "https://example.test/x"):
+            pytest.fail("unreachable")
+    assert caught.value.response.content == b"boom" * 50  # decoded, not re-decompressed
+    await client.aclose()
+
+
 async def test_stream_user_driven_success_body_not_capped() -> None:
     body = b"x" * 100_000
 

tests/test_client_stream_sync.py

@@ -360,6 +360,23 @@ def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
     client.close()
 
 
+def test_stream_error_pre_read_within_cap_gzip_decoded_sync() -> None:
+    import gzip  # noqa: PLC0415 — local to this regression test
+
+    raw = gzip.compress(b"boom" * 50)
+
+    def handler(request: httpx2.Request) -> httpx2.Response:  # noqa: ARG001
+        return httpx2.Response(500, headers={"content-encoding": "gzip"}, content=raw)
+
+    client = Client(
+        httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler)), max_response_body_bytes=1_000_000
+    )
+    with pytest.raises(InternalServerError) as caught, client.stream("GET", "https://example.test/x"):
+        pytest.fail("unreachable")
+    assert caught.value.response.content == b"boom" * 50
+    client.close()
+
+
 def test_stream_user_driven_success_body_not_capped_sync() -> None:
     body = b"x" * 100_000