State & ArchitectureBaseline · Widely

Outbox Queues, Idempotency Keys & Causal Ordering

Mental Model

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.

Interactive Simulator

Outbox Queue & Idempotency Key Retry

Trace how an IndexedDB outbox persists a mutation key, survives a dropped response, and deduplicates on retry.

IDB Outbox [1]
Network Worker
API Server
Step 1 / 3: 1. Enqueue Intent with Fixed UUID

User submits order; client generates Idempotency-Key once, writes to IndexedDB, and updates UI optimistically.

await idb.put('outbox', { seq: 1, key: '9b1d-...', body });
Internal State / Memory
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.

  1. Deterministic key: Generate crypto.randomUUID() once at enqueue time and store it on the outbox record so every retry sends the identical Idempotency-Key header.
  2. Causal FIFO drain: Dispatch head-of-line mutations sequentially (or partitioned per entity ID) so UPDATE never overtakes CREATE on the wire.
  3. Terminal vs transient errors: Retry 5xx or network timeouts with exponential backoff; dequeue and roll back on 4xx validation rejections.
TS
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 fetch retry 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

Production Pitfall
  • 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
  • When not to use a durable outbox: For read-only telemetry, ephemeral typing indicators, or idempotent PUT autosaves where only the latest snapshot matters, overwrite a single debounced slot instead of maintaining a replay queue.

Connections & Logical Next Steps

State & ArchitectureOutbox Queues, Idempotency Keys & Causal Ordering
What This Unlocks
Leaf concept

Seen in Architecture Autopsies