docs(planning): add body-cap module extraction design

Author: lesnik512

planning/changes/2026-07-13.01-body-cap-module-extraction.md

@@ -0,0 +1,155 @@
+---
+summary: Extract the body-cap subsystem and the httpx2-exception-mapper context managers out of client.py into dedicated _internal/ modules.
+---
+
+# Design: Extract the body-cap subsystem into `_internal/body_cap.py`
+
+## Summary
+
+`client.py:38-212` holds ~180 lines of pure, self-contained code with zero
+`self`/`Client`/`AsyncClient` coupling: the `max_response_body_bytes`
+body-capping subsystem (`_validate_max_response_body_bytes`,
+`_parse_content_length`, `_CapExceeded`, `_accumulate_capped`,
+`_safe_extensions`, `_buffered_headers`, `_response_has_body`,
+`_read_capped`, `_read_capped_async`) and two httpx2-exception-mapper context
+managers (`_httpx2_exception_mapper`, `_httpx2_exception_mapper_sync`). This
+change moves the body-cap subsystem into a new `_internal/body_cap.py`, and
+folds the two context managers into the existing `_internal/exception_mapping.py`
+next to the `map_httpx2_exception` function they wrap. No behavior change.
+
+## Motivation
+
+- `client.py` is 2,154 lines, by far the largest module in the package.
+  Everything genuinely coupled to `Client`/`AsyncClient` (`_terminal`,
+  `_prepare_request`, `stream()`) has to stay there; ~200 lines of this file
+  currently don't.
+- The package already has a home for exactly this shape of code:
+  `_internal/status.py` holds `_raise_on_status_error` and the
+  streaming-body predicates, `_internal/exception_mapping.py` holds
+  `map_httpx2_exception` — both pure, self-contained, shared by both clients.
+  The body-cap subsystem and the exception-mapper context managers are the
+  same shape and never received the same treatment.
+- Same-day precedent: `2026-06-23.01-retry-policy-extraction.md` and
+  `2026-06-23.02-decoder-resolver-extraction.md` pulled comparable
+  self-contained logic out of their hosting files into dedicated modules.
+  `2026-06-23.03-response-body-cap.md` landed the body-cap subsystem directly
+  in `client.py` the same day and never got the follow-up move.
+- **Depth:** the body-cap subsystem's own tests (`tests/test_capped_read.py`,
+  `tests/test_capped_read_props.py`) already exercise it as a standalone
+  unit, importing the functions directly rather than through `Client`. The
+  seam already exists in the tests; the source hasn't caught up.
+- **Deletion test:** delete `_internal/body_cap.py` after this change and the
+  ~150 lines of cap-accumulation/header-rebuild logic reappear somewhere —
+  it's real, load-bearing complexity, not a pass-through. It earns the move.
+
+## Design
+
+### 1. `_internal/body_cap.py` — new module
+
+Moves verbatim (no logic change):
+
+- `_MAX_RESPONSE_BODY_BYTES_INVALID`, `_validate_max_response_body_bytes`
+- `_parse_content_length`
+- `_CapExceeded`, `_accumulate_capped`
+- `_safe_extensions`
+- `_WIRE_BODY_HEADERS`, `_BODILESS_STATUS`, `_buffered_headers`
+- `_response_has_body`
+- `_read_capped`, `_read_capped_async`
+
+Needs its own imports: `httpx2`, `HTTPStatus` (from `http`), `Mapping` (from
+`collections.abc`), and `ResponseTooLargeError` (from `httpware.errors`) —
+all currently imported by `client.py` for this code's sake and dropped from
+`client.py`'s import block once it moves (`Mapping` and
+`ResponseTooLargeError` are used nowhere else in `client.py`; `HTTPStatus`
+stays imported in `client.py` because `stream()` uses it independently at
+`client.py:1152` and `:2146`).
+
+`_build_default_decoders` (`client.py:172-190`) stays in `client.py`.
+`architecture/decoders.md` documents its location explicitly ("`decoders=None`
+resolves via `client.py:_build_default_decoders()`"); it is the same shape of
+pure, self-contained code but moving it isn't part of this change's motivation
+and would mean editing a Seam B contract that this change has no reason to
+touch.
+
+### 2. `_internal/exception_mapping.py` — gains two context managers
+
+`_httpx2_exception_mapper` (async) and `_httpx2_exception_mapper_sync` (sync)
+move in next to `map_httpx2_exception`, which they already wrap. Same
+rationale as body-cap — pure, self-contained, sibling concern already has a
+module — bundled into this change rather than a second near-identical PR.
+
+### 3. `client.py` shrinks to three imported names
+
+Only `_validate_max_response_body_bytes` (called once per `__init__`),
+`_read_capped`, and `_read_capped_async` (called from `_terminal` and
+`stream()`, both worlds) are actually referenced from inside `Client`/
+`AsyncClient`. Every other moved name (`_parse_content_length`,
+`_CapExceeded`, `_accumulate_capped`, `_safe_extensions`, `_buffered_headers`,
+`_response_has_body`) is internal to `body_cap.py` and never imported by
+`client.py`. `_httpx2_exception_mapper`/`_httpx2_exception_mapper_sync` are
+imported by name, same call sites as today (`client.py:283`, `:1151`,
+`:1255`, `:2145`).
+
+```python
+from httpware._internal.body_cap import _read_capped, _read_capped_async, _validate_max_response_body_bytes
+from httpware._internal.exception_mapping import _httpx2_exception_mapper, _httpx2_exception_mapper_sync, map_httpx2_exception
+```
+
+Nine functions/one class collapse behind a three-name import in `client.py`
+for body-cap, plus the two context managers for exception mapping.
+
+### 4. `architecture/overview.md` — module-layout table
+
+Add a `body_cap.py` row under `_internal/`; update `exception_mapping.py`'s
+description to mention the context managers:
+
+```text
+└── _internal/
+    ├── 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
+```
+
+## Non-goals
+
+- No behavior change. Cap validation, accumulation, header rebuild,
+  `ResponseTooLargeError` reasons, and exception-mapping order stay
+  byte-identical.
+- Not moving `_build_default_decoders` (see Design §1).
+- Not touching the public `max_response_body_bytes` parameter, its
+  validation error message, or `ResponseTooLargeError`'s shape.
+- Not addressing the larger `Client`/`AsyncClient` sync/async duplication
+  (the per-verb methods, `_prepare_request`, `_request_with_body`) — a
+  separate, much larger candidate surfaced in the same architecture review,
+  deliberately deferred pending its own design call.
+
+## Testing
+
+- **Parity net:** rename `tests/test_capped_read.py` →
+  `tests/test_body_cap.py` and `tests/test_capped_read_props.py` →
+  `tests/test_body_cap_props.py`, updating their imports from
+  `httpware.client` to `httpware._internal.body_cap`. All existing
+  assertions stay unchanged — byte-identical behavior is the bar.
+- Move `test_parse_content_length` (currently `tests/test_client_stream.py:446-447`,
+  testing a `body_cap.py` function directly rather than `stream()` behavior)
+  into `tests/test_body_cap.py`, updating its import.
+- No new tests — this is a pure move with an existing, adequate net
+  (`test_body_cap.py`, `test_body_cap_props.py`, `test_client_body_cap.py`
+  for cap wiring through the client, `test_error_mapping_terminal.py` for
+  exception-mapping-at-terminal behavior).
+- `just lint && just test` green; 100% coverage maintained.
+
+## Risk
+
+- **Import cycle** (unlikely × medium): `_internal/body_cap.py` imports
+  `httpware.errors.ResponseTooLargeError`. *Mitigation:* `_internal/status.py`
+  already imports from `httpware.errors` today with no cycle — same
+  direction, same precedent.
+- **Missed call site during the move** (unlikely × low): a stale import left
+  in `client.py`, or a name imported but now unused. *Mitigation:* `just
+  lint` catches unused imports; `just test` exercises every moved function
+  through its existing suite.
+- **Test-file rename loses git history readability** (certain × low):
+  `git mv` preserves blame across the rename; low impact either way.