quadkit-http 0.0.43__tar.gz → 0.0.45__tar.gz

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit-http
-Version: 0.0.43
+Version: 0.0.45
 Summary: Outbound HTTP client for the Quadkit Framework
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-http"
-version = "0.0.43"
+version = "0.0.45"
 description = "Outbound HTTP client for the Quadkit Framework"
 readme = "README.md"
 requires-python = ">=3.11"

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/src/quadkit/http/__init__.py

@@ -35,7 +35,12 @@ __path__ = __import__("pkgutil").extend_path(__path__, __name__)
 from quadkit.http.constants import __version__ as __version__
 
 if TYPE_CHECKING:
-    from quadkit.http.client import BaseURLHTTPClient, HTTPClient, StreamContext, StreamResponse
+    from quadkit.http.client import (
+        BaseURLHTTPClient,
+        HTTPClient,
+        StreamContext,
+        StreamResponse,
+    )
     from quadkit.http.config import (
         ConnectionPoolConfig,
         HTTPClientConfig,

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/src/quadkit/http/cli/templates/api_client.py.jinja2

@@ -1,6 +1,14 @@
 """{{ client_name }} API client.
 
-This module provides a client for interacting with the {{ client_name }} API.
+Outbound boundary for the {{ client_name }} API: base URL, auth,
+pooling and retries stay inside; callers see framework-owned
+``HttpResponse`` objects, never the transport library.
+
+Convention: **Result + ProblemDetail** — ``_request`` answers
+``Result[HttpResponse, {{ client_name }}APIError]`` so a failing outbound
+call is a VALUE the caller maps (.map_sync / .map_err), not an exception it
+must catch. A request that cannot complete once becomes one ``Err`` —
+the caller's own Err arm (R6: absence is a value).
 """
 
 from __future__ import annotations
@@ -10,6 +18,7 @@ from typing import Any
 from quadkit.contracts.web import HttpResponse
 from quadkit.http import BaseURLHTTPClient
 from quadkit.logging import get_logger
+from quadkit.result import Err, Ok, Result
 
 logger = get_logger(__name__)
 
@@ -70,10 +79,10 @@ class {{ client_name }}Client:
     # =========================================================================
     # Add your API methods here. Examples:
     #
-    # async def get_user(self, user_id: str) -> dict[str, Any]:
+    # async def get_user(self, user_id: str) -> Result[dict[str, Any], {{ client_name }}APIError]:
     #     """Get a user by ID."""
-    #     response = await self._request("GET", f"/users/{user_id}")
-    #     return response.json or {}
+    #     result = await self._request("GET", f"/users/{user_id}")
+    #     return result.map_sync(lambda response: response.json or {})
     #
     # async def list_users(self, limit: int = 20, offset: int = 0) -> list[dict[str, Any]]:
     #     """List users with pagination."""
@@ -82,10 +91,10 @@ class {{ client_name }}Client:
     #     )
     #     return response.json or []
     #
-    # async def create_user(self, data: dict[str, Any]) -> dict[str, Any]:
+    # async def create_user(self, data: dict[str, Any]) -> Result[dict[str, Any], {{ client_name }}APIError]:
     #     """Create a new user."""
-    #     response = await self._request("POST", "/users", json=data)
-    #     return response.json or {}
+    #     result = await self._request("POST", "/users", json=data)
+    #     return result.map_sync(lambda response: response.json or {})
     #
     # async def update_user(self, user_id: str, data: dict[str, Any]) -> dict[str, Any]:
     #     """Update an existing user."""
@@ -105,8 +114,8 @@ class {{ client_name }}Client:
         method: str,
         endpoint: str,
         **kwargs: Any,
-    ) -> HttpResponse:
-        """Make an HTTP request with error handling.
+    ) -> Result[HttpResponse, {{ client_name }}APIError]:
+        """Make an HTTP request, answering the outcome as one Result.
 
         Args:
             method: HTTP method (GET, POST, PUT, PATCH, DELETE).
@@ -114,33 +123,39 @@ class {{ client_name }}Client:
             **kwargs: Additional arguments forwarded to the HTTP client.
 
         Returns:
