Two concurrent callers with the same key both run the action: an in-flight reservation is needed

[AlexeyShalaev]

Measured on 0.2.0 with the Redis repository. Two identical calls, same operation and key, 50 ms apart, with an action that takes 300 ms (a payment provider round trip):

--- two identical requests, 50 ms apart, same key ---
responses: ['ch_1', 'ch_1']
charges made by the provider: 2 -> ['ch_1', 'ch_2']

Both callers got the same response, and the card was charged twice. Rule 2 on the agents page says exactly this will happen, and the "WRONG — treating the decorator as a mutex" example shows it, so this is a known consequence of the design: the check is a GET, the write is a SET NX after the action, and nothing marks the key as taken in between. But the case that matters most for an idempotency key is a client that timed out and retried while the original is still in flight, and that is precisely the window where the library runs the action twice. The architecture page also still says the pattern "ensures at-most-once or exactly-once semantics", which the measurement contradicts.

What I think it needs is an in-flight reservation: before running the action, SET NX a pending marker under the same key with a lease (say 30 s, configurable), then run, then replace the marker with the final record. A second caller that finds a pending marker either waits for the final record (poll with a bound, the lease) or fails fast with a new IdempotencyInProgressError that an HTTP layer maps to 409, which is what Stripe does. An action that raises deletes the marker so the retry runs again, consistent with "failures are not cached". A marker whose lease expired is treated as absent, so a crashed worker cannot wedge a key. The mode belongs on the coordinator (in_flight="wait" | "raise", plus the lease); I lean towards reservation on by default in the next minor, with the old both-run behaviour available as in_flight="run" for callers whose action is genuinely safe to repeat, because a default that double-charges is the wrong default even when documented. Rule 2, the mutex example and the architecture page follow the code.

Script: measure.py in https://github.com/bedrock-python/bedrock-python.github.io/tree/docs/production-python-series/docs/blog/lab/2026-09-07-idempotency-keys. Related: the fingerprint issue filed alongside this one.

[AlexeyShalaev]

Reproduced on master with your script: charges made by the provider: 2. Here is what I intend to build; shout if any of it does not match what you had in mind.

The reservation is a record in a pending state, not a second key. IdempotencyRecord gets status: Literal["pending", "completed"] = "completed", so a marker is {"status": "pending", "result": null, "expires_at": now + lease, ...} under the very same storage key, and a record written before this change still decodes as completed. The coordinator reserves first rather than reading first: SET NX the pending record with the lease as its TTL, run the action, then write the final record over it with a new repository method, replace(record), which is save without NX. Reserve-first keeps a miss at two round trips, same as today's GET + SET NX; a hit costs two instead of one, and hits are the rare path. When the reservation collides, the coordinator reads the key: a completed record is a hit and is returned; a pending one is handled by the mode; nothing usable (the holder just abandoned it, or the record is undecodable, or storage failed) means the action runs unreserved and the result is written with replace, which also heals a stale-shape record instead of re-running until it expires.

Mode and lease sit on the coordinator: in_flight="wait" | "raise" | "run", in_flight_lease_seconds=30, both also on BaseIdempotencySettings and the Dishka provider. wait polls the key every 50 ms until the marker becomes a record (hit), disappears (the holder's action raised and it deleted the marker, or the lease ran out: the waiter tries to reserve and run itself) or the waiter has spent a full lease, at which point it raises IdempotencyInProgressError. raise raises it as soon as a pending marker is seen, which is the 409 shape. run is today's flow verbatim, GET then SET NX after the action, for actions that are genuinely safe to repeat. An action that raises deletes the marker before re-raising, cancellation included, so the retry runs again. IdempotencyInProgressError carries operation and key and does propagate out of coordinate() and the decorator: it is a decision about the caller's request, not storage trouble, so rule 6 stays true for what it is about.

I am going with wait as the default, as you lean. The retry-while-in-flight window is the one an idempotency key exists for, and a default that runs the effect twice there is wrong however well the agents page says so. The cost lands only on the duplicate caller, which waits for the winner's result instead of producing a second one, and in_flight="run" is one argument away for anyone who wants the old flow. This is a pre-1.0 minor with bump-minor-pre-major, same as the TTL change in 0.2.0, and the PR will carry an upgrade note. Two things the note has to say: a custom repository needs replace, and the coordinator raises TypeError at construction when the repository lacks it and the mode is not run, so that failure is at startup rather than a 30 s hang on every retry; and during a rolling upgrade an instance still on 0.2.x reads a pending marker as a completed record with a null result, which PydanticResultAdapter turns into a decode failure and a miss (today's behaviour) but JsonResultAdapter would replay as None, so either finish the rollout before relying on it or roll out with in_flight="run" and switch after.

Metrics: no new counter. IdempotencyMetricsProtocol is implemented by hand in the user guide, so a new method breaks every custom collector for an outcome that is already visible. record_collision keeps its meaning of two callers on one key at the same time and is what the second caller records when it finds a pending marker; a waiter that gets the record then records a hit as any hit does, and a refusal is the exception the application already counts as a 409. The reservation is timed under method="reserve", and a failed reservation or release shows up as storage_reserve_error / storage_release_error.

Rejected: a separate lock key or lock protocol (two keys per operation, two concepts, and cluster hash slots to worry about; a pending record is one concept and one key); a fencing token checked with a Lua script on the final write and the delete, which would only matter when the lease is shorter than the action, a misconfiguration that already degrades to exactly today's behaviour, and is not worth a lupa dependency on the test suite right now. Rule 2, the mutex example, the architecture page's "exactly-once" sentence and the user guide all get rewritten to follow the code, and the PR will paste your script's output before and after.

[AlexeyShalaev]

#28 is up. Your script against that branch, unmodified:

--- two identical requests, 50 ms apart, same key ---
responses: ['ch_1', 'ch_1']
charges made by the provider: 1 -> ['ch_1']

It is what the plan said, with one thing I only found by running the suite: when the result cannot be stored (a None under PydanticResultAdapter, an out-of-range TTL) the coordinator now deletes its own reservation too, otherwise every retry within the lease waited for a record that was never coming. The default is wait, in_flight="run" is the old flow, the lease is 30 s and has to outlive the action; the second caller's collision is the metric, no new counter. The PR title carries the !, and the commit's BREAKING CHANGE: footer holds the migration text: in_flight="run" to keep the previous behaviour, replace() on a custom repository, and finishing a rolling upgrade before relying on the reservation because a 0.2.x instance reads a pending record as a completed null.

Nothing changes on your side for the measurement. For a service, the one decision is whether a retry that lands mid-flight should wait or get a 409 — in_flight="raise" for the latter, and IdempotencyInProgressError is the exception to map.

The second block of your script, the reused key with amount 5, is #27; it goes on a branch based on this one.