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

svc_infra/webhooks/__init__.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+from .add import add_webhooks
+from .encryption import decrypt_secret, encrypt_secret, is_encrypted
+
+__all__ = [
+    "add_webhooks",
+    "encrypt_secret",
+    "decrypt_secret",
+    "is_encrypted",
+    "trigger_webhook",
+]
+
+_logger = logging.getLogger(__name__)
+
+
+async def trigger_webhook(
+    event: str,
+    data: dict[str, Any],
+    *,
+    webhook_service: Any | None = None,
+) -> int | None:
+    """
+    Trigger a webhook event.
+
+    This is a convenience function for sending webhook events. It requires
+    that webhooks have been configured via add_webhooks() first.
+
+    Args:
+        event: The event/topic name (e.g., "goal.milestone_reached")
+        data: The event payload data
+        webhook_service: Optional WebhookService instance. If not provided,
+                         attempts to use the global service from add_webhooks.
+
+    Returns:
+        The outbox message ID if successful, None if no webhook service configured.
+
+    Example:
+        from svc_infra.webhooks import trigger_webhook
+
+        await trigger_webhook(
+            event="user.created",
+            data={"user_id": "123", "email": "user@example.com"}
+        )
+
+    Note:
+        For this to work, you must first configure webhooks:
+
+        from svc_infra.webhooks import add_webhooks
+        add_webhooks(app)
+    """
+    if webhook_service is None:
+        # Try to get the global webhook service from app state
+        _logger.warning(
+            "No webhook_service provided and no global service configured. "
+            "Call add_webhooks(app) first to enable webhook delivery."
+        )
+        return None
+
+    try:
+        msg_id = cast(int, webhook_service.publish(event, data))
+        _logger.info(f"Triggered webhook event '{event}' with message ID {msg_id}")
+        return msg_id
+    except Exception as e:
+        _logger.error(f"Failed to trigger webhook event '{event}': {e}")
+        return None

svc_infra/webhooks/add.py

