pgdispatch 0.1.0__py3-none-any.whl

pgdispatch/core/endpoints.py

@@ -0,0 +1,338 @@
+"""Endpoint management operations."""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from collections.abc import Iterable, Mapping
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from pgdispatch.backends.base import Operation, Query
+from pgdispatch.core.common import (
+    ENDPOINT_COLUMNS,
+    UNSET,
+    OwnerFilter,
+    Unset,
+    first_or_not_found,
+    owner_condition,
+    validate_key,
+    validate_limit,
+)
+from pgdispatch.core.matching import validate_pattern
+from pgdispatch.core.secrets import SecretStore
+from pgdispatch.core.signing import generate_secret, validate_secret
+from pgdispatch.errors import ValidationError
+from pgdispatch.models import Endpoint
+from pgdispatch.security.ssrf import validate_endpoint_url
+
+__all__ = [
+    "UrlPolicy",
+    "create_endpoint",
+    "delete_endpoint",
+    "disable_endpoint",
+    "enable_endpoint",
+    "get_endpoint",
+    "get_secret",
+    "list_endpoints",
+    "rotate_secret",
+    "update_endpoint",
+]
+
+MAX_DESCRIPTION_LENGTH = 1024
+MAX_EVENT_TYPES = 100
+MAX_HEADERS = 20
+
+_HEADER_NAME = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]{1,128}$")
+_RESERVED_HEADERS = frozenset(
+    {
+        "connection",
+        "content-length",
+        "content-type",
+        "host",
+        "transfer-encoding",
+        "user-agent",
+        "webhook-id",
+        "webhook-signature",
+        "webhook-timestamp",
+    }
+)
+
+
+class UrlPolicy:
+    """Which endpoint URLs are acceptable (see :mod:`pgdispatch.security.ssrf`)."""
+
+    def __init__(self, *, allow_http: bool, allow_private_ips: bool) -> None:
+        self.allow_http = allow_http
+        self.allow_private_ips = allow_private_ips
+
+    def check(self, url: str) -> str:
+        return validate_endpoint_url(
+            url, allow_http=self.allow_http, allow_private_ips=self.allow_private_ips
+        )
+
+
+def create_endpoint(
+    *,
+    url: str,
+    event_types: Iterable[str],
+    owner_id: str | None,
+    description: str | None,
+    headers: Mapping[str, str] | None,
+    rate_limit_rps: float | None,
+    secret: str | None,
+    enabled: bool,
+    url_policy: UrlPolicy,
+    secret_store: SecretStore,
+) -> Operation[Endpoint]:
+    plaintext = validate_secret(secret) if secret is not None else generate_secret()
+    entry = secret_store.seal(plaintext, now=_now())
+    rows = yield Query(
+        f"""
+        INSERT INTO {{schema}}.endpoints AS e
+            (id, owner_id, url, description, event_types, secrets, headers, rate_limit_rps,
+             is_enabled)
+        VALUES (CAST(:id AS uuid), CAST(:owner_id AS text), CAST(:url AS text),
+                CAST(:description AS text), CAST(:event_types AS text[]),
+                CAST(:secrets AS jsonb), CAST(:headers AS jsonb),
+                CAST(:rate_limit_rps AS double precision), CAST(:enabled AS boolean))
+        RETURNING {ENDPOINT_COLUMNS}
+        """,
+        {
+            "id": str(uuid.uuid4()),
+            "owner_id": validate_key(owner_id, "owner_id") if owner_id is not None else None,
+            "url": url_policy.check(url),
+            "description": _validate_description(description),
+            "event_types": _validate_event_types(event_types),
+            "secrets": SecretStore.dump([entry]),
+            "headers": _dump_headers(headers or {}),
+            "rate_limit_rps": _validate_rate_limit(rate_limit_rps),
+            "enabled": enabled,
+        },
+    )
+    return Endpoint.from_row(rows[0], secret=plaintext)
+
+
+def get_endpoint(endpoint_id: uuid.UUID, *, owner_id: OwnerFilter) -> Operation[Endpoint]:
+    params: dict[str, Any] = {"id": str(endpoint_id)}
+    owner_sql = owner_condition("e.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        SELECT {ENDPOINT_COLUMNS} FROM {{schema}}.endpoints AS e
+        WHERE e.id = CAST(:id AS uuid) AND {owner_sql}
+        """,
+        params,
+    )
+    return Endpoint.from_row(first_or_not_found(rows, "endpoint", endpoint_id))
+
+
+def list_endpoints(
+    *,
+    owner_id: OwnerFilter,
+    enabled: bool | None,
+    limit: int,
+    after: uuid.UUID | None,
+) -> Operation[list[Endpoint]]:
+    """List endpoints ordered by id; pass the last id as ``after`` to get the next page."""
+    params: dict[str, Any] = {"limit": validate_limit(limit)}
+    conditions = [owner_condition("e.owner_id", owner_id, params)]
+    if enabled is not None:
+        params["enabled"] = enabled
+        conditions.append("e.is_enabled = CAST(:enabled AS boolean)")
+    if after is not None:
+        params["after"] = str(after)
+        conditions.append("e.id > CAST(:after AS uuid)")
+    rows = yield Query(
+        f"""
+        SELECT {ENDPOINT_COLUMNS} FROM {{schema}}.endpoints AS e
+        WHERE {" AND ".join(conditions)}
+        ORDER BY e.id
+        LIMIT CAST(:limit AS integer)
+        """,
+        params,
+    )
+    return [Endpoint.from_row(row) for row in rows]
+
+
+def update_endpoint(
+    endpoint_id: uuid.UUID,
+    *,
+    owner_id: OwnerFilter,
+    url: str | Unset,
+    event_types: Iterable[str] | Unset,
+    description: str | Unset | None,
+    headers: Mapping[str, str] | Unset,
+    rate_limit_rps: float | Unset | None,
+    url_policy: UrlPolicy,
+) -> Operation[Endpoint]:
+    params: dict[str, Any] = {"id": str(endpoint_id)}
+    assignments = ["updated_at = now()"]
+    if url is not UNSET:
+        params["url"] = url_policy.check(url)
+        assignments.append("url = CAST(:url AS text)")
+    if event_types is not UNSET:
+        params["event_types"] = _validate_event_types(event_types)
+        assignments.append("event_types = CAST(:event_types AS text[])")
+    if description is not UNSET:
+        params["description"] = _validate_description(description)
+        assignments.append("description = CAST(:description AS text)")
+    if headers is not UNSET:
+        params["headers"] = _dump_headers(headers)
+        assignments.append("headers = CAST(:headers AS jsonb)")
+    if rate_limit_rps is not UNSET:
+        params["rate_limit_rps"] = _validate_rate_limit(rate_limit_rps)
+        assignments.append("rate_limit_rps = CAST(:rate_limit_rps AS double precision)")
+    return (yield from _update(endpoint_id, ", ".join(assignments), params, owner_id))
+
+
+def enable_endpoint(endpoint_id: uuid.UUID, *, owner_id: OwnerFilter) -> Operation[Endpoint]:
+    """Enable the endpoint and reset its circuit breaker."""
+    assignments = """
+        is_enabled = true, disabled_reason = NULL, circuit_state = 'closed',
+        consecutive_failures = 0, failing_since = NULL, circuit_opened_at = NULL,
+        circuit_retry_at = NULL, circuit_trips = 0, updated_at = now()
+    """
+    return (yield from _update(endpoint_id, assignments, {"id": str(endpoint_id)}, owner_id))
+
+
+def disable_endpoint(
+    endpoint_id: uuid.UUID, *, reason: str | None, owner_id: OwnerFilter
+) -> Operation[Endpoint]:
+    """Stop deliveries to the endpoint. Pending deliveries resume when it is enabled again."""
+    params: dict[str, Any] = {"id": str(endpoint_id), "reason": reason or "disabled manually"}
+    assignments = "is_enabled = false, disabled_reason = CAST(:reason AS text), updated_at = now()"
+    return (yield from _update(endpoint_id, assignments, params, owner_id))
+
+
+def delete_endpoint(endpoint_id: uuid.UUID, *, owner_id: OwnerFilter) -> Operation[None]:
+    """Delete the endpoint together with its deliveries and their attempts."""
+    params: dict[str, Any] = {"id": str(endpoint_id)}
+    owner_sql = owner_condition("e.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        DELETE FROM {{schema}}.endpoints AS e
+        WHERE e.id = CAST(:id AS uuid) AND {owner_sql}
+        RETURNING e.id
+        """,
+        params,
+    )
+    first_or_not_found(rows, "endpoint", endpoint_id)
+
+
+def rotate_secret(
+    endpoint_id: uuid.UUID,
+    *,
+    grace_period: timedelta,
+    secret: str | None,
+    owner_id: OwnerFilter,
+    secret_store: SecretStore,
+) -> Operation[Endpoint]:
+    """Replace the signing secret; the old one keeps signing for ``grace_period``."""
+    if grace_period < timedelta(0):
+        msg = "grace_period must not be negative"
+        raise ValidationError(msg)
+    new_secret = validate_secret(secret) if secret is not None else generate_secret()
+    params: dict[str, Any] = {"id": str(endpoint_id)}
+    owner_sql = owner_condition("e.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        SELECT e.secrets::text AS secrets FROM {{schema}}.endpoints AS e
+        WHERE e.id = CAST(:id AS uuid) AND {owner_sql}
+        FOR UPDATE
+        """,
+        params,
+    )
+    current = SecretStore.load(first_or_not_found(rows, "endpoint", endpoint_id)["secrets"])
+    rotated = secret_store.rotate(current, new_secret, now=_now(), grace_period=grace_period)
+    rows = yield Query(
+        f"""
+        UPDATE {{schema}}.endpoints AS e
+        SET secrets = CAST(:secrets AS jsonb), updated_at = now()
+        WHERE e.id = CAST(:id AS uuid)
+        RETURNING {ENDPOINT_COLUMNS}
+        """,
+        {"id": str(endpoint_id), "secrets": SecretStore.dump(rotated)},
+    )
+    return Endpoint.from_row(rows[0], secret=new_secret)
+
+
+def get_secret(
+    endpoint_id: uuid.UUID, *, owner_id: OwnerFilter, secret_store: SecretStore
+) -> Operation[str]:
+    """Return the newest signing secret, e.g. for a "reveal secret" button."""
+    params: dict[str, Any] = {"id": str(endpoint_id)}
+    owner_sql = owner_condition("e.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        SELECT e.secrets::text AS secrets FROM {{schema}}.endpoints AS e
+        WHERE e.id = CAST(:id AS uuid) AND {owner_sql}
+        """,
+        params,
+    )
+    entries = SecretStore.load(first_or_not_found(rows, "endpoint", endpoint_id)["secrets"])
+    return secret_store.open(entries[0])
+
+
+def _update(
+    endpoint_id: uuid.UUID, assignments: str, params: dict[str, Any], owner_id: OwnerFilter
+) -> Operation[Endpoint]:
+    owner_sql = owner_condition("e.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        UPDATE {{schema}}.endpoints AS e SET {assignments}
+        WHERE e.id = CAST(:id AS uuid) AND {owner_sql}
+        RETURNING {ENDPOINT_COLUMNS}
+        """,
+        params,
+    )
+    return Endpoint.from_row(first_or_not_found(rows, "endpoint", endpoint_id))
+
+
+def _validate_event_types(event_types: Iterable[str]) -> list[str]:
+    if isinstance(event_types, str):
+        msg = "event_types must be a list of patterns, e.g. ['payment.*']"
+        raise ValidationError(msg)
+    patterns = list(dict.fromkeys(validate_pattern(pattern) for pattern in event_types))
+    if not patterns:
+        msg = "event_types must contain at least one pattern; use ['*'] for all events"
+        raise ValidationError(msg)
+    if len(patterns) > MAX_EVENT_TYPES:
+        msg = f"an endpoint can subscribe to at most {MAX_EVENT_TYPES} patterns"
+        raise ValidationError(msg)
+    return patterns
+
+
+def _validate_description(description: str | None) -> str | None:
+    if description is not None and len(description) > MAX_DESCRIPTION_LENGTH:
+        msg = f"description must be at most {MAX_DESCRIPTION_LENGTH} characters"
+        raise ValidationError(msg)
+    return description
+
+
+def _validate_rate_limit(rate_limit_rps: float | None) -> float | None:
+    if rate_limit_rps is not None and not rate_limit_rps > 0:
+        msg = "rate_limit_rps must be a positive number"
+        raise ValidationError(msg)
+    return rate_limit_rps
+
+
+def _dump_headers(headers: Mapping[str, str]) -> str:
+    if len(headers) > MAX_HEADERS:
+        msg = f"an endpoint can have at most {MAX_HEADERS} custom headers"
+        raise ValidationError(msg)
+    for name, value in headers.items():
+        if not isinstance(name, str) or not _HEADER_NAME.match(name):
+            msg = f"invalid header name {name!r}"
+            raise ValidationError(msg)
+        if name.lower() in _RESERVED_HEADERS:
+            msg = f"header {name!r} is set by pgdispatch and cannot be overridden"
+            raise ValidationError(msg)
+        if not isinstance(value, str) or any(char in value for char in "\r\n\0"):
+            msg = f"invalid value for header {name!r}"
+            raise ValidationError(msg)
+    return json.dumps(dict(headers))
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)

pgdispatch/core/events.py

@@ -0,0 +1,65 @@
+"""Reading published events."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from pgdispatch.backends.base import Operation, Query
+from pgdispatch.core.common import OwnerFilter, first_or_not_found, owner_condition, validate_limit
+from pgdispatch.core.matching import validate_event_type
+from pgdispatch.models import Event
+
+__all__ = ["get_event", "list_events"]
+
+_EVENT_COLUMNS = (
+    "ev.id, ev.event_type, ev.owner_id, ev.payload::text AS payload, "
+    "ev.idempotency_key, ev.created_at"
+)
+
+
+def get_event(event_id: uuid.UUID, *, owner_id: OwnerFilter) -> Operation[Event]:
+    params: dict[str, Any] = {"id": str(event_id)}
+    owner_sql = owner_condition("ev.owner_id", owner_id, params)
+    rows = yield Query(
+        f"""
+        SELECT {_EVENT_COLUMNS} FROM {{schema}}.events AS ev
+        WHERE ev.id = CAST(:id AS uuid) AND {owner_sql}
+        """,
+        params,
+    )
+    return Event.from_row(first_or_not_found(rows, "event", event_id))
+
+
+def list_events(
+    *,
+    owner_id: OwnerFilter,
+    event_type: str | None,
+    since: datetime | None,
+    before: uuid.UUID | None,
+    limit: int,
+) -> Operation[list[Event]]:
+    """Newest events first; pass the last id as ``before`` to get the next page."""
+    params: dict[str, Any] = {"limit": validate_limit(limit)}
+    conditions = [owner_condition("ev.owner_id", owner_id, params)]
+    if event_type is not None:
+        params["event_type"] = validate_event_type(event_type)
+        conditions.append("ev.event_type = CAST(:event_type AS text)")
+    if since is not None:
+        params["since"] = since
+        conditions.append("ev.created_at >= CAST(:since AS timestamptz)")
+    if before is not None:
+        # Event ids are UUIDv7, so they sort chronologically.
+        params["before"] = str(before)
+        conditions.append("ev.id < CAST(:before AS uuid)")
+    rows = yield Query(
+        f"""
+        SELECT {_EVENT_COLUMNS} FROM {{schema}}.events AS ev
+        WHERE {" AND ".join(conditions)}
+        ORDER BY ev.id DESC
+        LIMIT CAST(:limit AS integer)
+        """,
+        params,
+    )
+    return [Event.from_row(row) for row in rows]

pgdispatch/core/maintenance.py

@@ -0,0 +1,121 @@
+"""Queue statistics and retention clean-up."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+from pgdispatch.backends.base import Operation, Query
+
+__all__ = ["QueueStats", "delete_expired_events", "queue_stats"]
+
+
+@dataclass(frozen=True, slots=True)
+class QueueStats:
+    """A snapshot of the delivery queue, as shown by ``pgdispatch status``."""
+
+    pending: int
+    """Deliveries waiting for an attempt, on enabled endpoints."""
+    due: int
+    """Deliveries a worker could send right now (not held back by a breaker or ordering)."""
+    in_flight: int
+    """Deliveries being sent right now."""
+    failed_last_24h: int
+    oldest_due_age: timedelta
+    """How long the most overdue sendable delivery has been waiting: the delivery lag.
+
+    Deliveries held back on purpose (an open circuit breaker, an earlier
+    delivery with the same ordering key still retrying) do not count, so the
+    lag reflects worker capacity, not one customer's failing endpoint.
+    """
+    endpoints_enabled: int
+    endpoints_disabled: int
+    circuits_open: int
+    """Enabled endpoints whose circuit breaker is open or half-open."""
+    active_workers: int
+
+
+_STATS = """
+WITH active AS (
+    SELECT d.status, d.next_attempt_at,
+           -- A delivery is "due" only if a worker could send it right now:
+           -- its time has come, its endpoint's breaker is closed, and it is
+           -- not waiting behind an earlier delivery with the same ordering key.
+           d.status = 'pending'
+           AND d.next_attempt_at <= now()
+           AND e.circuit_state = 'closed'
+           AND (
+               d.ordering_key IS NULL
+               OR NOT EXISTS (
+                   SELECT 1 FROM {schema}.deliveries AS prior
+                   WHERE prior.endpoint_id = d.endpoint_id
+                     AND prior.ordering_key = d.ordering_key
+                     AND prior.id < d.id
+                     AND prior.status IN ('pending', 'in_flight')
+               )
+           ) AS is_due
+    FROM {schema}.deliveries AS d
+    JOIN {schema}.endpoints AS e ON e.id = d.endpoint_id
+    WHERE d.status IN ('pending', 'in_flight') AND e.is_enabled
+)
+SELECT
+    (SELECT count(*) FROM active WHERE status = 'pending') AS pending,
+    (SELECT count(*) FROM active WHERE is_due) AS due,
+    (SELECT count(*) FROM active WHERE status = 'in_flight') AS in_flight,
+    (SELECT count(*) FROM {schema}.deliveries
+      WHERE status = 'failed' AND finished_at > now() - interval '24 hours') AS failed_last_24h,
+    (SELECT coalesce(extract(epoch FROM now() - min(next_attempt_at)), 0)::double precision
+       FROM active WHERE is_due) AS oldest_due_age,
+    (SELECT count(*) FROM {schema}.endpoints WHERE is_enabled) AS endpoints_enabled,
+    (SELECT count(*) FROM {schema}.endpoints WHERE NOT is_enabled) AS endpoints_disabled,
+    (SELECT count(*) FROM {schema}.endpoints
+      WHERE is_enabled AND circuit_state <> 'closed') AS circuits_open,
+    (SELECT count(*) FROM {schema}.workers
+      WHERE heartbeat_at > now() - CAST(:worker_ttl AS double precision) * interval '1 second')
+      AS active_workers
+"""
+
+
+def queue_stats(*, worker_ttl: timedelta) -> Operation[QueueStats]:
+    rows = yield Query(_STATS, {"worker_ttl": worker_ttl.total_seconds()})
+    row = rows[0]
+    return QueueStats(
+        pending=row["pending"],
+        due=row["due"],
+        in_flight=row["in_flight"],
+        failed_last_24h=row["failed_last_24h"],
+        oldest_due_age=timedelta(seconds=row["oldest_due_age"]),
+        endpoints_enabled=row["endpoints_enabled"],
+        endpoints_disabled=row["endpoints_disabled"],
+        circuits_open=row["circuits_open"],
+        active_workers=row["active_workers"],
+    )
+
+
+def delete_expired_events(*, older_than: timedelta, batch_size: int) -> Operation[int]:
+    """Delete one batch of events older than ``older_than``; return how many were deleted.
+
+    Deliveries and attempts go with their event (``ON DELETE CASCADE``). Events
+    with a delivery that a worker is sending right now are left for the next run.
+    """
+    rows = yield Query(
+        """
+        WITH doomed AS (
+            SELECT ev.id FROM {schema}.events AS ev
+            WHERE ev.created_at < now() - CAST(:age AS double precision) * interval '1 second'
+              AND NOT EXISTS (
+                  SELECT 1 FROM {schema}.deliveries AS d
+                  WHERE d.event_id = ev.id AND d.status = 'in_flight' AND d.locked_until > now()
+              )
+            ORDER BY ev.created_at
+            LIMIT CAST(:batch_size AS integer)
+            FOR UPDATE SKIP LOCKED
+        ), deleted AS (
+            DELETE FROM {schema}.events AS ev USING doomed WHERE ev.id = doomed.id RETURNING 1
+        )
+        SELECT count(*) AS deleted FROM deleted
+        """,
+        {"age": older_than.total_seconds(), "batch_size": batch_size},
+    )
+    deleted: int = rows[0]["deleted"]
+    return deleted

pgdispatch/core/matching.py

@@ -0,0 +1,76 @@
+"""Event types and the subscription patterns that select them.
+
+An event type is a dot-separated name such as ``payment.paid``. An endpoint
+subscribes with patterns:
+
+* ``*`` matches every event type;
+* ``payment.paid`` matches exactly that type;
+* ``payment.*`` matches every type that starts with ``payment.``
+  (``payment.paid``, ``payment.refund.created``), but not ``payment`` itself.
+
+Because wildcards are only allowed as a trailing segment, the set of patterns
+that can match a given event type is small and known in advance. Publishing
+uses :func:`candidate_patterns` to find subscribers with a single array-overlap
+check (``event_types && candidates``), which PostgreSQL can serve from an index.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pgdispatch.errors import ValidationError
+
+__all__ = [
+    "MAX_EVENT_TYPE_LENGTH",
+    "candidate_patterns",
+    "matches",
+    "validate_event_type",
+    "validate_pattern",
+]
+
+MAX_EVENT_TYPE_LENGTH = 255
+WILDCARD = "*"
+
+_SEGMENT = r"[A-Za-z0-9_\-]+"
+_EVENT_TYPE = re.compile(rf"{_SEGMENT}(?:\.{_SEGMENT})*")
+_PATTERN = re.compile(rf"\*|{_SEGMENT}(?:\.{_SEGMENT})*(?:\.\*)?")
+
+
+def validate_event_type(event_type: str) -> str:
+    """Return ``event_type`` unchanged or raise :class:`ValidationError`."""
+    if len(event_type) > MAX_EVENT_TYPE_LENGTH or not _EVENT_TYPE.fullmatch(event_type):
+        msg = (
+            f"invalid event type {event_type!r}: use dot-separated segments of letters, "
+            "digits, '_' and '-', e.g. 'payment.paid'"
+        )
+        raise ValidationError(msg)
+    return event_type
+
+
+def validate_pattern(pattern: str) -> str:
+    """Return ``pattern`` unchanged or raise :class:`ValidationError`."""
+    if len(pattern) > MAX_EVENT_TYPE_LENGTH or not _PATTERN.fullmatch(pattern):
+        msg = (
+            f"invalid event type pattern {pattern!r}: expected '*', an event type such as "
+            "'payment.paid', or a prefix wildcard such as 'payment.*'"
+        )
+        raise ValidationError(msg)
+    return pattern
+
+
+def candidate_patterns(event_type: str) -> list[str]:
+    """List every pattern that matches ``event_type``.
+
+    >>> candidate_patterns("payment.refund.created")
+    ['*', 'payment.refund.created', 'payment.*', 'payment.refund.*']
+    """
+    segments = event_type.split(".")
+    prefixes = [".".join(segments[:size]) + ".*" for size in range(1, len(segments))]
+    return [WILDCARD, event_type, *prefixes]
+
+
+def matches(pattern: str, event_type: str) -> bool:
+    """Tell whether ``pattern`` selects ``event_type``."""
+    if pattern in (WILDCARD, event_type):
+        return True
+    return pattern.endswith(".*") and event_type.startswith(pattern[:-1])