rate-limiter-builder

name

rate-limiter-builder

description

Implements rate limiting middleware with configurable rules, sliding window or token bucket algorithms, Redis-backed distributed limiting, and response headers. Use this skill whenever a user says "add rate limiting", "protect this endpoint from abuse", "implement a rate limiter", "limit API requests per user", "throttle this endpoint", "add rate limits to my API", "prevent brute force on login", or "implement per-IP and per-user rate limits". Also activate when someone's API is being hammered or abused. Supports Express/Node.js and FastAPI/Python with Redis (distributed) or in-memory (single-server). Do NOT use for CDN-level rate limiting (Cloudflare, AWS WAF — infrastructure scope) or queue throttling (use background-job-designer).

Rate Limiter Builder

Implement production-ready rate limiting middleware with configurable windows, algorithms, Redis-backed distributed support, and proper response headers.

When to Use

• Protecting public API endpoints from abuse or scraping
• Preventing brute-force attacks on authentication endpoints
• Implementing per-user or per-API-key quotas
• Adding cost protection to expensive operations (LLM calls, file processing)

When NOT to Use

• CDN-level DDoS protection (Cloudflare, AWS WAF)
• Queue-based throttling of background jobs (use background-job-designer)
• Application-level concurrency limiting (semaphores)

---

Workflow

Step 1 — Define Rate Limit Rules

Ask for:

1. Endpoints to limit: All routes / specific routes / by route type?
2. Limit key: By IP / by user ID / by API key / by plan tier?
3. Limits: Requests per window (e.g., 100 req/15min, 10 req/sec)
4. Algorithm: Fixed window / Sliding window / Token bucket
5. Infrastructure: Redis available (distributed) or single server (in-memory)?
6. On limit exceeded: Hard block (429) / soft delay / queue?

Step 2 — Choose the Algorithm

Algorithm	Use case	Pro	Con
Fixed window	Simple use case	Easy to implement	Edge case: 2× burst at window boundary
Sliding window	General API limits	Fair, no burst edge case	More complex
Token bucket	Smooth flow control	Allows bursts, refills gradually	Most complex

Recommendation: Sliding window for API limits; Token bucket for expensive operations.

Step 3 — Express Middleware Implementation

Using express-rate-limit + rate-limit-redis (recommended for most apps):

// middleware/rateLimiter.ts
import rateLimit from "express-rate-limit";
import RedisStore from "rate-limit-redis";
import { createClient } from "redis";

const redisClient = createClient({ url: process.env.REDIS_URL });
await redisClient.connect();

// General API rate limit: 100 req / 15 min
export const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  limit: 100,
  standardHeaders: "draft-7", // includes RateLimit-Policy header
  legacyHeaders: false,
  store: new RedisStore({
    sendCommand: (...args: string[]) => redisClient.sendCommand(args),
  }),
  keyGenerator: (req) => {
    // Use authenticated user ID if available, fall back to IP
    return (req as any).user?.id ?? req.ip ?? "anonymous";
  },
  handler: (req, res) => {
    res.status(429).json({
      error: {
        code: "RATE_LIMIT_EXCEEDED",
        message: "Too many requests. Please slow down.",
        retryAfter: res.getHeader("Retry-After"),
      },
    });
  },
  skip: (req) => {
    // Skip rate limiting for internal/health-check routes
    return req.path === "/health";
  },
});

// Strict auth limit: 10 req / 15 min (brute force protection)
export const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  limit: 10,
  standardHeaders: "draft-7",
  legacyHeaders: false,
  store: new RedisStore({
    sendCommand: (...args: string[]) => redisClient.sendCommand(args),
    prefix: "auth_limit:",
  }),
  keyGenerator: (req) => req.ip ?? "unknown",
  handler: (_req, res) => {
    res.status(429).json({
      error: {
        code: "AUTH_RATE_LIMIT_EXCEEDED",
        message: "Too many login attempts. Try again in 15 minutes.",
      },
    });
  },
});

