feat: forward every httpx2 client option to the owned client (#148)

* feat: forward every httpx2 client option to the owned client

AsyncClient and Client forwarded only seven httpx2 client keywords, so
setting verify (or proxy, http2, transport, ...) meant building the httpx2
client by hand and closing it yourself. Every option is now forwarded,
typed via Unpack[TypedDict]; cert and event_hooks are refused, and
follow_redirects=True with max_response_body_bytes raises ValueError.

* docs: drop the ADR for httpx2 client option forwarding

Author: lesnik512

AGENTS.md

@@ -59,7 +59,7 @@ Every module under `src/httpware/` is named for what it does; read it. What a si
 
 ### Testing patterns
 
-Transport mocking is `httpx2.MockTransport` passed as `httpx2_client=`, never `respx` — `respx`
+Transport mocking is `httpx2.MockTransport` passed as `transport=`, never `respx` — `respx`
 targets `httpx`, not `httpx2`, and patches its internals. Concurrency-sensitive components carry
 Hypothesis property tests in `test_*_props.py`, and `stress`-marked tests drive real thread
 parallelism: they run under the GIL for coverage, but the proof comes from the free-threaded

docs/errors.md

@@ -190,7 +190,7 @@ Unlike `DecodeError`, this error fires *before* the HTTP request — no traffic
 
 ## `ResponseTooLargeError`
 
-Both `Client` and `AsyncClient` accept a `max_response_body_bytes: int | None = None` constructor argument. It's an opt-in cap — the default `None` means unbounded, matching current behavior. When set, a response body that exceeds the cap raises `ResponseTooLargeError` instead of being returned. The check is status-agnostic (a `200` can trip it just as easily as a `4xx`/`5xx`), and it counts **decoded** bytes. It fires from the non-streaming terminal (`send()` / verb methods) and from `stream()`'s internal error pre-read; bytes you pull yourself via `stream()` iteration are never capped.
+Both `Client` and `AsyncClient` accept a `max_response_body_bytes: int | None = None` constructor argument. It's an opt-in cap — the default `None` means unbounded, matching current behavior. When set, a response body that exceeds the cap raises `ResponseTooLargeError` instead of being returned. The check is status-agnostic (a `200` can trip it just as easily as a `4xx`/`5xx`), and it counts **decoded** bytes. It fires from the non-streaming terminal (`send()` / verb methods) and from `stream()`'s internal error pre-read; bytes you pull yourself via `stream()` iteration are never capped. Combining the cap with `follow_redirects=True`, on the client or on a passed `httpx2_client`, raises `ValueError`: `httpx2` reads every intermediate redirect body without it.
 
 `ResponseTooLargeError` carries:
 

docs/index.md

@@ -64,6 +64,21 @@ with Client(base_url="https://jsonplaceholder.typicode.com") as client:
 
 `base_url` must not contain a query string: constructing a client with one raises `ValueError`. Put query parameters shared by every request in `params=` instead.
 
+Every other keyword of `httpx2.AsyncClient`/`httpx2.Client` (`verify`, `proxy`, `http2`, `transport`, `follow_redirects`, ...) is forwarded to the `httpx2` client that `httpware` builds and closes. Two are refused: `cert`, deprecated by `httpx2` in favour of an `ssl.SSLContext` passed as `verify`, and `event_hooks`, which run below the middleware chain; use [middleware](middleware.md) instead.
+
+```python
+import ssl
+
+from httpware import AsyncClient
+
+client = AsyncClient(
+    base_url="https://internal.example",
+    verify=ssl.create_default_context(cafile="/etc/ssl/internal-ca.pem"),
+)
+```
+
+To share one connection pool between several clients, build the `httpx2` client yourself and pass it as `httpx2_client=`. It is then yours to close, and none of the options above can be combined with it.
+
 Typed decoding via `response_model=` works the same way in both worlds:
 
 ```python

docs/testing.md

@@ -1,8 +1,8 @@
 # Testing guide
 
-`httpware`'s test seam is `httpx2`. Pass any `httpx2.AsyncClient` (including one built on `httpx2.MockTransport`) to `AsyncClient(httpx2_client=...)` — the middleware chain still runs end-to-end, only the wire is mocked. No special test mode, no monkey-patching, no `respx`.
+`httpware`'s test seam is `httpx2`. Pass an `httpx2.MockTransport` as `AsyncClient(transport=...)` — the middleware chain still runs end-to-end, only the wire is mocked, and the client still owns and closes its `httpx2` client. No special test mode, no monkey-patching, no `respx`.
 
-`httpx2_client=` is mutually exclusive with `base_url`, `headers`, `params`, `cookies`, `timeout`, `limits`, and `auth`: passing any of those alongside a pre-built `httpx2_client=` raises `TypeError`. Configure the `httpx2.AsyncClient`/`httpx2.Client` you pass instead.
+A pre-built `httpx2.AsyncClient`/`httpx2.Client` can be passed as `httpx2_client=` instead. It is mutually exclusive with every `httpx2` client option (`base_url`, `headers`, `transport`, `verify`, ...): passing any of them alongside it raises `TypeError`. Configure the client you pass instead; `httpware` will not close it.
 
 ## The basic pattern
 
@@ -19,8 +19,7 @@ def handler(request: httpx2.Request) -> httpx2.Response:
 
 
 async def test_get_user() -> None:
-    transport = httpx2.MockTransport(handler)
-    async with AsyncClient(httpx2_client=httpx2.AsyncClient(transport=transport)) as client:
+    async with AsyncClient(transport=httpx2.MockTransport(handler)) as client:
         response = await client.get("https://api.example.test/users/1")
     assert response.status_code == HTTPStatus.OK
     assert response.json()["name"] == "Alice"
@@ -32,7 +31,7 @@ If you use `pytest-asyncio` in auto-mode (`asyncio_mode = "auto"` under `[tool.p
 
 ### Sync `Client`
 
-The same pattern works for the sync `Client` — pass an `httpx2.Client` (not `httpx2.AsyncClient`) built on `httpx2.MockTransport`:
+The same pattern works for the sync `Client`; `httpx2.MockTransport` serves both worlds:
 
 ```python
 from http import HTTPStatus
@@ -46,7 +45,7 @@ def test_get_returns_typed_response() -> None:
     def handler(request: httpx2.Request) -> httpx2.Response:
         return httpx2.Response(HTTPStatus.OK, request=request, json={"ok": True})
 
-    with Client(httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler))) as client:
+    with Client(transport=httpx2.MockTransport(handler)) as client:
         response = client.get("https://example.test/x")
 
     assert response.status_code == HTTPStatus.OK
@@ -76,9 +75,8 @@ class _ResponseSequence:
 
 async def test_retry_succeeds_after_503() -> None:
     handler = _ResponseSequence([HTTPStatus.SERVICE_UNAVAILABLE, HTTPStatus.OK])
-    transport = httpx2.MockTransport(handler)
     async with AsyncClient(
-        httpx2_client=httpx2.AsyncClient(transport=transport),
+        transport=httpx2.MockTransport(handler),
         middleware=[AsyncRetry(base_delay=0.001, max_delay=0.002)],
     ) as client:
         response = await client.get("https://example.test/x")
@@ -96,7 +94,7 @@ Compose your middleware with the mock transport to exercise the chain end-to-end
 async def test_my_middleware_adds_header() -> None:
     handler = _ResponseSequence([HTTPStatus.OK])
     async with AsyncClient(
-        httpx2_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)),
+        transport=httpx2.MockTransport(handler),
         middleware=[MyHeaderMiddleware()],
     ) as client:
         await client.get("https://example.test/x")

src/httpware/client.py

@@ -1,8 +1,9 @@
 """Client + AsyncClient — thin httpx2 wrappers with typed decoding and middleware."""
 
 import contextlib
+import ssl
 import typing
-from collections.abc import AsyncIterator, Iterator, Sequence
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping, Sequence
 from http import HTTPStatus
 
 import httpx2
@@ -29,10 +30,17 @@
 T = typing.TypeVar("T")
 
 
-_FORWARDED_KWARG_NAMES = ("base_url", "headers", "params", "cookies", "timeout", "limits", "auth")
 _HTTPX2_CLIENT_CONFLICT_MESSAGE = (
-    "httpx2_client=... cannot be combined with any of "
-    f"{_FORWARDED_KWARG_NAMES}; configure the httpx2 client you pass instead."
+    "httpx2_client=... cannot be combined with httpx2 client options {names}; "
+    "configure the httpx2 client you pass instead."
+)
+_UNSUPPORTED_OPTION_HINTS = {
+    "cert": "cert=... is deprecated by httpx2; pass verify=<ssl.SSLContext> configured with .load_cert_chain().",
+    "event_hooks": "event_hooks=... is not supported; use middleware=... instead.",
+}
+_FOLLOW_REDIRECTS_WITH_BODY_CAP_MESSAGE = (
+    "follow_redirects=True cannot be combined with max_response_body_bytes: httpx2 reads every "
+    "intermediate redirect body without the cap."
 )
 _BASE_URL_QUERY_MESSAGE = (
     "base_url must not contain a query string: httpx2 appends request paths after it, "
@@ -61,63 +69,75 @@ def _build_default_decoders() -> tuple[ResponseDecoder, ...]:
     return tuple(decoders)
 
 
-def _validate_httpx2_client_conflict(  # noqa: PLR0913 — 7 forwarded kwargs from caller's constructor
-    *,
-    base_url: str,
-    headers: dict[str, str] | None,
-    params: dict[str, str] | None,
-    cookies: dict[str, str] | None,
-    timeout: httpx2.Timeout | float | None,
-    limits: httpx2.Limits | None,
-    auth: httpx2.Auth | None,
-) -> None:
-    """Raise TypeError if httpx2_client=... is combined with a forwarded kwarg."""
-    forwarded = {
-        "base_url": base_url,
-        "headers": headers,
-        "params": params,
-        "cookies": cookies,
-        "timeout": timeout,
-        "limits": limits,
-        "auth": auth,
-    }
-    if any(value not in (None, "") for value in forwarded.values()):
-        raise TypeError(_HTTPX2_CLIENT_CONFLICT_MESSAGE)
-
-
 def _reject_base_url_query(base_url: httpx2.URL | str) -> None:
     """Raise ValueError if base_url carries a query string."""
     if httpx2.URL(base_url).query:
         raise ValueError(_BASE_URL_QUERY_MESSAGE)
 
 
-def _assemble_httpx2_client_kwargs(  # noqa: PLR0913 — 7 forwarded kwargs from caller's constructor
+class _ClientOptionsBase(typing.TypedDict, total=False):
+    base_url: str
+    headers: dict[str, str] | None
+    params: dict[str, str] | None
+    cookies: dict[str, str] | None
+    timeout: httpx2.Timeout | float | None
+    limits: httpx2.Limits | None
+    auth: httpx2.Auth | None
+    verify: ssl.SSLContext | bool
+    trust_env: bool
+    http1: bool
+    http2: bool
+    proxy: httpx2.URL | str | httpx2.Proxy | None
+    follow_redirects: bool
+    max_redirects: int
+    default_encoding: str | Callable[[bytes], str | None]
+
+
+class _AsyncClientOptions(_ClientOptionsBase, total=False):
+    """Keyword arguments `AsyncClient` forwards to the `httpx2.AsyncClient` it owns."""
+
+    transport: httpx2.AsyncBaseTransport | None
+    mounts: Mapping[str, httpx2.AsyncBaseTransport | None] | None
+
+
+class _ClientOptions(_ClientOptionsBase, total=False):
+    """Keyword arguments `Client` forwards to the `httpx2.Client` it owns."""
+
+    transport: httpx2.BaseTransport | None
+    mounts: Mapping[str, httpx2.BaseTransport | None] | None
+
+
+def _is_unset(value: object) -> bool:
+    return value is None or (isinstance(value, str) and not value)
+
+
+def _select_httpx2_options(
+    owner: str,
+    options: Mapping[str, typing.Any],
+    supported: frozenset[str],
     *,
-    base_url: str,
-    headers: dict[str, str] | None,
-    params: dict[str, str] | None,
-    cookies: dict[str, str] | None,
-    timeout: httpx2.Timeout | float | None,
-    limits: httpx2.Limits | None,
-    auth: httpx2.Auth | None,
+    httpx2_client: httpx2.Client | httpx2.AsyncClient | None,
+    max_response_body_bytes: int | None,
 ) -> dict[str, typing.Any]:
-    """Build the kwargs dict for constructing the owned httpx2 client."""
-    kwargs: dict[str, typing.Any] = {}
-    if base_url:
-        kwargs["base_url"] = base_url
-    if headers is not None:
-        kwargs["headers"] = headers
-    if params is not None:
-        kwargs["params"] = params
-    if cookies is not None:
-        kwargs["cookies"] = cookies
-    if timeout is not None:
-        kwargs["timeout"] = timeout
-    if limits is not None:
-        kwargs["limits"] = limits
-    if auth is not None:
-        kwargs["auth"] = auth
-    return kwargs
+    """Return the options to forward to the owned httpx2 client, dropping unset ones.
+
+    Raise TypeError for unsupported options or options combined with `httpx2_client`, and
+    ValueError when the client would follow redirects under a body cap.
+    """
+    unsupported = sorted(options.keys() - supported)
+    if unsupported:
+        hints = "".join(
+            f" {_UNSUPPORTED_OPTION_HINTS[name]}" for name in unsupported if name in _UNSUPPORTED_OPTION_HINTS
+        )
+        msg = f"{owner}() got unexpected keyword arguments {unsupported}.{hints}"
+        raise TypeError(msg)
+    forwarded = {name: value for name, value in options.items() if not _is_unset(value)}
+    if httpx2_client is not None and forwarded:
+        raise TypeError(_HTTPX2_CLIENT_CONFLICT_MESSAGE.format(names=sorted(forwarded)))
+    follows = httpx2_client.follow_redirects if httpx2_client is not None else forwarded.get("follow_redirects")
+    if follows and max_response_body_bytes is not None:
+        raise ValueError(_FOLLOW_REDIRECTS_WITH_BODY_CAP_MESSAGE)
+    return forwarded
 
 
 def _assemble_request_kwargs(  # noqa: PLR0913 — 9 per-request kwargs from httpx2 call signatures
@@ -175,47 +195,30 @@ class AsyncClient:
     _dispatch: AsyncNext
     _max_response_body_bytes: int | None
 
-    def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call API
+    def __init__(
         self,
         *,
-        base_url: str = "",
-        headers: dict[str, str] | None = None,
-        params: dict[str, str] | None = None,
-        cookies: dict[str, str] | None = None,
-        timeout: httpx2.Timeout | float | None = None,
-        limits: httpx2.Limits | None = None,
-        auth: httpx2.Auth | None = None,
         httpx2_client: httpx2.AsyncClient | None = None,
         decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[AsyncMiddleware] = (),
         max_response_body_bytes: int | None = None,
+        **httpx2_options: typing.Unpack[_AsyncClientOptions],
     ) -> None:
         _validate_max_response_body_bytes(max_response_body_bytes)
+        forwarded = _select_httpx2_options(
+            type(self).__name__,
+            httpx2_options,
+            _AsyncClientOptions.__optional_keys__,
+            httpx2_client=httpx2_client,
+            max_response_body_bytes=max_response_body_bytes,
+        )
         if httpx2_client is not None:
-            _validate_httpx2_client_conflict(
-                base_url=base_url,
-                headers=headers,
-                params=params,
-                cookies=cookies,
-                timeout=timeout,
-                limits=limits,
-                auth=auth,
-            )
             _reject_base_url_query(httpx2_client.base_url)
             self._httpx2_client = httpx2_client
             self._owns_client = False
         else:
-            _reject_base_url_query(base_url)
-            kwargs = _assemble_httpx2_client_kwargs(
-                base_url=base_url,
-                headers=headers,
-                params=params,
-                cookies=cookies,
-                timeout=timeout,
-                limits=limits,
-                auth=auth,
-            )
-            self._httpx2_client = httpx2.AsyncClient(**kwargs)
+            _reject_base_url_query(forwarded.get("base_url", ""))
+            self._httpx2_client = httpx2.AsyncClient(**forwarded)
             self._owns_client = True
 
         self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()
@@ -1129,47 +1132,30 @@ class Client:
     _dispatch: Next
     _max_response_body_bytes: int | None
 
-    def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call API
+    def __init__(
         self,
         *,
-        base_url: str = "",
-        headers: dict[str, str] | None = None,
-        params: dict[str, str] | None = None,
-        cookies: dict[str, str] | None = None,
-        timeout: httpx2.Timeout | float | None = None,
-        limits: httpx2.Limits | None = None,
-        auth: httpx2.Auth | None = None,
         httpx2_client: httpx2.Client | None = None,
         decoders: Sequence[ResponseDecoder] | None = None,
         middleware: Sequence[Middleware] = (),
         max_response_body_bytes: int | None = None,
+        **httpx2_options: typing.Unpack[_ClientOptions],
     ) -> None:
         _validate_max_response_body_bytes(max_response_body_bytes)
+        forwarded = _select_httpx2_options(
+            type(self).__name__,
+            httpx2_options,
+            _ClientOptions.__optional_keys__,
+            httpx2_client=httpx2_client,
+            max_response_body_bytes=max_response_body_bytes,
+        )
         if httpx2_client is not None:
-            _validate_httpx2_client_conflict(
-                base_url=base_url,
-                headers=headers,
-                params=params,
-                cookies=cookies,
-                timeout=timeout,
-                limits=limits,
-                auth=auth,
-            )
             _reject_base_url_query(httpx2_client.base_url)
             self._httpx2_client = httpx2_client
             self._owns_client = False
         else:
-            _reject_base_url_query(base_url)
-            kwargs = _assemble_httpx2_client_kwargs(
-                base_url=base_url,
-                headers=headers,
-                params=params,
-                cookies=cookies,
-                timeout=timeout,
-                limits=limits,
-                auth=auth,
-            )
-            self._httpx2_client = httpx2.Client(**kwargs)
+            _reject_base_url_query(forwarded.get("base_url", ""))
+            self._httpx2_client = httpx2.Client(**forwarded)
             self._owns_client = True
 
         self._decoders = tuple(decoders) if decoders is not None else _build_default_decoders()