svc-infra 0.1.595__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/webhooks/signing.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+from typing import Dict, Iterable
+
+logger = logging.getLogger(__name__)
+
+
+def canonical_body(payload: Dict) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), sort_keys=True).encode()
+
+
+def sign(secret: str, payload: Dict) -> str:
+    body = canonical_body(payload)
+    return hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+
+
+def verify(secret: str, payload: Dict, signature: str) -> bool:
+    expected = sign(secret, payload)
+    try:
+        return hmac.compare_digest(expected, signature)
+    except Exception as e:
+        logger.warning("Webhook signature verification failed: %s", e)
+        return False
+
+
+def verify_any(secrets: Iterable[str], payload: Dict, signature: str) -> bool:
+    for s in secrets:
+        if verify(s, payload, signature):
+            return True
+    return False

svc_infra/websocket/__init__.py

@@ -0,0 +1,79 @@
+"""
+WebSocket infrastructure for svc-infra.
+
+Provides client and server-side WebSocket utilities.
+
+Quick Start (Client):
+    from svc_infra.websocket import websocket_client
+
+    async with websocket_client("wss://api.example.com") as ws:
+        await ws.send_json({"hello": "world"})
+        async for message in ws:
+            print(message)
+
+Quick Start (Server):
+    from fastapi import FastAPI, WebSocket
+    from svc_infra.websocket import add_websocket_manager
+
+    app = FastAPI()
+    manager = add_websocket_manager(app)
+
+    @app.websocket("/ws/{user_id}")
+    async def ws_endpoint(websocket: WebSocket, user_id: str):
+        await manager.connect(user_id, websocket)
+        try:
+            async for msg in websocket.iter_json():
+                await manager.broadcast(msg)
+        finally:
+            await manager.disconnect(user_id, websocket)
+
+Quick Start (Auth):
+    Use the dual router system for WebSocket authentication:
+
+    from svc_infra.api.fastapi.dual import ws_protected_router
+    from svc_infra.api.fastapi.auth.ws_security import WSIdentity
+
+    router = ws_protected_router()
+
+    @router.websocket("/ws")
+    async def ws_endpoint(websocket: WebSocket, user: WSIdentity):
+        await manager.connect(user.id, websocket)
+        ...
+"""
+
+from .add import add_websocket_manager, get_ws_manager
+from .client import WebSocketClient
+from .config import WebSocketConfig
+from .easy import easy_websocket_client, websocket_client
+from .exceptions import (
+    AuthenticationError,
+    ConnectionClosedError,
+    ConnectionFailedError,
+    MessageTooLargeError,
+    WebSocketError,
+)
+from .manager import ConnectionManager
+from .models import ConnectionInfo, ConnectionState, WebSocketMessage
+
+__all__ = [
+    # Main API (simple)
+    "websocket_client",
+    "add_websocket_manager",
+    "get_ws_manager",
+    # Core classes (when you need more control)
+    "WebSocketClient",
+    "ConnectionManager",
+    "WebSocketConfig",
+    # Models
+    "ConnectionState",
+    "WebSocketMessage",
+    "ConnectionInfo",
+    # Exceptions
+    "WebSocketError",
+    "ConnectionClosedError",
+    "ConnectionFailedError",
+    "AuthenticationError",
+    "MessageTooLargeError",
+    # Backward compat
+    "easy_websocket_client",
+]

svc_infra/websocket/add.py