// Expensive operations: 5 req / minute per user
export const expensiveLimiter = rateLimit({
  windowMs: 60 * 1000,
  limit: 5,
  standardHeaders: "draft-7",
  legacyHeaders: false,
  keyGenerator: (req) => (req as any).user?.id ?? req.ip,
});

Route registration:

// app.ts
import { apiLimiter, authLimiter, expensiveLimiter } from "./middleware/rateLimiter";

// Apply broadly
app.use("/api/", apiLimiter);

// Override for auth endpoints (stricter)
app.use("/api/auth/", authLimiter);

// Override for expensive routes
app.use("/api/reports/", expensiveLimiter);

Step 4 — Custom Sliding Window (Redis, from scratch)

For fine-grained control:

// middleware/slidingWindowLimiter.ts
import { redis } from "../redis";

interface RateLimitOptions {
  key: string; // identifies the limiter (e.g., 'api:user:123')
  windowMs: number; // window in milliseconds
  maxRequests: number; // max requests per window
}

export async function checkRateLimit({ key, windowMs, maxRequests }: RateLimitOptions): Promise<{
  allowed: boolean;
  remaining: number;
  resetAt: Date;
}> {
  const now = Date.now();
  const windowStart = now - windowMs;

  // Redis sorted set: score = timestamp, member = unique request ID
  const pipeline = redis.pipeline();
  pipeline.zremrangebyscore(key, 0, windowStart); // remove expired entries
  pipeline.zadd(key, now, `${now}-${Math.random()}`); // add current request
  pipeline.zcard(key); // count in window
  pipeline.pexpire(key, windowMs); // set TTL

  const results = await pipeline.exec();
  const count = (results?.[2]?.[1] as number) ?? 0;

  return {
    allowed: count <= maxRequests,
    remaining: Math.max(0, maxRequests - count),
    resetAt: new Date(now + windowMs),
  };
}

Step 5 — Plan-Based Rate Limits

For tiered SaaS pricing:

const PLAN_LIMITS: Record<string, { windowMs: number; limit: number }> = {
  free: { windowMs: 60_000, limit: 60 }, // 60 req/min
  pro: { windowMs: 60_000, limit: 600 }, // 600 req/min
  enterprise: { windowMs: 60_000, limit: 6000 }, // 6000 req/min
};

export function createPlanLimiter() {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = (req as any).user;
    const plan = user?.plan ?? "free";
    const { windowMs, limit } = PLAN_LIMITS[plan] ?? PLAN_LIMITS.free;

    const result = await checkRateLimit({
      key: `plan_limit:${user?.id ?? req.ip}`,
      windowMs,
      maxRequests: limit,
    });

    res.setHeader("X-RateLimit-Limit", limit);
    res.setHeader("X-RateLimit-Remaining", result.remaining);
    res.setHeader("X-RateLimit-Reset", result.resetAt.toISOString());

    if (!result.allowed) {
      return res.status(429).json({
        error: {
          code: "RATE_LIMIT_EXCEEDED",
          message: "Rate limit exceeded for your plan.",
        },
      });
    }

    next();
  };
}

---

Standard Rate Limit Headers

All rate-limited endpoints should include:

RateLimit-Limit: 100
RateLimit-Remaining: 42
RateLimit-Reset: 1699999999
Retry-After: 47

---

Output Format

1. Rate limit rules table — endpoint, window, limit, key type
2. Middleware implementation — ready-to-use Express/FastAPI middleware
3. Route registration — where to apply each limiter
4. Response headers — standard RateLimit headers
5. Plan-based variant — if tiered limits are needed

---

Safety & Confirmation

• Always apply a strict rate limit to authentication endpoints (login, password reset, OTP) regardless of other limits.
• Use Redis-backed distributed rate limiting for multi-instance deployments — in-memory won't work behind a load balancer.
• Return Retry-After in the 429 response — don't leave clients guessing when to retry.
• Don't rate limit health check and monitoring endpoints.