Idempotent API Design: Zero-Duplicate Transactional Webhooks in High-Concurrency Systems

import { Request, Response, NextFunction } from 'express';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

export async function idempotencyMiddleware(req: Request, res: Response, next: NextFunction) {
  const idempotencyKey = req.headers['idempotency-key'] as string;
  if (!idempotencyKey) {
    return next(); // Non-idempotent or read-only request
  }

  const cacheKey = `idempotency:${idempotencyKey}`;
  const cachedResponse = await redis.get(cacheKey);

  if (cachedResponse) {
    const { status, body } = JSON.parse(cachedResponse);
    return res.status(status).json(body); // Replay original response
  }

  // Acquire atomic in-flight lock (TTL 30s)
  const lockAcquired = await redis.set(`lock:${idempotencyKey}`, 'processing', 'EX', 30, 'NX');
  if (!lockAcquired) {
    return res.status(409).json({ error: 'Request currently in-flight. Please retry in 1 second.' });
  }

  // Intercept response to cache on completion
  const originalJson = res.json.bind(res);
  res.json = (body: any) => {
    redis.set(cacheKey, JSON.stringify({ status: res.statusCode, body }), 'EX', 86400); // 24h
    redis.del(`lock:${idempotencyKey}`);
    return originalJson(body);
  };

  next();
}