Outbox Queues, Idempotency Keys & Causal Ordering
Firing independent fetch() calls for rapid edits lets slow earlier requests overwrite newer ones and turns retries into duplicate server records. A persistent FIFO outbox in IndexedDB serializes mutations in causal order, attaching one Idempotency-Key UUID per intent so retries remain safe.
Outbox Queue & Idempotency Key Retry
Trace how an IndexedDB outbox persists a mutation key, survives a dropped response, and deduplicates on retry.
User submits order; client generates Idempotency-Key once, writes to IndexedDB, and updates UI optimistically.
await idb.put('outbox', { seq: 1, key: '9b1d-...', body });- outboxLength
- 1
- idempotencyKey
- 9b1d-4c2a
- attempt
- 0
Under the Hood
An outbox separates intent capture from network delivery. When a user triggers a mutation, the client writes an immutable command record into IndexedDB and applies an Optimistic UI patch synchronously.
- Deterministic key: Generate
crypto.randomUUID()once at enqueue time and store it on the outbox record so every retry sends the identicalIdempotency-Keyheader. - Causal FIFO drain: Dispatch head-of-line mutations sequentially (or partitioned per entity ID) so
UPDATEnever overtakesCREATEon the wire. - Terminal vs transient errors: Retry
5xxor network timeouts with exponential backoff; dequeue and roll back on4xxvalidation rejections.
interface OutboxItem { id: string; key: string; payload: unknown }
async function drainOutbox(queue: OutboxItem[]) {
for (const item of queue) {
const res = await fetch('/api/orders', {
method: 'POST',
headers: { 'Idempotency-Key': item.key, 'Content-Type': 'application/json' },
body: JSON.stringify(item.payload),
});
if (res.status >= 500) break; // Keep head-of-line order; retry later
await removeFromIdbOutbox(item.id);
}
}Problem Genealogy
- 2014–2018 (Fire-and-Forget Retries): Naive
fetchretry wrappers regenerated request payloads on retry without keys, creating duplicate invoices when ACKs dropped on 3G networks. - 2019+ (Stripe & IETF
Idempotency-Key): Standardized client-generated UUID keys cached server-side for 24 hours to replay original responses safely. - 2022+ (Local-First Outboxes): Combined IndexedDB persistence with causal queues so mutations survive full browser restarts.
Production Pitfalls
- Duplicate records after mobile tunnel drop: Generating
crypto.randomUUID()inside the retry loop instead of at enqueue time gives each attempt a fresh key, defeating server deduplication. - Head-of-line blocking across unrelated entities: Sending all mutations through one global FIFO queue stalls a user's profile edit behind a failing 10 MB attachment upload.
- When not to use a durable outbox: For read-only telemetry, ephemeral typing indicators, or idempotent
PUTautosaves where only the latest snapshot matters, overwrite a single debounced slot instead of maintaining a replay queue.
Connections & Logical Next Steps
Queued mutations apply optimistic UI updates immediately and reconcile or roll back when the outbox drains.
Persisting the outbox inside IndexedDB readwrite transactions survives tab closes and offline periods.
Seen in Architecture Autopsies
Absent Idempotency-Key headers cause the payment gateway to treat retried TCP packets as two distinct charges.
Flaky cellular 4G retries replay outbox mutations without idempotency keys, duplicating or reordering operations.