roomkit 0.1.0__py3-none-any.whl

roomkit/realtime/memory.py

@@ -0,0 +1,158 @@
+"""In-memory realtime backend using asyncio queues."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections import OrderedDict
+from uuid import uuid4
+
+from roomkit.realtime.base import EphemeralCallback, EphemeralEvent, RealtimeBackend
+
+logger = logging.getLogger("roomkit.realtime")
+
+
+class InMemoryRealtime(RealtimeBackend):
+    """In-process realtime backend using asyncio queues.
+
+    Suitable for single-process deployments. For multi-process or
+    distributed setups, provide a custom ``RealtimeBackend`` backed by
+    Redis pub/sub, NATS, or similar.
+    """
+
+    def __init__(self, max_queue_size: int = 100) -> None:
+        """Initialize the in-memory realtime backend.
+
+        Args:
+            max_queue_size: Maximum number of events to queue per subscription.
+                Older events are dropped when the queue is full (LRU-style).
+        """
+        self._max_queue_size = max_queue_size
+        self._subscriptions: dict[str, _Subscription] = {}
+        self._channels: dict[str, set[str]] = {}  # channel -> subscription_ids
+        self._closed = False
+
+    async def publish(self, channel: str, event: EphemeralEvent) -> None:
+        """Publish an event to all subscribers on a channel."""
+        if self._closed:
+            return
+
+        sub_ids = self._channels.get(channel, set())
+        for sub_id in sub_ids:
+            sub = self._subscriptions.get(sub_id)
+            if sub is not None:
+                await sub.enqueue(event)
+
+    async def subscribe(self, channel: str, callback: EphemeralCallback) -> str:
+        """Subscribe to a channel with a callback.
+
+        Returns:
+            A subscription ID that can be used to unsubscribe.
+        """
+        sub_id = uuid4().hex
+        sub = _Subscription(
+            sub_id=sub_id,
+            channel=channel,
+            callback=callback,
+            max_queue_size=self._max_queue_size,
+        )
+        self._subscriptions[sub_id] = sub
+
+        if channel not in self._channels:
+            self._channels[channel] = set()
+        self._channels[channel].add(sub_id)
+
+        sub.start()
+        return sub_id
+
+    async def unsubscribe(self, subscription_id: str) -> bool:
+        """Unsubscribe and stop the subscription task.
+
+        Returns:
+            True if the subscription existed and was removed.
+        """
+        sub = self._subscriptions.pop(subscription_id, None)
+        if sub is None:
+            return False
+
+        channel_subs = self._channels.get(sub.channel)
+        if channel_subs:
+            channel_subs.discard(subscription_id)
+            if not channel_subs:
+                del self._channels[sub.channel]
+
+        await sub.stop()
+        return True
+
+    async def close(self) -> None:
+        """Stop all subscriptions and clean up."""
+        self._closed = True
+        for sub in list(self._subscriptions.values()):
+            await sub.stop()
+        self._subscriptions.clear()
+        self._channels.clear()
+
+    @property
+    def subscription_count(self) -> int:
+        """Return the number of active subscriptions."""
+        return len(self._subscriptions)
+
+
+class _Subscription:
+    """Internal subscription handler with queue and background task."""
+
+    def __init__(
+        self,
+        sub_id: str,
+        channel: str,
+        callback: EphemeralCallback,
+        max_queue_size: int,
+    ) -> None:
+        self.sub_id = sub_id
+        self.channel = channel
+        self.callback = callback
+        self._queue: OrderedDict[str, EphemeralEvent] = OrderedDict()
+        self._max_queue_size = max_queue_size
+        self._event = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+        self._stopped = False
+
+    async def enqueue(self, event: EphemeralEvent) -> None:
+        """Add an event to the queue, dropping oldest if full."""
+        if self._stopped:
+            return
+
+        # Drop oldest if at capacity (LRU-style)
+        while len(self._queue) >= self._max_queue_size:
+            self._queue.popitem(last=False)
+
+        self._queue[event.id] = event
+        self._event.set()
+
+    def start(self) -> None:
+        """Start the background task that drains the queue."""
+        self._task = asyncio.create_task(self._run())
+
+    async def stop(self) -> None:
+        """Stop the background task."""
+        self._stopped = True
+        self._event.set()
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+
+    async def _run(self) -> None:
+        """Background task that drains the queue and invokes callbacks."""
+        while not self._stopped:
+            await self._event.wait()
+            self._event.clear()
+
+            while self._queue and not self._stopped:
+                _, event = self._queue.popitem(last=False)
+                try:
+                    await self.callback(event)
+                except Exception:
+                    logger.exception("Error in realtime callback for subscription %s", self.sub_id)

roomkit/sources/__init__.py

@@ -0,0 +1,35 @@
+"""Event-driven message sources for RoomKit."""
+
+from typing import Any
+
+from roomkit.sources.base import (
+    BaseSourceProvider,
+    EmitCallback,
+    SourceHealth,
+    SourceProvider,
+    SourceStatus,
+)
+
+__all__ = [
+    "BaseSourceProvider",
+    "EmitCallback",
+    "SourceHealth",
+    "SourceProvider",
+    "SourceStatus",
+    # Lazy imports for optional sources
+    "WebSocketSource",
+    "default_json_parser",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for optional source providers."""
+    if name == "WebSocketSource":
+        from roomkit.sources.websocket import WebSocketSource
+
+        return WebSocketSource
+    if name == "default_json_parser":
+        from roomkit.sources.websocket import default_json_parser
+
+        return default_json_parser
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

