hookrelay 0.2.0__py3-none-any.whl

hookrelay/__init__.py

@@ -0,0 +1,19 @@
+from hookrelay.backends.base import Backend
+from hookrelay.backends.memory import MemoryBackend
+from hookrelay.exceptions import EventNotFoundError, HookRelayError
+from hookrelay.models import EventStatus, WebhookEvent
+from hookrelay.retry import RetryPolicy
+from hookrelay.worker import Worker
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Backend",
+    "MemoryBackend",
+    "EventStatus",
+    "WebhookEvent",
+    "RetryPolicy",
+    "Worker",
+    "HookRelayError",
+    "EventNotFoundError",
+]

hookrelay/backends/__init__.py

@@ -0,0 +1,4 @@
+from hookrelay.backends.base import Backend
+from hookrelay.backends.memory import MemoryBackend
+
+__all__ = ["Backend", "MemoryBackend"]

hookrelay/backends/base.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta, timezone
+
+from hookrelay.models import EventStatus, WebhookEvent
+from hookrelay.retry import RetryPolicy
+
+
+class Backend(ABC):
+    """Storage and scheduling contract shared by every hookrelay backend.
+
+    A backend only owns persistence and claiming semantics. The retry-vs-dead-letter
+    decision itself lives in `apply_failure()` below so every implementation applies
+    the exact same policy.
+    """
+
+    def __init__(self, retry_policy: RetryPolicy | None = None) -> None:
+        self.retry_policy = retry_policy or RetryPolicy()
+
+    @abstractmethod
+    async def enqueue(self, event: WebhookEvent) -> bool:
+        """Persist a new event. Returns False without error if its idempotency_key
+        already exists (the event is treated as already accepted)."""
+
+    @abstractmethod
+    async def claim_due(self, limit: int) -> list[WebhookEvent]:
+        """Atomically mark up to `limit` due pending events as processing and return them.
+        Safe to call concurrently from multiple workers: an event is claimed by at most one
+        caller."""
+
+    @abstractmethod
+    async def ack(self, event_id: str) -> None:
+        """Mark an event as successfully processed."""
+
+    @abstractmethod
+    async def fail(self, event_id: str, error: str) -> WebhookEvent:
+        """Record a failed processing attempt, scheduling a retry or moving the event
+        to the dead-letter queue once `max_attempts` is exhausted. Returns the updated
+        event so callers can tell which of the two happened without a second lookup."""
+
+    @abstractmethod
+    async def list_dead_letters(self, limit: int = 100, offset: int = 0) -> list[WebhookEvent]:
+        """List events that exhausted their retries, most recently failed first."""
+
+    @abstractmethod
+    async def requeue_dead_letter(self, event_id: str) -> bool:
+        """Reset a dead-lettered event back to pending for another full retry cycle.
+        Returns False if no dead-lettered event with that id exists."""
+
+
+def apply_failure(event: WebhookEvent, error: str, policy: RetryPolicy) -> WebhookEvent:
+    """Returns a copy of `event` updated after a failed processing attempt.
+
+    Centralizes the retry-count/backoff/dead-letter decision so every backend
+    (Postgres, Redis, memory, ...) applies identical semantics.
+    """
+    now = datetime.now(timezone.utc)
+    updated = event.model_copy(
+        update={
+            "attempts": event.attempts + 1,
+            "last_error": error,
+            "updated_at": now,
+        }
+    )
+    if updated.exhausted:
+        return updated.model_copy(update={"status": EventStatus.DEAD_LETTER})
+    delay = policy.delay_for_attempt(updated.attempts)
+    return updated.model_copy(
+        update={
+            "status": EventStatus.PENDING,
+            "next_retry_at": now + timedelta(seconds=delay),
+        }
+    )

