br-atomic-idempotency

better-route: atomic idempotency

Use atomic idempotency for writes whose side effect must not execute twice under concurrent retries. It reserves before invoking the handler; classic IdempotencyMiddleware only stores after completion.

Production setup

use BetterRoute\Middleware\Write\AtomicIdempotencyMiddleware;
use BetterRoute\Middleware\Write\WpdbAtomicIdempotencyStore;

register_activation_hook(__FILE__, static function (): void {
    (new WpdbAtomicIdempotencyStore())->installSchema();
});

$atomic = new AtomicIdempotencyMiddleware(
    store: new WpdbAtomicIdempotencyStore(),
    ttlSeconds: 86400,
    requireKey: true,
);

$router->post('/payments', $handler)
    ->protectedByMiddleware('bearerAuth')
    ->middleware([$auth, $atomic]);

Run installSchema() for both new installs and 1.0 upgrades. The 1.1 table has a per-reservation reservation_token; the installer creates or migrates that column.

Use ArrayAtomicIdempotencyStore only in tests or non-WordPress single-process checks.

Behavior

• First request reserves the canonical route + identity + client key and runs the handler.
• Same key and fingerprint while reserved returns 409 idempotency_in_progress.
• Same key with a different fingerprint returns 409 idempotency_conflict.
• Completed identical retry replays status/body/headers and adds Idempotency-Replayed: true.
• Missing key returns 400 idempotency_key_required when required.
• Invalid, non-printable, or overlong keys return 400 idempotency_key_invalid; default maximum length is 200.

The default fingerprint deeply canonicalizes route, method, identity, and request params. Associative key order does not change it; list order remains meaningful. Native logged-in WordPress users, auth middleware identities, and HMAC key identities scope defaults safely.

Failure semantics

In 1.1 releaseOnThrowable defaults to false. A thrown exception can occur after an irreversible external side effect but before the response is recorded, so the reservation remains in_progress until TTL rather than allowing a dangerous automatic retry.