@@ -0,0 +1,140 @@
+"""
+FastAPI integration for WebSocket infrastructure.
+
+Provides:
+- add_websocket_manager: Add a connection manager to a FastAPI app
+- get_ws_manager: Dependency to retrieve the manager
+
+Example:
+    from fastapi import FastAPI, WebSocket, Depends
+    from svc_infra.websocket import add_websocket_manager, get_ws_manager, ConnectionManager
+
+    app = FastAPI()
+    add_websocket_manager(app)
+
+    @app.websocket("/ws/{user_id}")
+    async def ws_endpoint(websocket: WebSocket, user_id: str):
+        manager = get_ws_manager(app)
+        await manager.connect(user_id, websocket)
+        try:
+            async for msg in websocket.iter_json():
+                await manager.broadcast(msg)
+        finally:
+            await manager.disconnect(user_id, websocket)
+
+    @app.get("/ws/stats")
+    async def ws_stats(manager: ConnectionManager = Depends(get_ws_manager)):
+        return {"connections": manager.connection_count}
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from .manager import ConnectionManager
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI, Request
+
+_WS_MANAGER_ATTR = "_svc_infra_ws_manager"
+
+
+def add_websocket_manager(
+    app: FastAPI,
+    manager: ConnectionManager | None = None,
+) -> ConnectionManager:
+    """
+    Add a WebSocket connection manager to a FastAPI app.
+
+    The manager is stored on app.state and can be retrieved via get_ws_manager().
+
+    Args:
+        app: FastAPI application instance
+        manager: Optional pre-configured ConnectionManager.
+                If not provided, a new one is created.
+
+    Returns:
+        The ConnectionManager instance (created or provided)
+
+    Example:
+        app = FastAPI()
+        manager = add_websocket_manager(app)
+
+        @app.websocket("/ws/{user_id}")
+        async def ws_endpoint(websocket: WebSocket, user_id: str):
+            await manager.connect(user_id, websocket)
+            try:
+                async for msg in websocket.iter_json():
+                    await manager.broadcast(msg)
+            finally:
+                await manager.disconnect(user_id, websocket)
+    """
+    if manager is None:
+        manager = ConnectionManager()
+
+    setattr(app.state, _WS_MANAGER_ATTR, manager)
+    return manager
+
+
+def get_ws_manager(app_or_request: FastAPI | Request) -> ConnectionManager:
+    """
+    Get the WebSocket manager from a FastAPI app or request.
+
+    Can be used as a FastAPI dependency or called directly.
+
+    Args:
+        app_or_request: Either a FastAPI app instance or a Request object
+
+    Returns:
+        The ConnectionManager instance
+
+    Raises:
+        RuntimeError: If no manager has been added to the app
+
+    Example (as dependency):
+        @app.get("/ws/stats")
+        async def ws_stats(manager: ConnectionManager = Depends(get_ws_manager)):
+            return {
+                "connections": manager.connection_count,
+                "users": manager.active_users,
+            }
+
+    Example (direct call):
+        @app.websocket("/ws/{user_id}")
+        async def ws_endpoint(websocket: WebSocket, user_id: str):
+            manager = get_ws_manager(websocket.app)
+            await manager.connect(user_id, websocket)
+    """
+    # Handle both FastAPI app and Request objects
+    if hasattr(app_or_request, "app"):
+        # It's a Request object
+        app = app_or_request.app
+    else:
+        # It's a FastAPI app
+        app = app_or_request
+
+    manager = getattr(app.state, _WS_MANAGER_ATTR, None)
+    if manager is None:
+        raise RuntimeError(
+            "WebSocket manager not found. "
+            "Did you forget to call add_websocket_manager(app)?"
+        )
+    return cast(ConnectionManager, manager)
+
+
+def get_ws_manager_dependency(request: Request) -> ConnectionManager:
+    """
+    FastAPI dependency to get the WebSocket manager.
+
+    This is an alternative to get_ws_manager that works directly as a Depends().
+
+    Example:
+        from fastapi import Depends
+
+        @app.get("/ws/stats")
+        async def ws_stats(
+            manager: ConnectionManager = Depends(get_ws_manager_dependency)
+        ):
+            return {"connections": manager.connection_count}
+    """
+    return get_ws_manager(request)

svc_infra/websocket/client.py

@@ -0,0 +1,282 @@
+"""
+WebSocket client for connecting to external services.
+
+Provides:
+- WebSocketClient: Async WebSocket client with context manager support
+- websocket_connect: Context manager/async iterator for connections
+
+Example:
+    from svc_infra.websocket import WebSocketClient
+
+    async with WebSocketClient("wss://api.example.com") as ws:
+        await ws.send_json({"type": "hello"})
+        async for message in ws:
+            print(message)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed, ConnectionClosedOK
+from websockets.typing import Subprotocol
+
+from .config import WebSocketConfig, get_default_config
+from .exceptions import ConnectionClosedError, ConnectionFailedError, WebSocketError
+
+if TYPE_CHECKING:
+    from websockets.asyncio.client import ClientConnection
+
+logger = logging.getLogger(__name__)
+
+
+class WebSocketClient:
+    """
+    Async WebSocket client for connecting to external services.
+
+    Features:
+    - Async context manager support
+    - Auto-reconnection with exponential backoff (via websocket_connect)
+    - Configurable ping/pong keepalive
+    - Send text, bytes, or JSON
+    - Async iterator for receiving messages
+
+    Example:
+        async with WebSocketClient("wss://api.example.com") as ws:
+            await ws.send_json({"type": "hello"})
+            async for message in ws:
+                print(message)
+
+    Args:
+        url: WebSocket URL (ws:// or wss://)
+        config: WebSocket configuration (timeouts, ping/pong, etc.)
+        headers: Additional HTTP headers for the handshake
+        subprotocols: List of subprotocols to negotiate
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        config: WebSocketConfig | None = None,
+        headers: dict[str, str] | None = None,
+        subprotocols: list[str] | None = None,
+    ):
+        self.url = url
+        self.config = config or get_default_config()
+        self.headers = headers or {}
+        self.subprotocols = subprotocols
+        self._connection: ClientConnection | None = None
+        self._closed = False
+
+    async def __aenter__(self) -> "WebSocketClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def connect(self) -> None:
+        """Establish WebSocket connection.
+
+        Raises:
+            ConnectionFailedError: If connection cannot be established
+        """
+        try:
+            # Cast subprotocols to Subprotocol type for type safety
+            subprotocols_typed: list[Subprotocol] | None = None
+            if self.subprotocols:
+                subprotocols_typed = [Subprotocol(s) for s in self.subprotocols]
+
+            self._connection = await connect(
+                self.url,
+                additional_headers=self.headers,
+                subprotocols=subprotocols_typed,
+                open_timeout=self.config.open_timeout,
+                ping_interval=self.config.ping_interval,
+                ping_timeout=self.config.ping_timeout,
+                close_timeout=self.config.close_timeout,
+                max_size=self.config.max_message_size,
+                max_queue=self.config.max_queue_size,
+            )
+            self._closed = False
+            logger.debug("Connected to %s", self.url)
+        except Exception as e:
+            raise ConnectionFailedError(f"Failed to connect to {self.url}: {e}") from e
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        """Close the connection gracefully.
+
+        Args:
+            code: WebSocket close code (default: 1000 = normal closure)
+            reason: Close reason message
+        """
+        if self._connection and not self._closed:
+            self._closed = True
+            try:
+                await self._connection.close(code=code, reason=reason)
+                logger.debug("Closed connection to %s", self.url)
+            except Exception as e:
+                logger.warning("Error closing connection to %s: %s", self.url, e)
+
+    async def send(self, data: str | bytes) -> None:
+        """Send text or binary message.
+
+        Args:
+            data: Message content (str for text, bytes for binary)
+
+        Raises:
+            WebSocketError: If not connected
+            ConnectionClosedError: If connection is closed
+        """
+        if not self._connection:
+            raise WebSocketError("Not connected")
+        try:
+            await self._connection.send(data)
+        except ConnectionClosedOK:
+            raise ConnectionClosedError(1000, "Normal closure")
+        except ConnectionClosed as e:
+            raise ConnectionClosedError(e.code, e.reason) from e
+
+    async def send_json(self, data: Any) -> None:
+        """Send JSON-serialized message.
+
+        Args:
+            data: Object to serialize and send
+
+        Raises:
+            WebSocketError: If not connected
+            ConnectionClosedError: If connection is closed
+            TypeError/ValueError: If data cannot be serialized
+        """
+        await self.send(json.dumps(data))
+
+    async def recv(self) -> str | bytes:
+        """Receive next message.
+
+        Returns:
+            Message content (str for text frames, bytes for binary)
+
+        Raises:
+            WebSocketError: If not connected
+            ConnectionClosedError: If connection is closed
+        """
+        if not self._connection:
+            raise WebSocketError("Not connected")
+        try:
+            result = await self._connection.recv()
+            return str(result) if isinstance(result, str) else bytes(result)
+        except ConnectionClosedOK:
+            raise ConnectionClosedError(1000, "Normal closure")
+        except ConnectionClosed as e:
+            raise ConnectionClosedError(e.code, e.reason) from e
+
+    async def recv_json(self) -> Any:
+        """Receive and parse JSON message.
+
+        Returns:
+            Parsed JSON object
+
+        Raises:
+            WebSocketError: If not connected
+            ConnectionClosedError: If connection is closed
+            json.JSONDecodeError: If message is not valid JSON
+        """
+        data = await self.recv()
+        if isinstance(data, bytes):
+            data = data.decode("utf-8")
+        return json.loads(data)
+
+    async def __aiter__(self) -> AsyncIterator[str | bytes]:
+        """Iterate over incoming messages until closed.
+
+        Yields:
+            Message content (str for text, bytes for binary)
+
+        Raises:
+            ConnectionClosedError: If connection is closed abnormally
+        """
+        if not self._connection:
+            raise WebSocketError("Not connected")
+        try:
+            async for message in self._connection:
+                yield message
+        except ConnectionClosedOK:
+            return
+        except ConnectionClosed as e:
+            raise ConnectionClosedError(e.code, e.reason) from e
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if connection is open."""
+        return self._connection is not None and not self._closed
+
+    @property
+    def latency(self) -> float:
+        """Connection latency in seconds (from ping/pong).
+
+        Returns 0.0 if not connected or no ping has been sent.
+        """
+        return self._connection.latency if self._connection else 0.0
+
+
+@asynccontextmanager
+async def websocket_connect(
+    url: str,
+    *,
+    config: WebSocketConfig | None = None,
+    headers: dict[str, str] | None = None,
+    auto_reconnect: bool = False,
+) -> AsyncIterator[WebSocketClient]:
+    """
+    Context manager for WebSocket connections.
+
+    Args:
+        url: WebSocket URL (ws:// or wss://)
+        config: WebSocket configuration
+        headers: Additional HTTP headers
+        auto_reconnect: If True, auto-reconnects on connection loss
+
+    Yields:
+        WebSocketClient instance
+
+    Example (simple):
+        async with websocket_connect("wss://api.example.com") as ws:
+            await ws.send_json({"hello": "world"})
+
+    Example (with auto-reconnect):
+        # Note: with auto_reconnect=True, this becomes an async iterator
+        async for ws in websocket_connect(url, auto_reconnect=True):
+            try:
+                async for msg in ws:
+                    process(msg)
+            except ConnectionClosedError:
+                continue  # Will reconnect
+    """
+    if auto_reconnect:
+        # Use websockets' built-in reconnection iterator
+        cfg = config or get_default_config()
+        async for connection in connect(
+            url,
+            additional_headers=headers or {},
+            open_timeout=cfg.open_timeout,
+            ping_interval=cfg.ping_interval,
+            ping_timeout=cfg.ping_timeout,
+            close_timeout=cfg.close_timeout,
+            max_size=cfg.max_message_size,
+        ):
+            client = WebSocketClient(url, config=config, headers=headers)
+            client._connection = connection
+            client._closed = False
+            yield client
+    else:
+        client = WebSocketClient(url, config=config, headers=headers)
+        await client.connect()
+        try:
+            yield client
+        finally:
+            await client.close()

