@lovrozagar/honey 0.1.0

package/src/client-python/_sse.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import re
+from typing import AsyncIterator, TypedDict
+
+import httpx
+
+
+class SSEEvent(TypedDict, total=False):
+    data: str
+    event: str
+    id: str
+    retry: int
+
+
+def _parse_sse_block(block: str) -> SSEEvent | None:
+    lines = block.splitlines()
+    is_comment = True
+    data: str | None = None
+    event: str | None = None
+    id_val: str | None = None
+    retry: int | None = None
+
+    for line in lines:
+        if line.startswith(":"):
+            continue
+        is_comment = False
+        colon_idx = line.find(":")
+        if colon_idx == -1:
+            field_name = line
+            val = ""
+        else:
+            field_name = line[:colon_idx]
+            val = line[colon_idx + 1:]
+            if val.startswith(" "):
+                val = val[1:]
+
+        if field_name == "data":
+            data = val if data is None else f"{data}\n{val}"
+        elif field_name == "event":
+            event = val
+        elif field_name == "id":
+            # per SSE spec: id containing null byte must be ignored
+            if "\0" not in val:
+                id_val = val
+        elif field_name == "retry":
+            try:
+                n = int(val)
+                if n >= 0:
+                    retry = n
+            except ValueError:
+                pass
+
+    if is_comment or data is None:
+        return None
+
+    result: SSEEvent = {"data": data}
+    if event is not None:
+        result["event"] = event
+    if id_val is not None:
+        result["id"] = id_val
+    if retry is not None:
+        result["retry"] = retry
+    return result
+
+
+DEFAULT_MAX_BUFFER = 1024 * 1024
+
+_SSE_BLOCK_RE = re.compile(r"\r\n\r\n|\r\n\r|\r\n\n|\r\r\n|\n\r\n|\n\r|\r\r|\n\n")
+
+
+async def parse_sse_stream(
+    response: httpx.Response,
+    max_buffer_size: int = DEFAULT_MAX_BUFFER,
+) -> AsyncIterator[SSEEvent]:
+    buffer = ""
+    async for chunk in response.aiter_text():
+        buffer += chunk
+        if len(buffer) > max_buffer_size:
+            raise RuntimeError(f"SSE buffer exceeded {max_buffer_size} characters")
+
+        # split on double-newline (any combo of \r\n, \r, \n)
+        blocks = _SSE_BLOCK_RE.split(buffer)
+        buffer = blocks.pop()
+
+        for block in blocks:
+            if not block.strip():
+                continue
+            event = _parse_sse_block(block)
+            if event is not None:
+                yield event
+
+    if buffer.strip():
+        event = _parse_sse_block(buffer)
+        if event is not None:
+            yield event
+
+
+__all__ = ["SSEEvent", "parse_sse_stream"]

