Idempotency & 'Exactly-Once' That Survives Contact

Idempotency keys: making a retry a no-op

The fix for the double charge is to make the operation idempotent: running it twice has the same effect as running it once. For naturally idempotent operations (set the address to X, delete order 7) you get this free — repeating them changes nothing. For operations with side effects that aren’t naturally idempotent — charge a card, send an email, increment a balance — you make them idempotent with a client-supplied idempotency key: a unique token the client generates per logical operation and reuses on every retry of it.

The server records the key the first time it sees it, performs the side effect, and stores the response — all atomically. Every subsequent request with that key returns the stored response without re-running the side effect. The lifecycle of that key is the whole pattern:

1func (s *Store) Charge(key string, amount int) ChargeResult {
2  if rec, ok := s.idem[key]; ok {
3    if rec.status == statusCompleted {
4      return ChargeResult{Response: rec.response, Replayed: true} // replay
5    }
6    return ChargeResult{Conflict: true} // original still running -> 409
7  }
8  // claim the key, do the side effect, enqueue the event, store the
9  // response — modeled single-threaded, but in production ONE transaction:
10  s.idem[key] = &idemRecord{status: statusInProgress}
11  s.ledger = append(s.ledger, fmt.Sprintf("charged %d (key=%s)", amount, key))
12  s.outbox.Add(fmt.Sprintf("charge.created amount=%d key=%s", amount, key))
13  resp := fmt.Sprintf("ok: charged %d", amount)
14  s.idem[key].status = statusCompleted
15  s.idem[key].response = resp
16  return ChargeResult{Response: resp}
17}

The Effectively-Once Triangle

Idempotency keys handle the synchronous request path. But the charge probably also emits an event — charge.created — that other services consume (email a receipt, update analytics, credit a referral). Now you have two new ways to leak a duplicate or lose an event entirely, and fixing them requires two more pieces. Together they form a triangle: remove any vertex and duplicates (or losses) leak through.

What this sounds like in an interview

Exercises

1async function charge(key: string, amount: number) {
2  // check if we've seen this idempotency key
3  const existing = await db.query("SELECT response FROM idem WHERE key = $1", [key])
4  if (existing) {
5    return existing.response               // replay
6  }
7  // not seen -> do the charge
8  const resp = await paymentGateway.charge(amount)
9  await db.query("INSERT INTO idem (key, response) VALUES ($1, $2)", [key, resp])
10  return resp
11}