oncely 0.1.0__py3-none-any.whl

oncely/__init__.py

@@ -0,0 +1,34 @@
+"""Idempotency keys and a transactional outbox for async SQLAlchemy and Postgres.
+
+Two small tools for the same problem: a network that retries.
+
+- `IdempotencyKeys` runs a piece of work once per key and gives every retry
+  the first answer.
+- `Outbox` records an event in the same transaction as the change it
+  describes, and a relay publishes it afterwards, at least once.
+
+`oncely.streams` adds a Redis Streams publisher and a consumer with
+retries and a dead-letter stream. It needs the `redis` extra.
+"""
+
+from oncely.idempotency import (
+    IdempotencyKeys,
+    KeyReused,
+    Outcome,
+    Refused,
+    fingerprint,
+    is_valid_key,
+)
+from oncely.outbox import Event, Outbox, Publisher
+
+__all__ = [
+    "Event",
+    "IdempotencyKeys",
+    "KeyReused",
+    "Outbox",
+    "Outcome",
+    "Publisher",
+    "Refused",
+    "fingerprint",
+    "is_valid_key",
+]

oncely/idempotency.py

@@ -0,0 +1,170 @@
+"""Idempotency keys: a retried request gets the first response and does nothing else.
+
+The key row, the work and the stored response all commit in one transaction,
+so there is no state in which the work happened but the key was not recorded,
+or the reverse.
+"""
+
+import hashlib
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import timedelta
+
+from sqlalchemy import (
+    Column,
+    Integer,
+    LargeBinary,
+    MetaData,
+    Table,
+    Text,
+    delete,
+    func,
+    select,
+    update,
+)
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession
+
+_KEY_FORMAT = re.compile(r"^[\x21-\x7e]{8,255}$")  # printable ASCII, no spaces
+
+
+def is_valid_key(key: str) -> bool:
+    """Whether a client-supplied key is usable: 8 to 255 printable characters."""
+    return _KEY_FORMAT.match(key) is not None
+
+
+def fingerprint(*parts: str | bytes) -> bytes:
+    """A digest of what the request asks for, e.g. method, path and body.
+
+    Stored with the key, so the same key arriving with a different request is
+    recognised as a client bug instead of being answered as a retry.
+    """
+    digest = hashlib.sha256()
+    for part in parts:
+        data = part.encode() if isinstance(part, str) else part
+        # Length-prefixed, so ("ab", "c") and ("a", "bc") differ.
+        digest.update(len(data).to_bytes(8, "big"))
+        digest.update(data)
+    return digest.digest()
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome:
+    """The response for a key: the status and body first produced for it."""
+
+    status: int
+    body: str
+    #: True when this call did no work and is repeating an earlier answer.
+    replayed: bool
+
+
+class Refused(Exception):
+    """Raise from the work to give a final answer that is not a success.
+
+    "That seat is taken" is as final as "here is your order": the work's
+    writes are undone, the refusal is stored, and every retry gets it again.
+    Any other exception is treated as a crash: nothing is stored, and a retry
+    runs the work from scratch.
+    """
+
+    def __init__(self, status: int, body: str) -> None:
+        super().__init__(f"refused with status {status}")
+        self.status = status
+        self.body = body
+
+
+class KeyReused(Exception):
+    """The key was already used for a different request."""
+
+
+class IdempotencyKeys:
+    """A table of keys, attached to your metadata so your migrations create it.
+
+    `scope` separates one caller's keys from another's (a user id, a tenant, an
+    API client), so two callers choosing the same key never see each other's
+    responses.
+    """
+
+    def __init__(self, metadata: MetaData, *, table_name: str = "idempotency_keys") -> None:
+        self.table = Table(
+            table_name,
+            metadata,
+            Column("scope", Text, primary_key=True),
+            Column("key", Text, primary_key=True),
+            Column("request_hash", LargeBinary, nullable=False),
+            Column("response_code", Integer),
+            # Text, exactly as first sent, so a replay is byte for byte the
+            # same response (jsonb would reorder the keys).
+            Column("response_body", Text),
+            Column(
+                "created_at",
+                TIMESTAMP(timezone=True),
+                server_default=func.now(),
+                nullable=False,
+                index=True,
+            ),
+        )
+
+    async def run(
+        self,
+        session: AsyncSession,
+        *,
+        scope: str,
+        key: str,
+        fingerprint: bytes,
+        work: Callable[[], Awaitable[tuple[int, str]]],
+    ) -> Outcome:
+        """Run `work` once per (scope, key) and return its answer on every call.
+
+        `work` returns (status, body). The caller owns the transaction: commit
+        it and the answer is permanent, roll it back and the key is free again.
+        Raises `KeyReused` if the key was first seen with another fingerprint.
+        """
+        t = self.table
+        mine = (t.c.scope == scope) & (t.c.key == key)
+
+        # If another request with this key is in flight, this insert waits for
+        # it to finish. Then either it committed (no row comes back and its
+        # response is replayed) or it rolled back (the row is ours, and so is
+        # the work).
+        claimed = await session.execute(
+            pg_insert(t)
+            .values(scope=scope, key=key, request_hash=fingerprint)
+            .on_conflict_do_nothing()
+            .returning(t.c.key)
+        )
+        if claimed.first() is None:
+            stored = (
+                await session.execute(
+                    select(t.c.request_hash, t.c.response_code, t.c.response_body).where(mine)
+                )
+            ).one()
+            if bytes(stored.request_hash) != fingerprint:
+                raise KeyReused(key)
+            if stored.response_code is None or stored.response_body is None:
+                # Cannot happen: the row and its response commit together.
+                raise RuntimeError("idempotency key stored without a response")
+            return Outcome(stored.response_code, stored.response_body, replayed=True)
+
+        try:
+            # A savepoint: if the work is refused, its partial writes are
+            # undone but the key row survives to record the refusal.
+            async with session.begin_nested():
+                status, body = await work()
+        except Refused as refusal:
+            status, body = refusal.status, refusal.body
+
+        await session.execute(
+            update(t).where(mine).values(response_code=status, response_body=body)
+        )
+        return Outcome(status, body, replayed=False)
+
+    async def prune(self, session: AsyncSession, *, older_than: timedelta) -> int:
+        """Delete keys past the retry window. Returns how many were removed."""
+        t = self.table
+        deleted = await session.execute(
+            delete(t).where(t.c.created_at < func.now() - older_than).returning(t.c.key)
+        )
+        return len(deleted.all())

