refactor(internal): extract body-cap subsystem + exception mappers from client.py

Move the max_response_body_bytes enforcement code (validation, capped
sync/async reads, and their helpers) into a new _internal/body_cap.py, and
move the _httpx2_exception_mapper(/_sync) context managers into the
existing _internal/exception_mapping.py alongside map_httpx2_exception.
Pure refactor: no behavior change, only import paths move. client.py drops
~160 lines of self-contained logic it never needed class access to.

Rename tests/test_capped_read(_props).py to tests/test_body_cap(_props).py
to match, and relocate test_parse_content_length out of
test_client_stream.py into the renamed test_body_cap.py.

Author: lesnik512

architecture/overview.md

@@ -35,8 +35,9 @@ src/httpware/
 │       └── _backoff.py    # full-jitter helper (shared)
 ├── decoders/              # shared (ResponseDecoder + adapters)
 └── _internal/
-    ├── exception_mapping.py  # map_httpx2_exception (shared)
-    ├── import_checker.py     # is_*_installed flags
-    ├── observability.py      # _emit_event
-    └── status.py             # _raise_on_status_error, _is_streaming_body_*, STREAMING_BODY_MARKER
+    ├── body_cap.py            # max_response_body_bytes: validate, read-capped (sync+async)
+    ├── exception_mapping.py   # map_httpx2_exception + context-manager wrappers (shared)
+    ├── import_checker.py      # is_*_installed flags
+    ├── observability.py       # _emit_event
+    └── status.py              # _raise_on_status_error, _is_streaming_body_*, STREAMING_BODY_MARKER
 ```

src/httpware/_internal/body_cap.py

@@ -0,0 +1,146 @@
+"""Response-body cap enforcement: validate, read-capped (sync + async)."""
+
+import typing
+from collections.abc import Mapping
+from http import HTTPStatus
+
+import httpx2
+
+from httpware.errors import ResponseTooLargeError
+
+
+_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:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value >= 0 else None
+
+
+class _CapExceeded(Exception):  # noqa: N818 — internal control-flow signal, not a user-facing error
+    """Internal signal: decoded bytes crossed the cap mid-read. Carries bytes read so far."""
+
+    def __init__(self, *, read: int) -> None:
+        self.read = read
+        super().__init__(f"decoded body exceeded cap after {read} bytes")
+
+
+def _accumulate_capped(chunks: typing.Iterable[bytes], cap: int) -> bytes:
+    """Concatenate `chunks`, raising `_CapExceeded` the moment the running total exceeds `cap`.
+
+    Counts decoded bytes (the in-memory footprint). Grown in a single bytearray
+    so there is no transient list-plus-join double allocation.
+    """
+    buf = bytearray()
+    for chunk in chunks:
+        buf += chunk
+        if len(buf) > cap:
+            raise _CapExceeded(read=len(buf))
+    return bytes(buf)
+
+
+def _safe_extensions(extensions: Mapping[str, typing.Any]) -> dict[str, typing.Any]:
+    """Copy response extensions, dropping the now-stale `network_stream`.
+
+    The rebuilt buffered Response never touches its network stream, so carrying a
+    consumed/closed one wholesale is sloppy. `http_version`/`reason_phrase` and
+    any other keys are preserved.
+    """
+    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.
+
+    Raises `ResponseTooLargeError` (reason="declared") if the declared
+    Content-Length already exceeds `cap` — before any byte is read — and
+    (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(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="declared"
+        )
+    try:
+        content = _accumulate_capped(response.iter_bytes(), cap)
+    except _CapExceeded:
+        raise ResponseTooLargeError(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="streamed"
+        ) from None
+    return httpx2.Response(
+        status_code=response.status_code,
+        headers=_buffered_headers(response.headers),
+        content=content,
+        request=request,
+        extensions=_safe_extensions(response.extensions),
+        history=response.history,
+    )
+
+
+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(
+            status_code=response.status_code, limit=cap, content_length=content_length, reason="declared"
+        )
+    buf = bytearray()
+    async for chunk in response.aiter_bytes():
+        buf += chunk
+        if len(buf) > cap:
+            raise ResponseTooLargeError(
+                status_code=response.status_code, limit=cap, content_length=content_length, reason="streamed"
+            )
+    return httpx2.Response(
+        status_code=response.status_code,
+        headers=_buffered_headers(response.headers),
+        content=bytes(buf),
+        request=request,
+        extensions=_safe_extensions(response.extensions),
+        history=response.history,
+    )

src/httpware/_internal/exception_mapping.py

@@ -1,11 +1,15 @@
-"""httpx2 -> httpware exception mapping.
+"""httpx2 -> httpware exception mapping + context-manager wrappers (shared).
 
-Pure function used by both Client._terminal and AsyncClient._terminal,
-and by both stream() methods. Clause ordering: TimeoutException ->
-InvalidURL/CookieConflict -> NetworkError -> HTTPError (subclass before
-parent so the right type wins).
+map_httpx2_exception is a pure function used by both Client._terminal and
+AsyncClient._terminal, and by both stream() methods. Clause ordering:
+TimeoutException -> InvalidURL/CookieConflict -> NetworkError -> HTTPError
+(subclass before parent so the right type wins). The two context managers
+below wrap it for use as `with`/`async with` blocks around the httpx2 call.
 """
 
+import contextlib
+from collections.abc import AsyncIterator, Iterator
+
 import httpx2
 
 from httpware.errors import NetworkError, TimeoutError, TransportError  # noqa: A004
@@ -26,3 +30,25 @@ def map_httpx2_exception(exc: BaseException) -> NetworkError | TimeoutError | Tr
     if isinstance(exc, httpx2.HTTPError):
         return TransportError(str(exc))
     return TransportError(str(exc))  # pragma: no cover — defensive default; httpx2.HTTPError is the root
+
+
+@contextlib.asynccontextmanager
+async def _httpx2_exception_mapper() -> AsyncIterator[None]:
+    """Map httpx2 exceptions to httpware exceptions. Shared by AsyncClient._terminal and stream()."""
+    try:
+        yield
+    except httpx2.HTTPError as exc:
+        raise map_httpx2_exception(exc) from exc
+    except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+        raise map_httpx2_exception(exc) from exc
+
+
+@contextlib.contextmanager
+def _httpx2_exception_mapper_sync() -> Iterator[None]:
+    """Map httpx2 exceptions to httpware exceptions. Sync sibling of _httpx2_exception_mapper."""
+    try:
+        yield
+    except httpx2.HTTPError as exc:
+        raise map_httpx2_exception(exc) from exc
+    except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+        raise map_httpx2_exception(exc) from exc