Rate Limiting & Throttling

plugins:
  # Global rate limit — per consumer
  - name: rate-limiting
    config:
      minute: 100
      hour: 5000
      policy: redis
      redis_host: redis-cluster
      redis_port: 6379
      limit_by: consumer  # per API key/consumer
      header_name: X-Consumer-ID

# Per-route override — expensive endpoint
routes:
  - name: search-route
    paths:
      - /api/v1/search
    plugins:
      - name: rate-limiting
        config:
          minute: 10
          policy: redis
          redis_host: redis-cluster
          limit_by: consumer

# Fixed window: 100 requests per minute
# Key: rate_limit:{client_id}:{window_timestamp}

# Window = current minute (floor to minute boundary)
WINDOW=$(date +%Y%m%d%H%M)
KEY="rate_limit:client_123:${WINDOW}"

# Atomic increment + check
CURRENT=$(redis-cli INCR "$KEY")
redis-cli EXPIRE "$KEY" 60  # Auto-cleanup

if [ "$CURRENT" -gt 100 ]; then
  echo "429 Too Many Requests"
fi

{
  "algorithm": "token_bucket",
  "bucket_capacity": 50,
  "refill_rate": 10,
  "refill_interval_ms": 1000,
  "comment": "Allows burst of 50 requests, sustained rate of 10/sec"
}

// State per client:
// {
//   "tokens": 42,
//   "last_refill": "2024-03-01T12:00:00.500Z"
// }
//
// On each request:
// 1. Calculate tokens to add since last_refill
// 2. tokens = min(tokens + added, bucket_capacity)
// 3. If tokens >= 1: consume token, allow request
// 4. If tokens < 1: reject with 429

-- Lua script for atomic sliding window rate limiting in Redis
-- Executed atomically — no race conditions between gateway instances

local key = KEYS[1]
local limit = tonumber(ARGV[1])
local window_ms = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local window_start = now - window_ms

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

-- Count requests in current window
local count = redis.call('ZCARD', key)

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

-- Add current request
redis.call('ZADD', key, now, now .. ':' .. math.random())
redis.call('PEXPIRE', key, window_ms)

return limit - count  -- Remaining requests

# Standard rate limit headers (RFC 6585 / draft-ietf-httpapi-ratelimit-headers)
HTTP/1.1 200 OK
X-RateLimit-Limit: 100        # Max requests in window
X-RateLimit-Remaining: 42     # Requests remaining
X-RateLimit-Reset: 1709251260 # Unix timestamp when window resets
Retry-After: 30               # Seconds until client should retry (on 429)

# When rate limited:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709251260
Retry-After: 30
Content-Type: application/json

{"error": "rate_limit_exceeded", "retry_after": 30}

# Envoy circuit breaker configuration
clusters:
  - name: order-service
    connect_timeout: 5s
    circuit_breakers:
      thresholds:
        - priority: DEFAULT
          max_connections: 100
          max_pending_requests: 50
          max_requests: 200
          max_retries: 3
    outlier_detection:
      consecutive_5xx: 5           # Trip after 5 consecutive 5xx
      interval: 10s                # Check every 10 seconds
      base_ejection_time: 30s      # Eject for 30 seconds minimum
      max_ejection_percent: 50     # Never eject more than 50% of hosts
      success_rate_minimum_hosts: 3

# NGINX rate limiting with burst queue (throttling)
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

server {
    location /api/ {
        # Allow burst of 20, delay requests beyond 10/s
        # First 10/s: immediate
        # Next 20: queued and released at 10/s (throttled)
        # Beyond 30: rejected with 503
        limit_req zone=api burst=20 delay=10;

        # Custom error response for rate-limited requests
        limit_req_status 429;

        proxy_pass http://backend;
    }
}