HTTP Idempotency
Explained

// Exponential backoff with jitter — production ready
async function fetchWithRetry(url, options, maxRetries = 4) {
  const BASE_DELAY = 500   // ms
  const CAP       = 8000  // ms max delay

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch(url, options)

      // Don't retry client errors (4xx) — they won't change
      if (res.status >= 400 && res.status < 500) return res

      if (res.ok) return res

      throw new Error(`Server error: ${res.status}`)

    } catch (err) {
      if (attempt === maxRetries) throw err

      // Full jitter: random between 0 and capped exponential
      const exp   = Math.min(CAP, BASE_DELAY * 2 ** attempt)
      const delay = Math.random() * exp

      console.log(`Retry ${attempt + 1} in ${Math.round(delay)}ms`)
      await new Promise(r => setTimeout(r, delay))
    }
  }
}

// Usage — always pass idempotency key for non-GET requests
await fetchWithRetry('/payments', {
  method:  'POST',
  headers: {
    'Content-Type':    'application/json',
    'Idempotency-Key': crypto.randomUUID() // generated once, before first attempt
  },
  body: JSON.stringify({ amount: 2999, currency: 'INR' })
})

async function idempotencyMiddleware(req, res, next) {
  const key = req.headers['idempotency-key']
  if (!key) return next()

  const lockKey = `idem:lock:${key}`
  const resultKey = `idem:result:${key}`

  // Check for completed result first
  const cached = await client.get(resultKey)
  if (cached) {
    const { status, body } = JSON.parse(cached)
    return res.status(status).json(body)
  }

  // Atomically acquire lock — NX = only set if key doesn't exist
  const locked = await client.set(lockKey, '1', {
    NX: true, EX: 30 // 30s lock TTL
  })

  if (!locked) {
    // Another request is processing — tell client to retry shortly
    return res
      .status(409)
      .json({ error: 'Request in progress, retry after 1s' })
  }

  // Intercept response to persist result + release lock
  const originalJson = res.json.bind(res)
  res.json = async (body) => {
    await Promise.all([
      client.setEx(resultKey, 86400, JSON.stringify({ status: res.statusCode, body })),
      client.del(lockKey)
    ])
    return originalJson(body)
  }

  next()
}

// POST — creates a NEW order every call
// Call twice → two orders in the database
app.post('/orders', async (req, res) => {
  const order = await Order.create({
    userId: req.body.userId,
    items:  req.body.items,
    total:  req.body.total,
    status: 'pending'
  })
  res.status(201).json(order)
})

// PUT — replaces order at a known ID
// Call twice → same result, one order
app.put('/orders/:id', async (req, res) => {
  const order = await Order.findByIdAndReplace(
    req.params.id,
    { userId: req.body.userId, items: req.body.items, total: req.body.total },
    { new: true, upsert: true }
  )
  res.json(order)
})

Idempotency cheatsheet:

  GET / HEAD / PUT / DELETE  → idempotent by spec, honour it
  POST / PATCH               → not idempotent, add idempotency keys

  Idempotency key            → UUID generated by client, per action
  Server stores             → key + response in Redis, 24h TTL
  Duplicate arrives         → return cached response, skip execution
  In-flight race            → Redis SET NX lock, return 409 if locked

  Retry strategy            → exponential backoff + jitter
  Never retry               → 4xx errors (client's fault)
  Always retry              → network timeouts, 5xx with idempotency key

  Rule of thumb: if a retry can cause harm → add an idempotency key

// Express middleware — idempotency key handler
const redis = require('redis')
const client = redis.createClient()

async function idempotencyMiddleware(req, res, next) {
  const key = req.headers['idempotency-key']

  // No key — allow through (or reject depending on policy)
  if (!key) return next()

  const cached = await client.get(`idem:${key}`)

  if (cached) {
    // Duplicate request — return stored response
    const { status, body } = JSON.parse(cached)
    return res.status(status).json(body)
  }

  // Intercept res.json to cache the response
  const originalJson = res.json.bind(res)
  res.json = async (body) => {
    await client.setEx(
      `idem:${key}`,
      86400, // 24 hour TTL
      JSON.stringify({ status: res.statusCode, body })
    )
    return originalJson(body)
  }

  next()
}

// Apply to payment routes only
app.post('/payments', idempotencyMiddleware, async (req, res) => {
  const charge = await processPayment(req.body)
  res.status(201).json(charge)
})