once

Run any side effect exactly once — even when 1,000 callers demand it at the same instant.

⚡ once — STORM DEMO
1,000 concurrent attempts to charge order #777 ($49.00)

ACTUAL EXECUTIONS   :      1   ← the whole point
served same answer  :  1,000 / 1,000
elapsed             :   0.1s

💰 double-spend prevented this run: $48,951.00

That's not a mock — it's a live attack you can run right now:

pip install once-kernel
python -m once.demo

The problem

Networks retry. Users double-click. Queues redeliver. AI agents re-fire tools at machine speed. Any of these turns one payment into two, one email into three, one server into two hundred.

Most teams hand-roll an idempotency table — and most of those are quietly broken under concurrent load: two identical requests both pass the "already done?" check, then both execute. The bugs are subtle, the failures are money.

once is that table done right, once, for everyone — a tiny idempotency kernel with the four defenses hand-rolled versions miss:

1. Atomic leader election — concurrent duplicates can't all pass the check; exactly one executes, the rest coalesce onto its result.
2. Payload fingerprinting (RFC 8785) — same key with a different body is a hard IdempotencyConflict, never someone else's cached answer.
3. Fence tokens + generations — a crashed worker's lease can be taken over, and when the "dead" worker wakes up late, it is locked out of corrupting the record.
4. Honest failure states — a failed attempt frees the key for retry; an unknown outcome never silently re-runs.

Use it

from once import Once

o = Once()

def charge():
    return gateway.charge(order_id="ord_1", amount_cents=4900)

# Retries, double submits, webhook redelivery, agent fan-out → runs ONCE
result = o.run("pay:ord_1", {"order": "ord_1", "amount_cents": 4900}, charge)

One box, several processes, no database server — SQLite, nothing to install:

from once import Once
from once.sqlite import SqliteStore

o = Once(SqliteStore("/var/lib/myapp/once.db"))  # schema auto-created

Survives restarts and works across processes (WAL mode). The default MemoryStore does neither — it is per-process, so the moment you run a second worker each one keeps its own private idea of what already ran, and the guard silently stops guarding.

Several machines — share state through the Postgres you already run:

from once import Once
from once.pg import PostgresStore

o = Once(PostgresStore("postgresql://user:pass@host/db"))  # table auto-created

Async (FastAPI, agents) — sync side effects go to a worker thread, waiters park on the event loop (no thread-pool starvation under duplicate storms; there's a test that proves it):

from once import AsyncOnce

ao = AsyncOnce()
result = await ao.run("pay:ord_1", payload, charge)

→ The full 5-minute guide

What you can rely on

The honest model (put this o

... View full README on GitHub