jambonz-python-sdk 0.2.0__py3-none-any.whl

jambonz_sdk/websocket/endpoint.py

@@ -0,0 +1,193 @@
+"""create_endpoint factory for WebSocket-based jambonz applications.
+
+Sets up a WebSocket server that handles both control (ws.jambonz.org)
+and audio (audio.drachtio.org) subprotocols.
+
+For env vars discovery (OPTIONS), a lightweight HTTP server runs alongside
+the WebSocket server on the same port using aiohttp, which hands off
+WebSocket upgrade requests to the websockets library.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import web
+
+from jambonz_sdk.websocket.client import WsClient
+from jambonz_sdk.websocket.router import WsRouter, _AudioService
+
+logger = logging.getLogger("jambonz_sdk.websocket.endpoint")
+
+
+class MakeService:
+    """Factory returned by ``create_endpoint`` for registering services.
+
+    Call this as a function to register control services, or use
+    ``.audio()`` to register audio services.
+    """
+
+    def __init__(self, router: WsRouter) -> None:
+        self._router = router
+
+    def __call__(self, *, path: str = "/") -> WsClient:
+        """Register a control WebSocket service at the given path.
+
+        Args:
+            path: URL path to listen on.
+
+        Returns:
+            A WsClient that emits ``'session:new'`` events.
+        """
+        client = WsClient(path)
+        self._router.use(path, client)
+        return client
+
+    def audio(self, *, path: str) -> _AudioService:
+        """Register an audio WebSocket service at the given path.
+
+        Args:
+            path: URL path for the audio WebSocket.
+
+        Returns:
+            An audio service that emits ``'connection'`` events with AudioStream.
+        """
+        return self._router.use_audio(path)
+
+
+async def create_endpoint(
+    *,
+    host: str = "0.0.0.0",
+    port: int = 3000,
+    env_vars: dict[str, dict[str, Any]] | None = None,
+    logger_: logging.Logger | None = None,
+) -> tuple[MakeService, web.AppRunner]:
+    """Create a WebSocket endpoint for jambonz applications.
+
+    Starts an HTTP + WebSocket server that handles:
+    - OPTIONS requests for env vars discovery
+    - WebSocket upgrades for jambonz control (ws.jambonz.org) and audio
+      (audio.drachtio.org) subprotocols
+
+    Args:
+        host: Bind address (default ``"0.0.0.0"``).
+        port: Bind port (default ``3000``).
+        env_vars: Application environment variable schema for portal discovery.
+        logger_: Optional logger instance.
+
+    Returns:
+        A tuple of ``(make_service, runner)`` where ``make_service`` is used
+        to register services and ``runner`` is the aiohttp AppRunner.
+
+    Example::
+
+        make_service, runner = await create_endpoint(port=3000)
+        svc = make_service(path="/")
+
+        svc.on("session:new", handle_session)
+
+        # Server is running; to stop:
+        await runner.cleanup()
+    """
+    log = logger_ or logger
+    router = WsRouter()
+    make_service = MakeService(router)
+
+    app = web.Application()
+
+    async def handle_options(request: web.Request) -> web.Response:
+        """Respond to OPTIONS with env_vars schema for portal discovery."""
+        if env_vars is not None:
+            return web.json_response({"env": env_vars})
+        return web.Response(status=200)
+
+    async def handle_websocket(request: web.Request) -> web.WebSocketResponse:
+        """Handle WebSocket upgrade and route to the appropriate service."""
+        # Determine subprotocol from the Sec-WebSocket-Protocol header
+        requested_protocols = request.headers.get("Sec-WebSocket-Protocol", "")
+        protocols = [p.strip() for p in requested_protocols.split(",") if p.strip()]
+
+        # Pick the best matching subprotocol
+        selected_protocol = None
+        for proto in ["audio.drachtio.org", "ws.jambonz.org"]:
+            if proto in protocols:
+                selected_protocol = proto
+                break
+
+        ws = web.WebSocketResponse(protocols=[selected_protocol] if selected_protocol else [])
+        await ws.prepare(request)
+
+        # Wrap aiohttp WS into an adapter that the router can use
+        adapter = _AiohttpWsAdapter(ws, request.path, selected_protocol)
+        await router.route(adapter)
+
+        return ws
+
+    # Register routes: OPTIONS on all paths, and WebSocket GET on all paths
+    app.router.add_route("OPTIONS", "/{path:.*}", handle_options)
+    app.router.add_route("GET", "/{path:.*}", handle_websocket)
+
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, host, port)
+    await site.start()
+
+    log.info("jambonz WebSocket endpoint listening on %s:%d", host, port)
+
+    return make_service, runner
+
+
+class _AiohttpWsAdapter:
+    """Adapts an aiohttp WebSocketResponse to the interface expected by WsClient/WsRouter.
+
+    The router and session code call ``ws.send()``, ``async for msg in ws:``,
+    ``ws.close()``, and access ``ws.request.path`` and ``ws.subprotocol``.
+    """
+
+    def __init__(self, ws: web.WebSocketResponse, path: str, subprotocol: str | None) -> None:
+        self._ws = ws
+        self._path = path
+        self._subprotocol = subprotocol
+
+    @property
+    def subprotocol(self) -> str | None:
+        return self._subprotocol
+
+    @property
+    def request(self) -> Any:
+        """Mimic websockets ServerConnection.request with a .path attribute."""
+        return _FakeRequest(self._path)
+
+    async def send(self, data: str | bytes) -> None:
+        if isinstance(data, bytes):
+            await self._ws.send_bytes(data)
+        else:
+            await self._ws.send_str(data)
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        await self._ws.close(code=code, message=reason.encode() if reason else b"")
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> str | bytes:
+        from aiohttp import WSMsgType
+
+        msg = await self._ws.receive()
+        if msg.type == WSMsgType.TEXT:
+            return msg.data
+        elif msg.type == WSMsgType.BINARY:
+            return msg.data
+        elif msg.type in (WSMsgType.CLOSE, WSMsgType.CLOSING, WSMsgType.CLOSED):
+            raise StopAsyncIteration
+        elif msg.type == WSMsgType.ERROR:
+            raise self._ws.exception() or ConnectionError("WebSocket error")
+        raise StopAsyncIteration
+
+
+class _FakeRequest:
+    """Minimal object with a .path attribute to satisfy router.route()."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path