hookrelay/backends/memory.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+
+from hookrelay.backends.base import Backend, apply_failure
+from hookrelay.exceptions import EventNotFoundError
+from hookrelay.models import EventStatus, WebhookEvent
+from hookrelay.retry import RetryPolicy
+
+
+class MemoryBackend(Backend):
+    """In-process backend backed by a plain dict.
+
+    Intended for local development, examples, and tests: it has no persistence
+    and does not coordinate across processes. Use PostgresBackend or RedisBackend
+    in production.
+    """
+
+    def __init__(self, retry_policy: RetryPolicy | None = None) -> None:
+        super().__init__(retry_policy)
+        self._events: dict[str, WebhookEvent] = {}
+        self._idempotency_keys: set[str] = set()
+        self._lock = asyncio.Lock()
+
+    async def enqueue(self, event: WebhookEvent) -> bool:
+        async with self._lock:
+            if event.idempotency_key is not None:
+                if event.idempotency_key in self._idempotency_keys:
+                    return False
+                self._idempotency_keys.add(event.idempotency_key)
+            self._events[event.id] = event
+            return True
+
+    async def claim_due(self, limit: int) -> list[WebhookEvent]:
+        now = datetime.now(timezone.utc)
+        async with self._lock:
+            due = sorted(
+                (
+                    e
+                    for e in self._events.values()
+                    if e.status == EventStatus.PENDING and e.next_retry_at <= now
+                ),
+                key=lambda e: e.next_retry_at,
+            )[:limit]
+            claimed = [e.model_copy(update={"status": EventStatus.PROCESSING}) for e in due]
+            for event in claimed:
+                self._events[event.id] = event
+            return claimed
+
+    async def ack(self, event_id: str) -> None:
+        async with self._lock:
+            event = self._events.get(event_id)
+            if event is not None:
+                self._events[event_id] = event.model_copy(update={"status": EventStatus.SUCCESS})
+
+    async def fail(self, event_id: str, error: str) -> WebhookEvent:
+        async with self._lock:
+            event = self._events.get(event_id)
+            if event is None:
+                raise EventNotFoundError(event_id)
+            updated = apply_failure(event, error, self.retry_policy)
+            self._events[event_id] = updated
+            return updated
+
+    async def list_dead_letters(self, limit: int = 100, offset: int = 0) -> list[WebhookEvent]:
+        async with self._lock:
+            dead = sorted(
+                (e for e in self._events.values() if e.status == EventStatus.DEAD_LETTER),
+                key=lambda e: e.updated_at,
+                reverse=True,
+            )
+            return dead[offset : offset + limit]
+
+    async def requeue_dead_letter(self, event_id: str) -> bool:
+        async with self._lock:
+            event = self._events.get(event_id)
+            if event is None or event.status != EventStatus.DEAD_LETTER:
+                return False
+            now = datetime.now(timezone.utc)
+            self._events[event_id] = event.model_copy(
+                update={
+                    "status": EventStatus.PENDING,
+                    "attempts": 0,
+                    "last_error": None,
+                    "next_retry_at": now,
+                    "updated_at": now,
+                }
+            )
+            return True

