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

svc_infra/webhooks/fastapi.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from fastapi import HTTPException, Request, status
+
+from .signing import verify, verify_any
+
+
+def require_signature(
+    secrets_provider: Callable[[], str | Sequence[str]],
+    *,
+    header_name: str = "X-Signature",
+):
+    async def _dep(request: Request):
+        sig = request.headers.get(header_name)
+        if not sig:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail="missing signature"
+            )
+        try:
+            body = await request.json()
+        except Exception:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid JSON body")
+        secrets = secrets_provider()
+        ok = False
+        if isinstance(secrets, str):
+            ok = verify(secrets, body, sig)
+        else:
+            ok = verify_any(secrets, body, sig)
+        if not ok:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid signature"
+            )
+        return body
+
+    return _dep

svc_infra/webhooks/router.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from svc_infra.db.outbox import InMemoryOutboxStore, OutboxStore
+
+from .service import InMemoryWebhookSubscriptions, WebhookService
+
+router = APIRouter(prefix="/_webhooks", tags=["webhooks"])
+
+
+def get_outbox() -> OutboxStore:
+    # For now expose an in-memory default. Apps can override via DI.
+    # In production, provide a proper store through dependency override.
+    return InMemoryOutboxStore()
+
+
+def get_subs() -> InMemoryWebhookSubscriptions:
+    return InMemoryWebhookSubscriptions()
+
+
+def get_service(
+    outbox: OutboxStore = Depends(get_outbox),
+    subs: InMemoryWebhookSubscriptions = Depends(get_subs),
+) -> WebhookService:
+    return WebhookService(outbox=outbox, subs=subs)
+
+
+@router.post("/subscriptions")
+def add_subscription(
+    body: dict[str, Any],
+    subs: InMemoryWebhookSubscriptions = Depends(get_subs),
+):
+    topic = body.get("topic")
+    url = body.get("url")
+    secret = body.get("secret")
+    if not topic or not url or not secret:
+        raise HTTPException(status_code=400, detail="Missing topic/url/secret")
+    subs.add(topic, url, secret)
+    return {"ok": True}
+
+
+@router.post("/test-fire")
+def test_fire(
+    body: dict[str, Any],
+    svc: WebhookService = Depends(get_service),
+):
+    topic = body.get("topic")
+    payload = body.get("payload") or {}
+    if not topic:
+        raise HTTPException(status_code=400, detail="Missing topic")
+    outbox_id = svc.publish(topic, payload)
+    return {"ok": True, "outbox_id": outbox_id}

svc_infra/webhooks/service.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from svc_infra.db.outbox import OutboxStore
+from svc_infra.webhooks.encryption import encrypt_secret
+
+
+@dataclass
+class WebhookSubscription:
+    topic: str
+    url: str
+    secret: str
+    id: str = field(default_factory=lambda: uuid4().hex)
+
+
+class InMemoryWebhookSubscriptions:
+    def __init__(self):
+        self._subs: dict[str, list[WebhookSubscription]] = {}
+
+    def add(self, topic: str, url: str, secret: str) -> None:
+        # Upsert semantics per (topic, url): if a subscription already exists
+        # for this topic and URL, rotate its secret instead of adding a new row.
+        # This mirrors typical real-world secret rotation flows where the
+        # endpoint remains the same but the signing secret changes.
+        lst = self._subs.setdefault(topic, [])
+        for sub in lst:
+            if sub.url == url:
+                sub.secret = secret
+                return
+        lst.append(WebhookSubscription(topic, url, secret))
+
+    def get_for_topic(self, topic: str) -> list[WebhookSubscription]:
+        return list(self._subs.get(topic, []))
+
+
+class WebhookService:
+    def __init__(self, outbox: OutboxStore, subs: InMemoryWebhookSubscriptions):
+        self._outbox = outbox
+        self._subs = subs
+
+    def publish(self, topic: str, payload: dict, *, version: int = 1) -> int:
+        created_at = datetime.now(UTC).isoformat()
+        base_event = {
+            "topic": topic,
+            "payload": payload,
+            "version": version,
+            "created_at": created_at,
+        }
+        # For each subscription, enqueue an outbox message with subscriber identity
+        last_id = 0
+        for sub in self._subs.get_for_topic(topic):
+            event = dict(base_event)
+            # Encrypt secret before storing in outbox for security
+            encrypted_secret = encrypt_secret(sub.secret)
+            msg_payload = {
+                "event": event,
+                "subscription": {
+                    "id": sub.id,
+                    "topic": sub.topic,
+                    "url": sub.url,
+                    "secret": encrypted_secret,
+                },
+            }
+            msg = self._outbox.enqueue(topic, msg_payload)
+            last_id = msg.id
+        return last_id

svc_infra/webhooks/signing.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+from collections.abc import 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,139 @@
+"""
+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,283 @@
+"""
+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 collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+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()