first commit

packages/core/src/ratelimit.ts

@@ -0,0 +1,126 @@
+/**
+ * Fixed-window rate limiting middleware. Keeps an in-memory counter per key
+ * (client IP by default, read from `x-forwarded-for` / `x-real-ip`) and rejects
+ * requests over the limit with a 429 and a `Retry-After` header. Sets the
+ * `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers.
+ *
+ * The store is process-local; behind multiple instances use a shared store
+ * (out of scope here). Suitable as-is for single-process apps and dev.
+ */
+
+import type { Context, Middleware } from "./context.ts";
+
+export interface RateLimitOptions {
+  /** Window length in milliseconds. Default 60_000 (1 minute). */
+  windowMs?: number;
+  /** Max requests allowed per key per window. Default 60. */
+  max?: number;
+  /** Derive the bucket key from the request. Default: client IP. */
+  key?: (ctx: Context) => string;
+  /**
+   * Trust `x-forwarded-for` / `x-real-ip` for the client IP. Default false —
+   * those headers are attacker-spoofable, so by default we key on the direct
+   * socket peer (`ctx.ip`). Enable ONLY when behind a proxy that overwrites
+   * these headers (nginx, a load balancer, Cloudflare).
+   */
+  trustProxy?: boolean;
+  /** Body returned on 429. Default "Too Many Requests". */
+  message?: string;
+  /** Emit RateLimit-* headers. Default true. */
+  headers?: boolean;
+  /** Persistence for the counters. Default: process-local memory. */
+  store?: RateLimitStore;
+  /** Maximum in-memory keys before oldest buckets are evicted. Ignored for custom stores. */
+  maxKeys?: number;
+}
+
+export interface Bucket {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * Pluggable rate-limit counter store. The default is process-local memory; swap
+ * in a shared store (Redis/SQL) so limits hold across instances. `hit` records
+ * one request for `key` in the current window and returns the running bucket.
+ * It may be async (e.g. a Redis INCR + PEXPIRE) — the middleware awaits it.
+ */
+export interface RateLimitStore {
+  hit(key: string, windowMs: number, now: number): Bucket | Promise<Bucket>;
+}
+
+function createMemoryRateLimitStore(maxKeys: number): RateLimitStore {
+  const buckets = new Map<string, Bucket>();
+  return {
+    hit(key, windowMs, now) {
+      let bucket = buckets.get(key);
+      if (!bucket || bucket.resetAt <= now) {
+        if (!bucket && buckets.size >= maxKeys) {
+          for (const [k, b] of buckets) if (b.resetAt <= now) buckets.delete(k);
+          while (buckets.size >= maxKeys) buckets.delete(buckets.keys().next().value!);
+        }
+        bucket = { count: 0, resetAt: now + windowMs };
+        buckets.set(key, bucket);
+      }
+      bucket.count++;
+      return bucket;
+    },
+  };
+}
+
+export function rateLimit(options: RateLimitOptions = {}): Middleware {
+  const windowMs = options.windowMs ?? 60_000;
+  const max = options.max ?? 60;
+  const emitHeaders = options.headers ?? true;
+  const maxKeys = options.maxKeys ?? 10_000;
+  if (!Number.isInteger(maxKeys) || maxKeys < 1)
+    throw new RangeError("rateLimit maxKeys must be a positive integer");
+  const keyOf = options.key ?? (options.trustProxy ? proxyKey : peerKey);
+  const store = options.store ?? createMemoryRateLimitStore(maxKeys);
+
+  return async (ctx, next) => {
+    const now = Date.now();
+    const bucket = await store.hit(keyOf(ctx), windowMs, now);
+
+    const resetSec = Math.max(0, Math.ceil((bucket.resetAt - now) / 1000));
+    const remaining = Math.max(0, max - bucket.count);
+
+    if (bucket.count > max) {
+      const res = new Response(options.message ?? "Too Many Requests", {
+        status: 429,
+        headers: { "content-type": "text/plain", "retry-after": String(resetSec) },
+      });
+      if (emitHeaders) applyHeaders(res, max, 0, resetSec);
+      return res;
+    }
+
+    const res = await next();
+    if (emitHeaders) applyHeaders(res, max, remaining, resetSec);
+    return res;
+  };
+}
+
+function applyHeaders(res: Response, limit: number, remaining: number, resetSec: number): void {
+  try {
+    res.headers.set("RateLimit-Limit", String(limit));
+    res.headers.set("RateLimit-Remaining", String(remaining));
+    res.headers.set("RateLimit-Reset", String(resetSec));
+  } catch {
+    /* immutable response — skip */
+  }
+}
+
+/** Non-spoofable key: the direct socket peer IP (set by the server). */
+export function peerKey(ctx: Context): string {
+  return ctx.ip ?? "global";
+}
+
+/** Proxy-aware key: trusts `x-forwarded-for` / `x-real-ip`, else the peer IP. */
+export function proxyKey(ctx: Context): string {
+  const xff = ctx.req.headers.get("x-forwarded-for");
+  if (xff) return xff.split(",")[0]!.trim();
+  return ctx.req.headers.get("x-real-ip") ?? ctx.ip ?? "global";
+}
+
+/** @deprecated Use `peerKey` (default) or `proxyKey`. Kept for compatibility. */
+export const defaultKey = proxyKey;