Per-user rate limiting tracks requests based on a user identifier. Unlike per-IP, this method follows a user identity header, ensuring each distinct user has their own rate limit.

​

Overview

• What it does: Controls how many requests each user (identified via header) can make.
• Common use cases:
  • Preventing account-level abuse.
  • Ensuring fair usage among registered or authenticated users.

​

Basic Configuration

Below is an example showing how to enable per_user limits:

curl -X POST http://localhost:8080/api/v1/gateways/{gateway-id} \
  -H "Content-Type: application/json" \
  -d '{
    "required_plugins": [
      {
        "name": "rate_limiter",
        "enabled": true,
        "stage": "pre_request",
        "priority": 1,
        "settings": {
          "limits": {
            "per_user": {
              "limit": 5,
              "window": "1m"
            }
          },
          "actions": {
            "type": "reject",
            "retry_after": "60"
          }
        }
      }
    ]
  }'

​

User Detection

The system detects user IDs from the following headers:

• X-User-ID
• X-User-Id
• X-UserID
• User-ID

If none of these headers are present, the user is labeled as anonymous. Make sure you configure your application or identity provider to set a consistent user ID header.

​

Configuration Fields

• limit Maximum number of requests allowed for each user within the specified window.

• window Time frame (e.g., 1m, 30s) for measuring requests.

• actions

  • type:
    • reject: Returns 429 status with retry information
    • block: Similar to reject but for permanent blocks
  • retry_after: Seconds to wait before retrying

​

Window Configuration

The window parameter supports any valid duration string:

• s: seconds (e.g., ”30s”)
• m: minutes (e.g., “5m”)
• h: hours (e.g., “1h”)
• d: days (e.g., “1d”)

Example combinations:

{
  "limits": {
    "per_ip": {
      "limit": 30,
      "window": "30s"
    },
    "per_user": {
      "limit": 100,
      "window": "1h"
    },
    "global": {
      "limit": 1000,
      "window": "1d"
    }
  }
}

​

Response Headers

The rate limiter adds the following headers to each response:

​

Per Limit Type Headers

X-RateLimit-{type}-Limit: [maximum requests]
X-RateLimit-{type}-Remaining: [requests remaining]
X-RateLimit-{type}-Reset: [reset timestamp]

Where {type} is one of:

• global
• per_ip
• per_user

​

Rate Limit Exceeded Response

{
  "error": "per_ip rate limit exceeded",
  "retry_after": "60"
}

​

Implementation Details

​

Storage and Tracking

• Uses Redis sorted sets for tracking
• Key format: ratelimit:{level}:{id}:{limit_type}:{key}
• Automatic cleanup of expired entries
• Thread-safe operations

​

Counter Implementation

requestID := fmt.Sprintf("%d:%s", now.Unix(), uuid.New().String())
pipe := redis.Pipeline()
pipe.ZRemRangeByScore(ctx, key, "0", windowStart)
pipe.ZAdd(ctx, key, &redis.Z{
    Score:  float64(now.Unix()),
    Member: requestID,
})
pipe.Expire(ctx, key, window)

​

Best Practices

​

Longer Windows

Per-user limits can often use slightly longer windows (1m to 1h) since they typically handle authenticated requests with more consistent patterns.

​

Combine with Other Limits

Even if you rate-limit by user, using per-IP and global limits as a fallback can prevent edge cases where multiple users share IP addresses or credentials.

​

Monitor Usage

Track how often users hit their limit; this could indicate malicious scripts or legitimate high-volume needs that may require higher quotas.