hookrelay/backends/postgres.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Index,
+    Integer,
+    MetaData,
+    Row,
+    String,
+    Table,
+    Text,
+    delete,
+    select,
+    update,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from hookrelay.backends.base import Backend, apply_failure
+from hookrelay.exceptions import EventNotFoundError
+from hookrelay.models import EventStatus, WebhookEvent
+from hookrelay.retry import RetryPolicy
+
+metadata = MetaData()
+
+events_table = Table(
+    "hookrelay_events",
+    metadata,
+    Column("id", String(36), primary_key=True),
+    Column("source", String(255), nullable=False),
+    Column("idempotency_key", String(255), nullable=True, unique=True),
+    Column("payload", JSONB, nullable=False),
+    Column("headers", JSONB, nullable=False, server_default="{}"),
+    Column("status", String(20), nullable=False),
+    Column("attempts", Integer, nullable=False, server_default="0"),
+    Column("max_attempts", Integer, nullable=False),
+    Column("last_error", Text, nullable=True),
+    Column("next_retry_at", DateTime(timezone=True), nullable=False),
+    Column("created_at", DateTime(timezone=True), nullable=False),
+    Column("updated_at", DateTime(timezone=True), nullable=False),
+    Index("ix_hookrelay_events_status_next_retry", "status", "next_retry_at"),
+)
+
+
+def _row_to_event(row: Row[Any]) -> WebhookEvent:
+    return WebhookEvent(
+        id=row.id,
+        source=row.source,
+        idempotency_key=row.idempotency_key,
+        payload=row.payload,
+        headers=row.headers,
+        status=EventStatus(row.status),
+        attempts=row.attempts,
+        max_attempts=row.max_attempts,
+        last_error=row.last_error,
+        next_retry_at=row.next_retry_at,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+class PostgresBackend(Backend):
+    """Postgres-backed implementation, safe for multiple concurrent workers.
+
+    Requires the `hookrelay_events` table to exist; call `init_schema()` once
+    (e.g. at application startup) or manage it through your own Alembic migrations
+    using the `hookrelay.backends.postgres.metadata` object.
+    """
+
+    def __init__(self, engine: AsyncEngine, retry_policy: RetryPolicy | None = None) -> None:
+        super().__init__(retry_policy)
+        self._engine = engine
+
+    async def init_schema(self) -> None:
+        async with self._engine.begin() as conn:
+            await conn.run_sync(metadata.create_all)
+
+    async def enqueue(self, event: WebhookEvent) -> bool:
+        stmt = pg_insert(events_table).values(
+            id=event.id,
+            source=event.source,
+            idempotency_key=event.idempotency_key,
+            payload=event.payload,
+            headers=event.headers,
+            status=event.status.value,
+            attempts=event.attempts,
+            max_attempts=event.max_attempts,
+            last_error=event.last_error,
+            next_retry_at=event.next_retry_at,
+            created_at=event.created_at,
+            updated_at=event.updated_at,
+        )
+        if event.idempotency_key is not None:
+            stmt = stmt.on_conflict_do_nothing(index_elements=["idempotency_key"])
+        async with self._engine.begin() as conn:
+            result = await conn.execute(stmt)
+            return result.rowcount > 0
+
+    async def claim_due(self, limit: int) -> list[WebhookEvent]:
+        now = datetime.now(timezone.utc)
+        claim_ids = (
+            select(events_table.c.id)
+            .where(events_table.c.status == EventStatus.PENDING.value)
+            .where(events_table.c.next_retry_at <= now)
+            .order_by(events_table.c.next_retry_at)
+            .limit(limit)
+            .with_for_update(skip_locked=True)
+        )
+        stmt = (
+            update(events_table)
+            .where(events_table.c.id.in_(claim_ids))
+            .values(status=EventStatus.PROCESSING.value, updated_at=now)
+            .returning(events_table)
+        )
+        async with self._engine.begin() as conn:
+            rows = (await conn.execute(stmt)).all()
+        return [_row_to_event(row) for row in rows]
+
+    async def ack(self, event_id: str) -> None:
+        stmt = (
+            update(events_table)
+            .where(events_table.c.id == event_id)
+            .values(status=EventStatus.SUCCESS.value, updated_at=datetime.now(timezone.utc))
+        )
+        async with self._engine.begin() as conn:
+            await conn.execute(stmt)
+
+    async def fail(self, event_id: str, error: str) -> WebhookEvent:
+        async with self._engine.begin() as conn:
+            row = (
+                await conn.execute(select(events_table).where(events_table.c.id == event_id))
+            ).first()
+            if row is None:
+                raise EventNotFoundError(event_id)
+            updated_event = apply_failure(_row_to_event(row), error, self.retry_policy)
+            await conn.execute(
+                update(events_table)
+                .where(events_table.c.id == event_id)
+                .values(
+                    status=updated_event.status.value,
+                    attempts=updated_event.attempts,
+                    last_error=updated_event.last_error,
+                    next_retry_at=updated_event.next_retry_at,
+                    updated_at=updated_event.updated_at,
+                )
+            )
+            return updated_event
+
+    async def list_dead_letters(self, limit: int = 100, offset: int = 0) -> list[WebhookEvent]:
+        stmt = (
+            select(events_table)
+            .where(events_table.c.status == EventStatus.DEAD_LETTER.value)
+            .order_by(events_table.c.updated_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+        async with self._engine.connect() as conn:
+            rows = (await conn.execute(stmt)).all()
+        return [_row_to_event(row) for row in rows]
+
+    async def requeue_dead_letter(self, event_id: str) -> bool:
+        now = datetime.now(timezone.utc)
+        stmt = (
+            update(events_table)
+            .where(events_table.c.id == event_id)
+            .where(events_table.c.status == EventStatus.DEAD_LETTER.value)
+            .values(
+                status=EventStatus.PENDING.value,
+                attempts=0,
+                last_error=None,
+                next_retry_at=now,
+                updated_at=now,
+            )
+        )
+        async with self._engine.begin() as conn:
+            result = await conn.execute(stmt)
+            return result.rowcount > 0
+
+    async def purge(
+        self,
+        older_than: datetime,
+        statuses: Sequence[EventStatus] = (EventStatus.SUCCESS, EventStatus.DEAD_LETTER),
+    ) -> int:
+        """Deletes events in one of `statuses` last updated before `older_than`.
+        Returns how many rows were removed. Call this periodically yourself
+        (hookrelay does not run it automatically) to keep a long-running
+        deployment's table from growing without bound."""
+        stmt = delete(events_table).where(
+            events_table.c.status.in_([s.value for s in statuses]),
+            events_table.c.updated_at < older_than,
+        )
+        async with self._engine.begin() as conn:
+            result = await conn.execute(stmt)
+            return result.rowcount

hookrelay/backends/redis.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import cast
+
+from redis.asyncio import Redis
+
+from hookrelay.backends.base import Backend, apply_failure
+from hookrelay.exceptions import EventNotFoundError
+from hookrelay.models import EventStatus, WebhookEvent
+from hookrelay.retry import RetryPolicy
+
+_IDEMPOTENCY_TTL_SECONDS = 7 * 24 * 60 * 60
+
+
+class RedisBackend(Backend):
+    """Redis-backed implementation.
+
+    Suitable for a small number of workers: claiming relies on `ZREM` being atomic
+    per member, which guarantees an event is only ever claimed once. A claimed event
+    is given a lease of `claim_lease_seconds`; if the worker that claimed it crashes
+    before acking or failing it, the event stays claimable again only after you call
+    `reap_stale_claims()`, which hookrelay does not do on its own. For very high
+    worker concurrency, prefer PostgresBackend.
+    """
+
+    def __init__(
+        self,
+        redis: Redis,
+        retry_policy: RetryPolicy | None = None,
+        namespace: str = "hookrelay",
+        claim_lease_seconds: float = 300.0,
+    ) -> None:
+        super().__init__(retry_policy)
+        self._redis = redis
+        self._namespace = namespace
+        self._claim_lease_seconds = claim_lease_seconds
+
+    def _event_key(self, event_id: str) -> str:
+        return f"{self._namespace}:event:{event_id}"
+
+    def _idempotency_key(self, key: str) -> str:
+        return f"{self._namespace}:idempotency:{key}"
+
+    @property
+    def _schedule_key(self) -> str:
+        return f"{self._namespace}:schedule"
+
+    @property
+    def _processing_key(self) -> str:
+        return f"{self._namespace}:processing"
+
+    @property
+    def _dead_letter_key(self) -> str:
+        return f"{self._namespace}:dead_letter"
+
+    @staticmethod
+    def _decode(raw: bytes | str) -> str:
+        return raw.decode() if isinstance(raw, bytes) else raw
+
+    async def _get_event(self, event_id: str) -> WebhookEvent | None:
+        data = await self._redis.get(self._event_key(event_id))
+        return WebhookEvent.model_validate_json(data) if data is not None else None
+
+    async def _save_event(self, event: WebhookEvent) -> None:
+        await self._redis.set(self._event_key(event.id), event.model_dump_json())
+
+    async def enqueue(self, event: WebhookEvent) -> bool:
+        if event.idempotency_key is not None:
+            is_new = await self._redis.set(
+                self._idempotency_key(event.idempotency_key),
+                event.id,
+                nx=True,
+                ex=_IDEMPOTENCY_TTL_SECONDS,
+            )
+            if not is_new:
+                return False
+        await self._save_event(event)
+        await self._redis.zadd(self._schedule_key, {event.id: event.next_retry_at.timestamp()})
+        return True
+
+    async def claim_due(self, limit: int) -> list[WebhookEvent]:
+        now = datetime.now(timezone.utc)
+        candidate_ids = cast(
+            list[bytes | str],
+            await self._redis.zrangebyscore(
+                self._schedule_key, min=0, max=now.timestamp(), start=0, num=limit
+            ),
+        )
+        claimed: list[WebhookEvent] = []
+        lease_expires_at = now.timestamp() + self._claim_lease_seconds
+        for raw_id in candidate_ids:
+            event_id = self._decode(raw_id)
+            removed = await self._redis.zrem(self._schedule_key, event_id)
+            if not removed:
+                continue  # another worker claimed it between the read and this ZREM
+            event = await self._get_event(event_id)
+            if event is None:
+                continue
+            processing_event = event.model_copy(update={"status": EventStatus.PROCESSING})
+            await self._save_event(processing_event)
+            await self._redis.zadd(self._processing_key, {event_id: lease_expires_at})
+            claimed.append(processing_event)
+        return claimed
+
+    async def ack(self, event_id: str) -> None:
+        await self._redis.zrem(self._processing_key, event_id)
+        await self._redis.delete(self._event_key(event_id))
+
+    async def fail(self, event_id: str, error: str) -> WebhookEvent:
+        await self._redis.zrem(self._processing_key, event_id)
+        event = await self._get_event(event_id)
+        if event is None:
+            raise EventNotFoundError(event_id)
+        updated_event = apply_failure(event, error, self.retry_policy)
+        await self._save_event(updated_event)
+        if updated_event.status is EventStatus.DEAD_LETTER:
+            await self._redis.zadd(
+                self._dead_letter_key, {event_id: updated_event.updated_at.timestamp()}
+            )
+        else:
+            await self._redis.zadd(
+                self._schedule_key, {event_id: updated_event.next_retry_at.timestamp()}
+            )
+        return updated_event
+
+    async def reap_stale_claims(self, limit: int = 100) -> int:
+        """Requeues or dead-letters events whose processing lease expired without the
+        worker that claimed them acking or failing them, most commonly because that
+        worker crashed mid-handler. This reuses `fail()`, so a reaped event counts as
+        a failed attempt toward `max_attempts` like any other failure, instead of
+        being retried forever by a handler that keeps crashing the same way.
+
+        hookrelay does not call this on its own: schedule it yourself, for example
+        every `claim_lease_seconds / 2`, from whatever periodic task runner you
+        already use. Returns how many stale claims were reaped.
+        """
+        now = datetime.now(timezone.utc).timestamp()
+        stale_ids = cast(
+            list[bytes | str],
+            await self._redis.zrangebyscore(
+                self._processing_key, min=0, max=now, start=0, num=limit
+            ),
+        )
+        reaped = 0
+        error = "stale claim: lease expired before the worker acked or failed it"
+        for raw_id in stale_ids:
+            event_id = self._decode(raw_id)
+            removed = await self._redis.zrem(self._processing_key, event_id)
+            if not removed:
+                continue  # acked, failed, or already reaped concurrently
+            try:
+                await self.fail(event_id, error)
+            except EventNotFoundError:
+                continue
+            reaped += 1
+        return reaped
+
+    async def list_dead_letters(self, limit: int = 100, offset: int = 0) -> list[WebhookEvent]:
+        end = offset + limit - 1
+        ids = cast(
+            list[bytes | str],
+            await self._redis.zrevrange(self._dead_letter_key, start=offset, end=end),
+        )
+        events = []
+        for raw_id in ids:
+            event_id = self._decode(raw_id)
+            event = await self._get_event(event_id)
+            if event is not None:
+                events.append(event)
+        return events
+
+    async def requeue_dead_letter(self, event_id: str) -> bool:
+        removed = await self._redis.zrem(self._dead_letter_key, event_id)
+        if not removed:
+            return False
+        event = await self._get_event(event_id)
+        if event is None:
+            return False
+        now = datetime.now(timezone.utc)
+        requeued_event = event.model_copy(
+            update={
+                "status": EventStatus.PENDING,
+                "attempts": 0,
+                "last_error": None,
+                "next_retry_at": now,
+                "updated_at": now,
+            }
+        )
+        await self._save_event(requeued_event)
+        await self._redis.zadd(self._schedule_key, {event_id: now.timestamp()})
+        return True