-            The framework HTTP response.
-
-        Raises:
-            {{ client_name }}APIError: If the API returns an error status.
+            ``Ok(response)`` on a passing status, ``Err(APIError)`` on a
+            client/server failure or a transport exception — never raised,
+            so consumers compose with .map_sync / .map_err instead of try/except.
         """
         try:
             response = await self._client.request(method, endpoint, **kwargs)
-            if response.status >= 400:
-                raise {{ client_name }}APIError(
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("{{ client_name_snake }}_request_error", method=method)
+            return Err(
+                {{ client_name }}APIError(
+                    message=f"Request failed: {exc}",
+                    status_code=None,
+                    response=None,
+                )
+            )
+        if response.status >= 400:
+            return Err(
+                {{ client_name }}APIError(
                     message=f"API request failed: {response.status}",
                     status_code=response.status,
                     response=response,
                 )
-            return response
-        except {{ client_name }}APIError:
-            raise
-        except Exception as exc:  # noqa: BLE001
-            logger.exception("{{ client_name_snake }}_request_error", method=method)
-            raise {{ client_name }}APIError(
-                message=f"Request failed: {exc}",
-                status_code=None,
-                response=None,
-            ) from exc
+            )
+        return Ok(response)
 
 
 class {{ client_name }}APIError(Exception):
-    """Exception raised when the {{ client_name }} API returns an error."""
+    """The {{ client_name }} API failure outcome as a value.
+
+    Carried in ``Err`` (R6) — callers compose instead of try/except. It
+    subclasses ``Exception`` only so a consumer MAY escalate it across an
+    outer infrastructure boundary unchanged.
+    """
 
     def __init__(
         self,

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/src/quadkit/http/client/__init__.py

@@ -7,4 +7,10 @@ from quadkit.http.client.base_url_client import BaseURLHTTPClient, StreamContext
 from quadkit.http.client.http_client import HTTPClient
 from quadkit.http.pool import ConnectionPool
 
-__all__ = ["BaseURLHTTPClient", "ConnectionPool", "HTTPClient", "StreamContext", "StreamResponse"]
+__all__ = [
+    "BaseURLHTTPClient",
+    "ConnectionPool",
+    "HTTPClient",
+    "StreamContext",
+    "StreamResponse",
+]

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/src/quadkit/http/websocket.py

@@ -9,7 +9,8 @@ client. HTTP applications use the same aiohttp connection stack as the rest of
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any
+from types import TracebackType
+from typing import Any, Self
 
 import aiohttp
 
@@ -42,7 +43,7 @@ class WebSocketClient:
         self._session: aiohttp.ClientSession | None = None
         self._socket: aiohttp.ClientWebSocketResponse | None = None
 
-    async def __aenter__(self) -> WebSocketClient:
+    async def __aenter__(self) -> Self:
         self._session = aiohttp.ClientSession(
             timeout=aiohttp.ClientTimeout(total=None, sock_connect=self.connect_timeout)
         )
@@ -59,7 +60,12 @@ class WebSocketClient:
             raise
         return self
 
-    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
         await self.close()
 
     @property

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/tests/unit/cli/test_api_client_generator.py

@@ -41,6 +41,19 @@ class TestAPIClientGenerator:
         assert "token" in content
         assert "PaymentsClient" in content
 
+    def test_request_answers_result_never_raises(self, tmp_path) -> None:
+        g = _gen(tmp_path)
+        g.generate("Stripe")
+        content = (tmp_path / "clients" / "stripe_client.py").read_text()
+        # the _request seam is Result-shaped: an outbound failure is a VALUE
+        assert "from quadkit.result import Err, Ok, Result" in content
+        assert "-> Result[HttpResponse, StripeAPIError]:" in content
+        assert "return Ok(response)" in content
+        assert content.count("return Err(") == 2
+        assert "raise StripeAPIError(" not in content
+        # scaffold examples teach composing, not catching
+        assert "return result.map_sync(lambda response:" in content
+
     def test_fields_str_invalid_raises(self, tmp_path) -> None:
         import pytest
 

{quadkit_http-0.0.43 → quadkit_http-0.0.45}/tests/unit/test_http_client_verbs.py

@@ -278,9 +278,9 @@ class TestTimeoutNormalization:
     async def test_get_normalises_aiohttp_connection_error(self):
         """aiohttp.ClientError (connect refused/DNS/reset) → Err(HTTPConnectionError).
 
-        Regression (QK-USE-3, gatewai probe adoption): raw aiohttp errors used
+        Detail (QK-USE-3, probe adoption): raw aiohttp errors used
         to escape `get()` instead of mapping to the documented connection-error
