javascript 54 lines · 8 steps

Idempotent POST requests in Express

A middleware factory that safely replays duplicate POST requests using an Idempotency-Key and a cache store.

Explained by highlit

Express Advanced idempotency middleware caching hashing api-design

1const crypto = require('crypto');
2 
3function idempotency({ store, ttlMs = 24 * 60 * 60 * 1000 }) {
return async function idempotencyMiddleware(req, res, next) {
  if (req.method !== 'POST') return next();
6 
  const key = req.get('Idempotency-Key');
  if (!key) {
    return res.status(400).json({ error: 'Idempotency-Key header is required' });
  }
11 
  const fingerprint = crypto
    .createHash('sha256')
    .update(JSON.stringify(req.body ?? {}))
    .digest('hex');
  const cacheId = `idem:${req.path}:${key}`;
17 
  const existing = await store.get(cacheId);
  if (existing) {
    if (existing.fingerprint !== fingerprint) {
      return res.status(422).json({
        error: 'Idempotency-Key already used with a different request body',
      });
    }
    if (existing.status === 'completed') {
      res.set('Idempotent-Replayed', 'true');
      return res.status(existing.statusCode).json(existing.body);
    }
    return res.status(409).json({ error: 'A request with this key is still processing' });
  }
31 
  await store.set(cacheId, { fingerprint, status: 'processing' }, ttlMs);
33 
  const originalJson = res.json.bind(res);
  res.json = (body) => {
    store
      .set(
        cacheId,
        { fingerprint, status: 'completed', statusCode: res.statusCode, body },
        ttlMs,
      )
      .catch(() => store.delete(cacheId));
    return originalJson(body);
  };
45 
  res.on('close', () => {
    if (!res.writableEnded) store.delete(cacheId).catch(() => {});
  });
49 
  next();
};
52}
53 
54module.exports = idempotency;

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Fingerprinting the body lets you distinguish a genuine retry from a key reused with different data.
2Recording a 'processing' state before work begins guards against concurrent duplicates and lets you replay completed results.
3Wrapping res.json is a clean way to capture a response for caching without touching every handler.

Related explainers

python

import time
import uuid
 
from django.utils.deprecation import MiddlewareMixin

Attaching per-request context in Django

middleware request lifecycle multi-tenancy

Intermediate 7 steps

javascript

function evaluate(expression) {
  const tokens = tokenize(expression);
  let pos = 0;

Building a recursive descent calculator

parsing recursion operator-precedence

Intermediate 8 steps

ruby

class LogAggregator
  BUCKET_FORMAT = "%Y-%m-%dT%H:%M"
 
  def initialize(entries)

Bucketing log entries by the minute in Ruby

aggregation hashing enumerable

Intermediate 5 steps

javascript

import { useState, useEffect, useCallback, useRef } from 'react';
 
const cache = new Map();
const inflight = new Map();

Building a stale-while-revalidate hook in React

caching request-deduplication custom-hooks

Advanced 10 steps

php

<?php
 
namespace App\Services;

Building a cached daily leaderboard in Laravel

caching aggregation eager-loading

Intermediate 9 steps

ruby

class ApplicationController < ActionController::Base
  EXPERIMENTS = {
    checkout_button_color: %w[control blue green],
    onboarding_flow: %w[control streamlined]