@lovrozagar/honey 0.6.8 → 0.7.1

package/dist/client-python/_sse.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import codecs
+from typing import AsyncIterator, Iterable, Iterator, TypedDict
+
+import httpx
+
+
+class SSEEvent(TypedDict, total=False):
+    data: str
+    event: str
+    id: str
+    retry: int
+
+
+DEFAULT_MAX_BUFFER = 1024 * 1024
+MAX_EVENT_DATA = 8 * 1024 * 1024
+
+
+class SSEParser:
+    """WHATWG event-stream parser.
+
+    Lines end in CRLF, LF or CR only (never U+2028 and friends, which
+    ``str.splitlines`` would also split on). A blank line dispatches the event;
+    a final event without its blank line is discarded; the id is sticky across
+    events; ``retry`` needs ASCII digits. Each chunk is scanned once.
+    """
+
+    def __init__(self, max_line: int = DEFAULT_MAX_BUFFER) -> None:
+        self._max_line = max_line
+        self._decoder = codecs.getincrementaldecoder("utf-8")("replace")
+        self._line: list[str] = []
+        self._line_len = 0
+        self._pending_cr = False
+        self._first = True
+        self._data: list[str] = []
+        self._data_len = 0
+        self._has_data = False
+        self._event: str | None = None
+        self._last_id: str | None = None
+        self._retry: int | None = None
+
+    def feed(self, chunk: bytes) -> Iterator[SSEEvent]:
+        yield from self._feed_text(self._decoder.decode(chunk))
+
+    def feed_text(self, text: str) -> Iterator[SSEEvent]:
+        yield from self._feed_text(text)
+
+    def _feed_text(self, text: str) -> Iterator[SSEEvent]:
+        start = 0
+        for i, ch in enumerate(text):
+            if i < start or (ch != "\r" and ch != "\n"):
+                continue
+            if ch == "\n" and self._pending_cr and i == start:
+                # LF completing a CRLF split across chunks
+                self._pending_cr = False
+                start = i + 1
+                continue
+            self._pending_cr = False
+            self._append(text[start:i])
+            line = "".join(self._line)
+            self._line = []
+            self._line_len = 0
+            if ch == "\r":
+                if i + 1 < len(text):
+                    if text[i + 1] == "\n":
+                        start = i + 2
+                        event = self._process(line)
+                        if event is not None:
+                            yield event
+                        continue
+                else:
+                    self._pending_cr = True
+            start = i + 1
+            event = self._process(line)
+            if event is not None:
+                yield event
+        if start < len(text):
+            self._pending_cr = False
+            self._append(text[start:])
+
+    def _append(self, part: str) -> None:
+        if not part:
+            return
+        self._line_len += len(part)
+        if self._line_len > self._max_line:
+            raise RuntimeError(f"SSE line exceeded {self._max_line} characters")
+        self._line.append(part)
+
+    def _process(self, line: str) -> SSEEvent | None:
+        if self._first:
+            self._first = False
+            if line.startswith("\ufeff"):
+                line = line[1:]
+        if line == "":
+            return self._dispatch()
+        if line.startswith(":"):
+            return None
+        name, sep, value = line.partition(":")
+        if sep and value.startswith(" "):
+            value = value[1:]
+        if name == "data":
+            self._data_len += len(value) + 1
+            if self._data_len > MAX_EVENT_DATA:
+                raise RuntimeError(f"SSE event exceeded {MAX_EVENT_DATA} characters")
+            self._data.append(value)
+            self._has_data = True
+        elif name == "event":
+            self._event = value
+        elif name == "id":
+            if "\0" not in value:
+                self._last_id = value
+        elif name == "retry":
+            if value and value.isascii() and value.isdigit():
+                self._retry = int(value)
+        return None
+
+    def _dispatch(self) -> SSEEvent | None:
+        event: SSEEvent | None = None
+        if self._has_data:
+            event = {"data": "\n".join(self._data)}
+            if self._event is not None:
+                event["event"] = self._event
+            if self._last_id is not None:
+                event["id"] = self._last_id
+            if self._retry is not None:
+                event["retry"] = self._retry
+        self._data = []
+        self._data_len = 0
+        self._has_data = False
+        self._event = None
+        self._retry = None
+        return event
+
+
+def parse_sse_text(chunks: Iterable[str]) -> list[SSEEvent]:
+    """Parse already-decoded text chunks; used by the conformance vectors."""
+    parser = SSEParser()
+    out: list[SSEEvent] = []
+    for chunk in chunks:
+        out.extend(parser.feed_text(chunk))
+    return out
+
+
+async def parse_sse_stream(
+    response: httpx.Response,
+    max_buffer_size: int = DEFAULT_MAX_BUFFER,
+) -> AsyncIterator[SSEEvent]:
+    parser = SSEParser(max_buffer_size)
+    async for chunk in response.aiter_bytes():
+        for event in parser.feed(chunk):
+            yield event
+
+
+__all__ = ["SSEEvent", "SSEParser", "parse_sse_stream", "parse_sse_text"]

