I Designed a Distributed Rate Limiter. Here's What the Single-Node Version Gets Wrong.

import { createCluster } from "redis";

const cluster = createCluster({
  rootNodes: [
    { url: "redis://node1:6379" },
    { url: "redis://node2:6379" },
    { url: "redis://node3:6379" },
  ],
});

await cluster.connect();

async function isRateLimited(userId: string, limit: number, windowSeconds: number): Promise<boolean> {
  const key = `ratelimit:user:${userId}`; // always routes to same node via CRC16 hash
  const now = Date.now();
  const windowStart = now - windowSeconds * 1000;

  // Pipeline is atomic within a single node
  const results = await cluster.multi()
    .zRemRangeByScore(key, 0, windowStart)
    .zCard(key)
    .zAdd(key, { score: now, value: `${now}-${Math.random()}` })
    .expire(key, windowSeconds * 2)
    .exec();

  const count = results[1] as number;
  return count >= limit;
}

// Without hash tags: user data might be on different nodes
const sessionKey = `session:${userId}`;     // slot X
const rateLimitKey = `ratelimit:${userId}`; // slot Y (different node)

// With hash tags: both keys hash on userId, guaranteed same slot
const sessionKey = `{${userId}}:session`;
const rateLimitKey = `{${userId}}:ratelimit`;

// Now you can pipeline these together
await cluster.multi()
  .get(`{${userId}}:session`)
  .zCard(`{${userId}}:ratelimit`)
  .exec();

const slidingWindowLua = `
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window_start = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local window_seconds = tonumber(ARGV[4])

-- Remove expired entries
redis.call('ZREMRANGEBYSCORE', key, 0, window_start)

-- Count current entries
local count = redis.call('ZCARD', key)

if count >= limit then
  return 0  -- rate limited
end

-- Add this request
redis.call('ZADD', key, now, now .. '-' .. math.random())
redis.call('EXPIRE', key, window_seconds * 2)

return 1  -- allowed
`;

async function isRateLimited(client: RedisClientType, userId: string, limit: number, windowSeconds: number): Promise<boolean> {
  const key = `ratelimit:user:${userId}`;
  const now = Date.now();
  const windowStart = now - windowSeconds * 1000;

  const result = await client.eval(slidingWindowLua, {
    keys: [key],
    arguments: [now.toString(), windowStart.toString(), limit.toString(), windowSeconds.toString()],
  });

  return result === 0; // 0 = rate limited, 1 = allowed
}

async function isRateLimited(userId: string, limit: number, windowSeconds: number): Promise<boolean> {
  try {
    // ... redis operations
  } catch (error) {
    if (isRedisConnectionError(error)) {
      // Fail open: allow request, Redis is down
      return false;

      // Or fail closed: block request, Redis is down
      // return true;
    }
    throw error;
  }
}

import { LRUCache } from "lru-cache";

const localLimiter = new LRUCache<string, number[]>({ max: 10000 });

async function isRateLimited(userId: string, limit: number, windowSeconds: number): Promise<boolean> {
  try {
    return await redisRateLimit(userId, limit, windowSeconds);
  } catch {
    // Redis unavailable: fall back to in-memory with stricter limit
    return localRateLimit(userId, Math.floor(limit * 0.5), windowSeconds);
  }
}

function localRateLimit(userId: string, limit: number, windowSeconds: number): boolean {
  const now = Date.now();
  const windowStart = now - windowSeconds * 1000;
  const key = `ratelimit:${userId}`;

  const timestamps = localLimiter.get(key) ?? [];
  const recent = timestamps.filter(t => t > windowStart);
  recent.push(now);
  localLimiter.set(key, recent);

  return recent.length > limit;
}

// Token bucket in Lua: constant memory, O(1) per request
const tokenBucketLua = `
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])  -- tokens per second
local now = tonumber(ARGV[3])

local data = redis.call('HMGET', key, 'tokens', 'last_refill')
local tokens = tonumber(data[1]) or capacity
local last_refill = tonumber(data[2]) or now

local elapsed = (now - last_refill) / 1000  -- seconds
tokens = math.min(capacity, tokens + elapsed * refill_rate)

if tokens < 1 then
  redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
  redis.call('EXPIRE', key, math.ceil(capacity / refill_rate) * 2)
  return 0  -- rate limited
end

redis.call('HMSET', key, 'tokens', tokens - 1, 'last_refill', now)
redis.call('EXPIRE', key, math.ceil(capacity / refill_rate) * 2)
return 1  -- allowed
`;

Do you need exact counts?
  Yes: Sliding window + Lua script on Redis Cluster
  No: Token bucket + Lua script, or approximate counting

Is Redis availability critical?
  Yes: Redis Sentinel/Cluster with replicas + in-memory fallback
  No: Single node with fail-open on errors

Is this at edge/CDN scale?
  Yes: Approximate distributed counting (Cloudflare Workers KV, Durable Objects)
  No: Redis Cluster handles it

Is memory a concern (10M+ users)?
  Yes: Token bucket (constant memory per user)
  No: Sliding window (more accurate, higher memory)

import { createCluster, RedisClusterType } from "redis";
import { LRUCache } from "lru-cache";

const cluster = createCluster({
  rootNodes: [
    { url: process.env.REDIS_NODE_1 },
    { url: process.env.REDIS_NODE_2 },
    { url: process.env.REDIS_NODE_3 },
  ],
  defaults: { socket: { connectTimeout: 3000 } },
});

const localCache = new LRUCache<string, number[]>({ max: 50000 });

const SLIDING_WINDOW_LUA = `
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window_start = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local window_seconds = tonumber(ARGV[4])
redis.call('ZREMRANGEBYSCORE', key, 0, window_start)
local count = redis.call('ZCARD', key)
if count >= limit then return 0 end
redis.call('ZADD', key, now, now .. math.random())
redis.call('EXPIRE', key, window_seconds * 2)
return 1
`;

export async function checkRateLimit(
  userId: string,
  limit: number,
  windowSeconds: number
): Promise<{ allowed: boolean; remaining: number }> {
  const key = `{${userId}}:rl`;
  const now = Date.now();

  try {
    const result = await cluster.eval(SLIDING_WINDOW_LUA, {
      keys: [key],
      arguments: [now.toString(), (now - windowSeconds * 1000).toString(), limit.toString(), windowSeconds.toString()],
    });

    const count = await cluster.zCard(key);
    return {
      allowed: result === 1,
      remaining: Math.max(0, limit - count),
    };
  } catch {
    // Redis unavailable: local fallback with 50% limit
    const fallbackLimit = Math.floor(limit * 0.5);
    const windowStart = now - windowSeconds * 1000;
    const timestamps = (localCache.get(userId) ?? []).filter(t => t > windowStart);
    const allowed = timestamps.length < fallbackLimit;
    if (allowed) {
      timestamps.push(now);
      localCache.set(userId, timestamps);
    }
    return { allowed, remaining: Math.max(0, fallbackLimit - timestamps.length) };
  }
}