txoutbox 0.1.0__py3-none-any.whl

txoutbox/__init__.py

@@ -0,0 +1,27 @@
+"""txoutbox: a storage-agnostic Transactional Outbox relay for asyncio.
+
+Bring your own table, bring your own broker. Implement :class:`Storage` over your
+database and :class:`Publisher` over your transport; :class:`Relay` does the rest.
+"""
+
+from .backoff import Backoff
+from .message import MessageId, OutboxMessage
+from .poller import AdaptivePoller
+from .protocols import Hooks, Publisher, Storage
+from .relay import Relay, RelayConfig, RoundResult, default_worker_id
+
+__all__ = [
+    "AdaptivePoller",
+    "Backoff",
+    "Hooks",
+    "MessageId",
+    "OutboxMessage",
+    "Publisher",
+    "Relay",
+    "RelayConfig",
+    "RoundResult",
+    "Storage",
+    "default_worker_id",
+]
+
+__version__ = "0.1.0"

txoutbox/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Built-in storage and publisher adapters.
+
+* :mod:`txoutbox.adapters.memory` - in-process, for tests and demos.
+* :mod:`txoutbox.adapters.sqlite` - stdlib ``sqlite3``, for small services and examples.
+* :mod:`txoutbox.adapters.postgres` - ``asyncpg`` with ``FOR UPDATE SKIP LOCKED``
+  (install extra ``postgres``).
+"""

txoutbox/adapters/memory.py

@@ -0,0 +1,162 @@
+"""In-memory storage and publisher. Deterministic, dependency-free, test-friendly."""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+
+from ..message import MessageId, OutboxMessage
+
+
+class Status(StrEnum):
+    PENDING = "pending"
+    DONE = "done"
+    DEAD = "dead"
+
+
+@dataclass(slots=True)
+class Record:
+    message: OutboxMessage
+    status: Status = Status.PENDING
+    attempts: int = 0
+    retry_at: datetime | None = None
+    leased_by: str | None = None
+    lease_until: datetime | None = None
+    last_error: str | None = None
+
+
+class MemoryStorage:
+    """A dict-backed outbox. Rows are inserted with :meth:`add` (your "transaction").
+
+    With ``strict_ordering`` (default), a message whose key has an earlier message that
+    is pending but not claimable right now (leased elsewhere, or waiting for a retry)
+    is held back, so retries never reorder a key.
+    """
+
+    def __init__(
+        self, *, clock: Callable[[], datetime] | None = None, strict_ordering: bool = True
+    ) -> None:
+        self.strict_ordering = strict_ordering
+        self._records: dict[MessageId, Record] = {}
+        self._ids = itertools.count(1)
+        self._clock = clock or (lambda: datetime.now(UTC))
+        self._lock = asyncio.Lock()
+
+    # -- producer side -----------------------------------------------------------------
+
+    def add(
+        self,
+        topic: str,
+        payload: bytes,
+        *,
+        key: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> MessageId:
+        message_id = next(self._ids)
+        self._records[message_id] = Record(
+            OutboxMessage(
+                id=message_id,
+                topic=topic,
+                payload=payload,
+                key=key,
+                headers=dict(headers or {}),
+                created_at=self._clock(),
+            )
+        )
+        return message_id
+
+    # -- inspection --------------------------------------------------------------------
+
+    def get(self, message_id: MessageId) -> Record:
+        return self._records[message_id]
+
+    def records(self, status: Status | None = None) -> list[Record]:
+        return [r for r in self._records.values() if status is None or r.status == status]
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    # -- Storage protocol --------------------------------------------------------------
+
+    async def claim(
+        self, *, batch_size: int, lease: timedelta, worker_id: str
+    ) -> Sequence[OutboxMessage]:
+        async with self._lock:
+            now = self._clock()
+            claimed: list[OutboxMessage] = []
+            blocked_keys: set[str] = set()
+            for record in self._records.values():
+                if len(claimed) >= batch_size:
+                    break
+                if record.status is not Status.PENDING:
+                    continue
+                key = record.message.key
+                not_due = record.retry_at is not None and record.retry_at > now
+                leased = record.lease_until is not None and record.lease_until > now
+                if not_due or leased or (key is not None and key in blocked_keys):
+                    if key is not None and self.strict_ordering:
+                        blocked_keys.add(key)
+                    continue
+                record.attempts += 1
+                record.leased_by = worker_id
+                record.lease_until = now + lease
+                record.retry_at = None
+                claimed.append(_with_attempts(record.message, record.attempts))
+            return claimed
+
+    async def ack(self, ids: Sequence[MessageId]) -> None:
+        async with self._lock:
+            for message_id in ids:
+                record = self._records[message_id]
+                record.status = Status.DONE
+                record.leased_by = record.lease_until = None
+
+    async def nack(self, message_id: MessageId, *, error: str, retry_at: datetime) -> None:
+        async with self._lock:
+            record = self._records[message_id]
+            record.last_error = error
+            record.retry_at = retry_at
+            record.leased_by = record.lease_until = None
+
+    async def dead_letter(self, message_id: MessageId, *, error: str) -> None:
+        async with self._lock:
+            record = self._records[message_id]
+            record.status = Status.DEAD
+            record.last_error = error
+            record.leased_by = record.lease_until = None
+
+
+def _with_attempts(message: OutboxMessage, attempts: int) -> OutboxMessage:
+    return OutboxMessage(
+        id=message.id,
+        topic=message.topic,
+        payload=message.payload,
+        key=message.key,
+        headers=message.headers,
+        attempts=attempts,
+        created_at=message.created_at,
+    )
+
+
+@dataclass(slots=True)
+class MemoryPublisher:
+    """Collects published messages. ``fail`` decides which publishes raise."""
+
+    published: list[OutboxMessage] = field(default_factory=list)
+    fail: Callable[[OutboxMessage], BaseException | None] | None = None
+    delay: float = 0.0
+
+    async def publish(self, message: OutboxMessage) -> None:
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        if self.fail is not None and (error := self.fail(message)) is not None:
+            raise error
+        self.published.append(message)
+
+    @property
+    def topics(self) -> list[str]:
+        return [m.topic for m in self.published]

txoutbox/adapters/postgres.py

@@ -0,0 +1,201 @@
+"""Outbox storage on PostgreSQL via ``asyncpg``.
+
+Claims use ``FOR UPDATE SKIP LOCKED`` so any number of relay workers can share one
+table without stepping on each other. Install with ``pip install txoutbox[postgres]``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from datetime import datetime, timedelta
+from typing import Any, Self
+
+from ..message import MessageId, OutboxMessage
+
+try:
+    import asyncpg
+except ImportError as _exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(
+        "txoutbox.adapters.postgres needs asyncpg: pip install 'txoutbox[postgres]'"
+    ) from _exc
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS {table} (
+    id          BIGSERIAL   PRIMARY KEY,
+    topic       TEXT        NOT NULL,
+    key         TEXT,
+    payload     BYTEA       NOT NULL,
+    headers     JSONB       NOT NULL DEFAULT '{{}}',
+    status      TEXT        NOT NULL DEFAULT 'pending',
+    attempts    INT         NOT NULL DEFAULT 0,
+    retry_at    TIMESTAMPTZ,
+    leased_by   TEXT,
+    lease_until TIMESTAMPTZ,
+    last_error  TEXT,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS {index} ON {table} (id) WHERE status = 'pending';
+"""
+
+
+class PostgresStorage:
+    """Outbox table in PostgreSQL, driven by an :class:`asyncpg.Pool`.
+
+    Pass your application's pool, or build a private one with :meth:`connect`.
+    ``strict_ordering`` (default) holds back a message while an earlier pending message
+    with the same key is not claimable (leased elsewhere, or waiting for its retry).
+    ``delete_on_ack`` removes delivered rows instead of marking them ``done``.
+    """
+
+    def __init__(
+        self,
+        pool: asyncpg.Pool,
+        *,
+        table: str = "outbox",
+        schema: str | None = None,
+        strict_ordering: bool = True,
+        delete_on_ack: bool = False,
+    ) -> None:
+        if not table.isidentifier():
+            raise ValueError("table must be a plain identifier")
+        if schema is not None and not schema.isidentifier():
+            raise ValueError("schema must be a plain identifier")
+        self.pool = pool
+        self.table = table
+        self.schema = schema
+        self.strict_ordering = strict_ordering
+        self.delete_on_ack = delete_on_ack
+        self._owns_pool = False
+        self._sql = _Sql(self.qualified_table, f"{table}_pending_idx", strict_ordering)
+
+    @classmethod
+    async def connect(cls, dsn: str, **kwargs: Any) -> Self:
+        """Create a storage with its own pool. ``kwargs`` go to the constructor."""
+        pool_kwargs = {k: kwargs.pop(k) for k in list(kwargs) if k not in _INIT_KWARGS}
+        pool = await asyncpg.create_pool(dsn, **pool_kwargs)
+        self = cls(pool, **kwargs)
+        self._owns_pool = True
+        return self
+
+    async def close(self) -> None:
+        """Close the pool, but only if :meth:`connect` created it."""
+        if self._owns_pool:
+            await self.pool.close()
+            self._owns_pool = False
+
+    @property
+    def qualified_table(self) -> str:
+        return f"{self.schema}.{self.table}" if self.schema else self.table
+
+    # -- setup -------------------------------------------------------------------------
+
+    def schema_sql(self) -> str:
+        """DDL for the outbox table. Paste it into your migration tool."""
+        return SCHEMA_SQL.format(table=self.qualified_table, index=f"{self.table}_pending_idx")
+
+    async def create_schema(self) -> None:
+        await self.pool.execute(self.schema_sql())
+
+    # -- producer side -----------------------------------------------------------------
+
+    async def insert(
+        self,
+        conn: asyncpg.Connection,
+        topic: str,
+        payload: bytes,
+        *,
+        key: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> int:
+        """Insert a row using *your* connection, inside *your* transaction."""
+        row_id: int = await conn.fetchval(
+            self._sql.insert, topic, key, payload, json.dumps(dict(headers or {}))
+        )
+        return row_id
+
+    async def add(
+        self,
+        topic: str,
+        payload: bytes,
+        *,
+        key: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> int:
+        """Insert a row on a pooled connection. Handy for demos and tests."""
+        async with self.pool.acquire() as conn:
+            return await self.insert(conn, topic, payload, key=key, headers=headers)
+
+    # -- Storage protocol --------------------------------------------------------------
+
+    async def claim(
+        self, *, batch_size: int, lease: timedelta, worker_id: str
+    ) -> Sequence[OutboxMessage]:
+        rows = await self.pool.fetch(self._sql.claim, worker_id, lease, batch_size)
+        return [_row_to_message(row) for row in rows]
+
+    async def ack(self, ids: Sequence[MessageId]) -> None:
+        if not ids:
+            return
+        sql = self._sql.delete if self.delete_on_ack else self._sql.ack
+        await self.pool.execute(sql, list(ids))
+
+    async def nack(self, message_id: MessageId, *, error: str, retry_at: datetime) -> None:
+        await self.pool.execute(self._sql.nack, retry_at, error, message_id)
+
+    async def dead_letter(self, message_id: MessageId, *, error: str) -> None:
+        await self.pool.execute(self._sql.dead_letter, error, message_id)
+
+
+_INIT_KWARGS = frozenset({"table", "schema", "strict_ordering", "delete_on_ack"})
+
+
+class _Sql:
+    """Statements pre-rendered for one table."""
+
+    def __init__(self, table: str, index: str, strict_ordering: bool) -> None:
+        blocked = (
+            " AND (o.key IS NULL OR NOT EXISTS ("
+            f"SELECT 1 FROM {table} p WHERE p.key = o.key AND p.id < o.id"
+            " AND p.status = 'pending' AND (p.retry_at > now() OR p.lease_until > now())))"
+            if strict_ordering
+            else ""
+        )
+        self.insert = (
+            f"INSERT INTO {table} (topic, key, payload, headers)"
+            " VALUES ($1, $2, $3, $4::jsonb) RETURNING id"
+        )
+        self.claim = (
+            f"UPDATE {table} SET attempts = attempts + 1, leased_by = $1,"
+            " lease_until = now() + $2, retry_at = NULL"
+            f" WHERE id IN (SELECT o.id FROM {table} o WHERE o.status = 'pending'"
+            " AND (o.retry_at IS NULL OR o.retry_at <= now())"
+            " AND (o.lease_until IS NULL OR o.lease_until <= now())"
+            f"{blocked} ORDER BY o.id LIMIT $3 FOR UPDATE SKIP LOCKED)"
+            " RETURNING id, topic, key, payload, headers::text AS headers, attempts, created_at"
+        )
+        self.ack = (
+            f"UPDATE {table} SET status = 'done', leased_by = NULL, lease_until = NULL"
+            " WHERE id = ANY($1::bigint[])"
+        )
+        self.delete = f"DELETE FROM {table} WHERE id = ANY($1::bigint[])"
+        self.nack = (
+            f"UPDATE {table} SET retry_at = $1, last_error = $2, leased_by = NULL,"
+            " lease_until = NULL WHERE id = $3"
+        )
+        self.dead_letter = (
+            f"UPDATE {table} SET status = 'dead', last_error = $1, leased_by = NULL,"
+            " lease_until = NULL WHERE id = $2"
+        )
+
+
+def _row_to_message(row: asyncpg.Record) -> OutboxMessage:
+    return OutboxMessage(
+        id=row["id"],
+        topic=row["topic"],
+        payload=bytes(row["payload"]),
+        key=row["key"],
+        headers=json.loads(row["headers"]),
+        attempts=row["attempts"],
+        created_at=row["created_at"],
+    )

txoutbox/adapters/sqlite.py

@@ -0,0 +1,216 @@
+"""Outbox storage on the standard library's ``sqlite3``.
+
+Good for small services, examples and integration tests. Calls run in a worker
+thread so the event loop is never blocked; a process-wide lock serialises them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import threading
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from ..message import MessageId, OutboxMessage
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS {table} (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    topic       TEXT    NOT NULL,
+    key         TEXT,
+    payload     BLOB    NOT NULL,
+    headers     TEXT    NOT NULL DEFAULT '{{}}',
+    status      TEXT    NOT NULL DEFAULT 'pending',
+    attempts    INTEGER NOT NULL DEFAULT 0,
+    retry_at    REAL,
+    leased_by   TEXT,
+    lease_until REAL,
+    last_error  TEXT,
+    created_at  REAL    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS {table}_pending_idx ON {table} (status, id);
+"""
+
+
+class SqliteStorage:
+    """Outbox table in a SQLite database.
+
+    ``strict_ordering`` (default) holds back a message while an earlier pending message
+    with the same key is not claimable (leased elsewhere, or waiting for its retry).
+    ``delete_on_ack`` removes delivered rows instead of marking them ``done``.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        *,
+        table: str = "outbox",
+        strict_ordering: bool = True,
+        delete_on_ack: bool = False,
+    ) -> None:
+        if not table.isidentifier():
+            raise ValueError("table must be a plain identifier")
+        self.path = path
+        self.table = table
+        self.strict_ordering = strict_ordering
+        self.delete_on_ack = delete_on_ack
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(path, check_same_thread=False, isolation_level=None)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA busy_timeout=5000")
+
+    # -- setup -------------------------------------------------------------------------
+
+    def create_schema(self) -> None:
+        with self._lock:
+            self._conn.executescript(SCHEMA.format(table=self.table))
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    # -- producer side -----------------------------------------------------------------
+
+    def insert(
+        self,
+        conn: sqlite3.Connection,
+        topic: str,
+        payload: bytes,
+        *,
+        key: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> MessageId:
+        """Insert a row using *your* connection, inside *your* transaction."""
+        cur = conn.execute(
+            f"INSERT INTO {self.table} (topic, key, payload, headers, created_at)"
+            " VALUES (?, ?, ?, ?, ?)",
+            (topic, key, payload, json.dumps(dict(headers or {})), _now()),
+        )
+        return cur.lastrowid
+
+    async def add(
+        self,
+        topic: str,
+        payload: bytes,
+        *,
+        key: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> MessageId:
+        """Insert a row on the storage's own connection. Handy for demos and tests."""
+
+        def _add() -> MessageId:
+            with self._lock:
+                return self.insert(self._conn, topic, payload, key=key, headers=headers)
+
+        return await asyncio.to_thread(_add)
+
+    # -- Storage protocol --------------------------------------------------------------
+
+    async def claim(
+        self, *, batch_size: int, lease: timedelta, worker_id: str
+    ) -> Sequence[OutboxMessage]:
+        return await asyncio.to_thread(self._claim, batch_size, lease, worker_id)
+
+    async def ack(self, ids: Sequence[MessageId]) -> None:
+        if not ids:
+            return
+        if self.delete_on_ack:
+            sql = f"DELETE FROM {self.table} WHERE id = ?"
+        else:
+            sql = (
+                f"UPDATE {self.table} SET status = 'done', leased_by = NULL, lease_until = NULL"
+                " WHERE id = ?"
+            )
+        await asyncio.to_thread(self._executemany, sql, [(i,) for i in ids])
+
+    async def nack(self, message_id: MessageId, *, error: str, retry_at: datetime) -> None:
+        await asyncio.to_thread(
+            self._execute,
+            f"UPDATE {self.table} SET retry_at = ?, last_error = ?, leased_by = NULL,"
+            " lease_until = NULL WHERE id = ?",
+            (retry_at.timestamp(), error, message_id),
+        )
+
+    async def dead_letter(self, message_id: MessageId, *, error: str) -> None:
+        await asyncio.to_thread(
+            self._execute,
+            f"UPDATE {self.table} SET status = 'dead', last_error = ?, leased_by = NULL,"
+            " lease_until = NULL WHERE id = ?",
+            (error, message_id),
+        )
+
+    # -- internals ---------------------------------------------------------------------
+
+    def _claim(self, batch_size: int, lease: timedelta, worker_id: str) -> list[OutboxMessage]:
+        t = self.table
+        now = _now()
+        blocked = (
+            f" AND (o.key IS NULL OR NOT EXISTS (SELECT 1 FROM {t} p WHERE p.key = o.key"
+            " AND p.id < o.id AND p.status = 'pending'"
+            " AND (p.retry_at > :now OR p.lease_until > :now)))"
+            if self.strict_ordering
+            else ""
+        )
+        select = (
+            f"SELECT o.id FROM {t} o WHERE o.status = 'pending'"
+            " AND (o.retry_at IS NULL OR o.retry_at <= :now)"
+            " AND (o.lease_until IS NULL OR o.lease_until <= :now)"
+            f"{blocked} ORDER BY o.id LIMIT :limit"
+        )
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                ids = [r[0] for r in self._conn.execute(select, {"now": now, "limit": batch_size})]
+                if not ids:
+                    self._conn.execute("COMMIT")
+                    return []
+                marks = ",".join("?" * len(ids))
+                self._conn.execute(
+                    f"UPDATE {t} SET attempts = attempts + 1, leased_by = ?, lease_until = ?,"
+                    f" retry_at = NULL WHERE id IN ({marks})",
+                    (worker_id, now + lease.total_seconds(), *ids),
+                )
+                rows = self._conn.execute(
+                    f"SELECT id, topic, key, payload, headers, attempts, created_at FROM {t}"
+                    f" WHERE id IN ({marks}) ORDER BY id",
+                    ids,
+                ).fetchall()
+                self._conn.execute("COMMIT")
+            except BaseException:
+                self._conn.execute("ROLLBACK")
+                raise
+        return [_row_to_message(row) for row in rows]
+
+    def _execute(self, sql: str, params: tuple[Any, ...]) -> None:
+        with self._lock:
+            self._conn.execute(sql, params)
+
+    def _executemany(self, sql: str, params: list[tuple[Any, ...]]) -> None:
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                self._conn.executemany(sql, params)
+                self._conn.execute("COMMIT")
+            except BaseException:
+                self._conn.execute("ROLLBACK")
+                raise
+
+
+def _now() -> float:
+    return datetime.now(UTC).timestamp()
+
+
+def _row_to_message(row: tuple[Any, ...]) -> OutboxMessage:
+    message_id, topic, key, payload, headers, attempts, created_at = row
+    return OutboxMessage(
+        id=message_id,
+        topic=topic,
+        payload=bytes(payload),
+        key=key,
+        headers=json.loads(headers),
+        attempts=attempts,
+        created_at=datetime.fromtimestamp(created_at, tz=UTC),
+    )

txoutbox/backoff.py

@@ -0,0 +1,38 @@
+"""Retry delay policy."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from datetime import timedelta
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Backoff:
+    """Exponential backoff with full jitter.
+
+    Delay for attempt ``n`` (1-based) is ``min(base * factor ** (n - 1), maximum)``,
+    multiplied by a random factor in ``[1 - jitter, 1 + jitter]``.
+    """
+
+    base: timedelta = timedelta(seconds=1)
+    factor: float = 2.0
+    maximum: timedelta = timedelta(minutes=5)
+    jitter: float = 0.25
+
+    def __post_init__(self) -> None:
+        if self.factor < 1:
+            raise ValueError("factor must be >= 1")
+        if not 0 <= self.jitter <= 1:
+            raise ValueError("jitter must be within [0, 1]")
+        if self.base <= timedelta(0):
+            raise ValueError("base must be positive")
+
+    def delay(self, attempt: int) -> timedelta:
+        if attempt < 1:
+            raise ValueError("attempt is 1-based")
+        raw = self.base.total_seconds() * self.factor ** (attempt - 1)
+        capped = min(raw, self.maximum.total_seconds())
+        if self.jitter:
+            capped *= random.uniform(1 - self.jitter, 1 + self.jitter)
+        return timedelta(seconds=capped)

txoutbox/message.py

@@ -0,0 +1,33 @@
+"""The message record that flows from storage to publisher."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from types import MappingProxyType
+from typing import Any
+
+#: Identifier of an outbox row. Opaque to the relay: it only passes ids back to storage.
+MessageId = Any
+
+_EMPTY_HEADERS: Mapping[str, str] = MappingProxyType({})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutboxMessage:
+    """One row of the outbox table, as seen by the relay.
+
+    Storage adapters build these from their rows; publishers receive them.
+    Everything except ``id``, ``topic`` and ``payload`` is optional.
+    """
+
+    id: MessageId
+    topic: str
+    payload: bytes
+    #: Ordering key. Messages sharing a key are published sequentially, in claim order.
+    key: str | None = None
+    headers: Mapping[str, str] = field(default_factory=lambda: _EMPTY_HEADERS)
+    #: How many times this message has been claimed, including the current claim.
+    attempts: int = 1
+    created_at: datetime | None = None