@mandujs/core 0.21.0 → 0.22.1

package/src/middleware/rate-limit/index.ts

@@ -0,0 +1,522 @@
+/**
+ * @mandujs/core/middleware/rate-limit
+ *
+ * Sliding-window rate limiter (Phase 6.1) with pluggable stores. Ships two
+ * backends out of the box:
+ *
+ *   - {@link createInMemoryStore} — process-local `Map`, zero deps, dies on
+ *     restart. The right choice for a single-process dev server or a small
+ *     production deployment where a dropped-on-restart limiter is acceptable.
+ *   - {@link createSqliteStore} — shared-file SQLite via `@mandujs/core/db`,
+ *     WAL mode (per RFC 0001 Appendix D.4). Survives restarts and covers
+ *     same-host multi-process; still NOT a distributed limiter (no
+ *     multi-host coordination — add Redis in a follow-up phase if needed).
+ *
+ * ## Algorithm — sliding window via fixed bucket
+ *
+ * Each key owns a bucket `{ windowStart, count }`. On each hit:
+ *
+ *   - If `now - windowStart >= windowMs` → bucket rolls over: the new window
+ *     starts at `now` with `count = 1`.
+ *   - Else → `count++` inside the existing window.
+ *
+ * The request is `allowed` when `count <= limit`. `resetAt = windowStart +
+ * windowMs`; `retryAfterSeconds = ceil((resetAt - now) / 1000)` when blocked.
+ *
+ * This is *not* a rolling-queue implementation (which would track every hit's
+ * timestamp). For typical bursty traffic the observable behaviour is the
+ * same — 1/ε the memory, 1/ε the work per hit, and no edge cases at the
+ * window boundary. Token-bucket is explicitly deferred to v2 as an
+ * alternative algorithm once a real-world use case justifies it.
+ *
+ * ## Usage
+ *
+ * ### As middleware
+ *
+ * ```ts
+ * import { rateLimit } from "@mandujs/core/middleware/rate-limit";
+ *
+ * export default Mandu.filling()
+ *   .use(rateLimit({ limit: 60, windowMs: 60_000 }))
+ *   .post((ctx) => ctx.ok({ ok: true }));
+ * ```
+ *
+ * ### As a guard for non-HTTP call sites
+ *
+ * The auth flows in Phase 5.3 (`verify.send`, `reset.send`) documented their
+ * lack of rate limiting explicitly. Wrap them with the guard:
+ *
+ * ```ts
+ * const sendGuard = createRateLimitGuard({ limit: 1, windowMs: 60_000 });
+ * // later, at a POST handler:
+ * await sendGuard.enforce(`verify:${userId}`);
+ * await verify.send(userId, email);
+ * ```
+ *
+ * Throwing {@link RateLimitError} carries the full {@link RateLimitResult}
+ * so the caller can shape its own 429 response.
+ *
+ * @module middleware/rate-limit
+ */
+
+import type { ManduContext } from "../../filling/context";
+
+// ─── Public types ───────────────────────────────────────────────────────────
+
+/** Outcome of a single `hit()` on a rate-limit store. */
+export interface RateLimitResult {
+  /** Whether the hit stayed within the configured budget. */
+  allowed: boolean;
+  /**
+   * Remaining budget in the current window, after this hit. Always clamped
+   * to `>= 0` — a blocked hit reports `0`.
+   */
+  remaining: number;
+  /** Unix ms at which the current window ends and a fresh one begins. */
+  resetAt: number;
+  /**
+   * `Math.ceil((resetAt - now) / 1000)` when blocked, `0` when allowed.
+   * Consumed directly as the `Retry-After` header value on 429 responses.
+   */
+  retryAfterSeconds: number;
+}
+
+/**
+ * Pluggable backing store. Each call to {@link hit} atomically records a
+ * single request against `key` and returns the resulting state — there is no
+ * separate "read then increment" path to avoid race conditions.
+ */
+export interface RateLimitStore {
+  /**
+   * Record one hit against `key` with `limit` / `windowMs` in effect. MUST
+   * be atomic: concurrent callers racing on the same key must observe a
+   * strictly-increasing count up to the rollover, never a lost update.
+   */
+  hit(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+  /**
+   * Delete entries whose window is older than `olderThanMs` ago. Returns
+   * the number of entries purged. Safe to call on a hot store — the cron
+   * schedulers may do so on a fixed tick.
+   */
+  gcNow(olderThanMs: number): Promise<number>;
+  /** Release any held resources. Optional; safe to omit for in-memory stores. */
+  close?(): Promise<void>;
+}
+
+/** Construction options for {@link rateLimit}. */
+export interface RateLimitMiddlewareOptions {
+  /** Maximum hits per window. Required. Must be a positive integer. */
+  limit: number;
+  /** Window duration in ms. Required. Must be a positive integer. */
+  windowMs: number;
+  /** Store backend. Default: a fresh in-memory store (per middleware instance). */
+  store?: RateLimitStore;
+  /**
+   * Compute the rate-limit key for the current request. Returning `null`
+   * skips limiting for this request — the middleware passes through
+   * without touching the store.
+   *
+   * Default: first entry of `x-forwarded-for` header → `x-real-ip` →
+   * `"unknown"`. Production behind a trusted proxy should set XFF; otherwise
+   * use a session-user-id key via a custom `keyFn` to limit authenticated
+   * traffic per account instead of per (shared) IP.
+   */
+  keyFn?: (ctx: ManduContext) => string | null;
+  /**
+   * Predicate to bypass limiting for specific requests. Return `true` to
+   * skip entirely — the store is not consulted, no headers are emitted.
+   * Default: never skips.
+   */
+  skip?: (ctx: ManduContext) => boolean;
+  /**
+   * Build the 429 response body on block. Default: JSON
+   * `{ error: "rate_limited", retryAfterSeconds }`. Callers can override to
+   * match their app's error envelope.
+   */
+  handler?: (ctx: ManduContext, result: RateLimitResult) => Response;
+}
+
+/** Middleware signature matching `csrf.ts` / `session.ts`. */
+export type RateLimitMiddleware = (
+  ctx: ManduContext,
+) => Promise<Response | void>;
+
+/** Construction options for {@link createRateLimitGuard}. */
+export interface RateLimitGuardOptions {
+  limit: number;
+  windowMs: number;
+  /** Store backend. Default: a fresh in-memory store (per guard instance). */
+  store?: RateLimitStore;
+}
+
+/**
+ * Imperative rate-limit handle for non-middleware call sites. Use
+ * {@link RateLimitGuard.enforce} to wrap sensitive operations like
+ * `verify.send(userId)` that don't live behind HTTP middleware.
+ */
+export interface RateLimitGuard {
+  /**
+   * Record one hit and return the full result. Never throws — inspect
+   * `result.allowed` to branch.
+   */
+  check(key: string): Promise<RateLimitResult>;
+  /**
+   * Record one hit and throw {@link RateLimitError} when blocked. Resolves
+   * silently when allowed. Ideal for `await guard.enforce(...)` prologues.
+   */
+  enforce(key: string): Promise<void>;
+}
+
+/**
+ * Error thrown by {@link RateLimitGuard.enforce} when a hit is blocked.
+ * Carries the full {@link RateLimitResult} so the caller can format the
+ * response with accurate `Retry-After` / `X-RateLimit-Reset` information.
+ */
+export class RateLimitError extends Error {
+  /** Public so handlers can derive `Retry-After` without downcasting. */
+  readonly result: RateLimitResult;
+  constructor(result: RateLimitResult, message?: string) {
+    super(
+      message ??
+        `rate_limited: retry after ${result.retryAfterSeconds}s (reset at ${new Date(
+          result.resetAt,
+        ).toISOString()})`,
+    );
+    this.name = "RateLimitError";
+    this.result = result;
+  }
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const DEFAULT_KEY_UNKNOWN = "unknown";
+
+/**
+ * Clock injector. Kept module-scoped (not per-store) so tests can freeze time
+ * across both the middleware and any stores it calls during a single
+ * scenario. Override via {@link _setClockForTests}; production callers never
+ * touch this.
+ *
+ * @internal
+ */
+let __now: () => number = () => Date.now();
+
+/**
+ * Replace the module-level clock. Test-only hook; not exported from the
+ * package surface.
+ *
+ * @internal
+ */
+export function _setClockForTests(fn: (() => number) | null): void {
+  __now = fn ?? (() => Date.now());
+}
+
+// ─── Key derivation ─────────────────────────────────────────────────────────
+
+/**
+ * Default key derivation. Reads the first hop of `x-forwarded-for` (the
+ * client IP when a trusted reverse proxy is in front), falling back to
+ * `x-real-ip`, and finally a literal `"unknown"` bucket.
+ *
+ * The `"unknown"` fallback is intentionally a single shared bucket: when the
+ * edge has not forwarded either header, we cannot tell callers apart, and a
+ * hostile client could otherwise bypass the limit by simply stripping the
+ * header. Shared throttling keeps the limiter safe but may be harsh on
+ * no-proxy dev setups — set a custom `keyFn` that uses a session id, API
+ * key, or user id for production traffic.
+ */
+function defaultKeyFn(ctx: ManduContext): string {
+  const xff = ctx.request.headers.get("x-forwarded-for");
+  if (typeof xff === "string" && xff.length > 0) {
+    // XFF is a comma-separated chain; the client is the first entry.
+    const first = xff.split(",")[0]?.trim();
+    if (first && first.length > 0) return first;
+  }
+  const realIp = ctx.request.headers.get("x-real-ip");
+  if (typeof realIp === "string" && realIp.length > 0) return realIp.trim();
+  return DEFAULT_KEY_UNKNOWN;
+}
+
+// ─── Middleware factory ─────────────────────────────────────────────────────
+
+function assertPositiveInt(name: string, value: number): void {
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value <= 0 ||
+    Math.floor(value) !== value
+  ) {
+    throw new TypeError(
+      `[@mandujs/core/middleware/rate-limit] '${name}' must be a positive integer; got ${String(
+        value,
+      )}.`,
+    );
+  }
+}
+
+/**
+ * Sliding-window rate-limit middleware.
+ *
+ * Behaviour:
+ *   1. If `skip(ctx)` returns `true`, the middleware returns void immediately
+ *      — no store access, no headers.
+ *   2. Otherwise, `keyFn(ctx)` produces a key. `null` skips the store (useful
+ *      for "only limit authenticated traffic" policies).
+ *   3. `store.hit(key, limit, windowMs)` records and evaluates.
+ *   4. On block: returns 429 with `Retry-After` + `X-RateLimit-*` headers and
+ *      a JSON body (or whatever `handler` returns). The caller's handler
+ *      pipeline is short-circuited.
+ *   5. On allow: returns void. No response mutation is performed here — the
+ *      middleware surface has no afterHandle hook on this variant. Callers
+ *      who want `X-RateLimit-*` headers on allowed responses should use
+ *      {@link rateLimitPlugin} (exposes beforeHandle + afterHandle) instead.
+ */
+export function rateLimit(
+  options: RateLimitMiddlewareOptions,
+): RateLimitMiddleware {
+  if (!options || typeof options !== "object") {
+    throw new TypeError(
+      "[@mandujs/core/middleware/rate-limit] rateLimit: options object required.",
+    );
+  }
+  assertPositiveInt("limit", options.limit);
+  assertPositiveInt("windowMs", options.windowMs);
+
+  const limit = options.limit;
+  const windowMs = options.windowMs;
+  const store = options.store ?? createInMemoryStore();
+  const keyFn = options.keyFn ?? defaultKeyFn;
+  const skip = options.skip;
+  const handler = options.handler ?? defaultBlockedHandler;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    if (skip && skip(ctx)) {
+      return;
+    }
+    const key = keyFn(ctx);
+    if (key === null) {
+      // Caller's key function explicitly opts out for this request.
+      return;
+    }
+
+    const result = await store.hit(key, limit, windowMs);
+
+    if (!result.allowed) {
+      const res = handler(ctx, result);
+      // The caller's `handler` may return a pre-built Response that already
+      // carries rate-limit headers. We only stamp them when absent so a
+      // custom handler that wants to hide the Retry-After (rare) can do so.
+      return applyRateLimitHeaders(res, limit, result);
+    }
+
+    // Allowed: pass through. Callers who need `X-RateLimit-*` headers on
+    // successful responses should layer {@link rateLimitPlugin} on top of
+    // the filling chain — this plain-middleware variant cannot mutate the
+    // outgoing Response without an afterHandle hook.
+    return;
+  };
+}
+
+/**
+ * Default 429 response body. Intentionally small — exposes only what a
+ * well-behaved client legitimately needs. `resetAt` is Unix-ms so clients
+ * don't have to negotiate timezone interpretation.
+ */
+function defaultBlockedHandler(
+  _ctx: ManduContext,
+  result: RateLimitResult,
+): Response {
+  return Response.json(
+    {
+      error: "rate_limited",
+      retryAfterSeconds: result.retryAfterSeconds,
+      resetAt: result.resetAt,
+    },
+    { status: 429 },
+  );
+}
+
+/**
+ * Stamp `Retry-After` + `X-RateLimit-*` headers on a blocked response. The
+ * `X-RateLimit-Reset` value is Unix-seconds (not ms) to match the informal
+ * convention used by GitHub / Twitter / Stripe — see GitHub's API docs.
+ *
+ * Preserves any header the caller's handler has already set (checked with
+ * `Headers.has`) so custom handlers can override values at will.
+ */
+function applyRateLimitHeaders(
+  response: Response,
+  limit: number,
+  result: RateLimitResult,
+): Response {
+  const headers = new Headers(response.headers);
+  if (!headers.has("Retry-After")) {
+    headers.set("Retry-After", String(result.retryAfterSeconds));
+  }
+  if (!headers.has("X-RateLimit-Limit")) {
+    headers.set("X-RateLimit-Limit", String(limit));
+  }
+  if (!headers.has("X-RateLimit-Remaining")) {
+    headers.set("X-RateLimit-Remaining", String(result.remaining));
+  }
+  if (!headers.has("X-RateLimit-Reset")) {
+    headers.set(
+      "X-RateLimit-Reset",
+      String(Math.floor(result.resetAt / 1000)),
+    );
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// ─── Guard (imperative) ─────────────────────────────────────────────────────
+
+/**
+ * Construct an imperative rate-limit guard. Use when the protected operation
+ * is NOT an HTTP handler — e.g. an outbound email from a server-side action.
+ *
+ * Every guard owns its own store by default, so two guards with the same
+ * `{ limit, windowMs }` are independent. Share a store explicitly when two
+ * guards must consume the same budget.
+ */
+export function createRateLimitGuard(
+  options: RateLimitGuardOptions,
+): RateLimitGuard {
+  if (!options || typeof options !== "object") {
+    throw new TypeError(
+      "[@mandujs/core/middleware/rate-limit] createRateLimitGuard: options object required.",
+    );
+  }
+  assertPositiveInt("limit", options.limit);
+  assertPositiveInt("windowMs", options.windowMs);
+
+  const limit = options.limit;
+  const windowMs = options.windowMs;
+  const store = options.store ?? createInMemoryStore();
+
+  return {
+    async check(key: string): Promise<RateLimitResult> {
+      if (typeof key !== "string" || key.length === 0) {
+        throw new TypeError(
+          "[@mandujs/core/middleware/rate-limit] check: key must be a non-empty string.",
+        );
+      }
+      return await store.hit(key, limit, windowMs);
+    },
+    async enforce(key: string): Promise<void> {
+      if (typeof key !== "string" || key.length === 0) {
+        throw new TypeError(
+          "[@mandujs/core/middleware/rate-limit] enforce: key must be a non-empty string.",
+        );
+      }
+      const result = await store.hit(key, limit, windowMs);
+      if (!result.allowed) {
+        throw new RateLimitError(result);
+      }
+    },
+  };
+}
+
+// ─── In-memory store ────────────────────────────────────────────────────────
+
+interface Bucket {
+  windowStart: number;
+  count: number;
+}
+
+/**
+ * Process-local in-memory store. No external dependencies, no persistence
+ * across restarts. Concurrency-safe within a single event loop (Map reads
+ * and writes are not preempted mid-operation in JS); no locking needed.
+ *
+ * Not safe across processes or hosts — use {@link createSqliteStore} for
+ * same-host multi-process, or a distributed store (future Redis backend)
+ * for multi-host.
+ */
+export function createInMemoryStore(): RateLimitStore {
+  const buckets = new Map<string, Bucket>();
+  let closed = false;
+
+  return {
+    async hit(
+      key: string,
+      limit: number,
+      windowMs: number,
+    ): Promise<RateLimitResult> {
+      if (closed) {
+        throw new Error(
+          "[@mandujs/core/middleware/rate-limit] in-memory store is closed.",
+        );
+      }
+      const now = __now();
+      const existing = buckets.get(key);
+
+      let bucket: Bucket;
+      if (!existing || now - existing.windowStart >= windowMs) {
+        // Window rollover (or first hit). Start a fresh window anchored at
+        // `now` — the simplest model that still reports a precise resetAt.
+        bucket = { windowStart: now, count: 1 };
+      } else {
+        // Still inside the current window — increment.
+        bucket = { windowStart: existing.windowStart, count: existing.count + 1 };
+      }
+      buckets.set(key, bucket);
+
+      const resetAt = bucket.windowStart + windowMs;
+      const allowed = bucket.count <= limit;
+      // `remaining` reports post-hit budget; clamped at 0 so a blocked hit
+      // never reports negative remaining (would confuse clients rendering a
+      // progress indicator).
+      const remaining = Math.max(0, limit - bucket.count);
+      const retryAfterSeconds = allowed
+        ? 0
+        : Math.max(1, Math.ceil((resetAt - now) / 1000));
+
+      return { allowed, remaining, resetAt, retryAfterSeconds };
+    },
+
+    async gcNow(olderThanMs: number): Promise<number> {
+      if (closed) return 0;
+      if (typeof olderThanMs !== "number" || olderThanMs < 0) {
+        throw new TypeError(
+          "[@mandujs/core/middleware/rate-limit] gcNow: olderThanMs must be a non-negative number.",
+        );
+      }
+      const now = __now();
+      let deleted = 0;
+      // Iterating + deleting from a Map during traversal is safe per the
+      // ES spec — entries visited before deletion yield, already-visited
+      // entries are skipped. We still collect keys into a throwaway array
+      // to keep the hot-path clean across engines.
+      const stale: string[] = [];
+      for (const [key, bucket] of buckets) {
+        if (now - bucket.windowStart > olderThanMs) {
+          stale.push(key);
+        }
+      }
+      for (const key of stale) {
+        buckets.delete(key);
+        deleted++;
+      }
+      return deleted;
+    },
+
+    async close(): Promise<void> {
+      if (closed) return;
+      closed = true;
+      buckets.clear();
+    },
+  };
+}
+
+// ─── SQLite store (re-export) ───────────────────────────────────────────────
+
+// The SQLite store lives in its own module so callers who never need it
+// don't pay the import cost of `@mandujs/core/db`.
+export {
+  createSqliteStore,
+  type SqliteRateLimitStoreOptions,
+} from "./sqlite-store";