oncely 0.1.0__tar.gz

oncely-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: oncely
+          POSTGRES_PASSWORD: oncely
+          POSTGRES_DB: oncely_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U oncely"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src tests
+      - run: uv run pytest
+      - run: uv build

oncely-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+
+# Publishing a GitHub release builds the package and uploads it to PyPI.
+# No token is stored anywhere: PyPI trusts this workflow in this repository
+# (trusted publishing), and checks that on every upload.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

oncely-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dump.rdb

oncely-0.1.0/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.

oncely-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,172 @@
+# 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/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "oncely"
+version = "0.1.0"
+description = "Idempotency keys and a transactional outbox for async SQLAlchemy and Postgres."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["idempotency", "outbox", "sqlalchemy", "postgres", "redis", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Typing :: Typed",
+]
+dependencies = ["sqlalchemy[asyncio]>=2.0.36"]
+
+[project.urls]
+Homepage = "https://github.com/tiff-xt/oncely"
+Issues = "https://github.com/tiff-xt/oncely/issues"
+
+[project.optional-dependencies]
+# The outbox publishes through any async function. This extra adds the
+# ready-made Redis Streams publisher and consumer.
+redis = ["redis>=5.2"]
+
+[dependency-groups]
+dev = [
+    "asyncpg>=0.30",
+    "redis>=5.2",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.9",
+    "mypy>=1.14",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oncely"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC", "S", "RUF", "PT", "T20"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S608"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

oncely-0.1.0/src/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",
+]