roomkit/sources/base.py

@@ -0,0 +1,207 @@
+"""Base abstraction for event-driven message sources."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from enum import StrEnum, unique
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from roomkit.models.delivery import InboundMessage, InboundResult
+
+logger = logging.getLogger("roomkit.sources")
+
+
+@unique
+class SourceStatus(StrEnum):
+    """Connection status for an event source."""
+
+    STOPPED = "stopped"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    ERROR = "error"
+
+
+class SourceHealth(BaseModel):
+    """Health information for an event source."""
+
+    status: SourceStatus = SourceStatus.STOPPED
+    connected_at: datetime | None = None
+    last_message_at: datetime | None = None
+    messages_received: int = 0
+    error: str | None = None
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+
+# Type alias for the emit callback
+EmitCallback = Callable[["InboundMessage"], Awaitable["InboundResult"]]
+
+
+class SourceProvider(ABC):
+    """Base class for event-driven message sources.
+
+    A SourceProvider actively listens for inbound messages from an external
+    system (WebSocket, NATS, SSE, WhatsApp via neonize, etc.) and emits them
+    into RoomKit's inbound pipeline.
+
+    Unlike webhook-based providers that receive HTTP POST requests, source
+    providers maintain persistent connections and push messages as they arrive.
+
+    Lifecycle:
+        1. Create source instance with configuration
+        2. Call `start(emit)` - source connects and begins listening
+        3. Source calls `emit(message)` for each inbound message
+        4. Call `stop()` to disconnect and cleanup
+
+    Example:
+        class MyWebSocketSource(SourceProvider):
+            def __init__(self, url: str):
+                self._url = url
+                self._ws = None
+                self._status = SourceStatus.STOPPED
+
+            @property
+            def name(self) -> str:
+                return f"websocket:{self._url}"
+
+            async def start(self, emit: EmitCallback) -> None:
+                self._status = SourceStatus.CONNECTING
+                async with websockets.connect(self._url) as ws:
+                    self._ws = ws
+                    self._status = SourceStatus.CONNECTED
+                    async for message in ws:
+                        inbound = self._parse(message)
+                        await emit(inbound)
+
+            async def stop(self) -> None:
+                self._status = SourceStatus.STOPPED
+                if self._ws:
+                    await self._ws.close()
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for this source instance.
+
+        Used for logging and framework events. Should be descriptive,
+        e.g. "neonize:session.db" or "nats:events.inbound".
+        """
+        ...
+
+    @abstractmethod
+    async def start(self, emit: EmitCallback) -> None:
+        """Start receiving messages and emit them via the callback.
+
+        This method should:
+        1. Establish connection to the external system
+        2. Listen for incoming messages in a loop
+        3. Parse each message into an InboundMessage
+        4. Call `await emit(message)` for each message
+        5. Handle reconnection internally if the connection drops
+
+        The method should run until `stop()` is called or an unrecoverable
+        error occurs. For recoverable errors (network issues), implement
+        reconnection with backoff.
+
+        Args:
+            emit: Callback to emit messages into RoomKit. Returns InboundResult
+                  indicating whether the message was processed or blocked.
+        """
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop receiving messages and release resources.
+
+        This method should:
+        1. Signal the start() loop to exit
+        2. Close any open connections
+        3. Cancel any pending tasks
+        4. Release any held resources
+
+        After stop() returns, start() should be safe to call again.
+        """
+        ...
+
+    @property
+    def status(self) -> SourceStatus:
+        """Current connection status.
+
+        Subclasses should override this to return the actual status.
+        Default implementation returns STOPPED.
+        """
+        return SourceStatus.STOPPED
+
+    async def healthcheck(self) -> SourceHealth:
+        """Return health information for monitoring.
+
+        Subclasses should override this to provide detailed health info
+        including message counts, timestamps, and any error details.
+        """
+        return SourceHealth(status=self.status)
+
+
+class BaseSourceProvider(SourceProvider):
+    """Convenience base class with common source functionality.
+
+    Provides:
+    - Status tracking
+    - Message counting
+    - Timestamp tracking
+    - Stop signal via asyncio.Event
+    """
+
+    def __init__(self) -> None:
+        self._status = SourceStatus.STOPPED
+        self._connected_at: datetime | None = None
+        self._last_message_at: datetime | None = None
+        self._messages_received: int = 0
+        self._error: str | None = None
+        self._stop_event = asyncio.Event()
+
+    @property
+    def status(self) -> SourceStatus:
+        return self._status
+
+    async def healthcheck(self) -> SourceHealth:
+        return SourceHealth(
+            status=self._status,
+            connected_at=self._connected_at,
+            last_message_at=self._last_message_at,
+            messages_received=self._messages_received,
+            error=self._error,
+        )
+
+    def _set_status(self, status: SourceStatus, error: str | None = None) -> None:
+        """Update status and optionally set error message."""
+        self._status = status
+        self._error = error
+        if status == SourceStatus.CONNECTED:
+            self._connected_at = datetime.now(UTC)
+            self._error = None
+
+    def _record_message(self) -> None:
+        """Record that a message was received."""
+        self._messages_received += 1
+        self._last_message_at = datetime.now(UTC)
+
+    async def stop(self) -> None:
+        """Signal the source to stop."""
+        self._stop_event.set()
+        self._status = SourceStatus.STOPPED
+
+    def _should_stop(self) -> bool:
+        """Check if stop has been requested."""
+        return self._stop_event.is_set()
+
+    def _reset_stop(self) -> None:
+        """Reset stop signal for restart."""
+        self._stop_event.clear()