package/src/client-python/_transport.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Protocol, runtime_checkable
+from urllib.parse import urlencode
+
+try:
+    import websockets
+except ImportError:
+    websockets = None  # type: ignore[assignment]
+
+try:
+    import httpx
+except ImportError:
+    httpx = None  # type: ignore[assignment]
+
+from ._sse import parse_sse_stream
+
+
+class TransportKind(str, Enum):
+    WS = "ws"
+    SSE = "sse"
+    LONGPOLL = "longpoll"
+
+
+@dataclass
+class TransportOpts:
+    reconnect_token: str | None = None
+    last_event_id: str | None = None
+    headers: dict[str, str] | None = None
+    max_reconnect_attempts: int = 5
+    reconnect_delay_ms: int = 1000
+    protocols: list[str] | None = None
+
+
+@runtime_checkable
+class TransportConn(Protocol):
+    async def recv(self) -> Any: ...
+    async def send(self, data: Any) -> None: ...
+    async def close(self) -> None: ...
+    def kind(self) -> TransportKind: ...
+
+
+@runtime_checkable
+class TransportAdapter(Protocol):
+    def name(self) -> str: ...
+    def kind(self) -> TransportKind: ...
+    async def connect(self, url: str, opts: TransportOpts) -> TransportConn: ...
+
+
+class _StubConn:
+    """Shared stub retained from 8.b.2 for backward compat.
+
+    Real wire conns below (_WsConn/_SseConn/_LongpollConn) supersede it
+    inside the default adapters. Still importable for consumer-authored
+    tests that stub before the real impls landed.
+    """
+
+    def __init__(self, kind: TransportKind) -> None:
+        self._kind = kind
+
+    async def recv(self) -> Any:
+        raise NotImplementedError(
+            "_StubConn.recv is a placeholder; use WsAdapter/SseAdapter/LongpollAdapter",
+        )
+
+    async def send(self, data: Any) -> None:
+        raise NotImplementedError(
+            "_StubConn.send is a placeholder; use WsAdapter/SseAdapter/LongpollAdapter",
+        )
+
+    async def close(self) -> None:
+        return None
+
+    def kind(self) -> TransportKind:
+        return self._kind
+
+
+def _to_ws_url(url: str) -> str:
+    if url.startswith("https://"):
+        return "wss://" + url[len("https://"):]
+    if url.startswith("http://"):
+        return "ws://" + url[len("http://"):]
+    return url
+
+
+class _WsConn:
+    def __init__(self, conn: Any) -> None:
+        self._conn = conn
+
+    async def recv(self) -> Any:
+        msg = await self._conn.recv()
+        if isinstance(msg, (bytes, bytearray)):
+            msg = msg.decode("utf-8")
+        try:
+            return json.loads(msg)
+        except (ValueError, TypeError):
+            return msg
+
+    async def send(self, data: Any) -> None:
+        if isinstance(data, (str, bytes, bytearray)):
+            payload: Any = data
+        else:
+            payload = json.dumps(data)
+        await self._conn.send(payload)
+
+    async def close(self) -> None:
+        try:
+            await self._conn.close()
+        except Exception:
+            """ swallow — close must never raise """
+            pass
+
+    def kind(self) -> TransportKind:
+        return TransportKind.WS
+
+
+@dataclass
+class WsAdapter:
+    """Default WebSocket adapter using `websockets.connect`."""
+
+    subprotocols: list[str] = field(default_factory=list)
+
+    def name(self) -> str:
+        return "ws"
+
+    def kind(self) -> TransportKind:
+        return TransportKind.WS
+
+    async def connect(self, url: str, opts: TransportOpts) -> TransportConn:
+        if websockets is None:
+            raise RuntimeError(
+                "pip install websockets to use the default WsAdapter",
+            )
+        ws_url = _to_ws_url(url)
+        query: dict[str, str] = {}
+        if opts.reconnect_token is not None:
+            query["reconnect_token"] = opts.reconnect_token
+        if opts.last_event_id is not None:
+            query["last_event_id"] = opts.last_event_id
+        if query:
+            sep = "&" if "?" in ws_url else "?"
+            ws_url = f"{ws_url}{sep}{urlencode(query)}"
+        subprotocols = opts.protocols or (self.subprotocols or None)
+        headers = opts.headers or None
+        conn = await websockets.connect(
+            ws_url,
+            subprotocols=subprotocols,
+            additional_headers=headers,
+        )
+        return _WsConn(conn)
+
+
+class _SseConn:
+    def __init__(
+        self,
+        client: Any,
+        owns_client: bool,
+        ctx: Any,
+        response: Any,
+    ) -> None:
+        self._client = client
+        self._owns_client = owns_client
+        self._ctx = ctx
+        self._response = response
+        self._iter = parse_sse_stream(response)
+
+    async def recv(self) -> Any:
+        event = await self._iter.__anext__()
+        data = event.get("data")
+        if data is None:
+            return event
+        try:
+            return json.loads(data)
+        except (ValueError, TypeError):
+            return data
+
+    async def send(self, data: Any) -> None:
+        raise RuntimeError("SSE transport is receive-only")
+
+    async def close(self) -> None:
+        try:
+            await self._ctx.__aexit__(None, None, None)
+        except Exception:
+            pass
+        if self._owns_client:
+            try:
+                await self._client.aclose()
+            except Exception:
+                pass
+
+    def kind(self) -> TransportKind:
+        return TransportKind.SSE
+
+
+@dataclass
+class SseAdapter:
+    """Default SSE adapter using `httpx.AsyncClient.stream`."""
+
+    http_client: Any | None = None
+
+    def name(self) -> str:
+        return "sse"
+
+    def kind(self) -> TransportKind:
+        return TransportKind.SSE
+
+    async def connect(self, url: str, opts: TransportOpts) -> TransportConn:
+        if httpx is None:
+            raise RuntimeError(
+                "pip install httpx to use the default SseAdapter",
+            )
+        params: dict[str, str] = {}
+        if opts.reconnect_token is not None:
+            params["reconnect_token"] = opts.reconnect_token
+        headers = dict(opts.headers or {})
+        headers.setdefault("Accept", "text/event-stream")
+        if opts.last_event_id is not None:
+            headers["Last-Event-ID"] = opts.last_event_id
+        client = self.http_client or httpx.AsyncClient()
+        owns_client = self.http_client is None
+        ctx = client.stream(
+            "GET", url, params=params or None, headers=headers,
+        )
+        response = await ctx.__aenter__()
+        response.raise_for_status()
+        return _SseConn(
+            client=client, owns_client=owns_client,
+            ctx=ctx, response=response,
+        )
+
+
+class _LongpollConn:
+    def __init__(
+        self,
+        client: Any,
+        owns_client: bool,
+        url: str,
+        headers: dict[str, str],
+        reconnect_token: str | None,
+        last_event_id: str | None,
+    ) -> None:
+        self._client = client
+        self._owns_client = owns_client
+        self._url = url
+        self._headers = headers
+        self._reconnect_token = reconnect_token
+        self._last_event_id = last_event_id
+        self._closed = False
+
+    async def recv(self) -> Any:
+        if self._closed:
+            raise RuntimeError("longpoll connection closed")
+        params: dict[str, str] = {}
+        if self._reconnect_token is not None:
+            params["reconnect_token"] = self._reconnect_token
+        if self._last_event_id is not None:
+            params["last_event_id"] = self._last_event_id
+        resp = await self._client.get(
+            self._url,
+            headers=self._headers or None,
+            params=params or None,
+        )
+        resp.raise_for_status()
+        payload: Any
+        try:
+            payload = resp.json()
+        except Exception:
+            payload = resp.text
+        if isinstance(payload, dict):
+            new_token = payload.get("reconnect_token")
+            if isinstance(new_token, str):
+                self._reconnect_token = new_token
+            new_id = payload.get("id") or payload.get("last_event_id")
+            if isinstance(new_id, (str, int)):
+                self._last_event_id = str(new_id)
+        return payload
+
+    async def send(self, data: Any) -> None:
+        raise RuntimeError("longpoll transport is receive-only")
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._owns_client:
+            try:
+                await self._client.aclose()
+            except Exception:
+                pass
+
+    def kind(self) -> TransportKind:
+        return TransportKind.LONGPOLL
+
+
+@dataclass
+class LongpollAdapter:
+    """Default long-poll adapter using repeated `httpx.AsyncClient.get`."""
+
+    http_client: Any | None = None
+    poll_timeout: float = 30.0
+
+    def name(self) -> str:
+        return "longpoll"
+
+    def kind(self) -> TransportKind:
+        return TransportKind.LONGPOLL
+
+    async def connect(self, url: str, opts: TransportOpts) -> TransportConn:
+        if httpx is None:
+            raise RuntimeError(
+                "pip install httpx to use the default LongpollAdapter",
+            )
+        client = self.http_client or httpx.AsyncClient(timeout=self.poll_timeout)
+        owns_client = self.http_client is None
+        return _LongpollConn(
+            client=client,
+            owns_client=owns_client,
+            url=url,
+            headers=dict(opts.headers or {}),
+            reconnect_token=opts.reconnect_token,
+            last_event_id=opts.last_event_id,
+        )
+
+
+__all__ = [
+    "LongpollAdapter",
+    "SseAdapter",
+    "TransportAdapter",
+    "TransportConn",
+    "TransportKind",
+    "TransportOpts",
+    "WsAdapter",
+    "_StubConn",
+]

