Fixing the Thundering Herd: How Cache Stampede Almost Took Down My Node.js API

import { redis } from './redis.config';

interface CachedOptions {
  ttl: number;
  lockTtl?: number;
  retryDelayMs?: number;
  jitterMax?: number;
}

export async function cached<T>(
  key: string,
  fetcher: () => Promise<T>,
  options: CachedOptions
): Promise<T> {
  const {
    ttl,
    lockTtl = 10,
    retryDelayMs = 50,
    jitterMax = 30,
  } = options;

  // 1. Try hot path
  const hit = await redis.get(key);
  if (hit) return JSON.parse(hit) as T;

  // 2. Try to acquire single-flight lock
  const lockKey = `${key}:lock`;
  const acquired = await redis.set(lockKey, '1', 'EX', lockTtl, 'NX');

  if (!acquired) {
    // 3. Someone else is fetching. Wait and retry.
    await new Promise(r => setTimeout(r, retryDelayMs));
    return cached(key, fetcher, options);
  }

  try {
    // 4. We own the lock. Fetch fresh data.
    const fresh = await fetcher();
    const jitteredTtl = ttl + Math.floor(Math.random() * jitterMax);
    await redis.set(key, JSON.stringify(fresh), 'EX', jitteredTtl);
    return fresh;
  } finally {
    await redis.del(lockKey);
  }
}

import Redis from 'ioredis';

export const redis = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD,
  db: 0,
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  retryStrategy(times) {
    const delay = Math.min(times * 50, 2000);
    return delay;
  },
  reconnectOnError(err) {
    const targetErrors = ['READONLY', 'ECONNRESET'];
    return targetErrors.some(e => err.message.includes(e));
  },
});

redis.on('connect', () => console.log('[Redis] Connected'));
redis.on('error', (err) => console.error('[Redis] Error:', err.message));
redis.on('reconnecting', () => console.warn('[Redis] Reconnecting...'));

version: '3.8'

services:
  redis:
    image: redis:7.2-alpine
    container_name: dev-redis
    restart: always
    ports:
      - "6379:6379"
    command: >
      redis-server
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
      --save ""
      --appendonly no
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  postgres:
    image: postgres:16-alpine
    container_name: dev-postgres
    restart: always
    environment:
      POSTGRES_USER: dev_admin
      POSTGRES_PASSWORD: dev_secure_password
      POSTGRES_DB: app_database
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata: