pgdispatch 0.1.0__py3-none-any.whl

pgdispatch/core/payload.py

@@ -0,0 +1,108 @@
+"""Event payload serialization and the body format sent to receivers.
+
+Receivers get the envelope recommended by Standard Webhooks::
+
+    {"type": "payment.paid", "timestamp": "2026-11-01T10:15:00.123Z", "data": {...}}
+
+The body is produced once per attempt and the exact same bytes are signed and
+sent.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import json
+import os
+import time
+import uuid
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from typing import Any
+
+from pgdispatch.errors import PayloadTooLargeError, ValidationError
+
+__all__ = ["build_body", "dumps", "serialize_payload", "uuid7"]
+
+
+def dumps(value: Any) -> str:
+    """Serialize to compact JSON, understanding common Python types.
+
+    Supported beyond plain JSON: ``datetime``/``date`` (ISO 8601), ``UUID``,
+    ``Decimal`` (as a string, to keep precision), ``Enum``, sets and tuples,
+    dataclasses and Pydantic models.
+    """
+    return json.dumps(
+        value,
+        default=_default,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+    )
+
+
+def serialize_payload(payload: Any, *, max_bytes: int) -> str:
+    """Serialize an event payload, enforcing the size limit and PostgreSQL's ``jsonb`` rules."""
+    try:
+        text = dumps(payload)
+    except (TypeError, ValueError) as exc:
+        msg = f"payload is not JSON-serializable: {exc}"
+        raise ValidationError(msg) from exc
+    if "\\u0000" in text:
+        msg = "payload must not contain NUL characters (\\u0000); PostgreSQL jsonb rejects them"
+        raise ValidationError(msg)
+    size = len(text.encode())
+    if size > max_bytes:
+        msg = f"payload is {size} bytes, the limit is {max_bytes} (max_payload_bytes)"
+        raise PayloadTooLargeError(msg)
+    return text
+
+
+def build_body(event_type: str, created_at: datetime, payload_json: str) -> bytes:
+    """Wrap a stored payload in the Standard Webhooks envelope.
+
+    ``payload_json`` is the payload exactly as PostgreSQL returned it, so it is
+    embedded verbatim instead of being decoded and encoded again.
+    """
+    timestamp = created_at.astimezone(timezone.utc).isoformat(timespec="milliseconds")
+    timestamp = timestamp.replace("+00:00", "Z")
+    head = dumps({"type": event_type, "timestamp": timestamp})
+    return f'{head[:-1]},"data":{payload_json}}}'.encode()
+
+
+def uuid7() -> uuid.UUID:
+    """Generate a time-ordered UUID (RFC 9562, version 7).
+
+    Time ordering keeps the events primary-key index compact and lets ids be
+    sorted chronologically.
+    """
+    timestamp_ms = time.time_ns() // 1_000_000
+    rand = int.from_bytes(os.urandom(10), "big")
+    value = (timestamp_ms & 0xFFFF_FFFF_FFFF) << 80
+    value |= 0x7 << 76  # version
+    value |= (rand >> 68) << 64  # 12 random bits
+    value |= 0b10 << 62  # variant
+    value |= rand & 0x3FFF_FFFF_FFFF_FFFF  # 62 random bits
+    return uuid.UUID(int=value)
+
+
+def _default(value: Any) -> Any:  # noqa: PLR0911 - one return per supported type
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, (set, frozenset, tuple)):
+        return list(value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump(mode="json")
+    msg = f"Object of type {type(value).__name__} is not JSON serializable"
+    raise TypeError(msg)

pgdispatch/core/publisher.py

@@ -0,0 +1,232 @@
+"""Publishing events: the transactional outbox.
+
+:func:`publish` runs inside the caller's transaction and, in one statement,
+
+1. inserts the event (skipping it if the idempotency key is already known),
+2. fans it out into one ``deliveries`` row per subscribed endpoint, and
+3. queues a ``NOTIFY`` for the workers.
+
+PostgreSQL delivers notifications only when the transaction commits, so a
+rolled-back transaction leaves no event, no deliveries and no wake-up.
+Subscriptions are resolved at publish time: an endpoint created later does not
+receive earlier events (use replay for that).
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import timedelta
+from typing import Any
+
+from pgdispatch.backends.base import Operation, Query
+from pgdispatch.core.common import (
+    OwnerFilter,
+    first_or_not_found,
+    owner_condition,
+    validate_key,
+)
+from pgdispatch.core.matching import candidate_patterns, validate_event_type
+from pgdispatch.core.payload import serialize_payload, uuid7
+from pgdispatch.errors import ConflictError, NotFoundError
+from pgdispatch.models import PublishResult, to_uuid
+
+__all__ = ["TEST_EVENT_TYPE", "publish", "replay", "send_test"]
+
+TEST_EVENT_TYPE = "webhook.test"
+
+_FANOUT_TARGETS = """
+    FROM {schema}.endpoints AS e
+    WHERE e.is_enabled
+      AND {owner_match}
+      AND e.event_types && CAST(:patterns AS text[])
+"""
+
+_PUBLISH = """
+WITH new_event AS (
+    INSERT INTO {schema}.events (id, event_type, owner_id, payload, idempotency_key)
+    VALUES (CAST(:event_id AS uuid), CAST(:event_type AS text), CAST(:event_owner AS text),
+            CAST(:payload AS jsonb), CAST(:idempotency_key AS text))
+    ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
+    RETURNING id
+), fanout AS (
+    INSERT INTO {schema}.deliveries (event_id, endpoint_id, ordering_key, next_attempt_at)
+    SELECT new_event.id, e.id, CAST(:ordering_key AS text),
+           now() + CAST(:initial_delay AS double precision) * interval '1 second'
+    FROM new_event, ({targets}) AS e
+    RETURNING 1
+), wake AS (
+    SELECT pg_notify(CAST(:channel AS text), '') FROM fanout LIMIT 1
+)
+SELECT (SELECT count(*) FROM new_event) AS inserted,
+       (SELECT count(*) FROM fanout) AS deliveries,
+       (SELECT count(*) FROM wake) AS notified
+"""
+
+
+def publish(
+    *,
+    event_type: str,
+    payload: Any,
+    owner_id: str | None,
+    ordering_key: str | None,
+    idempotency_key: str | None,
+    channel: str,
+    max_payload_bytes: int,
+    initial_delay: timedelta = timedelta(0),
+) -> Operation[PublishResult]:
+    validate_event_type(event_type)
+    params: dict[str, Any] = {
+        "event_id": str(uuid7()),
+        "event_type": event_type,
+        "event_owner": validate_key(owner_id, "owner_id") if owner_id is not None else None,
+        "payload": serialize_payload(payload, max_bytes=max_payload_bytes),
+        "ordering_key": validate_key(ordering_key, "ordering_key") if ordering_key else None,
+        "idempotency_key": (
+            validate_key(idempotency_key, "idempotency_key") if idempotency_key else None
+        ),
+        "patterns": candidate_patterns(event_type),
+        "channel": channel,
+        "initial_delay": initial_delay.total_seconds(),
+    }
+    sql = _PUBLISH.replace("{targets}", "SELECT e.id " + _fanout_targets(owner_id, params))
+    rows = yield Query(sql, params)
+    row = rows[0]
+    if row["inserted"]:
+        return PublishResult(event_id=uuid.UUID(params["event_id"]), deliveries=row["deliveries"])
+
+    # The idempotency key exists. In READ COMMITTED this statement sees rows
+    # committed after the previous one started, so a concurrent duplicate is found.
+    rows = yield Query(
+        "SELECT id FROM {schema}.events WHERE idempotency_key = CAST(:key AS text)",
+        {"key": idempotency_key},
+    )
+    if not rows:  # pragma: no cover - only under REPEATABLE READ with a concurrent publisher
+        msg = f"an event with idempotency key {idempotency_key!r} is being published concurrently"
+        raise ConflictError(msg)
+    return PublishResult(event_id=to_uuid(rows[0]["id"]), deliveries=0, duplicate=True)
+
+
+def replay(
+    event_id: uuid.UUID,
+    *,
+    endpoint_id: uuid.UUID | None,
+    owner_id: OwnerFilter,
+    channel: str,
+) -> Operation[list[int]]:
+    """Deliver an existing event again; return the ids of the new deliveries.
+
+    Without ``endpoint_id`` the event goes to every enabled endpoint that is
+    subscribed *now*, which is how you backfill a newly created endpoint.
+    Replays bypass ``ordering_key`` so they never wait behind live traffic.
+    """
+    params: dict[str, Any] = {"event_id": str(event_id), "channel": channel}
+    owner_sql = owner_condition("ev.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        SELECT ev.id, ev.event_type, ev.owner_id FROM {{schema}}.events AS ev
+        WHERE ev.id = CAST(:event_id AS uuid) AND {owner_sql}
+        """,
+        params,
+    )
+    event = first_or_not_found(rows, "event", event_id)
+
+    insert_params: dict[str, Any] = {"event_id": str(event_id), "channel": channel}
+    if endpoint_id is not None:
+        # Only endpoints of the event's owner may receive it: never leak across tenants.
+        insert_params["endpoint_id"] = str(endpoint_id)
+        same_owner = _owner_match(event["owner_id"], insert_params, column="e.owner_id")
+        targets = f"""
+            SELECT e.id FROM {{schema}}.endpoints AS e
+            WHERE e.id = CAST(:endpoint_id AS uuid) AND {same_owner}
+        """
+    else:
+        insert_params["patterns"] = candidate_patterns(event["event_type"])
+        targets = "SELECT e.id " + _fanout_targets(event["owner_id"], insert_params)
+
+    rows = yield Query(
+        f"""
+        WITH created AS (
+            INSERT INTO {{schema}}.deliveries (event_id, endpoint_id)
+            SELECT CAST(:event_id AS uuid), targets.id FROM ({targets}) AS targets
+            RETURNING id
+        ), wake AS (
+            SELECT pg_notify(CAST(:channel AS text), '') FROM created LIMIT 1
+        )
+        SELECT id, (SELECT count(*) FROM wake) AS notified FROM created ORDER BY id
+        """,
+        insert_params,
+    )
+    if endpoint_id is not None and not rows:
+        msg = f"endpoint {endpoint_id} not found for the owner of event {event_id}"
+        raise NotFoundError(msg)
+    return [row["id"] for row in rows]
+
+
+def send_test(
+    endpoint_id: uuid.UUID,
+    *,
+    owner_id: OwnerFilter,
+    channel: str,
+) -> Operation[PublishResult]:
+    """Send a ``webhook.test`` event to one endpoint, regardless of its subscriptions."""
+    params: dict[str, Any] = {"endpoint_id": str(endpoint_id)}
+    owner_sql = owner_condition("e.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        SELECT e.id, e.owner_id, e.is_enabled FROM {{schema}}.endpoints AS e
+        WHERE e.id = CAST(:endpoint_id AS uuid) AND {owner_sql}
+        FOR SHARE
+        """,
+        params,
+    )
+    endpoint = first_or_not_found(rows, "endpoint", endpoint_id)
+    if not endpoint["is_enabled"]:
+        msg = f"endpoint {endpoint_id} is disabled; enable it before sending a test event"
+        raise ConflictError(msg)
+
+    event_id = uuid7()
+    payload = {
+        "message": "This is a test event sent by pgdispatch.",
+        "endpoint_id": str(endpoint_id),
+    }
+    yield Query(
+        """
+        WITH new_event AS (
+            INSERT INTO {schema}.events (id, event_type, owner_id, payload)
+            VALUES (CAST(:event_id AS uuid), CAST(:event_type AS text),
+                    CAST(:owner_id AS text), CAST(:payload AS jsonb))
+            RETURNING id
+        ), delivery AS (
+            INSERT INTO {schema}.deliveries (event_id, endpoint_id)
+            SELECT new_event.id, CAST(:endpoint_id AS uuid) FROM new_event
+            RETURNING 1
+        ), wake AS (
+            SELECT pg_notify(CAST(:channel AS text), '') FROM delivery LIMIT 1
+        )
+        SELECT (SELECT count(*) FROM delivery) AS deliveries,
+               (SELECT count(*) FROM wake) AS notified
+        """,
+        {
+            "event_id": str(event_id),
+            "event_type": TEST_EVENT_TYPE,
+            "owner_id": endpoint["owner_id"],
+            "payload": serialize_payload(payload, max_bytes=1024),
+            "endpoint_id": str(endpoint_id),
+            "channel": channel,
+        },
+    )
+    return PublishResult(event_id=event_id, deliveries=1)
+
+
+def _fanout_targets(owner_id: str | None, params: dict[str, Any]) -> str:
+    owner_match = _owner_match(owner_id, params, column="e.owner_id")
+    return _FANOUT_TARGETS.replace("{owner_match}", owner_match)
+
+
+def _owner_match(owner_id: str | None, params: dict[str, Any], *, column: str) -> str:
+    # Events are only ever delivered to endpoints of the same owner (or, for
+    # events without an owner, to endpoints without an owner).
+    if owner_id is None:
+        return f"{column} IS NULL"
+    params["target_owner"] = owner_id
+    return f"{column} = CAST(:target_owner AS text)"

pgdispatch/core/retry.py

@@ -0,0 +1,90 @@
+"""Retry schedule, jitter and ``Retry-After`` handling."""
+
+from __future__ import annotations
+
+import random
+from datetime import datetime, timedelta, timezone
+from email.utils import parsedate_to_datetime
+
+__all__ = [
+    "DEFAULT_RETRY_SCHEDULE",
+    "exponential_backoff",
+    "next_retry_delay",
+    "parse_retry_after",
+]
+
+#: Eight attempts over roughly 27 hours, the schedule popularised by Stripe and Svix.
+#: Element *n* is the delay before attempt *n + 1*; the first attempt is immediate.
+DEFAULT_RETRY_SCHEDULE: tuple[timedelta, ...] = (
+    timedelta(0),
+    timedelta(seconds=5),
+    timedelta(minutes=5),
+    timedelta(minutes=30),
+    timedelta(hours=2),
+    timedelta(hours=5),
+    timedelta(hours=10),
+    timedelta(hours=10),
+)
+
+
+def exponential_backoff(
+    attempts: int,
+    *,
+    initial: timedelta = timedelta(seconds=5),
+    factor: float = 2.0,
+    max_delay: timedelta = timedelta(hours=10),
+) -> tuple[timedelta, ...]:
+    """Build a retry schedule whose delays grow geometrically.
+
+    ``exponential_backoff(4, initial=timedelta(seconds=10))`` yields delays of
+    0 s, 10 s, 20 s and 40 s. The result can be passed as ``retry_schedule``.
+    """
+    if attempts < 1:
+        msg = "attempts must be at least 1"
+        raise ValueError(msg)
+    if factor < 1:
+        msg = "factor must be at least 1"
+        raise ValueError(msg)
+    delays = [timedelta(0)]
+    for retry in range(attempts - 1):
+        delays.append(min(initial * factor**retry, max_delay))
+    return tuple(delays)
+
+
+def next_retry_delay(
+    schedule: tuple[timedelta, ...],
+    attempts_made: int,
+    *,
+    jitter: float = 0.0,
+    rng: random.Random | None = None,
+) -> timedelta | None:
+    """Return the delay before the next attempt, or ``None`` when attempts are exhausted.
+
+    ``attempts_made`` counts the attempts already performed in the current retry
+    round. A random spread of ``±jitter`` is applied so that retries for many
+    deliveries that failed together do not hit the receiver at the same instant.
+    """
+    if attempts_made >= len(schedule):
+        return None
+    delay = schedule[attempts_made]
+    if jitter and delay:
+        spread = (rng or random).uniform(1 - jitter, 1 + jitter)
+        delay = delay * spread
+    return delay
+
+
+def parse_retry_after(value: str | None, *, now: datetime | None = None) -> timedelta | None:
+    """Parse an HTTP ``Retry-After`` header (delta-seconds or HTTP-date)."""
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return timedelta(seconds=int(value))
+    try:
+        moment = parsedate_to_datetime(value)
+    except (TypeError, ValueError, IndexError):
+        return None
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    delay = moment - (now or datetime.now(timezone.utc))
+    return max(delay, timedelta(0))

pgdispatch/core/secrets.py

@@ -0,0 +1,138 @@
+"""Storage of endpoint signing secrets, including rotation and optional encryption.
+
+An endpoint keeps a list of secrets in a ``jsonb`` column::
+
+    [{"key": "whsec_...", "encrypted": false,
+      "created_at": "2026-11-01T10:00:00+00:00", "expires_at": null}]
+
+The newest secret comes first. When a secret is rotated the previous ones get
+an ``expires_at`` timestamp; until then requests are signed with every active
+secret, so receivers can switch keys without dropping a single webhook.
+
+Secrets cannot be hashed because the worker needs them to sign requests. They
+can, however, be encrypted at rest with any object implementing
+:class:`SecretCipher` — ``cryptography.fernet.Fernet`` and ``MultiFernet`` fit.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any, Protocol
+
+from pgdispatch.errors import ConfigurationError
+
+__all__ = ["SecretCipher", "SecretEntry", "SecretStore", "fernet_cipher"]
+
+
+class SecretCipher(Protocol):
+    """Symmetric encryption used for secrets at rest (``Fernet`` compatible)."""
+
+    def encrypt(self, data: bytes) -> bytes: ...
+
+    def decrypt(self, token: bytes) -> bytes: ...
+
+
+@dataclass(frozen=True, slots=True)
+class SecretEntry:
+    key: str
+    encrypted: bool
+    created_at: datetime
+    expires_at: datetime | None
+
+    def is_active(self, now: datetime) -> bool:
+        return self.expires_at is None or self.expires_at > now
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "encrypted": self.encrypted,
+            "created_at": self.created_at.isoformat(),
+            "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> SecretEntry:
+        expires_at = data.get("expires_at")
+        return cls(
+            key=data["key"],
+            encrypted=bool(data.get("encrypted", False)),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            expires_at=datetime.fromisoformat(expires_at) if expires_at else None,
+        )
+
+
+class SecretStore:
+    """Seals, opens and rotates the secrets of an endpoint."""
+
+    def __init__(self, cipher: SecretCipher | None = None) -> None:
+        self._cipher = cipher
+
+    def seal(self, secret: str, *, now: datetime) -> SecretEntry:
+        if self._cipher is None:
+            return SecretEntry(key=secret, encrypted=False, created_at=now, expires_at=None)
+        token = self._cipher.encrypt(secret.encode()).decode("ascii")
+        return SecretEntry(key=token, encrypted=True, created_at=now, expires_at=None)
+
+    def open(self, entry: SecretEntry) -> str:
+        if not entry.encrypted:
+            return entry.key
+        if self._cipher is None:
+            msg = (
+                "endpoint secrets are encrypted but no decryption key is configured; "
+                "set secret_encryption_keys (PGDISPATCH_SECRET_ENCRYPTION_KEYS)"
+            )
+            raise ConfigurationError(msg)
+        return self._cipher.decrypt(entry.key.encode("ascii")).decode()
+
+    def active_secrets(self, raw: str | Sequence[dict[str, Any]], *, now: datetime) -> list[str]:
+        """Plaintext secrets that must sign a request at ``now``, newest first."""
+        return [self.open(entry) for entry in self.load(raw) if entry.is_active(now)]
+
+    @staticmethod
+    def load(raw: str | Sequence[dict[str, Any]]) -> list[SecretEntry]:
+        items = json.loads(raw) if isinstance(raw, str) else raw
+        return [SecretEntry.from_json(item) for item in items]
+
+    @staticmethod
+    def dump(entries: Sequence[SecretEntry]) -> str:
+        return json.dumps([entry.to_json() for entry in entries])
+
+    def rotate(
+        self,
+        entries: Sequence[SecretEntry],
+        new_secret: str,
+        *,
+        now: datetime,
+        grace_period: timedelta,
+    ) -> list[SecretEntry]:
+        """Put ``new_secret`` first; currently active secrets expire after ``grace_period``."""
+        deadline = now + grace_period
+        kept = [
+            SecretEntry(
+                key=entry.key,
+                encrypted=entry.encrypted,
+                created_at=entry.created_at,
+                expires_at=min(entry.expires_at, deadline) if entry.expires_at else deadline,
+            )
+            for entry in entries
+            if entry.is_active(now) and grace_period > timedelta(0)
+        ]
+        return [self.seal(new_secret, now=now), *kept]
+
+
+def fernet_cipher(keys: Sequence[str]) -> SecretCipher:
+    """Build a ``MultiFernet`` cipher; the first key encrypts, all keys decrypt."""
+    try:
+        from cryptography.fernet import Fernet, MultiFernet
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        msg = (
+            'secret encryption requires the encryption extra: pip install "pgdispatch[encryption]"'
+        )
+        raise ConfigurationError(msg) from exc
+    if not keys:
+        msg = "at least one Fernet key is required"
+        raise ConfigurationError(msg)
+    return MultiFernet([Fernet(key) for key in keys])