@@ -0,0 +1,339 @@
+"""FastAPI integration helpers for the webhooks router.
+
+The :func:`add_webhooks` helper wires the public router into an app and makes
+sure dependency overrides share a single set of stores instead of the in-file
+defaults that create a new in-memory object per request.  Callers can:
+
+* rely on the in-memory defaults (suitable for tests / local usage);
+* configure persistent stores through environment variables; or
+* provide concrete instances / factories explicitly via keyword arguments.
+
+When queue / scheduler objects are provided the helper also wires up the
+standard outbox tick task and webhook delivery job handler so the caller only
+needs to start their existing worker loop.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections.abc import Callable, Iterable, Mapping
+from datetime import datetime, timezone
+from typing import Any, Protocol, TypeGuard, TypeVar, cast
+
+from fastapi import FastAPI
+
+from svc_infra.db.inbox import InboxStore, InMemoryInboxStore
+from svc_infra.db.outbox import InMemoryOutboxStore, OutboxMessage, OutboxStore
+from svc_infra.jobs.builtins.outbox_processor import make_outbox_tick
+from svc_infra.jobs.builtins.webhook_delivery import make_webhook_handler
+from svc_infra.jobs.queue import JobQueue
+from svc_infra.jobs.scheduler import InMemoryScheduler
+
+from . import router as router_module
+from .service import InMemoryWebhookSubscriptions
+
+try:  # Optional dependency – only required when redis backends are selected.
+    from redis import Redis
+except Exception:  # pragma: no cover - redis is optional in most test runs.
+    Redis = None  # type: ignore[misc,assignment]
+
+logger = logging.getLogger(__name__)
+
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+class _Factory(Protocol[T_co]):
+    def __call__(self) -> T_co:
+        pass
+
+
+class RedisOutboxStore(OutboxStore):
+    """Minimal Redis-backed outbox implementation used by :func:`add_webhooks`.
+
+    The implementation is intentionally lightweight – it keeps message payloads
+    in Redis hashes and a FIFO list of message identifiers.  It fulfils the
+    contract expected by :func:`make_outbox_tick` while remaining simple enough
+    for environments where a fully fledged SQL implementation is unavailable.
+    """
+
+    def __init__(self, client: "Redis", *, prefix: str = "webhooks:outbox"):
+        if Redis is None:  # pragma: no cover - defensive guard
+            raise RuntimeError("redis-py is required for RedisOutboxStore")
+        self._client = client
+        self._prefix = prefix.rstrip(":")
+
+    # Redis key helpers -------------------------------------------------
+    @property
+    def _seq_key(self) -> str:
+        return f"{self._prefix}:seq"
+
+    @property
+    def _queue_key(self) -> str:
+        return f"{self._prefix}:queue"
+
+    def _msg_key(self, msg_id: int) -> str:
+        return f"{self._prefix}:msg:{msg_id}"
+
+    # Protocol methods --------------------------------------------------
+    def enqueue(self, topic: str, payload: dict[str, Any]) -> OutboxMessage:
+        incr_result = cast(Any, self._client.incr(self._seq_key))
+        # Redis incr always returns an int for the sync client. Be defensive for mocks.
+        try:
+            msg_id = int(incr_result)
+        except (TypeError, ValueError):
+            msg_id = 0
+        created_at = datetime.now(timezone.utc)
+        record: dict[str, str] = {
+            "id": str(msg_id),
+            "topic": topic,
+            "payload": json.dumps(payload),
+            "created_at": created_at.isoformat(),
+            "attempts": "0",
+            "processed_at": "",
+        }
+        self._client.hset(self._msg_key(msg_id), mapping=record)
+        self._client.rpush(self._queue_key, msg_id)
+        return OutboxMessage(
+            id=msg_id, topic=topic, payload=payload, created_at=created_at
+        )
+
+    def fetch_next(self, topics: Iterable[str] | None = None) -> OutboxMessage | None:
+        allowed = set(topics) if topics else None
+        ids = cast(list[Any], self._client.lrange(self._queue_key, 0, -1))
+        for raw_id in ids:
+            raw_id_str = (
+                raw_id.decode()
+                if isinstance(raw_id, (bytes, bytearray))
+                else str(raw_id)
+            )
+            msg_id = int(raw_id_str)
+            msg = cast(dict[Any, Any], self._client.hgetall(self._msg_key(msg_id)))
+            if not msg:
+                continue
+            topic = msg.get(b"topic")
+            if topic is None:
+                continue
+            topic_str = (
+                topic.decode() if isinstance(topic, (bytes, bytearray)) else str(topic)
+            )
+            if allowed is not None and topic_str not in allowed:
+                continue
+            attempts = int(msg.get(b"attempts", 0))
+            processed_raw = msg.get(b"processed_at") or b""
+            if processed_raw:
+                continue
+            if attempts > 0:
+                continue
+            payload_raw = msg.get(b"payload") or b"{}"
+            payload_txt = (
+                payload_raw.decode()
+                if isinstance(payload_raw, (bytes, bytearray))
+                else str(payload_raw)
+            )
+            payload = json.loads(payload_txt)
+            created_raw = msg.get(b"created_at") or b""
+            created_at = (
+                datetime.fromisoformat(
+                    created_raw.decode()
+                    if isinstance(created_raw, (bytes, bytearray))
+                    else str(created_raw)
+                )
+                if created_raw
+                else datetime.now(timezone.utc)
+            )
+            return OutboxMessage(
+                id=msg_id,
+                topic=topic_str,
+                payload=payload,
+                created_at=created_at,
+                attempts=attempts,
+            )
+        return None
+
+    def mark_processed(self, msg_id: int) -> None:
+        key = self._msg_key(msg_id)
+        if not self._client.exists(key):
+            return
+        self._client.hset(key, "processed_at", datetime.now(timezone.utc).isoformat())
+
+    def mark_failed(self, msg_id: int) -> None:
+        key = self._msg_key(msg_id)
+        self._client.hincrby(key, "attempts", 1)
+
+
+class RedisInboxStore(InboxStore):
+    """Lightweight Redis dedupe store for webhook deliveries."""
+
+    def __init__(self, client: "Redis", *, prefix: str = "webhooks:inbox"):
+        if Redis is None:  # pragma: no cover - defensive guard
+            raise RuntimeError("redis-py is required for RedisInboxStore")
+        self._client = client
+        self._prefix = prefix.rstrip(":")
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}:{key}"
+
+    def mark_if_new(self, key: str, ttl_seconds: int = 24 * 3600) -> bool:
+        return bool(self._client.set(self._key(key), 1, nx=True, ex=ttl_seconds))
+
+    def purge_expired(self) -> int:
+        # Redis takes care of expirations. We return 0 to satisfy the interface.
+        return 0
+
+    def is_marked(self, key: str) -> bool:
+        return bool(self._client.exists(self._key(key)))
+
+
+def _is_factory(obj: Any) -> TypeGuard[Callable[[], Any]]:
+    return callable(obj) and not isinstance(obj, (str, bytes, bytearray))
+
+
+def _resolve_value(
+    value: T_co | _Factory[T_co] | None, default_factory: _Factory[T_co]
+) -> T_co:
+    if value is None:
+        return default_factory()
+    if _is_factory(value):
+        return cast(T_co, value())
+    return cast(T_co, value)
+
+
+def _build_redis_client(env: Mapping[str, str]) -> "Redis" | None:
+    if Redis is None:
+        logger.warning(
+            "Redis backend requested but redis-py is not installed; falling back to in-memory stores"
+        )
+        return None
+    url = env.get("REDIS_URL", "redis://localhost:6379/0")
+    return Redis.from_url(url)
+
+
+def _default_outbox(env: Mapping[str, str]) -> OutboxStore:
+    backend = (env.get("WEBHOOKS_OUTBOX") or "memory").lower()
+    if backend == "redis":
+        client = _build_redis_client(env)
+        if client is not None:
+            logger.info("Using Redis outbox store for webhooks")
+            return RedisOutboxStore(client)
+    elif backend == "sql":  # pragma: no cover - SQL backend is currently a placeholder
+        logger.warning(
+            "WEBHOOKS_OUTBOX=sql specified but SQL backend is not implemented; falling back to in-memory store"
+        )
+    return InMemoryOutboxStore()
+
+
+def _default_inbox(env: Mapping[str, str]) -> InboxStore:
+    backend = (env.get("WEBHOOKS_INBOX") or "memory").lower()
+    if backend == "redis":
+        client = _build_redis_client(env)
+        if client is not None:
+            logger.info("Using Redis inbox store for webhooks")
+            return RedisInboxStore(client)
+    return InMemoryInboxStore()
+
+
+def _default_subscriptions() -> InMemoryWebhookSubscriptions:
+    return InMemoryWebhookSubscriptions()
+
+
+def _subscription_lookup(
+    subs: InMemoryWebhookSubscriptions,
+) -> tuple[Callable[[str], str], Callable[[str], str]]:
+    def _get_url(topic: str) -> str:
+        items = subs.get_for_topic(topic)
+        if not items:
+            raise LookupError(f"No webhook subscription for topic '{topic}'")
+        return items[0].url
+
+    def _get_secret(topic: str) -> str:
+        items = subs.get_for_topic(topic)
+        if not items:
+            raise LookupError(f"No webhook subscription for topic '{topic}'")
+        return items[0].secret
+
+    return _get_url, _get_secret
+
+
+def add_webhooks(
+    app: FastAPI,
+    *,
+    outbox: OutboxStore | _Factory[OutboxStore] | None = None,
+    inbox: InboxStore | _Factory[InboxStore] | None = None,
+    subscriptions: (
+        InMemoryWebhookSubscriptions | _Factory[InMemoryWebhookSubscriptions] | None
+    ) = None,
+    queue: JobQueue | None = None,
+    scheduler: InMemoryScheduler | None = None,
+    schedule_tick: bool = True,
+    env: Mapping[str, str] = os.environ,
+) -> None:
+    """Attach the shared webhooks router and stores to a FastAPI app.
+
+    Parameters
+    ----------
+    app:
+        The FastAPI application to configure.
+    outbox / inbox / subscriptions:
+        Optional instances or callables returning instances to use.  When left
+        as ``None`` the helper chooses sensible defaults: in-memory stores for
+        local runs or Redis-backed stores when ``WEBHOOKS_OUTBOX`` /
+        ``WEBHOOKS_INBOX`` are set to ``"redis"`` and ``REDIS_URL`` is
+        available.
+    queue / scheduler:
+        Provide these when you want :func:`make_outbox_tick` and the webhook
+        delivery handler registered for you.  The tick task is scheduled every
+        second by default; disable that registration by passing
+        ``schedule_tick=False``.
+    env:
+        Mapping used to resolve environment-driven defaults.  Defaults to
+        :data:`os.environ` so standard environment variables Just Work.
+
+    Side effects
+    ------------
+    * ``app.include_router`` is invoked for :mod:`svc_infra.webhooks.router`.
+    * ``app.dependency_overrides`` is populated so router dependencies reuse the
+      shared stores.
+    * References are stored on ``app.state`` for further customisation:
+      ``webhooks_outbox``, ``webhooks_inbox``, ``webhooks_subscriptions``,
+      ``webhooks_outbox_tick`` (when a queue is present) and
+      ``webhooks_delivery_handler`` (when queue+inbox are present).
+    """
+
+    resolved_outbox = _resolve_value(outbox, lambda: _default_outbox(env))
+    resolved_inbox = _resolve_value(inbox, lambda: _default_inbox(env))
+    resolved_subs = _resolve_value(subscriptions, _default_subscriptions)
+
+    app.state.webhooks_outbox = resolved_outbox
+    app.state.webhooks_inbox = resolved_inbox
+    app.state.webhooks_subscriptions = resolved_subs
+
+    app.include_router(router_module.router)
+
+    app.dependency_overrides[router_module.get_outbox] = lambda: resolved_outbox
+    app.dependency_overrides[router_module.get_subs] = lambda: resolved_subs
+
+    outbox_tick = None
+    if queue is not None:
+        outbox_tick = make_outbox_tick(resolved_outbox, queue)
+        app.state.webhooks_outbox_tick = outbox_tick
+        if scheduler is not None and schedule_tick:
+            scheduler.add_task("webhooks.outbox", 1, outbox_tick)
+
+        url_lookup, secret_lookup = _subscription_lookup(resolved_subs)
+        handler = make_webhook_handler(
+            outbox=resolved_outbox,
+            inbox=resolved_inbox,
+            get_webhook_url_for_topic=url_lookup,
+            get_secret_for_topic=secret_lookup,
+        )
+        app.state.webhooks_delivery_handler = handler
+    elif scheduler is not None and schedule_tick:
+        logger.warning(
+            "Scheduler provided without queue; skipping outbox tick registration"
+        )
+
+
+__all__ = ["add_webhooks"]

svc_infra/webhooks/encryption.py

@@ -0,0 +1,115 @@
+"""Encryption utilities for webhook secrets.
+
+Provides symmetric encryption for webhook secrets stored in the outbox.
+Uses Fernet (AES-128-CBC with HMAC-SHA256) for authenticated encryption.
+
+The encryption key is derived from WEBHOOK_ENCRYPTION_KEY environment variable.
+In production, this MUST be set to a securely generated 32-byte base64 key.
+
+Generate a key:
+    python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from functools import lru_cache
+from typing import cast
+
+from svc_infra.app.env import require_secret
+
+# Marker prefix for encrypted values
+_ENCRYPTED_PREFIX = "enc:v1:"
+
+
+def _get_encryption_key() -> bytes:
+    """Get the webhook encryption key, requiring it in production."""
+    key_str = require_secret(
+        os.getenv("WEBHOOK_ENCRYPTION_KEY"),
+        "WEBHOOK_ENCRYPTION_KEY",
+        dev_default="dev-only-webhook-encryption-key-not-for-production",
+    )
+    # If it's a Fernet key (44 chars base64), use it directly
+    # Otherwise derive a key from it using SHA256
+    if len(key_str) == 44 and key_str.endswith("="):
+        return base64.urlsafe_b64decode(key_str)
+    # Derive a 32-byte key from arbitrary string
+    return hashlib.sha256(key_str.encode()).digest()
+
+
+@lru_cache(maxsize=1)
+def _get_fernet():
+    """Get or create the Fernet cipher for encryption/decryption."""
+    try:
+        from cryptography.fernet import Fernet
+    except ImportError:
+        # If cryptography is not installed, fall back to no encryption
+        # but log a warning
+        import logging
+
+        logging.getLogger(__name__).warning(
+            "cryptography package not installed - webhook secrets will NOT be encrypted. "
+            "Install with: pip install cryptography"
+        )
+        return None
+
+    key = _get_encryption_key()
+    # Fernet requires a 32-byte key encoded as base64
+    fernet_key = base64.urlsafe_b64encode(key)
+    return Fernet(fernet_key)
+
+
+def encrypt_secret(plaintext: str) -> str:
+    """Encrypt a webhook secret for storage.
+
+    Args:
+        plaintext: The secret to encrypt
+
+    Returns:
+        Encrypted string with "enc:v1:" prefix, or original if encryption unavailable
+    """
+    fernet = _get_fernet()
+    if fernet is None:
+        return plaintext
+
+    encrypted = fernet.encrypt(plaintext.encode())
+    return _ENCRYPTED_PREFIX + cast(str, encrypted.decode())
+
+
+def decrypt_secret(ciphertext: str) -> str:
+    """Decrypt a webhook secret from storage.
+
+    Args:
+        ciphertext: The encrypted secret (with "enc:v1:" prefix)
+
+    Returns:
+        Decrypted plaintext secret
+
+    Note:
+        If the value doesn't have the encryption prefix, it's returned as-is
+        for backwards compatibility with existing unencrypted secrets.
+    """
+    # If not encrypted, return as-is (backwards compatibility)
+    if not ciphertext.startswith(_ENCRYPTED_PREFIX):
+        return ciphertext
+
+    fernet = _get_fernet()
+    if fernet is None:
+        # Can't decrypt without cryptography - return as-is
+        # This shouldn't happen in practice if encrypt_secret was used
+        import logging
+
+        logging.getLogger(__name__).error(
+            "Cannot decrypt webhook secret - cryptography package not installed"
+        )
+        return ciphertext
+
+    encrypted = ciphertext[len(_ENCRYPTED_PREFIX) :].encode()
+    return cast(str, fernet.decrypt(encrypted).decode())
+
+
+def is_encrypted(value: str) -> bool:
+    """Check if a value is encrypted."""
+    return value.startswith(_ENCRYPTED_PREFIX)

svc_infra/webhooks/fastapi.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing 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, Dict
+
+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,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List
+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(timezone.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