Rate Limiting¶

Overview¶

Katal rate limiting now supports pluggable storage adapters.

Built-ins: - MemoryRateLimitStore (default) - RedisRateLimitStore (distributed-friendly)

Basic Usage¶

import { createRateLimitMiddleware } from "katal";

app.use(
  createRateLimitMiddleware({
    windowMs: 60_000,
    maxRequests: 100,
  }),
);

Custom Client Key¶

app.use(
  createRateLimitMiddleware({
    windowMs: 60_000,
    maxRequests: 100,
    keyGenerator: (request) => request.headers.get("x-api-key") ?? "anonymous",
  }),
);

Redis Store Example¶

import {
  createRateLimitMiddleware,
  RedisRateLimitStore,
} from "katal";

const redisStore = new RedisRateLimitStore(redisClient);

app.use(
  createRateLimitMiddleware({
    windowMs: 60_000,
    maxRequests: 100,
    store: redisStore,
  }),
);

redisClient must provide: - get(key) - set(key, value, mode, duration) - del(key)

Response Behavior¶

When limit is exceeded: - status: 429 - content type: application/problem+json - headers: - Retry-After - X-RateLimit-Limit - X-RateLimit-Remaining - X-RateLimit-Reset

Store Contract¶

interface RateLimitStore {
  get(key: string): Promise<RateLimitRecord | null> | RateLimitRecord | null;
  set(key: string, value: RateLimitRecord): Promise<void> | void;
  delete(key: string): Promise<void> | void;
}

---

## See Also

- [Middleware](MIDDLEWARE.md)
- [Application & Router](CORE.md)