fix: reject a base_url that contains a query string (#147)

httpx2 appends the trailing slash and request path after the query,
producing malformed URLs. Raise ValueError at construction, for both
owned and caller-provided httpx2 clients.

Author: lesnik512

docs/index.md

@@ -62,6 +62,8 @@ with Client(base_url="https://jsonplaceholder.typicode.com") as client:
     print(response.json())
 ```
 
+`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.
+
 Typed decoding via `response_model=` works the same way in both worlds:
 
 ```python

src/httpware/client.py

@@ -34,6 +34,10 @@
     "httpx2_client=... cannot be combined with any of "
     f"{_FORWARDED_KWARG_NAMES}; configure the httpx2 client you pass instead."
 )
+_BASE_URL_QUERY_MESSAGE = (
+    "base_url must not contain a query string: httpx2 appends request paths after it, "
+    "producing malformed URLs. Pass the query as params=... instead."
+)
 
 
 def _build_default_decoders() -> tuple[ResponseDecoder, ...]:
@@ -81,6 +85,12 @@ def _validate_httpx2_client_conflict(  # noqa: PLR0913 — 7 forwarded kwargs fr
         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
     *,
     base_url: str,
@@ -191,9 +201,11 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
                 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,
@@ -1143,9 +1155,11 @@ def __init__(  # noqa: PLR0913 — wide constructor is the cost of a single-call
                 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,

tests/test_base_url_query.py

@@ -0,0 +1,39 @@
+"""A `base_url` carrying a query string is rejected at construction."""
+
+import httpx2
+import pytest
+
+from httpware import AsyncClient, Client
+
+
+_BASE_URL_WITH_QUERY = "https://example.test/api?key=secret"
+
+
+def test_async_client_rejects_base_url_with_query() -> None:
+    with pytest.raises(ValueError, match="query string") as exc_info:
+        AsyncClient(base_url=_BASE_URL_WITH_QUERY)
+    assert "secret" not in str(exc_info.value)
+
+
+def test_sync_client_rejects_base_url_with_query() -> None:
+    with pytest.raises(ValueError, match="query string") as exc_info:
+        Client(base_url=_BASE_URL_WITH_QUERY)
+    assert "secret" not in str(exc_info.value)
+
+
+def test_async_client_rejects_caller_owned_httpx2_client_base_url_with_query() -> None:
+    with pytest.raises(ValueError, match="query string"):
+        AsyncClient(httpx2_client=httpx2.AsyncClient(base_url=_BASE_URL_WITH_QUERY))
+
+
+def test_sync_client_rejects_caller_owned_httpx2_client_base_url_with_query() -> None:
+    with pytest.raises(ValueError, match="query string"):
+        Client(httpx2_client=httpx2.Client(base_url=_BASE_URL_WITH_QUERY))
+
+
+@pytest.mark.parametrize(
+    "base_url", ["", "https://example.test", "https://example.test/api/", "https://example.test/#f"]
+)
+def test_base_url_without_query_is_accepted(base_url: str) -> None:
+    assert Client(base_url=base_url)
+    assert AsyncClient(base_url=base_url)