Rate Limiting Pattern | Bootspring Docs

Protect your APIs from abuse with in-memory, Redis-based, and sliding window rate limiting implementations.

Overview#

Rate limiting controls how many requests a client can make to your API within a time window. It's essential for preventing abuse, ensuring fair usage, and protecting your infrastructure.

When to use:

Protecting public APIs from abuse
Implementing fair usage policies
Preventing DDoS attacks
Controlling costs for expensive operations

Key features:

Multiple algorithms (fixed window, sliding window, token bucket)
In-memory and Redis-based implementations
Per-user and per-IP limiting
Configurable limits per endpoint

Code Example#

In-Memory Rate Limiter#

// lib/rate-limit.ts
const rateLimitMap = new Map<string, { count: number; resetTime: number }>()

export function rateLimit(
  key: string,
  limit: number,
  windowMs: number
): { success: boolean; remaining: number; resetIn: number } {
  const now = Date.now()
  const record = rateLimitMap.get(key)

  if (!record || now > record.resetTime) {
    rateLimitMap.set(key, { count: 1, resetTime: now + windowMs })
    return { success: true, remaining: limit - 1, resetIn: windowMs }
  }

  if (record.count >= limit) {
    return {
      success: false,
      remaining: 0,
      resetIn: record.resetTime - now
    }
  }

  record.count++
  return {
    success: true,
    remaining: limit - record.count,
    resetIn: record.resetTime - now
  }
}

Redis Rate Limiter#

// lib/rate-limit-redis.ts
import { Redis } from '@upstash/redis'

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_URL!,
  token: process.env.UPSTASH_REDIS_TOKEN!
})

export async function rateLimitRedis(
  key: string,
  limit: number,
  windowSeconds: number
) {
  const current = await redis.incr(key)

  if (current === 1) {
    await redis.expire(key, windowSeconds)
  }

  const ttl = await redis.ttl(key)

  return {
    success: current <= limit,
    remaining: Math.max(0, limit - current),
    resetIn: ttl > 0 ? ttl * 1000 : windowSeconds * 1000
  }
}

Sliding Window Rate Limiter#

// lib/rate-limit-sliding.ts
import { Redis } from '@upstash/redis'

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_URL!,
  token: process.env.UPSTASH_REDIS_TOKEN!
})

export async function slidingWindowRateLimit(
  key: string,
  limit: number,
  windowMs: number
) {
  const now = Date.now()
  const windowStart = now - windowMs

  // Remove old entries and add new one
  const pipeline = redis.pipeline()
  pipeline.zremrangebyscore(key, 0, windowStart)
  pipeline.zadd(key, { score: now, member: `${now}-${Math.random()}` })
  pipeline.zcard(key)
  pipeline.expire(key, Math.ceil(windowMs / 1000))

  const results = await pipeline.exec()
  const count = results[2] as number

  return {
    success: count <= limit,
    remaining: Math.max(0, limit - count),
    resetIn: windowMs
  }
}

Rate Limit Middleware#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { rateLimitRedis } from '@/lib/rate-limit-redis'

const RATE_LIMITS = {
  '/api/': { limit: 100, window: 60 },           // 100 req/min
  '/api/auth/': { limit: 10, window: 60 },       // 10 req/min
  '/api/ai/': { limit: 20, window: 60 }          // 20 req/min
}

export async function middleware(request: NextRequest) {
  const ip = request.ip ?? request.headers.get('x-forwarded-for') ?? 'unknown'
  const path = request.nextUrl.pathname

  // Find matching rate limit
  let config = { limit: 100, window: 60 }
  for (const [prefix, limits] of Object.entries(RATE_LIMITS)) {
    if (path.startsWith(prefix)) {
      config = limits
      break
    }
  }

  const key = `rate-limit:${ip}:${path}`
  const result = await rateLimitRedis(key, config.limit, config.window)

  if (!result.success) {
    return NextResponse.json(
      { error: 'Too many requests' },
      {
        status: 429,
        headers: {
          'X-RateLimit-Limit': config.limit.toString(),
          'X-RateLimit-Remaining': '0',
          'X-RateLimit-Reset': Math.ceil(Date.now() / 1000 + result.resetIn / 1000).toString(),
          'Retry-After': Math.ceil(result.resetIn / 1000).toString()
        }
      }
    )
  }

  const response = NextResponse.next()
  response.headers.set('X-RateLimit-Limit', config.limit.toString())
  response.headers.set('X-RateLimit-Remaining', result.remaining.toString())

  return response
}

export const config = {
  matcher: '/api/:path*'
}

Per-User Rate Limiting#

// lib/rate-limit-user.ts
import { auth } from '@/auth'

export async function userRateLimit(baseLimit: number) {
  const session = await auth()
  const userId = session?.user?.id

  // Higher limits for authenticated users
  const limit = userId ? baseLimit * 2 : baseLimit

  // Use user ID or IP as key
  const key = userId ?? (await getClientIP())

  return rateLimitRedis(`user:${key}`, limit, 60)
}

Token Bucket Algorithm#

// lib/token-bucket.ts
interface Bucket {
  tokens: number
  lastRefill: number
}

const buckets = new Map<string, Bucket>()

export function tokenBucket(
  key: string,
  maxTokens: number,
  refillRate: number // tokens per second
): boolean {
  const now = Date.now()
  let bucket = buckets.get(key)

  if (!bucket) {
    bucket = { tokens: maxTokens, lastRefill: now }
    buckets.set(key, bucket)
  }

  // Refill tokens
  const timePassed = (now - bucket.lastRefill) / 1000
  bucket.tokens = Math.min(maxTokens, bucket.tokens + timePassed * refillRate)
  bucket.lastRefill = now

  // Try to consume a token
  if (bucket.tokens >= 1) {
    bucket.tokens -= 1
    return true
  }

  return false
}

Usage in Route Handler#

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { rateLimit } from '@/lib/rate-limit'

export async function POST(request: NextRequest) {
  const ip = request.headers.get('x-forwarded-for') ?? 'anonymous'

  const result = rateLimit(ip, 10, 60000) // 10 requests per minute

  if (!result.success) {
    return NextResponse.json(
      { error: 'Too many requests' },
      {
        status: 429,
        headers: {
          'Retry-After': Math.ceil(result.resetIn / 1000).toString()
        }
      }
    )
  }

  // Continue with handler...
}

Usage Instructions#

Choose algorithm: Select fixed window, sliding window, or token bucket based on needs
Choose storage: In-memory for single instance, Redis for distributed
Configure limits: Set appropriate limits per endpoint type
Add to middleware: Implement as middleware for automatic enforcement
Return headers: Include rate limit headers in responses

Best Practices#

Use Redis for production - In-memory rate limiting doesn't work with multiple instances
Set appropriate limits - Consider endpoint cost and user expectations
Include rate limit headers - Help clients implement backoff strategies
Differentiate by user type - Higher limits for authenticated/premium users
Monitor and adjust - Track rate limit hits and adjust as needed
Use sliding windows - More accurate than fixed windows for sustained traffic
Handle gracefully - Return clear error messages with retry information

Middleware - Request preprocessing
Error Handling - Consistent error responses
Caching - Reduce load with caching
Route Handler - API endpoint implementation