actor-ts 0.9.1 → 0.11.0

package/dist/http/cache/IdempotencyKey.d.ts

@@ -1,48 +1,4 @@
-import type { Cache } from '../../cache/Cache.js';
 import { type HttpRequest, type HttpResponse } from '../types.js';
-/**
- * Idempotency-key middleware.  Implements the Stripe / Adyen pattern:
- * clients send an `Idempotency-Key` header on retryable requests
- * (typically POST), and the server records the first response under
- * that key so subsequent requests with the same key replay the same
- * outcome.
- *
- * Three states for a given key:
- *   1. **Absent** — handler runs; the (status, headers, body) tuple is
- *      cached under the key for `ttlMs` (default 24h).
- *   2. **In-flight** — another worker is currently processing this key.
- *      We respond `409 Conflict` so the client retries later.
- *   3. **Completed** — replay the cached response verbatim.
- *
- * Storage is JSON-encoded — bodies that are `Uint8Array` are base64'd
- * so the round-trip preserves bytes.
- *
- * Usage:
- *
- *   const dedup = idempotent({ cache: ext.cache(), ttlMs: 24 * 60 * 60_000 });
- *   route(post('/payments', dedup(handler)));
- */
-export interface IdempotencyOptions {
-    readonly cache: Cache;
-    /** How long to remember responses.  Default: 24 hours. */
-    readonly ttlMs?: number;
-    /**
-     * Header to read the idempotency key from.  Default: `'idempotency-key'`
-     * (the standard).  Header names are matched case-insensitively against
-     * the `req.headers` map (which holds them lower-cased).
-     */
-    readonly headerName?: string;
-    /**
-     * Cache-key namespace.  Default: `'idem:'`.
-     */
-    readonly keyPrefix?: string;
-    /**
-     * What to do when the request lacks the header.  Default: `'reject'`
-     * (respond 400).  Setting `'pass-through'` runs the handler unchanged
-     * — useful when only some clients use idempotency and you don't want
-     * to break the others.
-     */
-    readonly missingHeader?: 'reject' | 'pass-through';
-}
-export declare function idempotent(opts: IdempotencyOptions): (handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => (req: HttpRequest) => Promise<HttpResponse>;
+import { type IdempotencyOptions } from './IdempotencyOptions.js';
+export declare function idempotent(options: IdempotencyOptions): (handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => (req: HttpRequest) => Promise<HttpResponse>;
 //# sourceMappingURL=IdempotencyKey.d.ts.map

package/dist/http/cache/IdempotencyKey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IdempotencyKey.d.ts","sourceRoot":"","sources":["../../../src/http/cache/IdempotencyKey.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAU,MAAM,aAAa,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC;CACpD;AAuBD,wBAAgB,UAAU,CAAC,IAAI,EAAE,kBAAkB,IAS5B,SAAS,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,MACxD,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CA2DzE"}
+{"version":3,"file":"IdempotencyKey.d.ts","sourceRoot":"","sources":["../../../src/http/cache/IdempotencyKey.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAU,MAAM,aAAa,CAAC;AAC1E,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,yBAAyB,CAAC;AA8CjC,wBAAgB,UAAU,CAAC,OAAO,EAAE,kBAAkB,IAS/B,SAAS,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,MACxD,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CA+DzE"}

package/dist/http/cache/IdempotencyKey.js

@@ -1,14 +1,15 @@
 import { complete } from '../Route.js';
 import { Status } from '../types.js';
+import { IdempotencyOptionsValidator, } from './IdempotencyOptions.js';
 const IN_FLIGHT_MARKER = { inFlight: true };
-export function idempotent(opts) {
+export function idempotent(options) {
+    const opts = options;
+    new IdempotencyOptionsValidator().validate(opts);
     const ttlMs = opts.ttlMs ?? 24 * 60 * 60_000;
-    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-        throw new Error(`idempotent: ttlMs must be a positive finite number, got ${ttlMs}`);
-    }
     const header = (opts.headerName ?? 'idempotency-key').toLowerCase();
     const prefix = opts.keyPrefix ?? 'idem:';
     const missing = opts.missingHeader ?? 'reject';
+    const identity = opts.identity;
     return function wrap(handler) {
         return async function deduped(req) {
             const userKey = req.headers[header];
@@ -19,7 +20,11 @@ export function idempotent(opts) {
                     error: `missing required '${header}' header`,
                 });
             }
-            const cacheKey = `${prefix}${userKey}`;
+            // Fold the caller scope into the key so a cached response can't be
+            // replayed to a different caller (HTTP-4).  Empty when no `identity`
+            // is configured — identical key space to before.
+            const scope = identity ? await identity(req) : '';
+            const cacheKey = `${prefix}${scope}${scope ? ':' : ''}${userKey}`;
             const fingerprint = await computeRequestFingerprint(req);
             // Probe — if the key already holds a completed response, replay.
             const existing = await opts.cache.get(cacheKey);
@@ -73,16 +78,16 @@ export function idempotent(opts) {
 function isInFlight(value) {
     return typeof value === 'object' && value !== null && value.inFlight === true;
 }
-function encodeResponse(r, requestFingerprint) {
-    let body = r.body;
+function encodeResponse(response, requestFingerprint) {
+    let body = response.body;
     if (body instanceof Uint8Array) {
         body = { __bin: bytesToBase64(body) };
     }
     return {
-        status: r.status,
-        headers: r.headers,
+        status: response.status,
+        headers: response.headers,
         body,
-        contentType: r.contentType,
+        contentType: response.contentType,
         requestFingerprint,
     };
 }
@@ -121,26 +126,26 @@ async function computeRequestFingerprint(req) {
     }
     return `fnv:${(h1 >>> 0).toString(16)}${(h2 >>> 0).toString(16)}`;
 }
-function decodeResponse(c) {
-    let body = c.body;
-    if (typeof c.body === 'object' && c.body !== null && '__bin' in c.body) {
-        body = base64ToBytes(c.body.__bin);
+function decodeResponse(cached) {
+    let body = cached.body;
+    if (typeof cached.body === 'object' && cached.body !== null && '__bin' in cached.body) {
+        body = base64ToBytes(cached.body.__bin);
     }
     return {
-        status: c.status,
-        headers: c.headers,
+        status: cached.status,
+        headers: cached.headers,
         body,
-        contentType: c.contentType,
+        contentType: cached.contentType,
     };
 }
 function bytesToBase64(bytes) {
     // Bun, Node 16+, and Deno all expose `Buffer`; keeping this simple.
     if (typeof Buffer !== 'undefined')
         return Buffer.from(bytes).toString('base64');
-    let s = '';
+    let binaryString = '';
     for (let i = 0; i < bytes.length; i++)
-        s += String.fromCharCode(bytes[i]);
-    return btoa(s);
+        binaryString += String.fromCharCode(bytes[i]);
+    return btoa(binaryString);
 }
 function base64ToBytes(b64) {
     if (typeof Buffer !== 'undefined')

package/dist/http/cache/IdempotencyKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"IdempotencyKey.js","sourceRoot":"","sources":["../../../src/http/cache/IdempotencyKey.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IdempotencyKey.js","sourceRoot":"","sources":["../../../src/http/cache/IdempotencyKey.ts"],"names":[],"mappings":"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"}

package/dist/http/cache/IdempotencyOptions.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Options for the {@link idempotent} middleware.  Follows the repo's
+ * `XOptions.ts` convention (type / builder / validator / union), but the
+ * builder is purely ADDITIVE: `idempotent(...)` still accepts a plain
+ * options object exactly as before.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+import type { Cache } from '../../cache/Cache.js';
+import type { HttpRequest } from '../types.js';
+/** Plain options-object shape accepted by {@link idempotent}. */
+export interface IdempotencyOptionsType {
+    readonly cache: Cache;
+    /** How long to remember responses.  Default: 24 hours. */
+    readonly ttlMs?: number;
+    /**
+     * Header to read the idempotency key from.  Default: `'idempotency-key'`
+     * (the standard).  Header names are matched case-insensitively against
+     * the `req.headers` map (which holds them lower-cased).
+     */
+    readonly headerName?: string;
+    /**
+     * Cache-key namespace.  Default: `'idem:'`.
+     */
+    readonly keyPrefix?: string;
+    /**
+     * What to do when the request lacks the header.  Default: `'reject'`
+     * (respond 400).  Setting `'pass-through'` runs the handler unchanged
+     * — useful when only some clients use idempotency and you don't want
+     * to break the others.
+     */
+    readonly missingHeader?: 'reject' | 'pass-through';
+    /**
+     * Derive a per-caller scope folded into the cache key so a cached response
+     * is NEVER replayed to a different caller (security audit HTTP-4).
+     * Without it, two callers sending the same method + path + body under the
+     * same `Idempotency-Key` share one cache entry — fine for a public
+     * endpoint, unsafe when the response is identity-specific (the second
+     * caller would get the first caller's data / `Set-Cookie`).  Return the
+     * authenticated principal (user / tenant / API-key id), e.g.
+     * `identity: (req) => req.headers['x-account-id'] ?? 'anon'`.
+     */
+    readonly identity?: (req: HttpRequest) => string | Promise<string>;
+}
+/**
+ * Fluent builder for {@link IdempotencyOptionsType}:
+ *
+ *     idempotent(IdempotencyOptions.create().withCache(cache).withTtlMs(24 * 60 * 60_000))
+ */
+export declare class IdempotencyOptionsBuilder extends OptionsBuilder<IdempotencyOptionsType> {
+    /** Start a fresh builder.  Equivalent to `new IdempotencyOptionsBuilder()`. */
+    static create(): IdempotencyOptionsBuilder;
+    /** Backing cache used to record first responses. */
+    withCache(cache: Cache): this;
+    /** How long to remember responses (ms).  Default: 24 hours. */
+    withTtlMs(ttlMs: number): this;
+    /** Header to read the idempotency key from.  Default: `'idempotency-key'`. */
+    withHeaderName(headerName: string): this;
+    /** Cache-key namespace.  Default: `'idem:'`. */
+    withKeyPrefix(keyPrefix: string): this;
+    /** Behaviour when the request lacks the header.  Default: `'reject'`. */
+    withMissingHeader(missingHeader: 'reject' | 'pass-through'): this;
+    /** Per-caller scope folded into the cache key (security audit HTTP-4). */
+    withIdentity(identity: (req: HttpRequest) => string | Promise<string>): this;
+}
+/**
+ * Validates resolved {@link IdempotencyOptionsType} settings: `ttlMs` (the
+ * response-retention window) must be a positive finite number of
+ * milliseconds, and `missingHeader` must be one of its allowed literals.
+ * (Presence of `cache` is a required-field concern, not a validity one.)
+ */
+export declare class IdempotencyOptionsValidator extends OptionsValidator<IdempotencyOptionsType> {
+    constructor();
+    protected rules(_s: Partial<IdempotencyOptionsType>): void;
+}
+/**
+ * Accepted input for {@link idempotent}: the fluent
+ * {@link IdempotencyOptionsBuilder} OR a plain {@link IdempotencyOptionsType}
+ * object.
+ */
+export type IdempotencyOptions = IdempotencyOptionsBuilder | Partial<IdempotencyOptionsType>;
+/** Value alias so `IdempotencyOptions.create()` / `new IdempotencyOptions()` resolve to the builder. */
+export declare const IdempotencyOptions: typeof IdempotencyOptionsBuilder;
+//# sourceMappingURL=IdempotencyOptions.d.ts.map

package/dist/http/cache/IdempotencyOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdempotencyOptions.d.ts","sourceRoot":"","sources":["../../../src/http/cache/IdempotencyOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC;IACnD;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,sBAAsB,CAAC;IACnF,+EAA+E;IAC/E,MAAM,CAAC,MAAM,IAAI,yBAAyB;IAI1C,oDAAoD;IACpD,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAI7B,+DAA+D;IAC/D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B,8EAA8E;IAC9E,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIxC,gDAAgD;IAChD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAItC,yEAAyE;IACzE,iBAAiB,CAAC,aAAa,EAAE,QAAQ,GAAG,cAAc,GAAG,IAAI;IAIjE,0EAA0E;IAC1E,YAAY,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI;CAG7E;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,gBAAgB,CAAC,sBAAsB,CAAC;;IAIvF,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI;CAI3D;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAC7F,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,kCAA4B,CAAC"}

package/dist/http/cache/IdempotencyOptions.js

@@ -0,0 +1,61 @@
+/**
+ * Options for the {@link idempotent} middleware.  Follows the repo's
+ * `XOptions.ts` convention (type / builder / validator / union), but the
+ * builder is purely ADDITIVE: `idempotent(...)` still accepts a plain
+ * options object exactly as before.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link IdempotencyOptionsType}:
+ *
+ *     idempotent(IdempotencyOptions.create().withCache(cache).withTtlMs(24 * 60 * 60_000))
+ */
+export class IdempotencyOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new IdempotencyOptionsBuilder()`. */
+    static create() {
+        return new IdempotencyOptionsBuilder();
+    }
+    /** Backing cache used to record first responses. */
+    withCache(cache) {
+        return this.set('cache', cache);
+    }
+    /** How long to remember responses (ms).  Default: 24 hours. */
+    withTtlMs(ttlMs) {
+        return this.set('ttlMs', ttlMs);
+    }
+    /** Header to read the idempotency key from.  Default: `'idempotency-key'`. */
+    withHeaderName(headerName) {
+        return this.set('headerName', headerName);
+    }
+    /** Cache-key namespace.  Default: `'idem:'`. */
+    withKeyPrefix(keyPrefix) {
+        return this.set('keyPrefix', keyPrefix);
+    }
+    /** Behaviour when the request lacks the header.  Default: `'reject'`. */
+    withMissingHeader(missingHeader) {
+        return this.set('missingHeader', missingHeader);
+    }
+    /** Per-caller scope folded into the cache key (security audit HTTP-4). */
+    withIdentity(identity) {
+        return this.set('identity', identity);
+    }
+}
+/**
+ * Validates resolved {@link IdempotencyOptionsType} settings: `ttlMs` (the
+ * response-retention window) must be a positive finite number of
+ * milliseconds, and `missingHeader` must be one of its allowed literals.
+ * (Presence of `cache` is a required-field concern, not a validity one.)
+ */
+export class IdempotencyOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('IdempotencyOptions');
+    }
+    rules(_s) {
+        this.positiveNumber('ttlMs');
+        this.oneOf('missingHeader', ['reject', 'pass-through']);
+    }
+}
+/** Value alias so `IdempotencyOptions.create()` / `new IdempotencyOptions()` resolve to the builder. */
+export const IdempotencyOptions = IdempotencyOptionsBuilder;
+//# sourceMappingURL=IdempotencyOptions.js.map

package/dist/http/cache/IdempotencyOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdempotencyOptions.js","sourceRoot":"","sources":["../../../src/http/cache/IdempotencyOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAuClE;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,cAAsC;IACnF,+EAA+E;IAC/E,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,yBAAyB,EAAE,CAAC;IACzC,CAAC;IAED,oDAAoD;IACpD,SAAS,CAAC,KAAY;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,+DAA+D;IAC/D,SAAS,CAAC,KAAa;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,8EAA8E;IAC9E,cAAc,CAAC,UAAkB;QAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,gDAAgD;IAChD,aAAa,CAAC,SAAiB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,yEAAyE;IACzE,iBAAiB,CAAC,aAAwC;QACxD,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;IAClD,CAAC;IAED,0EAA0E;IAC1E,YAAY,CAAC,QAAwD;QACnE,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,2BAA4B,SAAQ,gBAAwC;IACvF;QACE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC9B,CAAC;IACS,KAAK,CAAC,EAAmC;QACjD,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC;IAC1D,CAAC;CACF;AAQD,wGAAwG;AACxG,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC"}

package/dist/http/cache/RateLimit.d.ts

@@ -1,5 +1,5 @@
-import type { Cache } from '../../cache/Cache.js';
 import { type HttpRequest, type HttpResponse } from '../types.js';
+import { type RateLimitOptions } from './RateLimitOptions.js';
 /**
  * HTTP rate-limiting middleware backed by a `Cache` (Redis recommended
  * for multi-process deployments; InMemoryCache for single-process).
@@ -24,42 +24,23 @@ import { type HttpRequest, type HttpResponse } from '../types.js';
  *     cache: ext.cache(),
  *     windowMs: 60_000,
  *     max: 100,
- *     key: (req) => req.headers['x-forwarded-for'] ?? '<anon>',
+ *     key: (req) => req.remoteAddress ?? '<anon>',
  *   });
  *   route(post('/api/expensive', limited(handler)));
+ *
+ * **Security — choosing `key` (security audit HTTP-3):** derive it from a
+ * value the client can't freely forge.  `req.remoteAddress` (the socket peer)
+ * is the safe default.  Do NOT key on a client-settable header such as
+ * `x-forwarded-for` unless a trusted proxy strips and re-sets it — otherwise
+ * an attacker rotates the header per request for a fresh bucket each time
+ * (limit bypassed), while clients without the header collapse into a single
+ * shared bucket (one client can exhaust everyone's quota).
  */
-export interface RateLimitOptions {
-    /** Backing cache.  Should be a shared/distributed one (Redis) in prod. */
-    readonly cache: Cache;
-    /** Length of the rolling window in milliseconds. */
-    readonly windowMs: number;
-    /** Maximum requests allowed per window per key. */
-    readonly max: number;
-    /** Identity function — typically derives from IP, user id, or API key. */
-    readonly key: (req: HttpRequest) => string | Promise<string>;
-    /**
-     * Cache-key namespace prepended to the user key.  Defaults to
-     * `'rl:'` so multiple rate-limiters in the same cache don't collide.
-     */
-    readonly keyPrefix?: string;
-    /**
-     * Custom 429 response builder.  Receives the limit context for
-     * full control over the body / headers.  Default: a plain 429 with
-     * `Retry-After` (seconds-rounded-up).
-     */
-    readonly onLimit?: (ctx: RateLimitContext) => HttpResponse;
-}
-export interface RateLimitContext {
-    readonly key: string;
-    readonly count: number;
-    readonly max: number;
-    readonly windowMs: number;
-    readonly retryAfterSeconds: number;
-}
 /**
  * Build a rate-limiter higher-order handler.  The returned function
  * wraps a normal handler and returns a new one with rate-limit checks
- * in front.
+ * in front.  Accepts a plain options object or the fluent
+ * {@link RateLimitOptions} builder.
  */
-export declare function rateLimit(opts: RateLimitOptions): (handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => (req: HttpRequest) => Promise<HttpResponse>;
+export declare function rateLimit(options: RateLimitOptions): (handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => (req: HttpRequest) => Promise<HttpResponse>;
 //# sourceMappingURL=RateLimit.d.ts.map

package/dist/http/cache/RateLimit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimit.d.ts","sourceRoot":"","sources":["../../../src/http/cache/RateLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAU,MAAM,aAAa,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,YAAY,CAAC;CAC5D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,IAUzB,SAAS,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,MACxD,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CAiCzE"}
+{"version":3,"file":"RateLimit.d.ts","sourceRoot":"","sources":["../../../src/http/cache/RateLimit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAU,MAAM,aAAa,CAAC;AAC1E,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,IAM5B,SAAS,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,MACxD,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CAiCzE"}

package/dist/http/cache/RateLimit.js

@@ -1,17 +1,51 @@
 import { complete } from '../Route.js';
 import { Status } from '../types.js';
+import { RateLimitOptionsValidator, } from './RateLimitOptions.js';
+/**
+ * HTTP rate-limiting middleware backed by a `Cache` (Redis recommended
+ * for multi-process deployments; InMemoryCache for single-process).
+ *
+ * Algorithm: **fixed-window counter**.  The key derived from the request
+ * is incremented on every request; the first increment seeds the TTL
+ * to `windowMs`.  Once the counter exceeds `max`, the wrapper short-
+ * circuits with a `429 Too Many Requests` response carrying a
+ * `Retry-After` header.
+ *
+ * Why fixed-window over token-bucket / sliding-log?
+ *   - One Redis op per request (`INCR + EXPIRE`).  Cheap, atomic.
+ *   - Industry-standard for "X requests per minute" guarantees.
+ *   - The well-known burst-at-window-boundary edge case (2× quota in a
+ *     small window around the rollover) is acceptable for almost every
+ *     real use-case.  If you need precision, a sliding window would be
+ *     a separate primitive.
+ *
+ * Usage:
+ *
+ *   const limited = rateLimit({
+ *     cache: ext.cache(),
+ *     windowMs: 60_000,
+ *     max: 100,
+ *     key: (req) => req.remoteAddress ?? '<anon>',
+ *   });
+ *   route(post('/api/expensive', limited(handler)));
+ *
+ * **Security — choosing `key` (security audit HTTP-3):** derive it from a
+ * value the client can't freely forge.  `req.remoteAddress` (the socket peer)
+ * is the safe default.  Do NOT key on a client-settable header such as
+ * `x-forwarded-for` unless a trusted proxy strips and re-sets it — otherwise
+ * an attacker rotates the header per request for a fresh bucket each time
+ * (limit bypassed), while clients without the header collapse into a single
+ * shared bucket (one client can exhaust everyone's quota).
+ */
 /**
  * Build a rate-limiter higher-order handler.  The returned function
  * wraps a normal handler and returns a new one with rate-limit checks
- * in front.
+ * in front.  Accepts a plain options object or the fluent
+ * {@link RateLimitOptions} builder.
  */
-export function rateLimit(opts) {
-    if (!Number.isFinite(opts.windowMs) || opts.windowMs <= 0) {
-        throw new Error(`rateLimit: windowMs must be a positive finite number, got ${opts.windowMs}`);
-    }
-    if (!Number.isInteger(opts.max) || opts.max <= 0) {
-        throw new Error(`rateLimit: max must be a positive integer, got ${opts.max}`);
-    }
+export function rateLimit(options) {
+    const opts = options;
+    new RateLimitOptionsValidator().validate(opts);
     const prefix = opts.keyPrefix ?? 'rl:';
     const onLimit = opts.onLimit ?? defaultOnLimit;
     return function wrap(handler) {

package/dist/http/cache/RateLimit.js.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimit.js","sourceRoot":"","sources":["../../../src/http/cache/RateLimit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAuC,MAAM,EAAE,MAAM,aAAa,CAAC;AA6D1E;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,6DAA6D,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,kDAAkD,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC;IAE/C,OAAO,SAAS,IAAI,CAAC,OAAmE;QACtF,OAAO,KAAK,UAAU,OAAO,CAAC,GAAgB;YAC5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,QAAQ,GAAG,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;YACvC,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;gBAChE,4DAA4D;gBAC5D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;YACD,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACrB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC;gBAChE,OAAO,OAAO,CAAC;oBACb,GAAG,EAAE,OAAO;oBACZ,KAAK;oBACL,GAAG,EAAE,IAAI,CAAC,GAAG;oBACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,iBAAiB,EAAE,UAAU;iBAC9B,CAAC,CAAC;YACL,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YACpC,wEAAwE;YACxE,MAAM,OAAO,GAA2B;gBACtC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;gBACrC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC;aAC/D,CAAC;YACF,OAAO;gBACL,GAAG,QAAQ;gBACX,OAAO,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,GAAG,OAAO,EAAE;aACrD,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,GAAqB;IAC3C,OAAO,QAAQ,CACb,MAAM,CAAC,eAAe,EACtB,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,CAAC,iBAAiB,EAAE,EAC5D;QACE,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC5C,mBAAmB,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QACpC,uBAAuB,EAAE,GAAG;KAC7B,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"RateLimit.js","sourceRoot":"","sources":["../../../src/http/cache/RateLimit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAuC,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EACL,yBAAyB,GAI1B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,MAAM,IAAI,GAAG,OAA+B,CAAC;IAC7C,IAAI,yBAAyB,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC;IAE/C,OAAO,SAAS,IAAI,CAAC,OAAmE;QACtF,OAAO,KAAK,UAAU,OAAO,CAAC,GAAgB;YAC5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,QAAQ,GAAG,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;YACvC,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;gBAChE,4DAA4D;gBAC5D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;YACD,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACrB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC;gBAChE,OAAO,OAAO,CAAC;oBACb,GAAG,EAAE,OAAO;oBACZ,KAAK;oBACL,GAAG,EAAE,IAAI,CAAC,GAAG;oBACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,iBAAiB,EAAE,UAAU;iBAC9B,CAAC,CAAC;YACL,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YACpC,wEAAwE;YACxE,MAAM,OAAO,GAA2B;gBACtC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;gBACrC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC;aAC/D,CAAC;YACF,OAAO;gBACL,GAAG,QAAQ;gBACX,OAAO,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,GAAG,OAAO,EAAE;aACrD,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,GAAqB;IAC3C,OAAO,QAAQ,CACb,MAAM,CAAC,eAAe,EACtB,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,CAAC,iBAAiB,EAAE,EAC5D;QACE,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC5C,mBAAmB,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QACpC,uBAAuB,EAAE,GAAG;KAC7B,CACF,CAAC;AACJ,CAAC"}

package/dist/http/cache/RateLimitOptions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Options for the {@link rateLimit} middleware.  Follows the repo's
+ * `XOptions.ts` convention (type / builder / validator / union), but the
+ * builder is purely ADDITIVE: `rateLimit(...)` still accepts a plain
+ * options object exactly as before.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+import type { Cache } from '../../cache/Cache.js';
+import type { HttpRequest, HttpResponse } from '../types.js';
+/** Context handed to a custom {@link RateLimitOptionsType.onLimit} builder. */
+export interface RateLimitContext {
+    readonly key: string;
+    readonly count: number;
+    readonly max: number;
+    readonly windowMs: number;
+    readonly retryAfterSeconds: number;
+}
+/** Plain options-object shape accepted by {@link rateLimit}. */
+export interface RateLimitOptionsType {
+    /** Backing cache.  Should be a shared/distributed one (Redis) in prod. */
+    readonly cache: Cache;
+    /** Length of the rolling window in milliseconds. */
+    readonly windowMs: number;
+    /** Maximum requests allowed per window per key. */
+    readonly max: number;
+    /** Identity function — typically derives from IP, user id, or API key. */
+    readonly key: (req: HttpRequest) => string | Promise<string>;
+    /**
+     * Cache-key namespace prepended to the user key.  Defaults to
+     * `'rl:'` so multiple rate-limiters in the same cache don't collide.
+     */
+    readonly keyPrefix?: string;
+    /**
+     * Custom 429 response builder.  Receives the limit context for
+     * full control over the body / headers.  Default: a plain 429 with
+     * `Retry-After` (seconds-rounded-up).
+     */
+    readonly onLimit?: (ctx: RateLimitContext) => HttpResponse;
+}
+/**
+ * Fluent builder for {@link RateLimitOptionsType}:
+ *
+ *     rateLimit(RateLimitOptions.create().withCache(cache).withWindowMs(60_000).withMax(100).withKey((req) => req.remoteAddress ?? '<anon>'))
+ */
+export declare class RateLimitOptionsBuilder extends OptionsBuilder<RateLimitOptionsType> {
+    /** Start a fresh builder.  Equivalent to `new RateLimitOptionsBuilder()`. */
+    static create(): RateLimitOptionsBuilder;
+    /** Backing cache.  Should be a shared/distributed one (Redis) in prod. */
+    withCache(cache: Cache): this;
+    /** Length of the rolling window in milliseconds. */
+    withWindowMs(windowMs: number): this;
+    /** Maximum requests allowed per window per key. */
+    withMax(max: number): this;
+    /** Identity function — typically derives from IP, user id, or API key. */
+    withKey(key: (req: HttpRequest) => string | Promise<string>): this;
+    /** Cache-key namespace prepended to the user key.  Default `'rl:'`. */
+    withKeyPrefix(keyPrefix: string): this;
+    /** Custom 429 response builder — full control over the limit response. */
+    withOnLimit(onLimit: (ctx: RateLimitContext) => HttpResponse): this;
+}
+/**
+ * Validates resolved {@link RateLimitOptionsType} settings: the rolling
+ * window (`windowMs`) must be a positive finite number of milliseconds and
+ * the per-window cap (`max`) a positive integer.  (Presence of `cache` /
+ * `key` is a required-field concern, not a domain-validity one.)
+ */
+export declare class RateLimitOptionsValidator extends OptionsValidator<RateLimitOptionsType> {
+    constructor();
+    protected rules(_s: Partial<RateLimitOptionsType>): void;
+}
+/**
+ * Accepted input for {@link rateLimit}: the fluent
+ * {@link RateLimitOptionsBuilder} OR a plain {@link RateLimitOptionsType}
+ * object.
+ */
+export type RateLimitOptions = RateLimitOptionsBuilder | Partial<RateLimitOptionsType>;
+/** Value alias so `RateLimitOptions.create()` / `new RateLimitOptions()` resolve to the builder. */
+export declare const RateLimitOptions: typeof RateLimitOptionsBuilder;
+//# sourceMappingURL=RateLimitOptions.d.ts.map

package/dist/http/cache/RateLimitOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimitOptions.d.ts","sourceRoot":"","sources":["../../../src/http/cache/RateLimitOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,YAAY,CAAC;CAC5D;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,cAAc,CAAC,oBAAoB,CAAC;IAC/E,6EAA6E;IAC7E,MAAM,CAAC,MAAM,IAAI,uBAAuB;IAIxC,0EAA0E;IAC1E,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAI7B,oDAAoD;IACpD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpC,mDAAmD;IACnD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI;IAIlE,uEAAuE;IACvE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAItC,0EAA0E;IAC1E,WAAW,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,YAAY,GAAG,IAAI;CAGpE;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,gBAAgB,CAAC,oBAAoB,CAAC;;IAInF,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;CAIzD;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACvF,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,gCAA0B,CAAC"}

package/dist/http/cache/RateLimitOptions.js

@@ -0,0 +1,61 @@
+/**
+ * Options for the {@link rateLimit} middleware.  Follows the repo's
+ * `XOptions.ts` convention (type / builder / validator / union), but the
+ * builder is purely ADDITIVE: `rateLimit(...)` still accepts a plain
+ * options object exactly as before.
+ */
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link RateLimitOptionsType}:
+ *
+ *     rateLimit(RateLimitOptions.create().withCache(cache).withWindowMs(60_000).withMax(100).withKey((req) => req.remoteAddress ?? '<anon>'))
+ */
+export class RateLimitOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new RateLimitOptionsBuilder()`. */
+    static create() {
+        return new RateLimitOptionsBuilder();
+    }
+    /** Backing cache.  Should be a shared/distributed one (Redis) in prod. */
+    withCache(cache) {
+        return this.set('cache', cache);
+    }
+    /** Length of the rolling window in milliseconds. */
+    withWindowMs(windowMs) {
+        return this.set('windowMs', windowMs);
+    }
+    /** Maximum requests allowed per window per key. */
+    withMax(max) {
+        return this.set('max', max);
+    }
+    /** Identity function — typically derives from IP, user id, or API key. */
+    withKey(key) {
+        return this.set('key', key);
+    }
+    /** Cache-key namespace prepended to the user key.  Default `'rl:'`. */
+    withKeyPrefix(keyPrefix) {
+        return this.set('keyPrefix', keyPrefix);
+    }
+    /** Custom 429 response builder — full control over the limit response. */
+    withOnLimit(onLimit) {
+        return this.set('onLimit', onLimit);
+    }
+}
+/**
+ * Validates resolved {@link RateLimitOptionsType} settings: the rolling
+ * window (`windowMs`) must be a positive finite number of milliseconds and
+ * the per-window cap (`max`) a positive integer.  (Presence of `cache` /
+ * `key` is a required-field concern, not a domain-validity one.)
+ */
+export class RateLimitOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('RateLimitOptions');
+    }
+    rules(_s) {
+        this.positiveNumber('windowMs');
+        this.positiveInt('max');
+    }
+}
+/** Value alias so `RateLimitOptions.create()` / `new RateLimitOptions()` resolve to the builder. */
+export const RateLimitOptions = RateLimitOptionsBuilder;
+//# sourceMappingURL=RateLimitOptions.js.map

package/dist/http/cache/RateLimitOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimitOptions.js","sourceRoot":"","sources":["../../../src/http/cache/RateLimitOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAoClE;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,cAAoC;IAC/E,6EAA6E;IAC7E,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,uBAAuB,EAAE,CAAC;IACvC,CAAC;IAED,0EAA0E;IAC1E,SAAS,CAAC,KAAY;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,oDAAoD;IACpD,YAAY,CAAC,QAAgB;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,mDAAmD;IACnD,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,0EAA0E;IAC1E,OAAO,CAAC,GAAmD;QACzD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,uEAAuE;IACvE,aAAa,CAAC,SAAiB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,0EAA0E;IAC1E,WAAW,CAAC,OAAgD;QAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,gBAAsC;IACnF;QACE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC5B,CAAC;IACS,KAAK,CAAC,EAAiC;QAC/C,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;CACF;AAQD,oGAAoG;AACpG,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC"}