package/dist/client-python/_transport.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Protocol, cast, 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:
+    """Options for each transport connect.
+
+    ``max_reconnect_attempts`` caps consecutive failed reconnects (0 or less:
+    unlimited); ``reconnect_delay_ms`` is the first backoff delay. ``headers``
+    are sent on every transport (the generated SDK fills in config headers and
+    auth). ``max_message_bytes`` caps one WebSocket message.
+    """
+
+    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
+    max_message_bytes: int = 16 * 1024 * 1024
+
+
+@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=cast(Any, subprotocols),
+            additional_headers=headers,
+            max_size=opts.max_message_bytes,
+        )
+        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
+        if not any(k.lower() == "x-request-id" for k in headers):
+            headers["x-request-id"] = str(uuid.uuid4())
+        client = self.http_client or httpx.AsyncClient()
+        owns_client = self.http_client is None
+        # a stream may idle between events: no read timeout
+        ctx = client.stream(
+            "GET",
+            url,
+            params=params or None,
+            headers=headers,
+            timeout=httpx.Timeout(30.0, read=None),
+        )
+        try:
+            response = await ctx.__aenter__()
+        except BaseException:
+            if owns_client:
+                await client.aclose()
+            raise
+        try:
+            response.raise_for_status()
+        except BaseException:
+            await ctx.__aexit__(None, None, None)
+            if owns_client:
+                await client.aclose()
+            raise
+        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/dist/client-python/_ws.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Callable, cast
+
+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
+        self._close_fired = False
+
+    async def __aenter__(self) -> _TypedWebSocket:
+        if websockets is None:
+            raise ImportError("pip install honey-sdk[ws] to use WebSocket methods")
+        self._conn = await _connect(self._url, self._protocols, self._extra_headers)
+        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()
+            self._fire_close(
+                self.close_code if self.close_code is not None else 1000,
+                self.close_reason if self.close_reason is not None else "",
+            )
+
+    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
+        except Exception as exc:
+            closed_ok = websockets is not None and isinstance(
+                exc, getattr(websockets.exceptions, "ConnectionClosedOK", ())
+            )
+            if not closed_ok:
+                for handler in self._handlers["error"]:
+                    try:
+                        handler(exc)
+                    except Exception:
+                        pass
+                raise
+        finally:
+            self._capture_close()
+            if self.close_code is not None:
+                self._fire_close(self.close_code, self.close_reason or "")
+
+    def _fire_close(self, code: int, reason: str) -> None:
+        if self._close_fired:
+            return
+        self._close_fired = True
+        for handler in self._handlers["close"]:
+            try:
+                handler(code, reason)
+            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: Any) -> None:
+        """Send str/bytes as-is; anything else (dict, list, numbers) as JSON text."""
+        if not isinstance(data, (str, bytes, bytearray)):
+            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)
+
+
+async def _connect(url: str, protocols: list[str], headers: dict[str, str]) -> Any:
+    """websockets >= 14 takes ``additional_headers``; older releases take
+    ``extra_headers``."""
+    assert websockets is not None
+    try:
+        return await websockets.connect(
+            url,
+            subprotocols=cast(Any, protocols or None),
+            additional_headers=headers or None,
+        )
+    except TypeError:
+        return await websockets.connect(
+            url,
+            subprotocols=cast(Any, protocols or None),
+            extra_headers=headers or None,
+        )
+
+
+__all__ = ["_TypedWebSocket"]