jambonz_sdk/websocket/router.py

@@ -0,0 +1,87 @@
+"""WsRouter - path-based routing for multiple WebSocket services."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from jambonz_sdk.websocket.audio_stream import AudioStream
+from jambonz_sdk.websocket.client import WsClient
+
+logger = logging.getLogger("jambonz_sdk.websocket.router")
+
+
+class _AudioService:
+    """Manages audio WebSocket connections for a specific path."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self._handlers: dict[str, list] = {}
+
+    def on(self, event: str, handler: object) -> _AudioService:
+        if event not in self._handlers:
+            self._handlers[event] = []
+        self._handlers[event].append(handler)
+        return self
+
+    async def handle_connection(self, ws: Any) -> None:
+        stream = AudioStream(ws)
+        handlers = self._handlers.get("connection", [])
+        for handler in handlers:
+            result = handler(stream)
+            if asyncio.iscoroutine(result):
+                await result
+        await stream._run()
+
+
+class WsRouter:
+    """Routes incoming WebSocket connections to the appropriate service by path.
+
+    Supports both control (``ws.jambonz.org``) and audio (``audio.drachtio.org``)
+    WebSocket subprotocols.
+    """
+
+    def __init__(self) -> None:
+        self._services: dict[str, WsClient] = {}
+        self._audio_services: dict[str, _AudioService] = {}
+
+    def use(self, path: str, client: WsClient) -> None:
+        """Register a control service for a path."""
+        self._services[path] = client
+
+    def use_audio(self, path: str) -> _AudioService:
+        """Register an audio service for a path.
+
+        Returns an _AudioService that emits ``'connection'`` events with
+        an AudioStream instance.
+        """
+        svc = _AudioService(path)
+        self._audio_services[path] = svc
+        return svc
+
+    async def route(self, ws: Any) -> None:
+        """Route a WebSocket connection to the appropriate service.
+
+        Called by the WebSocket server for each new connection.
+        """
+        path = ws.request.path if ws.request else "/"
+
+        # Check subprotocol to determine if this is audio or control
+        subprotocol = ws.subprotocol
+
+        if subprotocol == "audio.drachtio.org":
+            svc = self._audio_services.get(path)
+            if svc:
+                await svc.handle_connection(ws)
+            else:
+                logger.warning("No audio service for path: %s", path)
+                await ws.close(4004, "No audio service for path")
+        else:
+            # Default to control protocol
+            svc_ctrl = self._services.get(path)
+            if svc_ctrl:
+                await svc_ctrl.handle_connection(ws)
+            else:
+                logger.warning("No service for path: %s", path)
+                await ws.close(4004, "No service for path")

