Rate Limiting

Production-ready rate limiting using Bun’s native Redis client with sliding window algorithm.

Overview

┌──────────────────────────────────────────────────────────────┐
│                    Rate Limit Flow                           │
│                                                              │
│  Request ──▶ Extract ID ──▶ Check Redis ──▶ Allow/Deny       │
│                 (user/IP)    Window Counter                  │
│                                                              │
│  If exceeded:                                                │
│    ← 429 Too Many Requests + Retry-After header              │
└──────────────────────────────────────────────────────────────┘

Response Headers

Every response includes rate limit info:

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests left in current window
`X-RateLimit-Reset`	Unix timestamp when window resets

Rate Limited Response (429)

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 45 seconds.",
    "retryAfter": 45
  }
}

With headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704124800
Retry-After: 45

How It Works

Sliding Window Algorithm

┌─────────────────────────────────────────────────────┐
│  Window: 60 seconds                                 │
│                                                     │
│  Redis Key: ratelimit:user:usr_123                  │
│                                                     │
│  Operations:                                        │
│  1. ZREMRANGEBYSCORE key 0 (now - 60)               │
│  2. ZCARD key                                       │
│  3. ZADD key (now) score (now)                      │
│  4. EXPIRE key 60                                   │
│                                                     │
│  If count > limit ──▶ DENY (429)                    │
└─────────────────────────────────────────────────────┘

Identifier Selection

The key is what the limiter counts requests against. Authenticated requests key on the user; everyone else keys on their client IP (see Client IP behind a proxy for how that IP is resolved safely).

// createUserKeyGenerator() in rate-limit.middleware.ts
function keyGenerator(c: Context): string {
  const user = c.get('user');
  return user
    ? `user:${user.id}`          // authenticated → per-user bucket
    : `ip:${clientAddress(c)}`;  // anonymous → per-client-IP bucket
}

Do not key an anonymous request on a raw X-Forwarded-For / X-Real-IP value. Those headers are attacker-supplied — a client can put any address in them and rotate it every request to get a fresh bucket, bypassing the limiter entirely. The IP must come from a source the caller cannot forge. See below.

Client IP behind a proxy

The gateway never talks to end users directly — a proxy (Fly Proxy in production, and often a reverse proxy elsewhere) sits in front of it. That changes what “the client IP” means and, if handled naively, breaks rate limiting.

The problem

The network socket only tells the server who it is directly connected to. Behind a proxy, that is always the proxy, not the real client:

Real client (8.8.8.8) ──▶ Fly Proxy ──▶ Gateway
                                          │
                          socket peer = Fly Proxy, NOT 8.8.8.8

If the gateway keyed on the socket peer, every request in the world would share one bucket (the proxy’s address) and a single busy client would rate-limit everybody. So the real client IP must be recovered from the request — but safely, because the obvious source (X-Forwarded-For) is caller-controlled.

How the gateway resolves it

clientAddress() tries three sources, in order, and stops at the first that applies:

Trusted platform header (preferred)

A header the fronting proxy overwrites on every request with the real client IP. Because the proxy replaces whatever the caller sent, it cannot be spoofed and is used verbatim — no socket check needed. Configured via CLIENT_IP_HEADER. On Fly.io this is Fly-Client-IP.

x-forwarded-for, resolved from the RIGHT

Only if the socket peer is an allowlisted proxy (TRUSTED_PROXY_IPS). X-Forwarded-For grows left→right as spoofable…, realClient; the proxy appends the address it observed, so the real client is on the right. The gateway walks from the right, discards allowlisted proxy hops, and takes the first untrusted hop. Picking the leftmost entry (index 0) would let the caller choose its own key.

Socket address (fallback)

A direct client with no trusted header and no allowlisted proxy in front is keyed on its socket address — the only value it cannot forge.

Why the platform header can’t be faked. Fly-Client-IP is set by Fly Proxy itself and overwrites any value the caller supplies — unlike X-Forwarded-For, which Fly appends to. That guarantee is why the header can be trusted verbatim. See Fly request headers.

Production boot-guard

Because a misconfigured proxy boundary silently collapses all traffic into one bucket, the gateway refuses to start in production when rate limiting is on but neither a trusted header nor a proxy allowlist is configured:

Rate limiting is enabled in production but neither CLIENT_IP_HEADER nor
TRUSTED_PROXY_IPS is set — every request would key on the proxy socket
(one shared bucket). Set CLIENT_IP_HEADER (e.g. Fly-Client-IP) or disable
rate limiting.

The Fly deployment is self-configuring: fly.toml sets CLIENT_IP_HEADER = 'Fly-Client-IP', so a correct deploy needs nothing extra.

Local development

There is no proxy locally, so the socket address is already the real client and no client-IP config is needed. To silence 429s entirely during testing (e.g. an emulator retry loop), disable the limiter:

