Production-Grade Idempotency Middleware with Redis and Lua Scripts

// DO NOT USE THIS IN PRODUCTION - FLAWED EXAMPLE
async function naiveIdempotencyCheck(idempotencyKey) {
  const redisKey = `idempotency:${idempotencyKey}`;
  const isNew = await redis.setnx(redisKey, 'locked');

  if (isNew) {
    // New request, proceed with business logic
    return { canProceed: true };
  } else {
    // Duplicate request
    return { canProceed: false };
  }
}

// Example value for key 'idempotency:27b50a58-...' 

// State: PROCESSING
{ "status": "processing" }

// State: COMPLETED
{ "status": "completed", "statusCode": 201, "body": { "orderId": "ord_123", "amount": 1000 } }

-- KEYS[1]: The idempotency key (e.g., 'idempotency:some-uuid')
-- ARGV[1]: The 'processing' state payload (e.g., '{"status":"processing"}')
-- ARGV[2]: The lock TTL in seconds (e.g., 30)

local key = KEYS[1]
local processing_payload = ARGV[1]
local lock_ttl = ARGV[2]

-- redis.call returns 'false' for a non-existent key
local existing_value = redis.call('GET', key)

if existing_value == false then
  -- Key does not exist. This is the first time we've seen this request.
  -- Set the key to the processing state with a TTL.
  redis.call('SET', key, processing_payload, 'EX', lock_ttl)
  return 'PROCEED'
else
  -- Key exists. Return the stored value (which is either the 'processing' payload
  -- or the final 'completed' result).
  return existing_value
end

// Filename: redis/idempotency.js
const Redis = require('ioredis');
const fs = require('fs');
const path = require('path');

// --- Redis Setup and Lua Script Loading ---
const redis = new Redis({
  // your connection options
});

// Load Lua scripts at application startup
const LUA_SCRIPTS = {
  beginProcessing: fs.readFileSync(path.join(__dirname, 'lua/begin_processing.lua'), 'utf8'),
  // We will add complete_processing.lua later
};

// Register scripts with Redis for caching via SHA1 hash
const SCRIPT_SHAS = {};
(async () => {
  for (const [name, script] of Object.entries(LUA_SCRIPTS)) {
    SCRIPT_SHAS[name] = await redis.script('load', script);
    console.log(`Lua script '${name}' loaded with SHA: ${SCRIPT_SHAS[name]}`);
  }
})();

// --- Middleware Implementation ---

const LOCK_TTL_SECONDS = 30; // A reasonable default
const RESULT_TTL_SECONDS = 24 * 60 * 60; // 24 hours

async function idempotencyMiddleware(req, res, next) {
  const idempotencyKey = req.get('Idempotency-Key');

  if (!idempotencyKey) {
    // Or handle as a non-idempotent request, depending on your API contract
    return res.status(400).json({ error: 'Idempotency-Key header is required.' });
  }

  const redisKey = `idempotency:${idempotencyKey}`;
  const processingPayload = JSON.stringify({ status: 'processing' });

  try {
    const result = await redis.evalsha(
      SCRIPT_SHAS.beginProcessing,
      1, // Number of keys
      redisKey,
      processingPayload,
      LOCK_TTL_SECONDS
    );

    if (result === 'PROCEED') {
      // This is a new request. Attach the key to the response object
      // so we can store the result later.
      res.locals.idempotencyKey = idempotencyKey;
      
      // Monkey-patch res.json and res.send to capture the result
      const originalJson = res.json.bind(res);
      res.json = (body) => {
          res.locals.result = { statusCode: res.statusCode, body };
          return originalJson(body);
      };

      // Listen for the 'finish' event to store the result after the response is sent.
      res.on('finish', async () => {
        if (res.locals.result) {
          await completeProcessing(idempotencyKey, res.locals.result);
        }
      });

      return next(); // Proceed to the actual business logic
    } else {
      // This is a duplicate request.
      const storedState = JSON.parse(result);

      if (storedState.status === 'processing') {
        // A request is already in-flight.
        return res.status(409).json({ 
          error: 'Conflict: A request with this Idempotency-Key is already being processed.' 
        });
      } else if (storedState.status === 'completed') {
        // The original request completed. Return the saved result.
        console.log(`Returning cached response for Idempotency-Key: ${idempotencyKey}`);
        return res.status(storedState.statusCode).json(storedState.body);
      }
    }
  } catch (err) {
    console.error('Redis error during idempotency check:', err);
    // This is a critical failure. See section on fail-open vs fail-closed.
    return res.status(503).json({ error: 'Service Unavailable: Could not contact idempotency store.' });
  }
}