jambonz_sdk/websocket/session.py

@@ -0,0 +1,259 @@
+"""WebSocket Session class representing a single call.
+
+A Session is created for each incoming call over a persistent WebSocket
+connection. It extends VerbBuilder with send/reply semantics and event
+handling for actionHook callbacks.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from jambonz_sdk.verb_builder import VerbBuilder
+
+logger = logging.getLogger("jambonz_sdk.websocket.session")
+
+EventHandler = Callable[..., Any]
+
+
+class Session(VerbBuilder):
+    """Represents a single call session over WebSocket.
+
+    Provides verb building (inherited from VerbBuilder), message sending,
+    and event-based actionHook handling.
+
+    Attributes:
+        call_sid: Unique call identifier.
+        account_sid: Account identifier.
+        application_sid: Application identifier.
+        direction: Call direction ("inbound" or "outbound").
+        from_: Caller phone number or SIP URI.
+        to: Called phone number or SIP URI.
+        call_id: SIP Call-ID.
+        data: Full session data from session:new message.
+        locals: Application-local storage dict for the session.
+    """
+
+    def __init__(
+        self,
+        ws: Any,
+        data: dict[str, Any],
+        msgid: str,
+    ) -> None:
+        super().__init__()
+        self._ws = ws
+        self._msgid = msgid
+        self._handlers: dict[str, list[EventHandler]] = {}
+
+        # Extract call properties from session data
+        self.data = data
+        self.call_sid: str = data.get("call_sid", "")
+        self.account_sid: str = data.get("account_sid", "")
+        self.application_sid: str = data.get("application_sid", "")
+        self.direction: str = data.get("direction", "")
+        self.from_: str = data.get("from", "")
+        self.to: str = data.get("to", "")
+        self.call_id: str = data.get("call_id", "")
+        self.b3: str = data.get("b3", "")
+        self.locals: dict[str, Any] = {}
+
+    def on(self, event: str, handler: EventHandler) -> Session:
+        """Register an event handler for an actionHook or lifecycle event.
+
+        Args:
+            event: Event name (e.g., ``'/gather-result'``, ``'close'``, ``'error'``).
+            handler: Callback function to invoke when the event fires.
+
+        Returns:
+            self for chaining.
+        """
+        if event not in self._handlers:
+            self._handlers[event] = []
+        self._handlers[event].append(handler)
+        return self
+
+    def _emit(self, event: str, *args: Any) -> bool:
+        """Emit an event to registered handlers.
+
+        Returns True if any handler was called.
+        """
+        handlers = self._handlers.get(event, [])
+        for handler in handlers:
+            handler(*args)
+        return bool(handlers)
+
+    async def _emit_async(self, event: str, *args: Any) -> bool:
+        """Emit an event, awaiting async handlers.
+
+        Returns True if any handler was called.
+        """
+        import asyncio
+
+        handlers = self._handlers.get(event, [])
+        for handler in handlers:
+            result = handler(*args)
+            if asyncio.iscoroutine(result):
+                await result
+        return bool(handlers)
+
+    async def send(self, **opts: Any) -> None:
+        """Send the initial verb array (response to session:new).
+
+        This should be called exactly once per session, after building
+        the initial verb chain. Use ``.reply()`` for all subsequent
+        responses (actionHook events).
+        """
+        verbs = self.to_list()
+        msg = {
+            "type": "ack",
+            "msgid": self._msgid,
+            "data": verbs,
+        }
+        if opts:
+            msg.update(opts)
+        await self._ws.send(json.dumps(msg))
+
+    async def reply(self, **opts: Any) -> None:
+        """Reply to an actionHook event with the next verb array.
+
+        Must be called after receiving a verb:hook event. Uses the
+        most recently received message ID for correlation.
+        """
+        verbs = self.to_list()
+        msg = {
+            "type": "ack",
+            "msgid": self._msgid,
+            "data": verbs,
+        }
+        if opts:
+            msg.update(opts)
+        await self._ws.send(json.dumps(msg))
+
+    def _update_msgid(self, msgid: str) -> None:
+        """Update the current message ID for reply correlation."""
+        self._msgid = msgid
+
+    # ── Inject Commands ─────────────────────────────────────────────
+
+    async def inject_command(self, command: str, data: dict[str, Any] | None = None) -> None:
+        """Send an immediate command (bypasses verb queue)."""
+        msg: dict[str, Any] = {"type": "command", "command": command}
+        if data:
+            msg["data"] = data
+        await self._ws.send(json.dumps(msg))
+
+    async def inject_record(self, action: str, data: dict[str, Any] | None = None) -> None:
+        """Control call recording.
+
+        Args:
+            action: One of 'startCallRecording', 'stopCallRecording',
+                'pauseCallRecording', 'resumeCallRecording'.
+            data: Additional recording options (e.g., siprecServerURL).
+        """
+        cmd_data: dict[str, Any] = {"action": action}
+        if data:
+            cmd_data.update(data)
+        await self.inject_command("record", cmd_data)
+
+    async def inject_whisper(self, verb: dict[str, Any]) -> None:
+        """Inject a whisper verb (say/play) to one party."""
+        await self.inject_command("whisper", {"whisper": verb})
+
+    async def inject_mute(self, status: str) -> None:
+        """Mute or unmute the call.
+
+        Args:
+            status: ``'mute'`` or ``'unmute'``.
+        """
+        await self.inject_command("mute", {"mute_status": status})
+
+    async def inject_listen_status(self, status: str) -> None:
+        """Pause or resume audio streaming.
+
+        Args:
+            status: ``'pause'`` or ``'resume'``.
+        """
+        await self.inject_command("listen:status", {"listen_status": status})
+
+    async def inject_noise_isolation(
+        self, status: str, opts: dict[str, Any] | None = None
+    ) -> None:
+        """Enable or disable noise isolation.
+
+        Args:
+            status: ``'on'`` or ``'off'``.
+            opts: Additional options (vendor, level, etc.).
+        """
+        data: dict[str, Any] = {"noiseIsolation_status": status}
+        if opts:
+            data.update(opts)
+        await self.inject_command("noiseIsolation:status", data)
+
+    async def inject_dtmf(self, dtmf: str) -> None:
+        """Send DTMF digits."""
+        await self.inject_command("dtmf", {"dtmf": dtmf})
+
+    async def inject_tag(self, data: dict[str, Any]) -> None:
+        """Attach metadata to the call."""
+        await self.inject_command("tag", data)
+
+    async def inject_redirect(self, hook: str) -> None:
+        """Redirect the call to a new webhook."""
+        await self.inject_command("redirect", {"call_hook": hook})
+
+    # ── TTS Token Streaming ─────────────────────────────────────────
+
+    async def send_tts_tokens(self, text: str, **opts: Any) -> None:
+        """Stream TTS text tokens for incremental synthesis."""
+        msg: dict[str, Any] = {"type": "tts:tokens", "data": {"tokens": text}}
+        if opts:
+            msg["data"].update(opts)
+        await self._ws.send(json.dumps(msg))
+
+    async def flush_tts_tokens(self, **opts: Any) -> None:
+        """Signal end of a TTS token stream."""
+        msg: dict[str, Any] = {"type": "tts:flush", "data": {}}
+        if opts:
+            msg["data"].update(opts)
+        await self._ws.send(json.dumps(msg))
+
+    async def clear_tts_tokens(self) -> None:
+        """Clear pending TTS tokens."""
+        await self._ws.send(json.dumps({"type": "tts:clear", "data": {}}))
+
+    # ── LLM Tool Output ────────────────────────────────────────────
+
+    async def tool_output(self, tool_call_id: str, result: Any) -> Session:
+        """Return a tool call result to the pipeline LLM.
+
+        Args:
+            tool_call_id: The tool_call_id from the llm:tool-call event.
+            result: The tool result (will be JSON-serialized).
+
+        Returns:
+            self for chaining with .reply().
+        """
+        msg = {
+            "type": "llm:tool-output",
+            "data": {
+                "tool_call_id": tool_call_id,
+                "output": result,
+            },
+        }
+        await self._ws.send(json.dumps(msg))
+        return self
+
+    # ── Pipeline Updates ────────────────────────────────────────────
+
+    async def update_pipeline(self, data: dict[str, Any]) -> None:
+        """Send a mid-conversation pipeline update.
+
+        Args:
+            data: Update payload with ``type`` key (e.g., 'update_instructions',
+                'inject_context', 'update_tools', 'generate_reply').
+        """
+        msg = {"type": "pipeline:update", "data": data}
+        await self._ws.send(json.dumps(msg))