oncely/outbox.py

@@ -0,0 +1,162 @@
+"""Transactional outbox.
+
+An event is written to a table in the same transaction as the change it
+describes, so it exists if and only if the change happened. A relay then
+hands events to a publisher. Delivery is at least once: every consumer must
+be safe to run twice.
+"""
+
+import os
+import threading
+import time
+import uuid
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any
+
+from sqlalchemy import (
+    Column,
+    Index,
+    MetaData,
+    Table,
+    Text,
+    Uuid,
+    delete,
+    func,
+    select,
+    text,
+    update,
+)
+from sqlalchemy.dialects.postgresql import JSONB, TIMESTAMP
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+_last_id = 0
+_last_id_lock = threading.Lock()
+
+
+def uuid7() -> uuid.UUID:
+    """A time-ordered UUID (RFC 9562), so id order is creation order.
+
+    Two ids made in the same millisecond would otherwise be ordered by their
+    random bits, so within a process each id is also made greater than the
+    one before it. Across processes, order is to the millisecond.
+    """
+    global _last_id
+    millis = time.time_ns() // 1_000_000
+    rand = int.from_bytes(os.urandom(10))
+    value = (millis & ((1 << 48) - 1)) << 80
+    value |= 0x7 << 76
+    value |= (rand >> 68) << 64
+    value |= 0b10 << 62
+    value |= rand & ((1 << 62) - 1)
+    with _last_id_lock:
+        if value <= _last_id:
+            value = _last_id + 1
+        _last_id = value
+    return uuid.UUID(int=value)
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    id: uuid.UUID
+    topic: str
+    payload: dict[str, Any]
+    #: Context that travels with the event and is not part of its meaning:
+    #: a trace id, a tenant, a schema version.
+    headers: dict[str, str] | None = None
+
+
+#: Sends a batch somewhere durable: a stream, a queue, a webhook. If it
+#: raises, nothing is marked published and the batch is offered again.
+Publisher = Callable[[Sequence[Event]], Awaitable[None]]
+
+
+class Outbox:
+    """A table of events, attached to your metadata so your migrations create it."""
+
+    def __init__(self, metadata: MetaData, *, table_name: str = "outbox") -> None:
+        self.table = Table(
+            table_name,
+            metadata,
+            Column("id", Uuid, primary_key=True),
+            Column("topic", Text, nullable=False),
+            Column("payload", JSONB, nullable=False),
+            Column("headers", JSONB),
+            Column(
+                "created_at", TIMESTAMP(timezone=True), server_default=func.now(), nullable=False
+            ),
+            Column("published_at", TIMESTAMP(timezone=True)),
+            # The relay's only query: oldest unpublished first. Partial, so it
+            # stays tiny however many events have already been published.
+            Index(f"{table_name}_pending_idx", "id", postgresql_where=text("published_at IS NULL")),
+        )
+
+    async def emit(
+        self,
+        session: AsyncSession,
+        topic: str,
+        payload: dict[str, Any],
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> uuid.UUID:
+        """Record an event. It is published only if the caller's transaction commits."""
+        event_id = uuid7()
+        await session.execute(
+            self.table.insert().values(id=event_id, topic=topic, payload=payload, headers=headers)
+        )
+        return event_id
+
+    async def relay_once(
+        self,
+        sessionmaker: async_sessionmaker[AsyncSession],
+        publish: Publisher,
+        *,
+        batch: int = 100,
+    ) -> list[Event]:
+        """Publish one batch of pending events, oldest first. Returns them.
+
+        If the process dies after publishing but before the commit that marks
+        the rows, they are published again next time. That is the "at least
+        once".
+        """
+        t = self.table
+        async with sessionmaker.begin() as session:
+            rows = (
+                await session.execute(
+                    select(t.c.id, t.c.topic, t.c.payload, t.c.headers)
+                    .where(t.c.published_at.is_(None))
+                    .order_by(t.c.id)
+                    .limit(batch)
+                    # Several relays can run: each takes rows the others have not.
+                    .with_for_update(skip_locked=True)
+                )
+            ).all()
+            if not rows:
+                return []
+            events = [Event(row.id, row.topic, row.payload, row.headers) for row in rows]
+            await publish(events)
+            await session.execute(
+                update(t)
+                .where(t.c.id.in_([event.id for event in events]))
+                .values(published_at=func.now())
+            )
+            return events
+
+    async def lag_seconds(self, session: AsyncSession) -> float:
+        """Age of the oldest unpublished event. The outbox's key health number."""
+        t = self.table
+        oldest = await session.scalar(
+            select(func.extract("epoch", func.now() - func.min(t.c.created_at))).where(
+                t.c.published_at.is_(None)
+            )
+        )
+        return float(oldest or 0)
+
+    async def prune(self, session: AsyncSession, *, older_than: timedelta) -> int:
+        """Delete events published longer ago than this. Returns how many."""
+        t = self.table
+        deleted = await session.execute(
+            delete(t).where(t.c.published_at < func.now() - older_than).returning(t.c.id)
+        )
+        return len(deleted.all())

oncely/streams.py

@@ -0,0 +1,178 @@
+"""Redis Streams: a publisher for the outbox relay, and a consumer.
+
+The consumer uses a consumer group: each event goes to one worker, stays
+"pending" until that worker acknowledges it, and can be taken over by another
+worker if the first one dies. An event whose handlers keep failing is moved
+to a dead-letter stream after a fixed number of attempts, so one poison
+message cannot block the rest or retry forever.
+"""
+
+import asyncio
+import json
+import time
+import uuid
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, Literal
+
+from redis.asyncio import Redis
+from redis.exceptions import ResponseError
+
+from oncely.outbox import Event, Publisher
+
+Handler = Callable[[Event], Awaitable[None]]
+#: Wraps the handling of one event: open a span, bind log context, time it.
+Around = Callable[[Event, Callable[[], Awaitable[None]]], Awaitable[None]]
+Result = Literal["ok", "retry", "dead"]
+#: Told how each attempt ended and how long it took, for metrics and logs.
+#: `error` is the exception behind a "retry" or "dead".
+OnResult = Callable[[Event, Result, float, BaseException | None], None]
+
+
+def stream_publisher(redis: Redis, stream: str) -> Publisher:
+    """A publisher that appends each event to a Redis stream."""
+
+    async def publish(events: Sequence[Event]) -> None:
+        pipeline = redis.pipeline(transaction=False)
+        for event in events:
+            pipeline.xadd(stream, _encode(event))  # type: ignore[arg-type]
+        await pipeline.execute()
+
+    return publish
+
+
+def _encode(event: Event) -> dict[str, str]:
+    fields = {"id": str(event.id), "topic": event.topic, "payload": json.dumps(event.payload)}
+    if event.headers:
+        fields["headers"] = json.dumps(event.headers)
+    return fields
+
+
+def _decode(fields: dict[str, str]) -> Event:
+    return Event(
+        id=uuid.UUID(fields["id"]),
+        topic=fields["topic"],
+        payload=json.loads(fields["payload"]),
+        headers=json.loads(fields["headers"]) if "headers" in fields else None,
+    )
+
+
+class StreamConsumer:
+    """One worker in a consumer group. Run as many as you like.
+
+    Handlers must be safe to run twice: an event is delivered again if a
+    handler raised, if the worker died before acknowledging it, or if the
+    relay published it twice.
+    """
+
+    def __init__(
+        self,
+        redis: Redis,
+        *,
+        stream: str,
+        group: str = "workers",
+        consumer: str | None = None,
+        retry_after_ms: int = 30_000,
+        max_attempts: int = 5,
+        concurrency: int = 16,
+        dead_letter_stream: str | None = None,
+        around: Around | None = None,
+        on_result: OnResult | None = None,
+    ) -> None:
+        self.redis = redis
+        self.stream = stream
+        self.group = group
+        self.consumer = consumer or f"worker-{uuid.uuid4().hex[:8]}"
+        self.retry_after_ms = retry_after_ms
+        self.max_attempts = max_attempts
+        self.concurrency = concurrency
+        self.dead_letter_stream = dead_letter_stream or f"{stream}:dead"
+        self._attempts = f"{stream}:attempts"
+        self._around = around
+        self._on_result = on_result
+        self._handlers: dict[str, list[Handler]] = {}
+
+    def subscribe(self, topic: str, handler: Handler) -> None:
+        handlers = self._handlers.setdefault(topic, [])
+        if handler not in handlers:
+            handlers.append(handler)
+
+    async def _ensure_group(self) -> None:
+        try:
+            await self.redis.xgroup_create(self.stream, self.group, id="0", mkstream=True)
+        except ResponseError as exc:
+            if "BUSYGROUP" not in str(exc):  # already exists: fine
+                raise
+
+    async def run_once(self, *, count: int = 50, block_ms: int | None = None) -> int:
+        """Handle one batch: first events whose earlier attempt failed or whose
+        worker died, then new ones. Returns how many were settled (handled, or
+        given up on and dead-lettered)."""
+        await self._ensure_group()
+
+        # Take over anything delivered but not acknowledged for long enough.
+        claimed: Any = await self.redis.xautoclaim(
+            self.stream,
+            self.group,
+            self.consumer,
+            min_idle_time=self.retry_after_ms,
+            start_id="0-0",
+            count=count,
+        )
+        fresh: Any = await self.redis.xreadgroup(
+            self.group, self.consumer, {self.stream: ">"}, count=count, block=block_ms
+        )
+        messages: list[tuple[str, dict[str, str]]] = list(claimed[1])
+        messages += [message for _, batch in fresh for message in batch]
+
+        # Handlers mostly wait on the network, so a batch is worked on
+        # together, not one event at a time.
+        gate = asyncio.Semaphore(self.concurrency)
+
+        async def one(message_id: str, fields: dict[str, str]) -> bool:
+            async with gate:
+                if not fields:  # the entry was trimmed from the stream
+                    await self.redis.xack(self.stream, self.group, message_id)
+                    return False
+                return await self._handle(message_id, fields)
+
+        return sum(await asyncio.gather(*(one(*message) for message in messages)))
+
+    async def _handle(self, message_id: str, fields: dict[str, str]) -> bool:
+        event = _decode(fields)
+        started = time.perf_counter()
+
+        async def handlers() -> None:
+            for handler in self._handlers.get(event.topic, []):
+                await handler(event)
+
+        def report(result: Result, error: BaseException | None = None) -> None:
+            if self._on_result:
+                self._on_result(event, result, time.perf_counter() - started, error)
+
+        try:
+            if self._around:
+                await self._around(event, handlers)
+            else:
+                await handlers()
+        except Exception as exc:
+            attempts = await self.redis.hincrby(self._attempts, message_id, 1)
+            if attempts < self.max_attempts:
+                # Leave it pending. It is retried once it has been idle long enough.
+                report("retry", exc)
+                return False
+            dead: dict[Any, Any] = {**fields, "attempts": str(attempts)}
+            await self.redis.xadd(self.dead_letter_stream, dead)
+            report("dead", exc)
+        else:
+            report("ok")
+
+        # Reached on success, and after dead-lettering.
+        pipeline = self.redis.pipeline(transaction=False)
+        pipeline.xack(self.stream, self.group, message_id)
+        pipeline.hdel(self._attempts, message_id)
+        await pipeline.execute()
+        return True
+
+    async def trim(self, *, keep: int = 100_000) -> None:
+        """Bound the stream's size. Acknowledged entries are not needed again."""
+        await self.redis.xtrim(self.stream, maxlen=keep, approximate=True)

oncely-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: oncely
+Version: 0.1.0
+Summary: Idempotency keys and a transactional outbox for async SQLAlchemy and Postgres.
+Project-URL: Homepage, https://github.com/tiff-xt/oncely
+Project-URL: Issues, https://github.com/tiff-xt/oncely/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,idempotency,outbox,postgres,redis,sqlalchemy
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36
+Provides-Extra: redis
+Requires-Dist: redis>=5.2; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# oncely
+
+[![CI](https://github.com/tiff-xt/oncely/actions/workflows/ci.yml/badge.svg)](https://github.com/tiff-xt/oncely/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oncely)](https://pypi.org/project/oncely/)
+
+Idempotency keys and a transactional outbox for async SQLAlchemy and Postgres.
+
+Two small tools for the same problem: a network that retries.
+
+- **Idempotency keys.** A client that times out sends the request again. The
+  work runs once, and every retry gets the first answer, byte for byte.
+- **Transactional outbox.** "Save the order, then publish an event" can do one
+  without the other. Here the event is a row written in the same transaction
+  as the change, and a relay publishes it afterwards.
+
+About 400 lines, typed, no framework required. It was extracted from
+[lobbyd](https://github.com/tiff-xt/lobbyd), a ticketing backend, where it sits under every
+purchase and every payment.
+
+## Install
+
+```bash
+pip install "oncely[redis]"
+```
+
+The `redis` extra adds a Redis Streams publisher and consumer. Without it the
+package needs only SQLAlchemy 2 and a Postgres driver such as asyncpg.
+
+## Idempotency keys
+
+Attach the table to your metadata, so your own migrations create it:
+
+```python
+from oncely import IdempotencyKeys, Refused, fingerprint
+
+keys = IdempotencyKeys(Base.metadata)
+```
+
+Then wrap the work. This is a FastAPI route, but nothing here depends on it:
+
+```python
+@router.post("/orders", status_code=201)
+async def create_order(
+    body: NewOrder,
+    request: Request,
+    user: CurrentUser,
+    session: Session,
+    key: str = Header(alias="Idempotency-Key"),
+):
+    async def work() -> tuple[int, str]:
+        seat = await claim_seat(session, body.seat_id)
+        if seat is None:
+            raise Refused(409, '{"code": "seat_taken"}')
+        order = await place_order(session, user, seat)
+        return 201, order.model_dump_json()
+
+    outcome = await keys.run(
+        session,
+        scope=str(user.id),
+        key=key,
+        fingerprint=fingerprint(request.method, request.url.path, body.model_dump_json()),
+        work=work,
+    )
+    return Response(outcome.body, outcome.status, media_type="application/json")
+```
+
+What you get:
+
+| Situation | Result |
+| --- | --- |
+| First request | `work` runs. Its answer is stored in the same transaction as its writes. |
+| Retry after success | The stored answer. `work` does not run. `outcome.replayed` is true. |
+| Retry while the first is still running | Waits for the first to finish, then gets its answer. |
+| `work` raises `Refused` | Its writes are undone, the refusal is stored, and retries get it again. |
+| `work` raises anything else | Nothing is stored. The retry starts from scratch. |
+| Same key, different request | `KeyReused` is raised. That is a client bug, not a retry. |
+
+The caller owns the transaction. Commit, and the answer is permanent. Roll
+back, and the key is free again. There is no state in which the work happened
+but the key was not recorded.
+
+`scope` keeps callers apart: two users who pick the same key never see each
+other's responses. Run `keys.prune(session, older_than=timedelta(hours=24))`
+on a timer to drop keys past your retry window.
+
+## Transactional outbox
+
+```python
+from oncely import Outbox
+
+outbox = Outbox(Base.metadata)
+
+async with sessionmaker.begin() as session:
+    order.status = "paid"
+    await outbox.emit(session, "order.paid", {"order_id": str(order.id)})
+# Committed together, or not at all.
+```
+
+A relay moves events out. It takes any async function as the publisher:
+
+```python
+from oncely.streams import stream_publisher
+
+publish = stream_publisher(redis, "shop:events")
+
+while True:
+    if not await outbox.relay_once(sessionmaker, publish):
+        await asyncio.sleep(0.2)
+```
+
+- Events leave oldest first.
+- Run as many relays as you like. Rows are taken with `FOR UPDATE SKIP LOCKED`,
+  so two relays never publish the same batch.
+- If the publisher raises, nothing is marked and the batch is offered again.
+- If the process dies between publishing and committing, the batch is published
+  twice. Delivery is **at least once**, so handlers must be safe to repeat.
+- `outbox.lag_seconds(session)` is the age of the oldest unpublished event. It
+  is the one number worth an alert.
+
+`headers` on `emit` carries context that is not part of the event's meaning,
+such as a trace id, so a handler can continue the trace of the request that
+caused it.
+
+## Consuming from Redis Streams
+
+```python
+from oncely.streams import StreamConsumer
+
+worker = StreamConsumer(redis, stream="shop:events", max_attempts=5)
+
+
+async def send_receipt(event):
+    await mail.send(event.payload["order_id"])
+
+
+worker.subscribe("order.paid", send_receipt)
+
+while True:
+    await worker.run_once(block_ms=1000)
+```
+
+Each event goes to one worker in the group. If a handler raises, the event is
+retried after `retry_after_ms`. If its worker dies, another takes it over.
+After `max_attempts` it moves to `shop:events:dead`, so one bad message cannot
+block the rest. `around` wraps each event's handling (a span, log context) and
+`on_result` reports how each attempt ended (metrics).
+
+## What it does not do
+
+- **Exactly-once delivery.** Nothing does, across a network. The name refers to
+  the work behind a key, which does run once.
+- **Other databases.** It uses Postgres features on purpose: `ON CONFLICT`,
+  `SKIP LOCKED`, partial indexes.
+- **Migrations.** The tables join your metadata, and Alembic's autogenerate
+  picks them up like any other.
+
+## Tests
+
+The suite runs against a real Postgres and Redis, including the races: twelve
+retries of one key at once, and two relays competing for the same events.
+
+```bash
+ONCELY_TEST_DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db \
+ONCELY_TEST_REDIS_URL=redis://localhost:6379/14 \
+pytest
+```
+
+It works inside its own Postgres schema (`oncely_test`) and drops it when done.
+
+## License
+
+MIT

oncely-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+oncely/__init__.py,sha256=aWOcAqjM6Q5K5YVf4EVZl0F2FulvVotNTIpqJwq9fmc,863
+oncely/idempotency.py,sha256=Sq_zdaU9N2Nvjje4GKiObzJvLWJKLH64Lmwe8_ciJJs,6101
+oncely/outbox.py,sha256=UuUIwaou2OqhcGWso4uGxYppJRhgR3eGTCbSwfTUwnQ,5500
+oncely/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oncely/streams.py,sha256=1xCp7keC--1-uKynlu4xYwJid44W_C7k1GY5iIj9djI,6851
+oncely-0.1.0.dist-info/METADATA,sha256=sA1rETczjmke6PjsHPVgmlfqTb0vAexLFRTLJIrGB-M,6727
+oncely-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+oncely-0.1.0.dist-info/licenses/LICENSE,sha256=VnTfSF6NFjMEFwxncha8sClcZ9gAjCoR-WB8C9x8Tnc,1065
+oncely-0.1.0.dist-info/RECORD,,

oncely-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

oncely-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiff! :)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.