async function completeProcessing(idempotencyKey, result) {
    const redisKey = `idempotency:${idempotencyKey}`;
    const completedPayload = JSON.stringify({ 
        status: 'completed', 
        ...result 
    });
    
    console.log(`Storing final result for Idempotency-Key: ${idempotencyKey}`);
    // Use SET with a longer TTL for the final result
    await redis.set(redisKey, completedPayload, 'EX', RESULT_TTL_SECONDS);
}

module.exports = { idempotencyMiddleware };

-- KEYS[1]: The idempotency key
-- ARGV[1]: The 'completed' state payload (e.g., '{"status":"completed", ...}')
-- ARGV[2]: The final result TTL in seconds

local key = KEYS[1]
local completed_payload = ARGV[1]
local result_ttl = ARGV[2]

-- We only want to store the result if the key is still in the 'processing' state.
-- This prevents overwriting a result from a competing process if our lock expired.
local current_value = redis.call('GET', key)

-- We could be more specific and check if current_value is '{"status":"processing"}'
-- but for simplicity, we assume any existing non-completed value is our lock.
if current_value then 
  redis.call('SET', key, completed_payload, 'EX', result_ttl)
  return 'OK'
else
  -- The key expired before we could save the result. This indicates the process
  -- took too long. Another worker may have already started.
  return 'LOCK_EXPIRED'
end

// In idempotency.js
async function completeProcessing(idempotencyKey, result) {
    const redisKey = `idempotency:${idempotencyKey}`;
    const completedPayload = JSON.stringify({ 
        status: 'completed', 
        ...result 
    });
    
    console.log(`Storing final result for Idempotency-Key: ${idempotencyKey}`);
    
    const scriptResult = await redis.evalsha(
      SCRIPT_SHAS.completeProcessing, // Assuming this is loaded
      1,
      redisKey,
      completedPayload,
      RESULT_TTL_SECONDS
    );

    if (scriptResult === 'LOCK_EXPIRED') {
        // CRITICAL: Our lock expired before we could save the result.
        // This means another process might have started or completed the same operation.
        // The system is in a potentially inconsistent state for this specific operation.
        // This requires immediate alerting and investigation.
        console.error(`CRITICAL ALERT: Idempotency lock expired for key ${idempotencyKey} before result was stored.`);
    }
}

// In your business logic controller/service
async function processPayment(req, res) {
    const { idempotencyKey } = res.locals;
    const redisKey = `idempotency:${idempotencyKey}`;

    // Start a heartbeat to extend the lock every 10 seconds
    const heartbeatInterval = setInterval(() => {
        console.log(`Heartbeating lock for key: ${redisKey}`);
        redis.expire(redisKey, LOCK_TTL_SECONDS).catch(err => {
            console.error(`Failed to heartbeat lock for key ${redisKey}:`, err);
            // If heartbeating fails, we should probably stop the process
            // to avoid running without a lock.
            clearInterval(heartbeatInterval);
            // Implement cancellation logic here if possible.
        });
    }, (LOCK_TTL_SECONDS / 3) * 1000); // Heartbeat at 1/3 of the TTL

    try {
        // --- Your long-running business logic here --- //
        const result = await someLongRunningTask();
        // --- End of business logic --- //
        
        res.status(201).json(result);
    } catch (error) {
        // Handle business logic errors
        res.status(500).json({ error: 'Payment processing failed.' });
    } finally {
        // IMPORTANT: Always clear the heartbeat interval
        clearInterval(heartbeatInterval);
    }
}

// Example of a fail-open strategy
// ... inside the catch block of idempotencyMiddleware
} catch (err) {
    console.error('Redis error during idempotency check. FAILING OPEN:', err);
    // WARNING: This risks duplicate processing.
    // Use only for non-critical operations.
    return next(); 
}

const express = require('express');
const { idempotencyMiddleware } = require('./redis/idempotency');

const app = express();
app.use(express.json());

// A mock long-running task
const processPayment = (amount) => {
    console.log(`Processing payment for ${amount}...`);
    return new Promise(resolve => setTimeout(() => {
        const paymentId = `pay_${Date.now()}`;
        console.log(`Payment successful: ${paymentId}`);
        resolve({ paymentId, status: 'succeeded', amount });
    }, 2000)); // Simulate 2 seconds of work
};

// Apply the middleware to a critical endpoint
app.post('/api/payments', idempotencyMiddleware, async (req, res) => {
    try {
        const { amount, currency } = req.body;
        if (!amount || !currency) {
            return res.status(400).json({ error: 'Amount and currency are required.' });
        }

        // The business logic itself is now clean and unaware of idempotency concerns
        const paymentResult = await processPayment(amount);

        res.status(201).json(paymentResult);
    } catch (err) {
        console.error('Error in payment processing:', err);
        // The middleware will still capture this and store an error state if needed
        res.status(500).json({ error: 'Internal Server Error' });
    }
});

const PORT = 3000;
app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
});

    curl -X POST http://localhost:3000/api/payments \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
    -d '{"amount": 100, "currency": "USD"}'