-        Result — unreachable hosts crashed callers that expected `Err`.
+        Result — unreachable hosts reach callers that expected `Err`.
         """
         client = HTTPClientImpl(
             config=HTTPClientConfig(enforce_url_safety=False),

quadkit_http-0.0.45/tests/unit/test_websocket.py

@@ -0,0 +1,253 @@
+"""Unit tests for the outbound WebSocket transport."""
+
+from __future__ import annotations
+
+from dataclasses import FrozenInstanceError
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import aiohttp
+import pytest
+
+from quadkit.http.websocket import WebSocketClient, WebSocketMessage
+
+
+def _frame(msg_type: aiohttp.WSMsgType, data: Any = None) -> SimpleNamespace:
+    """A stand-in for aiohttp's WSMessage, which is a namedtuple we only read."""
+    return SimpleNamespace(type=msg_type, data=data)
+
+
+def _connected_client(socket: AsyncMock | None = None) -> WebSocketClient:
+    """A client whose socket is already attached, bypassing __aenter__."""
+    client = WebSocketClient("ws://example.test/socket")
+    client._socket = socket if socket is not None else AsyncMock(closed=False)
+    return client
+
+
+class TestWebSocketMessage:
+    """The normalized message value object."""
+
+    def test_defaults(self) -> None:
+        message = WebSocketMessage("text")
+        assert message.type == "text"
+        assert message.data is None
+
+    def test_is_frozen(self) -> None:
+        message = WebSocketMessage("text", "payload")
+        with pytest.raises(FrozenInstanceError):
+            message.type = "bytes"  # type: ignore[misc]
+
+
+class TestConstruction:
+    """Scheme validation and stored configuration."""
+
+    @pytest.mark.parametrize("url", ["ws://example.test/s", "wss://example.test/s"])
+    def test_accepts_websocket_schemes(self, url: str) -> None:
+        client = WebSocketClient(url)
+        assert client.url == url
+
+    @pytest.mark.parametrize(
+        "url", ["http://example.test", "https://example.test", "example.test"]
+    )
+    def test_rejects_non_websocket_schemes(self, url: str) -> None:
+        with pytest.raises(ValueError, match="must start with ws:// or wss://"):
+            WebSocketClient(url)
+
+    def test_defaults(self) -> None:
+        client = WebSocketClient("ws://example.test/s")
+        assert client.headers == {}
+        assert client.connect_timeout == 30.0
+        assert client.heartbeat == 30.0
+        assert client._session is None
+        assert client._socket is None
+
+    def test_overrides(self) -> None:
+        client = WebSocketClient(
+            "wss://example.test/s",
+            headers={"Authorization": "Bearer t"},
+            connect_timeout=5.0,
+            heartbeat=None,
+        )
+        assert client.headers == {"Authorization": "Bearer t"}
+        assert client.connect_timeout == 5.0
+        assert client.heartbeat is None
+
+
+class TestClosedProperty:
+    """`closed` reports the upstream socket, not the wrapper."""
+
+    def test_true_before_connect(self) -> None:
+        assert WebSocketClient("ws://example.test/s").closed is True
+
+    def test_false_while_socket_open(self) -> None:
+        assert _connected_client(AsyncMock(closed=False)).closed is False
+
+    def test_true_once_socket_closed(self) -> None:
+        assert _connected_client(AsyncMock(closed=True)).closed is True
+
+
+class TestSendRequiresConnection:
+    """Every send fails fast rather than silently dropping the frame."""
+
+    async def test_send_json(self) -> None:
+        with pytest.raises(RuntimeError, match="not connected"):
+            await WebSocketClient("ws://example.test/s").send_json({"a": 1})
+
+    async def test_send_text(self) -> None:
+        with pytest.raises(RuntimeError, match="not connected"):
+            await WebSocketClient("ws://example.test/s").send_text("hi")
+
+    async def test_send_bytes(self) -> None:
+        with pytest.raises(RuntimeError, match="not connected"):
+            await WebSocketClient("ws://example.test/s").send_bytes(b"\x00")
+
+    async def test_receive(self) -> None:
+        with pytest.raises(RuntimeError, match="not connected"):
+            await WebSocketClient("ws://example.test/s").receive()
+
+
+class TestSendDelegation:
+    """Connected sends reach the matching aiohttp call."""
+
+    async def test_send_json(self) -> None:
+        socket = AsyncMock(closed=False)
+        await _connected_client(socket).send_json({"a": 1})
+        socket.send_json.assert_awaited_once_with({"a": 1})
+
+    async def test_send_text(self) -> None:
+        socket = AsyncMock(closed=False)
+        await _connected_client(socket).send_text("hi")
+        socket.send_str.assert_awaited_once_with("hi")
+
+    async def test_send_bytes(self) -> None:
+        socket = AsyncMock(closed=False)
+        await _connected_client(socket).send_bytes(b"\x01")
+        socket.send_bytes.assert_awaited_once_with(b"\x01")
+
+
+class TestReceiveNormalization:
+    """Upstream frame types map onto the transport's own vocabulary."""
+
+    async def test_text(self) -> None:
+        socket = AsyncMock(closed=False)
+        socket.receive.return_value = _frame(aiohttp.WSMsgType.TEXT, "hello")
+        assert await _connected_client(socket).receive() == WebSocketMessage(
+            "text", "hello"
+        )
+
+    async def test_binary(self) -> None:
+        socket = AsyncMock(closed=False)
+        socket.receive.return_value = _frame(aiohttp.WSMsgType.BINARY, b"\x01\x02")
+        assert await _connected_client(socket).receive() == WebSocketMessage(
+            "bytes", b"\x01\x02"
+        )
+
+    @pytest.mark.parametrize(
+        "msg_type", [aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSED]
+    )
+    async def test_close_frames(self, msg_type: aiohttp.WSMsgType) -> None:
+        socket = AsyncMock(closed=False)
+        socket.receive.return_value = _frame(msg_type, None)
+        assert await _connected_client(socket).receive() == WebSocketMessage(
+            "close", None
+        )
+
+    async def test_error_stringifies_the_exception(self) -> None:
+        socket = AsyncMock(closed=False)
+        socket.receive.return_value = _frame(
+            aiohttp.WSMsgType.ERROR, ValueError("boom")
+        )
+        message = await _connected_client(socket).receive()
+        assert message.type == "error"
+        assert message.data == "boom"
+
+    async def test_control_frames_are_exposed_lowercased(self) -> None:
+        """Ping/pong are autoping'd, but callers can still see them."""
+        socket = AsyncMock(closed=False)
+        socket.receive.return_value = _frame(aiohttp.WSMsgType.PING, b"")
+        message = await _connected_client(socket).receive()
+        assert message.type == str(aiohttp.WSMsgType.PING).lower()
+        assert message.data == b""
+
+
+class TestConnectionLifecycle:
+    """__aenter__ owns the session, including when the handshake fails."""
+
+    async def test_aenter_connects_and_returns_self(self) -> None:
+        socket = AsyncMock(closed=False)
+        session = MagicMock()
+        session.ws_connect = AsyncMock(return_value=socket)
+        session.close = AsyncMock()
+
+        with patch(
+            "quadkit.http.websocket.aiohttp.ClientSession", return_value=session
+        ):
+            client = WebSocketClient(
+                "wss://example.test/s", headers={"X": "1"}, heartbeat=7.0
+            )
+            entered = await client.__aenter__()
+
+        assert entered is client
+        assert client._session is session
+        assert client._socket is socket
+        session.ws_connect.assert_awaited_once_with(
+            "wss://example.test/s",
+            headers={"X": "1"},
+            heartbeat=7.0,
+            autoping=True,
+        )
+        session.close.assert_not_awaited()
+
+    async def test_aenter_closes_the_session_when_the_handshake_fails(self) -> None:
+        """A failed connect must not leak the ClientSession it just opened."""
+        session = MagicMock()
+        session.ws_connect = AsyncMock(side_effect=OSError("refused"))
+        session.close = AsyncMock()
+
+        with patch(
+            "quadkit.http.websocket.aiohttp.ClientSession", return_value=session
+        ):
+            client = WebSocketClient("ws://example.test/s")
+            with pytest.raises(OSError, match="refused"):
+                await client.__aenter__()
+
+        session.close.assert_awaited_once()
+        assert client._session is None
+        assert client.closed is True
+
+    async def test_aexit_closes(self) -> None:
+        client = _connected_client(AsyncMock(closed=False))
+        client._session = MagicMock(close=AsyncMock())
+        await client.__aexit__(None, None, None)
+        assert client._socket is None
+        assert client._session is None
+
+
+class TestClose:
+    """close() is safe to call on an already-torn-down client."""
+
+    async def test_closes_open_socket_and_session(self) -> None:
+        socket = AsyncMock(closed=False)
+        session = MagicMock(close=AsyncMock())
+        client = _connected_client(socket)
+        client._session = session
+
+        await client.close()
+
+        socket.close.assert_awaited_once()
+        session.close.assert_awaited_once()
+        assert client._socket is None
+        assert client._session is None
+
+    async def test_skips_an_already_closed_socket(self) -> None:
+        socket = AsyncMock(closed=True)
+        client = _connected_client(socket)
+        await client.close()
+        socket.close.assert_not_awaited()
+
+    async def test_idempotent_on_a_fresh_client(self) -> None:
+        client = WebSocketClient("ws://example.test/s")
+        await client.close()
+        await client.close()
+        assert client.closed is True