The Complete Production SOP: How to Deploy and Run Distributed Rate Limiting with Redis Token Bucket in Autonomous AI Agents

---
name: "rate-limiting-token-bucket-redis"
description: "Protect APIs against credential stuffing, brute force, and DoS using Redis rate limiters."
metadata:
  author: "Upstash"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "implement redis rate limiting"
  - "sliding window rate limiter"
  - "prevent brute force login"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Distributed Rate Limiting with Redis Token Bucket

Implements distributed rate limiting algorithms in Redis: atomic Lua scripts, sliding window counters, and standard HTTP 429 response headers.

import Redis from 'ioredis';

const redisUrl = process.env.REDIS_URL || 'redis://127.0.0.1:6379';
export const redis = new Redis(redisUrl, {
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  lazyConnect: true,
});

local key = KEYS[1]
local now = tonumber(ARGV[1])
local capacity = tonumber(ARGV[2])
local refillRate = tonumber(ARGV[3])
local requested = tonumber(ARGV[4])

local data = redis.call('HMGET', key, 'tokens', 'lastUpdated')
local tokens = tonumber(data[1])
local lastUpdated = tonumber(data[2])

if tokens == nil then
  tokens = capacity
  lastUpdated = now
else
  local delta = math.max(0, now - lastUpdated)
  tokens = math.min(capacity, tokens + (delta * refillRate))
  lastUpdated = now
end

if tokens >= requested then
  tokens = tokens - requested
  redis.call('HMSET', key, 'tokens', tokens, 'lastUpdated', lastUpdated)
  redis.call('EXPIRE', key, math.ceil(capacity / refillRate))
  return {1, math.floor(tokens)}
else
  local retryAfter = math.ceil((requested - tokens) / refillRate)
  return {0, math.floor(tokens), retryAfter}
end

import { describe, it, expect, beforeEach } from 'vitest';
import { rateLimit } from '../src/middleware/rateLimiter';
import { redis } from '../src/lib/redis';

describe('Distributed Rate Limiter SOP Verification', () => {
  beforeEach(async () => {
    await redis.flushdb();
  });

  it('permits requests within capacity and blocks over-limit traffic', async () => {
    const ip = '192.168.1.100';
    const results = [];
    for (let i = 0; i < 5; i++) {
      results.push(await rateLimit(ip, { capacity: 3, refillRate: 1 }));
    }
    expect(results[0].allowed).toBe(true);
    expect(results[2].allowed).toBe(true);
    expect(results[3].allowed).toBe(false);
    expect(results[3].retryAfter).toBeGreaterThanOrEqual(1);
  });
});