package/src/client-python/_ws.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Callable
+
+try:
+    import websockets
+except ImportError:
+    websockets = None  # type: ignore[assignment]
+
+_VALID_EVENTS = frozenset({"open", "close", "error", "message"})
+
+
+class _TypedWebSocket:
+    """Async context-manager wrapping a websockets connection.
+
+    Parity notes (Phase 10 WS audit):
+    - Remote close code + reason surfaced via close_code / close_reason after
+      __aexit__ or after the iterator terminates; also passed to "close"
+      handlers registered via .on().
+    - Auth handshake: caller passes query-string params (e.g. ?token=) to the
+      emitted method; server rejects via close frame which this class fires
+      as a "close" event plus sets close_code.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        protocols: list[str] | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        if websockets is None:
+            raise ImportError("pip install honey-sdk[ws] to use WebSocket methods")
+        self._url = url
+        self._protocols = protocols or []
+        self._extra_headers = extra_headers or {}
+        self._conn: Any = None
+        self._handlers: dict[str, list[Callable[..., Any]]] = {
+            "open": [],
+            "close": [],
+            "error": [],
+            "message": [],
+        }
+        self.close_code: int | None = None
+        self.close_reason: str | None = None
+
+    async def __aenter__(self) -> _TypedWebSocket:
+        if websockets is None:
+            raise ImportError("pip install honey-sdk[ws] to use WebSocket methods")
+        self._conn = await websockets.connect(
+            self._url,
+            subprotocols=self._protocols or None,
+            additional_headers=self._extra_headers or None,
+        )
+        for handler in self._handlers["open"]:
+            try:
+                handler()
+            except Exception:
+                pass
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if self._conn is not None:
+            try:
+                await self._conn.close()
+            except Exception:
+                pass
+            self._capture_close()
+            code = self.close_code if self.close_code is not None else 1000
+            reason = self.close_reason if self.close_reason is not None else ""
+            for handler in self._handlers["close"]:
+                try:
+                    handler(code, reason)
+                except Exception:
+                    pass
+
+    def __aiter__(self) -> AsyncIterator[str | bytes]:
+        return self._iter_messages()
+
+    async def _iter_messages(self) -> AsyncIterator[str | bytes]:
+        try:
+            async for msg in self._conn:
+                for handler in self._handlers["message"]:
+                    try:
+                        handler(msg)
+                    except Exception:
+                        pass
+                yield msg
+        finally:
+            self._capture_close()
+            code = self.close_code
+            reason = self.close_reason
+            if code is not None:
+                for handler in self._handlers["close"]:
+                    try:
+                        handler(code, reason or "")
+                    except Exception:
+                        pass
+
+    def _capture_close(self) -> None:
+        """Read close code/reason from the underlying websockets.Connection once
+        the peer sends a Close frame. websockets exposes these as attributes on
+        the connection object after the receive loop sees Close."""
+        if self._conn is None:
+            return
+        code = getattr(self._conn, "close_code", None)
+        reason = getattr(self._conn, "close_reason", None)
+        if code is not None and self.close_code is None:
+            self.close_code = int(code)
+        if reason is not None and self.close_reason is None:
+            self.close_reason = str(reason)
+
+    def on(self, event: str, callback: Callable[..., Any]) -> None:
+        """Register a callback for open, close, error, or message events."""
+        if event not in _VALID_EVENTS:
+            raise ValueError(
+                f"event must be one of {sorted(_VALID_EVENTS)}, got {event!r}",
+            )
+        self._handlers[event].append(callback)
+
+    async def send(self, data: str | bytes | dict[str, Any]) -> None:
+        if isinstance(data, dict):
+            data = json.dumps(data)
+        await self._conn.send(data)
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        if self._conn is not None:
+            await self._conn.close(code, reason)
+
+
+__all__ = ["_TypedWebSocket"]