svc_infra/websocket/config.py

@@ -0,0 +1,69 @@
+"""
+WebSocket configuration with environment variable support.
+
+Environment Variables (WS_ prefix):
+    WS_OPEN_TIMEOUT: Connection timeout in seconds (default: 10.0)
+    WS_CLOSE_TIMEOUT: Close handshake timeout (default: 10.0)
+    WS_PING_INTERVAL: Keepalive ping interval, None to disable (default: 20.0)
+    WS_PING_TIMEOUT: Pong response timeout (default: 20.0)
+    WS_MAX_MESSAGE_SIZE: Max message size in bytes (default: 1048576 = 1MB)
+    WS_MAX_QUEUE_SIZE: Max queued messages (default: 16)
+    WS_RECONNECT_ENABLED: Enable auto-reconnection (default: true)
+    WS_RECONNECT_MAX_ATTEMPTS: Max reconnect attempts, 0=infinite (default: 5)
+    WS_RECONNECT_BACKOFF_BASE: Base backoff in seconds (default: 1.0)
+    WS_RECONNECT_BACKOFF_MAX: Max backoff in seconds (default: 60.0)
+    WS_RECONNECT_JITTER: Jitter factor 0-1 (default: 0.1)
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class WebSocketConfig(BaseSettings):
+    """WebSocket client configuration with environment variable support."""
+
+    model_config = SettingsConfigDict(env_prefix="WS_")
+
+    # Connection settings
+    open_timeout: float = Field(
+        default=10.0, description="Connection timeout in seconds"
+    )
+    close_timeout: float = Field(
+        default=10.0, description="Close handshake timeout in seconds"
+    )
+
+    # Keepalive (ping/pong)
+    ping_interval: float | None = Field(
+        default=20.0, description="Ping interval in seconds (None to disable)"
+    )
+    ping_timeout: float | None = Field(
+        default=20.0, description="Pong response timeout in seconds"
+    )
+
+    # Message limits
+    max_message_size: int = Field(
+        default=1_048_576, description="Max message size in bytes (1MB default)"
+    )
+    max_queue_size: int = Field(default=16, description="Max queued messages")
+
+    # Reconnection policy
+    reconnect_enabled: bool = Field(
+        default=True, description="Enable auto-reconnection"
+    )
+    reconnect_max_attempts: int = Field(
+        default=5, description="Max reconnect attempts (0=infinite)"
+    )
+    reconnect_backoff_base: float = Field(
+        default=1.0, description="Base backoff in seconds"
+    )
+    reconnect_backoff_max: float = Field(
+        default=60.0, description="Max backoff in seconds"
+    )
+    reconnect_jitter: float = Field(default=0.1, description="Jitter factor (0-1)")
+
+
+def get_default_config() -> WebSocketConfig:
+    """Load WebSocket config from environment with defaults."""
+    return WebSocketConfig()

svc_infra/websocket/easy.py

@@ -0,0 +1,76 @@
+"""
+Easy builders for WebSocket infrastructure.
+
+Provides simple factory functions with sensible defaults.
+
+Example:
+    from svc_infra.websocket import websocket_client
+
+    async with websocket_client("wss://api.openai.com/v1/realtime") as ws:
+        await ws.send_json({"type": "session.update"})
+        async for event in ws:
+            print(event)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import WebSocketClient
+from .config import WebSocketConfig, get_default_config
+
+
+def websocket_client(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    subprotocols: list[str] | None = None,
+    **config_overrides: Any,
+) -> WebSocketClient:
+    """
+    Create a WebSocket client with sensible defaults.
+
+    Config can be overridden via kwargs or WS_* environment variables.
+
+    Args:
+        url: WebSocket URL to connect to
+        headers: Optional headers to send with the connection
+        subprotocols: Optional list of subprotocols to negotiate
+        **config_overrides: Override any WebSocketConfig field
+
+    Returns:
+        WebSocketClient ready to be used as async context manager
+
+    Example:
+        async with websocket_client("wss://api.openai.com/v1/realtime") as ws:
+            await ws.send_json({"type": "session.update"})
+            async for event in ws:
+                print(event)
+
+        # With custom config
+        async with websocket_client(
+            "wss://...",
+            headers={"Authorization": "Bearer token"},
+            ping_interval=30,
+            max_message_size=16 * 1024 * 1024,  # 16MB for audio
+        ) as ws:
+            ...
+    """
+    config = get_default_config()
+
+    # Apply any overrides
+    if config_overrides:
+        config_dict = config.model_dump()
+        config_dict.update(config_overrides)
+        config = WebSocketConfig(**config_dict)
+
+    return WebSocketClient(
+        url,
+        config=config,
+        headers=headers,
+        subprotocols=subprotocols,
+    )
+
+
+# Backward compatibility alias
+easy_websocket_client = websocket_client