roomkit/sources/websocket.py

@@ -0,0 +1,260 @@
+"""WebSocket event source for RoomKit."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.event import TextContent
+from roomkit.sources.base import BaseSourceProvider, EmitCallback, SourceStatus
+
+# Optional dependency - import for type checking and availability check
+try:
+    import websockets
+    from websockets import ClientConnection
+
+    HAS_WEBSOCKETS = True
+except ImportError:
+    websockets = None  # type: ignore[assignment]
+    ClientConnection = None  # type: ignore[assignment, misc]
+    HAS_WEBSOCKETS = False
+
+logger = logging.getLogger("roomkit.sources.websocket")
+
+# Type alias for message parser
+MessageParser = Callable[[str | bytes], InboundMessage | None]
+
+
+def default_json_parser(channel_id: str) -> MessageParser:
+    """Create a default JSON message parser.
+
+    Expects messages in format:
+    {
+        "sender_id": "user123",
+        "text": "Hello world",
+        "external_id": "msg-456",  # optional
+        "metadata": {}             # optional
+    }
+
+    Args:
+        channel_id: Channel ID to use for parsed messages.
+
+    Returns:
+        A parser function that converts JSON to InboundMessage.
+    """
+
+    def parser(raw: str | bytes) -> InboundMessage | None:
+        try:
+            if isinstance(raw, bytes):
+                raw = raw.decode("utf-8")
+
+            data = json.loads(raw)
+
+            # Skip non-message events (e.g., pings, acks)
+            if not isinstance(data, dict):
+                return None
+            if "sender_id" not in data:
+                return None
+
+            return InboundMessage(
+                channel_id=channel_id,
+                sender_id=data["sender_id"],
+                content=TextContent(body=data.get("text", "")),
+                external_id=data.get("external_id"),
+                metadata=data.get("metadata", {}),
+            )
+        except (json.JSONDecodeError, KeyError, TypeError) as e:
+            logger.debug("Failed to parse message: %s", e)
+            return None
+
+    return parser
+
+
+class WebSocketSource(BaseSourceProvider):
+    """WebSocket client source for receiving messages.
+
+    Connects to a WebSocket server and emits parsed messages into RoomKit.
+    Handles reconnection automatically when the connection drops.
+
+    Example:
+        from roomkit import RoomKit
+        from roomkit.sources.websocket import WebSocketSource
+
+        # Simple usage with default JSON parser
+        source = WebSocketSource(
+            url="wss://chat.example.com/events",
+            channel_id="websocket-chat",
+        )
+        await kit.attach_source("websocket-chat", source)
+
+        # Custom parser for non-JSON messages
+        def my_parser(raw: str) -> InboundMessage | None:
+            parts = raw.split("|")
+            if len(parts) < 2:
+                return None
+            return InboundMessage(
+                channel_id="custom",
+                sender_id=parts[0],
+                content=TextContent(body=parts[1]),
+            )
+
+        source = WebSocketSource(
+            url="wss://custom.example.com/stream",
+            channel_id="custom",
+            parser=my_parser,
+        )
+    """
+
+    def __init__(
+        self,
+        url: str,
+        channel_id: str,
+        *,
+        parser: MessageParser | None = None,
+        headers: dict[str, str] | None = None,
+        subprotocols: list[str] | None = None,
+        ping_interval: float | None = 20.0,
+        ping_timeout: float | None = 20.0,
+        close_timeout: float = 10.0,
+        max_size: int = 2**20,  # 1 MB
+        origin: str | None = None,
+    ) -> None:
+        """Initialize WebSocket source.
+
+        Args:
+            url: WebSocket URL to connect to (ws:// or wss://).
+            channel_id: Channel ID for emitted messages.
+            parser: Function to parse raw messages into InboundMessage.
+                If None, uses default JSON parser.
+            headers: Additional HTTP headers for the connection.
+            subprotocols: WebSocket subprotocols to request.
+            ping_interval: Interval between ping frames in seconds.
+                Set to None to disable pings.
+            ping_timeout: Timeout for pong response in seconds.
+            close_timeout: Timeout for close handshake in seconds.
+            max_size: Maximum message size in bytes.
+            origin: Origin header value.
+        """
+        super().__init__()
+        self._url = url
+        self._channel_id = channel_id
+        self._parser = parser or default_json_parser(channel_id)
+        self._headers = headers or {}
+        self._subprotocols = subprotocols
+        self._ping_interval = ping_interval
+        self._ping_timeout = ping_timeout
+        self._close_timeout = close_timeout
+        self._max_size = max_size
+        self._origin = origin
+        self._ws: ClientConnection | None = None
+
+    @property
+    def name(self) -> str:
+        return f"websocket:{self._url}"
+
+    async def start(self, emit: EmitCallback) -> None:
+        """Connect and start receiving messages.
+
+        This method handles reconnection automatically using the websockets
+        library's built-in reconnection support.
+        """
+        if not HAS_WEBSOCKETS:
+            raise ImportError(
+                "websockets is required for WebSocketSource. "
+                "Install it with: pip install roomkit[websocket]"
+            )
+
+        self._reset_stop()
+        self._set_status(SourceStatus.CONNECTING)
+
+        # Build connection kwargs
+        connect_kwargs: dict[str, Any] = {
+            "uri": self._url,
+            "additional_headers": self._headers if self._headers else None,
+            "subprotocols": self._subprotocols,
+            "ping_interval": self._ping_interval,
+            "ping_timeout": self._ping_timeout,
+            "close_timeout": self._close_timeout,
+            "max_size": self._max_size,
+            "origin": self._origin,
+        }
+        # Remove None values
+        connect_kwargs = {k: v for k, v in connect_kwargs.items() if v is not None}
+
+        try:
+            async with websockets.connect(**connect_kwargs) as ws:
+                self._ws = ws
+                self._set_status(SourceStatus.CONNECTED)
+                logger.info("Connected to %s", self._url)
+
+                await self._receive_loop(ws, emit)
+
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            self._set_status(SourceStatus.ERROR, str(e))
+            raise
+
+    async def _receive_loop(
+        self,
+        ws: ClientConnection,
+        emit: EmitCallback,
+    ) -> None:
+        """Main receive loop - reads messages and emits them."""
+        while not self._should_stop():
+            try:
+                # Use wait_for to allow checking stop flag periodically
+                raw = await asyncio.wait_for(ws.recv(), timeout=1.0)
+
+                # Parse the message
+                message = self._parser(raw)
+                if message is not None:
+                    result = await emit(message)
+                    self._record_message()
+
+                    if result.blocked:
+                        logger.debug(
+                            "Message blocked: %s",
+                            result.reason,
+                        )
+
+            except TimeoutError:
+                # Normal timeout - check stop flag and continue
+                continue
+            except Exception:
+                # Connection error or other issue
+                if self._should_stop():
+                    break
+                raise
+
+    async def stop(self) -> None:
+        """Stop receiving and close the connection."""
+        await super().stop()
+
+        if self._ws is not None:
+            with contextlib.suppress(Exception):
+                await self._ws.close()
+            self._ws = None
+
+        logger.info("WebSocket source stopped")
+
+    async def send(self, message: str | bytes) -> None:
+        """Send a message through the WebSocket connection.
+
+        This allows bidirectional communication if needed.
+
+        Args:
+            message: Message to send (string or bytes).
+
+        Raises:
+            RuntimeError: If not connected.
+        """
+        if self._ws is None or self._status != SourceStatus.CONNECTED:
+            raise RuntimeError("WebSocket not connected")
+
+        await self._ws.send(message)