brutalsystems-realtime-client 0.1.0__tar.gz

brutalsystems_realtime_client-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.pytest_cache/
+dist/
+*.egg-info/

brutalsystems_realtime_client-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: brutalsystems-realtime-client
+Version: 0.1.0
+Summary: Python SDK for the realtime service — WebSocket subscriber + publisher and a generic JWT minter. `pip install brutalsystems-realtime-client`, then `import realtime_client`.
+Requires-Python: >=3.13
+Requires-Dist: brutalsystems-realtime-core==0.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=13

brutalsystems_realtime_client-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "brutalsystems-realtime-client"
+version = "0.1.0"
+description = "Python SDK for the realtime service — WebSocket subscriber + publisher and a generic JWT minter. `pip install brutalsystems-realtime-client`, then `import realtime_client`."
+requires-python = ">=3.13"
+dependencies = [
+    "brutalsystems-realtime-core==0.1.0",
+    "websockets>=13",
+    "httpx>=0.27",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["realtime_client"]

brutalsystems_realtime_client-0.1.0/realtime_client/__init__.py

@@ -0,0 +1,5 @@
+"""Python SDK for the realtime service."""
+from realtime_client.publisher import RealtimePublisher, rest_publish
+from realtime_client.subscriber import RealtimeSubscriber
+
+__all__ = ["RealtimeSubscriber", "RealtimePublisher", "rest_publish"]

brutalsystems_realtime_client-0.1.0/realtime_client/publisher.py

@@ -0,0 +1,140 @@
+# python/packages/realtime-client/realtime_client/publisher.py
+"""Realtime publisher.
+
+Best-effort background publisher ported from an internal best-effort publisher
+— KEEP the bounded queue with drop-oldest, the worker
+task, lazy reconnect with token re-mint, and the ping_interval keepalive.
+publish() never blocks the caller. `rest_publish` is a thin typed helper for
+the REST endpoint — a stand-in until openapi-python-client codegen lands."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import httpx
+
+from realtime_core import bearer_subprotocol, publish_frame
+
+logger = logging.getLogger(__name__)
+
+# websockets keepalive: ping every 20s so a dead socket surfaces promptly.
+_PING_INTERVAL = 20
+
+
+async def _default_connect(url: str, subprotocols: list[str]) -> Any:
+    import websockets
+
+    return await websockets.connect(
+        url, subprotocols=subprotocols or None, ping_interval=_PING_INTERVAL,
+    )
+
+
+class RealtimePublisher:
+    def __init__(
+        self, *, url: str, token_provider: Callable[[], str] | None = None,
+        max_queue_size: int = 1000,
+        _connect: Callable[[str, list[str]], Awaitable[Any]] = _default_connect,
+    ) -> None:
+        self._url = url
+        self._token_provider = token_provider
+        self._connect = _connect
+        self._queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=max_queue_size)
+        self._worker_task: asyncio.Task[Any] | None = None
+        self._stop = asyncio.Event()
+        self._ws: Any | None = None
+
+    async def __aenter__(self) -> RealtimePublisher:
+        await self.start()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.stop()
+
+    async def start(self) -> None:
+        self._stop.clear()
+        self._worker_task = asyncio.create_task(self._worker())
+
+    async def stop(self) -> None:
+        self._stop.set()
+        if self._worker_task is not None:
+            await self._worker_task
+            self._worker_task = None
+        if self._ws is not None:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    async def publish(self, channel: str, data: dict[str, Any], *, scope: str | None = None) -> None:
+        """Non-blocking enqueue. On a full queue, drop the OLDEST event."""
+        frame = publish_frame(channel, data, scope=scope)
+        try:
+            self._queue.put_nowait(frame)
+        except asyncio.QueueFull:
+            try:
+                self._queue.get_nowait()  # drop oldest
+            except asyncio.QueueEmpty:
+                pass
+            try:
+                self._queue.put_nowait(frame)
+            except asyncio.QueueFull:
+                logger.warning("realtime publish queue full; dropped event")
+
+    async def publish_event(
+        self, channel: str, event: str, payload: dict[str, Any], *, scope: str | None = None,
+    ) -> None:
+        """Convenience matching the prior internal publisher signature."""
+        await self.publish(channel, {"event": event, "payload": payload}, scope=scope)
+
+    async def _worker(self) -> None:
+        while not self._stop.is_set():
+            try:
+                frame = await asyncio.wait_for(self._queue.get(), timeout=0.5)
+            except TimeoutError:
+                continue
+            try:
+                await self._send_one(frame)
+            except Exception as exc:
+                # Best-effort: log + drop the socket; the next event reconnects
+                # (and re-mints the token) via _ensure_connected.
+                logger.warning("realtime publish failed: %s", exc)
+                if self._ws is not None:
+                    try:
+                        await self._ws.close()
+                    except Exception:
+                        pass
+                    self._ws = None
+
+    async def _ensure_connected(self) -> None:
+        if self._ws is not None:
+            return
+        subprotocols: list[str] = []
+        if self._token_provider is not None:
+            subprotocols = [bearer_subprotocol(self._token_provider())]
+        self._ws = await self._connect(self._url, subprotocols)
+
+    async def _send_one(self, frame: dict[str, Any]) -> None:
+        await self._ensure_connected()
+        assert self._ws is not None
+        await self._ws.send(json.dumps(frame))
+
+
+async def rest_publish(
+    base_url: str, channel: str, data: dict[str, Any], *,
+    token: str, client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    url = f"{base_url}/api/v1/channels/{channel}/messages"
+    headers = {"Authorization": f"Bearer {token}"}
+    owns = client is None
+    client = client or httpx.AsyncClient()
+    try:
+        resp = await client.post(url, json={"data": data}, headers=headers)
+        resp.raise_for_status()
+        return resp.json()
+    finally:
+        if owns:
+            await client.aclose()

brutalsystems_realtime_client-0.1.0/realtime_client/subscriber.py

@@ -0,0 +1,146 @@
+"""Realtime WebSocket subscriber.
+
+Single WS connection multiplexed across subscribe() calls; each subscribe()
+returns an async iterator filtered to its channel(s). Ported from an internal
+realtime client — KEEP the reconnect/backoff/resubscribe
+behavior and the eager subscribe() semantics. `_connect` is injectable for
+tests; the env-var names in from_env are generic (not service-specific)."""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+import websockets
+
+from realtime_core import (
+    EventFrame,
+    TokenMinter,
+    bearer_subprotocol,
+    parse_inbound,
+    subscribe_frame,
+)
+
+_BACKOFF_SECONDS = (0.1, 0.5, 1.0, 2.0, 5.0)
+
+
+async def _default_connect(url: str, subprotocols: list[str]) -> Any:
+    return await websockets.connect(url, subprotocols=subprotocols)
+
+
+class RealtimeSubscriber:
+    def __init__(
+        self, *, url: str, token_provider: Callable[[], str],
+        _connect: Callable[[str, list[str]], Awaitable[Any]] = _default_connect,
+    ) -> None:
+        self._url = url
+        self._token_provider = token_provider
+        self._connect = _connect
+        self._ws: Any | None = None
+        self._queues: dict[str, asyncio.Queue[EventFrame]] = {}
+        self._reader_task: asyncio.Task[Any] | None = None
+
+    @classmethod
+    def from_env(cls, *, owner_service: str, tenant_id: str = "_org") -> RealtimeSubscriber:
+        """Build a TokenMinter from generic env vars (REALTIME_URL,
+        REALTIME_JWT_ISSUER, REALTIME_JWT_PRIVATE_KEY). The names are generic
+        on purpose — a public SDK must not hardcode a single consumer's
+        identity; each consumer wires its own env (or passes an explicit
+        token_provider)."""
+        url = os.environ.get("REALTIME_URL")
+        issuer = os.environ.get("REALTIME_JWT_ISSUER")
+        private_key = os.environ.get("REALTIME_JWT_PRIVATE_KEY")
+        missing = [n for n, v in
+                   (("REALTIME_URL", url), ("REALTIME_JWT_ISSUER", issuer),
+                    ("REALTIME_JWT_PRIVATE_KEY", private_key)) if not v]
+        if missing:
+            raise RuntimeError(f"missing env vars for from_env: {', '.join(missing)}")
+        minter = TokenMinter(
+            private_key=private_key, issuer=issuer,
+            subject=owner_service, tenant_id=tenant_id,
+        )
+        return cls(url=url, token_provider=minter)
+
+    async def __aenter__(self) -> RealtimeSubscriber:
+        token = self._token_provider()
+        self._ws = await self._connect(self._url, [bearer_subprotocol(token)])
+        self._reader_task = asyncio.create_task(self._reader())
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        if self._reader_task is not None:
+            self._reader_task.cancel()
+            try:
+                await self._reader_task
+            except BaseException:
+                pass
+        if self._ws is not None:
+            await self._ws.close()
+
+    async def _reader(self) -> None:
+        backoff_idx = 0
+        while True:
+            try:
+                assert self._ws is not None
+                async for raw in self._ws:
+                    msg = json.loads(raw)
+                    evt = parse_inbound(msg)
+                    if evt is None:
+                        continue
+                    q = self._queues.get(evt.channel)
+                    if q is not None:
+                        await q.put(evt)
+                # remote closed cleanly — fall through to reconnect
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                pass
+
+            # reconnect path (ported verbatim)
+            delay = _BACKOFF_SECONDS[min(backoff_idx, len(_BACKOFF_SECONDS) - 1)]
+            backoff_idx += 1
+            if backoff_idx > 10:
+                return
+            await asyncio.sleep(delay)
+            new_ws = None
+            try:
+                token = self._token_provider()
+                new_ws = await self._connect(self._url, [bearer_subprotocol(token)])
+                for ch in list(self._queues.keys()):
+                    await new_ws.send(json.dumps(subscribe_frame(ch)))
+                self._ws = new_ws
+                backoff_idx = 0
+            except Exception:
+                if new_ws is not None:
+                    try:
+                        await new_ws.close()
+                    except BaseException:
+                        pass
+                continue
+
+    async def subscribe(self, channels: list[str]) -> AsyncIterator[EventFrame]:
+        """Register `channels` eagerly and return an async iterator over events.
+
+        EAGER: the queue is installed and the subscribe frame is sent before
+        this returns, so a caller can subscribe, trigger work, then iterate
+        without losing an event published in between. Must NOT be a lazy
+        generator (a generator body runs only on first __anext__, deferring
+        registration)."""
+        assert self._ws is not None
+        queue: asyncio.Queue[EventFrame] = asyncio.Queue()
+        for ch in channels:
+            self._queues[ch] = queue
+            await self._ws.send(json.dumps(subscribe_frame(ch)))
+        return self._drain(channels, queue)
+
+    async def _drain(
+        self, channels: list[str], queue: asyncio.Queue[EventFrame],
+    ) -> AsyncIterator[EventFrame]:
+        try:
+            while True:
+                yield await queue.get()
+        finally:
+            for ch in channels:
+                self._queues.pop(ch, None)