# Br Atomic Idempotency

> Use better-route 0.5.0 AtomicIdempotencyMiddleware for high-side-effect write endpoints where concurrent duplicate requests must not execute twice. Triggers on AtomicIdempotencyMiddleware, WpdbAtomicIdempotencyStore, ArrayAtomicIdempotencyStore, AtomicIdempotencyStoreInterface, idempotency_in_progress, Idempotency-Key for payment/order/subscription/account-like writes, or when reviewing retry-saf…

- **Type:** Skill
- **Install:** `agentstack add skill-lonsdale201-wp-agent-skills-br-atomic-idempotency`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Lonsdale201](https://agentstack.voostack.com/s/lonsdale201)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Lonsdale201](https://github.com/Lonsdale201)
- **Source:** https://github.com/Lonsdale201/wp-agent-skills/tree/main/better-route/br-atomic-idempotency

## Install

```sh
agentstack add skill-lonsdale201-wp-agent-skills-br-atomic-idempotency
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# better-route: Atomic idempotency

Use this when a write route must reserve an `Idempotency-Key` before the handler runs. This is stronger than `IdempotencyMiddleware`, which is still useful as a replay cache but stores only after handler completion.

## Pick the middleware

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

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

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

Use `WpdbAtomicIdempotencyStore` in production. `ArrayAtomicIdempotencyStore` is for tests and local single-process checks only.

## Route pattern

```php
$router->post('/actions/confirm', $handler)
    ->middleware([$jwt, $atomic])
    ->protectedByMiddleware('bearerAuth');
```

Order matters: auth first, atomic idempotency after auth. The default storage key includes route path, authenticated identity, and the client key.

## Behavior

- First matching request reserves the key, then runs the handler.
- Same key and same fingerprint while the first request is running returns `409 idempotency_in_progress`.
- Same key and same fingerprint after completion replays the stored response.
- Same key with a different fingerprint returns `409 idempotency_conflict`.
- Missing key returns `400 idempotency_key_required` when `requireKey: true`.
- Thrown exceptions release the reservation by default so a client can retry.

## Rules

- Use this for side-effectful writes. Keep `IdempotencyMiddleware` for low-risk replay caching or backwards-compatible adoption.
- Install the DB schema on activation before the route is used.
- Keep TTL long enough for realistic client retries.
- Return `BetterRoute\Http\Response` when clients need replay headers such as `Idempotency-Replayed: true`.
- Use a custom `keyResolver` for tenant-scoped APIs where user ID alone is not enough.
- Use a custom `fingerprintResolver` if query/body defaults include unstable values.

## Source refs

- `libraries/better-route/src/Middleware/Write/AtomicIdempotencyMiddleware.php`
- `libraries/better-route/src/Middleware/Write/WpdbAtomicIdempotencyStore.php`
- `libraries/better-route/src/Middleware/Write/AtomicIdempotencyStoreInterface.php`
- `libraries/better-route/src/Middleware/Write/AtomicIdempotencyRecord.php`
- `libraries/better-route/tests/WriteSafetyMiddlewareTest.php`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Lonsdale201](https://github.com/Lonsdale201)
- **Source:** [Lonsdale201/wp-agent-skills](https://github.com/Lonsdale201/wp-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lonsdale201-wp-agent-skills-br-atomic-idempotency
- Seller: https://agentstack.voostack.com/s/lonsdale201
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.