RATE_LIMIT_ENABLED=false

The boot-guard only fires in production, so this is always safe on a dev machine.

Configuration

# Toggle. "false" fully disables the limiter (does NOT mount the middleware).
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_MS=60000       # sliding window length, ms
RATE_LIMIT_MAX_REQUESTS=100      # max requests per window per key

# Client-IP resolution behind a proxy (see section above).
# A header the fronting proxy OVERWRITES with the real client IP (spoof-proof,
# used verbatim). On Fly.io: Fly-Client-IP. Empty = not used.
CLIENT_IP_HEADER=
# Comma-separated IPs/CIDRs (v4/v6) whose x-forwarded-for is trusted. Empty =
# trust nobody. Used only when CLIENT_IP_HEADER is not set.
TRUSTED_PROXY_IPS=

Environment Examples

Env	Window	Max	Client-IP source
Development	60s	1000	socket (or `RATE_LIMIT_ENABLED=false`)
Staging	60s	200	`CLIENT_IP_HEADER` / `TRUSTED_PROXY_IPS`
Production (Fly)	60s	100	`CLIENT_IP_HEADER=Fly-Client-IP`
Strict	60s	20	same as its environment

Endpoint-Specific Limits

Override limits per endpoint in route config:

// Standard endpoints
app.post('/api/v1/users', rateLimitMiddleware(), createUser);

// Strict endpoints (login, password reset)
app.post('/api/v1/auth/login',
  rateLimitMiddleware({ max: 5, window: 60 }),
  login
);

// Password reset (very strict)
app.post('/api/v1/auth/password-reset',
  rateLimitMiddleware({ max: 3, window: 3600 }),
  passwordReset
);

Skip Rate Limiting

Internal service calls can skip rate limiting:

// Internal request header
app.use('/api/v1/internal/*',
  skipRateLimitMiddleware(),
  internalHandler
);

Redis Key Schema

ratelimit:<type>:<identifier>  TTL: <window>

Type	Example Key	TTL
User	`ratelimit:user:usr_abc123`	60s
IP	`ratelimit:ip:192.168.1.1`	60s
API Key	`ratelimit:apikey:hash_xyz`	60s

Performance

Redis O(log N) for sorted set operations
< 1ms typical latency
Atomic operations (no race conditions)
No external calls if Redis unavailable (fail-open by default)

Monitoring

Log Rate Limit Events

// Middleware logs when limit exceeded
logger.warn('Rate limit exceeded', {
  identifier: id,
  count: currentCount,
  limit: maxRequests,
  window: ttl,
});

Metrics to Track

rate_limit_exceeded_total — Counter of denials
rate_limit_remaining — Gauge of remaining requests
rate_limit_reset_seconds — Time until window reset

Security Considerations

Concern	Mitigation
IP spoofing	Prefer a proxy-overwritten header (`CLIENT_IP_HEADER`); trust `X-Forwarded-For` only from allowlisted proxies (`TRUSTED_PROXY_IPS`), resolved right-to-left — see above
API key sharing	Rate limit by user after auth
DoS attack	Fail-open (allow) vs fail-closed (deny)
Cost	Redis memory: ~1KB per identifier per window

Best Practices

Set generous limits — Users shouldn’t hit limits during normal use
Communicate limits — Document in API docs
Include headers — Let clients track their usage
Fail-open — Allow requests if Redis unavailable
Monitor — Track exceeded events in production

Getting Started

API

Guides

Rate Limiting

Rate Limiting

Overview

Response Headers

Rate Limited Response (429)

How It Works

Sliding Window Algorithm

Identifier Selection

Client IP behind a proxy

The problem

How the gateway resolves it

Production boot-guard

Local development

Configuration

Environment Examples

Endpoint-Specific Limits

Skip Rate Limiting

Redis Key Schema

Performance

Monitoring

Log Rate Limit Events

Metrics to Track

Security Considerations

Best Practices

​Rate Limiting

​Overview

​Response Headers

​Rate Limited Response (429)

​How It Works

​Sliding Window Algorithm

​Identifier Selection

​Client IP behind a proxy

​The problem

​How the gateway resolves it

​Production boot-guard

​Local development

​Configuration

​Environment Examples

​Endpoint-Specific Limits

​Skip Rate Limiting

​Redis Key Schema

​Performance

​Monitoring

​Log Rate Limit Events

​Metrics to Track

​Security Considerations

​Best Practices

Rate Limiting

Overview

Response Headers

Rate Limited Response (429)

How It Works

Sliding Window Algorithm

Identifier Selection

Client IP behind a proxy

The problem

How the gateway resolves it

Production boot-guard

Local development

Configuration

Environment Examples

Endpoint-Specific Limits

Skip Rate Limiting

Redis Key Schema

Performance

Monitoring

Log Rate Limit Events

Metrics to Track

Security Considerations

Best Practices