actor-ts 0.9.0

package/dist/http/cache/IdempotencyKey.js

@@ -0,0 +1,154 @@
+import { complete } from '../Route.js';
+import { Status } from '../types.js';
+const IN_FLIGHT_MARKER = { inFlight: true };
+export function idempotent(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';
+    return function wrap(handler) {
+        return async function deduped(req) {
+            const userKey = req.headers[header];
+            if (!userKey) {
+                if (missing === 'pass-through')
+                    return handler(req);
+                return complete(Status.BadRequest, {
+                    error: `missing required '${header}' header`,
+                });
+            }
+            const cacheKey = `${prefix}${userKey}`;
+            const fingerprint = await computeRequestFingerprint(req);
+            // Probe — if the key already holds a completed response, replay.
+            const existing = await opts.cache.get(cacheKey);
+            if (existing.isSome()) {
+                const value = existing.value;
+                if (isInFlight(value)) {
+                    return complete(Status.Conflict, {
+                        error: 'idempotency-key in-flight; retry shortly',
+                    });
+                }
+                // Security: same idempotency key + DIFFERENT body = client
+                // tried to reuse a key for a semantically-different request.
+                // Stripe's spec says reject with 422.  Returning the cached
+                // (unrelated) response would let an attacker poison the
+                // cache with a key they guessed/observed and steal another
+                // client's response.
+                if (value.requestFingerprint !== fingerprint) {
+                    return complete(Status.UnprocessableEntity, {
+                        error: 'idempotency-key already used with a different request body',
+                    });
+                }
+                return decodeResponse(value);
+            }
+            // Try to claim the key.  `setIfAbsent` is the kernel — if it
+            // returns false, somebody else got there a microsecond ago, fall
+            // back to the same in-flight response.
+            const claimed = await opts.cache.setIfAbsent(cacheKey, IN_FLIGHT_MARKER, ttlMs);
+            if (!claimed) {
+                return complete(Status.Conflict, {
+                    error: 'idempotency-key in-flight; retry shortly',
+                });
+            }
+            let response;
+            try {
+                response = await handler(req);
+            }
+            catch (e) {
+                // On error, drop our in-flight claim so the client can retry.
+                await opts.cache.delete(cacheKey);
+                throw e;
+            }
+            // Replace the in-flight marker with the actual response,
+            // remembering the request fingerprint so subsequent replays
+            // can verify the request body matches.
+            await opts.cache.set(cacheKey, encodeResponse(response, fingerprint), ttlMs);
+            return response;
+        };
+    };
+}
+/* ------------------------------ internals -------------------------------- */
+function isInFlight(value) {
+    return typeof value === 'object' && value !== null && value.inFlight === true;
+}
+function encodeResponse(r, requestFingerprint) {
+    let body = r.body;
+    if (body instanceof Uint8Array) {
+        body = { __bin: bytesToBase64(body) };
+    }
+    return {
+        status: r.status,
+        headers: r.headers,
+        body,
+        contentType: r.contentType,
+        requestFingerprint,
+    };
+}
+/**
+ * Compute a stable fingerprint of the request body + method + path
+ * for the idempotency-key duplicate-body check.  SHA-256 base64
+ * — fast (sub-ms for typical payloads), collision-resistant, and
+ * the base64 form is JSON-safe for storage in the cache.
+ *
+ * We include `method + path` so even a body-less GET can be
+ * fingerprinted, and a same-body POST/PUT mix doesn't collide.
+ */
+async function computeRequestFingerprint(req) {
+    const subtle = globalThis.crypto?.subtle;
+    const prelude = new TextEncoder().encode(`${req.method} ${req.path}\n`);
+    const body = req.body ?? new Uint8Array(0);
+    const combined = new Uint8Array(prelude.byteLength + body.byteLength);
+    combined.set(prelude, 0);
+    combined.set(body, prelude.byteLength);
+    if (subtle) {
+        // Cast through BufferSource — TS 5.7+'s DOM types tighten the
+        // `BufferSource` constraint in a way that doesn't match
+        // `Uint8Array<ArrayBufferLike>` cleanly.
+        const digest = await subtle.digest('SHA-256', combined);
+        return bytesToBase64(new Uint8Array(digest));
+    }
+    // Fallback: FNV-1a 64-bit hex.  Slower convergence than SHA-256
+    // but still ~ 2^32 collision resistance for the fingerprint.  Only
+    // reached on exotic runtimes without WebCrypto, which we already
+    // refuse to run encryption on.
+    let h1 = 0x811c9dc5 >>> 0;
+    let h2 = 0xcbf29ce4 >>> 0;
+    for (let i = 0; i < combined.length; i++) {
+        h1 = Math.imul(h1 ^ combined[i], 16777619);
+        h2 = Math.imul(h2 ^ combined[i], 2246822519);
+    }
+    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);
+    }
+    return {
+        status: c.status,
+        headers: c.headers,
+        body,
+        contentType: c.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 = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return btoa(s);
+}
+function base64ToBytes(b64) {
+    if (typeof Buffer !== 'undefined')
+        return new Uint8Array(Buffer.from(b64, 'base64'));
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+//# sourceMappingURL=IdempotencyKey.js.map

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

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

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

@@ -0,0 +1,65 @@
+import type { Cache } from '../../cache/Cache.js';
+import { type HttpRequest, type HttpResponse } from '../types.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.headers['x-forwarded-for'] ?? '<anon>',
+ *   });
+ *   route(post('/api/expensive', limited(handler)));
+ */
+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.
+ */
+export declare function rateLimit(opts: RateLimitOptions): (handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => (req: HttpRequest) => Promise<HttpResponse>;
+//# sourceMappingURL=RateLimit.d.ts.map

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

@@ -0,0 +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"}

package/dist/http/cache/RateLimit.js

@@ -0,0 +1,60 @@
+import { complete } from '../Route.js';
+import { Status } from '../types.js';
+/**
+ * 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.
+ */
+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}`);
+    }
+    const prefix = opts.keyPrefix ?? 'rl:';
+    const onLimit = opts.onLimit ?? defaultOnLimit;
+    return function wrap(handler) {
+        return async function limited(req) {
+            const userKey = await opts.key(req);
+            const cacheKey = `${prefix}${userKey}`;
+            let count;
+            try {
+                count = await opts.cache.incr(cacheKey, opts.windowMs);
+            }
+            catch {
+                // Cache fault → fail open (let the request through).  Better to
+                // serve traffic than to take down the API on Redis hiccups.
+                return handler(req);
+            }
+            if (count > opts.max) {
+                const retryAfter = Math.max(1, Math.ceil(opts.windowMs / 1000));
+                return onLimit({
+                    key: userKey,
+                    count,
+                    max: opts.max,
+                    windowMs: opts.windowMs,
+                    retryAfterSeconds: retryAfter,
+                });
+            }
+            const response = await handler(req);
+            // Surface the standard X-RateLimit headers when we still have headroom.
+            const headers = {
+                'x-ratelimit-limit': String(opts.max),
+                'x-ratelimit-remaining': String(Math.max(0, opts.max - count)),
+            };
+            return {
+                ...response,
+                headers: { ...(response.headers ?? {}), ...headers },
+            };
+        };
+    };
+}
+function defaultOnLimit(ctx) {
+    return complete(Status.TooManyRequests, { error: 'rate limited', retryAfter: ctx.retryAfterSeconds }, {
+        'retry-after': String(ctx.retryAfterSeconds),
+        'x-ratelimit-limit': String(ctx.max),
+        'x-ratelimit-remaining': '0',
+    });
+}
+//# sourceMappingURL=RateLimit.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,49 @@
+import type { Cache } from '../../cache/Cache.js';
+import type { HttpRequest, HttpResponse } from '../types.js';
+/**
+ * HTTP response-cache directive.  Wraps a handler with a read-through
+ * cache: on hit, the cached response is returned without invoking the
+ * inner handler; on miss, the handler runs and its response (if its
+ * status code is in `cacheStatuses`) is stored under the user's key.
+ *
+ * **Stampede protection:** when many requests hit the same cache-miss
+ * concurrently, only one runs the handler; the rest await its result
+ * via an in-process `Map<key, Promise<HttpResponse>>`.  This is
+ * **per-process** — cluster-wide single-flight is explicitly out of
+ * scope (the complexity-to-value ratio is poor for a cache layer).
+ *
+ * Invalidation is the caller's responsibility: write handlers should
+ * `cache.delete(key)` on mutate.  We deliberately avoid auto-magic
+ * (tags, patterns) because those are the source of most stale-cache
+ * production bugs.
+ *
+ * Usage:
+ *
+ *   const userCache = cached({
+ *     cache: ext.cache(),
+ *     ttlMs: 30_000,
+ *     key: (req) => `users:${req.params.id}`,
+ *   });
+ *   route(get('/users/:id', userCache(req => askUserActor(req.params.id))));
+ */
+export interface ResponseCacheOptions {
+    /** Backing cache. */
+    readonly cache: Cache;
+    /** TTL on stored responses (milliseconds).  Required — no TTL invites unbounded growth. */
+    readonly ttlMs: number;
+    /** Identity function — derives the cache key from the request. */
+    readonly key: (req: HttpRequest) => string | Promise<string>;
+    /**
+     * Cache-key namespace prepended to the user key.  Default `'rsp:'` so
+     * multiple response-caches in one Redis don't collide.
+     */
+    readonly keyPrefix?: string;
+    /**
+     * Status codes whose responses are cacheable.  Default `[200]` — only
+     * 2xx are cached.  Pass `[200, 404]` if you want to cache "not found"
+     * responses (saves repeat lookups when callers query unknown ids).
+     */
+    readonly cacheStatuses?: ReadonlyArray<number>;
+}
+export declare function cached(opts: ResponseCacheOptions): (handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => (req: HttpRequest) => Promise<HttpResponse>;
+//# sourceMappingURL=ResponseCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/ResponseCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,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,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAUD,wBAAgB,MAAM,CAAC,IAAI,EAAE,oBAAoB,IAU1B,SAAS,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,MAClD,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CA4B/E"}

package/dist/http/cache/ResponseCache.js

@@ -0,0 +1,84 @@
+export function cached(opts) {
+    if (!Number.isFinite(opts.ttlMs) || opts.ttlMs <= 0) {
+        throw new Error(`cached: ttlMs must be a positive finite number, got ${opts.ttlMs}`);
+    }
+    const prefix = opts.keyPrefix ?? 'rsp:';
+    const cacheStatuses = new Set(opts.cacheStatuses ?? [200]);
+    // Per-process single-flight map.  Lifetime: the time it takes the
+    // wrapped handler to run for one key.  Cleaned up in finally.
+    const inflight = new Map();
+    return function wrap(handler) {
+        return async function cachedHandler(req) {
+            const userKey = await opts.key(req);
+            const cacheKey = `${prefix}${userKey}`;
+            // 1. Cache hit?
+            const hit = await opts.cache.get(cacheKey);
+            if (hit.isSome()) {
+                return decodeResponse(hit.value);
+            }
+            // 2. Miss — but is another request already running this key?
+            const existingFlight = inflight.get(cacheKey);
+            if (existingFlight)
+                return existingFlight;
+            // 3. We're the leader for this key.  Run the handler, then cache
+            // the result if its status is cacheable.
+            const work = (async () => {
+                const response = await handler(req);
+                if (cacheStatuses.has(response.status)) {
+                    await opts.cache.set(cacheKey, encodeResponse(response), opts.ttlMs);
+                }
+                return response;
+            })();
+            inflight.set(cacheKey, work);
+            try {
+                return await work;
+            }
+            finally {
+                inflight.delete(cacheKey);
+            }
+        };
+    };
+}
+/* ------------------------------ internals -------------------------------- */
+function encodeResponse(r) {
+    let body = r.body;
+    if (body instanceof Uint8Array) {
+        body = { __bin: bytesToBase64(body) };
+    }
+    return {
+        status: r.status,
+        headers: r.headers,
+        body,
+        contentType: r.contentType,
+    };
+}
+function decodeResponse(c) {
+    let body = c.body;
+    if (typeof c.body === 'object' && c.body !== null && '__bin' in c.body) {
+        body = base64ToBytes(c.body.__bin);
+    }
+    return {
+        status: c.status,
+        headers: c.headers,
+        body,
+        contentType: c.contentType,
+    };
+}
+function bytesToBase64(bytes) {
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(bytes).toString('base64');
+    let s = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return btoa(s);
+}
+function base64ToBytes(b64) {
+    if (typeof Buffer !== 'undefined')
+        return new Uint8Array(Buffer.from(b64, 'base64'));
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+//# sourceMappingURL=ResponseCache.js.map

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

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

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

@@ -0,0 +1,7 @@
+export { rateLimit } from './RateLimit.js';
+export type { RateLimitOptions, RateLimitContext } from './RateLimit.js';
+export { idempotent } from './IdempotencyKey.js';
+export type { IdempotencyOptions } from './IdempotencyKey.js';
+export { cached } from './ResponseCache.js';
+export type { ResponseCacheOptions } from './ResponseCache.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/http/cache/index.js

@@ -0,0 +1,4 @@
+export { rateLimit } from './RateLimit.js';
+export { idempotent } from './IdempotencyKey.js';
+export { cached } from './ResponseCache.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/http/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/http/index.d.ts

@@ -0,0 +1,18 @@
+export { HttpExtension, HttpExtensionId } from './HttpExtension.js';
+export type { ServerBuilder } from './HttpExtension.js';
+export { concat, complete, completeJson, completeText, compile, del, get, head, options, patch, path, pathParam, pathPrefix, post, put, queryParam, redirect, reject, } from './Route.js';
+export type { CompiledRoute, Route } from './Route.js';
+export { entity, marshal, pickRequestSerializer, pickResponseSerializer } from './Marshalling.js';
+export { HttpClient } from './HttpClient.js';
+export type { HttpClientRequest, HttpClientResponse } from './HttpClient.js';
+export { FastifyBackend } from './backend/FastifyBackend.js';
+export { ExpressBackend } from './backend/ExpressBackend.js';
+export type { ExpressBackendOptions } from './backend/ExpressBackend.js';
+export { HonoBackend } from './backend/HonoBackend.js';
+export type { HonoBackendOptions } from './backend/HonoBackend.js';
+export type { HttpServerBackend, RouteRegistration, ServerBinding, } from './backend/HttpServerBackend.js';
+export { HttpError, Status, } from './types.js';
+export type { HttpMethod, HttpRequest, HttpResponse } from './types.js';
+export { rateLimit, idempotent, cached } from './cache/index.js';
+export type { RateLimitOptions, RateLimitContext, IdempotencyOptions, ResponseCacheOptions, } from './cache/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EACL,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,GAAG,EACH,GAAG,EACH,IAAI,EACJ,OAAO,EACP,KAAK,EACL,IAAI,EACJ,SAAS,EACT,UAAU,EACV,IAAI,EACJ,GAAG,EACH,UAAU,EACV,QAAQ,EACR,MAAM,GACP,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAElG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GACd,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,MAAM,GACP,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACjE,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/http/index.js

@@ -0,0 +1,11 @@
+export { HttpExtension, HttpExtensionId } from './HttpExtension.js';
+export { concat, complete, completeJson, completeText, compile, del, get, head, options, patch, path, pathParam, pathPrefix, post, put, queryParam, redirect, reject, } from './Route.js';
+export { entity, marshal, pickRequestSerializer, pickResponseSerializer } from './Marshalling.js';
+export { HttpClient } from './HttpClient.js';
+export { FastifyBackend } from './backend/FastifyBackend.js';
+export { ExpressBackend } from './backend/ExpressBackend.js';
+export { HonoBackend } from './backend/HonoBackend.js';
+export { HttpError, Status, } from './types.js';
+// HTTP caching middleware (response-cache, rate-limit, idempotency-key).
+export { rateLimit, idempotent, cached } from './cache/index.js';
+//# sourceMappingURL=index.js.map

package/dist/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGpE,OAAO,EACL,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,GAAG,EACH,GAAG,EACH,IAAI,EACJ,OAAO,EACP,KAAK,EACL,IAAI,EACJ,SAAS,EACT,UAAU,EACV,IAAI,EACJ,GAAG,EACH,UAAU,EACV,QAAQ,EACR,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAElG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQvD,OAAO,EACL,SAAS,EACT,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,yEAAyE;AACzE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/http/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared HTTP types.  Kept small and backend-agnostic: the Route DSL works
+ * only with these shapes, and the different backends (Fastify, BunServe,
+ * Express) translate to/from their native APIs.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+export interface HttpRequest {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly query: Readonly<Record<string, string | string[] | undefined>>;
+    /** Path parameters extracted from `/users/:id` patterns. */
+    readonly params: Readonly<Record<string, string>>;
+    /** Raw bytes of the request body (undefined for GET / HEAD). */
+    readonly body: Uint8Array | null;
+}
+export interface HttpResponse {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Body — if string or JSON object, the marshaller adds Content-Type. */
+    readonly body?: string | Uint8Array | object | null;
+    /** Forced content-type.  Overrides whatever the marshaller picks. */
+    readonly contentType?: string;
+}
+/** Named HTTP status codes for callers that don't want magic numbers. */
+export declare const Status: {
+    readonly OK: 200;
+    readonly Created: 201;
+    readonly Accepted: 202;
+    readonly NoContent: 204;
+    readonly MovedPermanently: 301;
+    readonly Found: 302;
+    readonly NotModified: 304;
+    readonly BadRequest: 400;
+    readonly Unauthorized: 401;
+    readonly Forbidden: 403;
+    readonly NotFound: 404;
+    readonly MethodNotAllowed: 405;
+    readonly Conflict: 409;
+    readonly UnsupportedMediaType: 415;
+    /** Used by the idempotency-key middleware when the same key is reused with a different body. */
+    readonly UnprocessableEntity: 422;
+    readonly TooManyRequests: 429;
+    readonly InternalServerError: 500;
+    readonly BadGateway: 502;
+    readonly ServiceUnavailable: 503;
+};
+/** Error thrown from inside a handler to produce a 4xx/5xx with details. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly extra?: Readonly<Record<string, unknown>> | undefined;
+    constructor(status: number, message: string, extra?: Readonly<Record<string, unknown>> | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/http/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;IACxE,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,yEAAyE;AACzE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;IAejB,gGAAgG;;;;;;CAMxF,CAAC;AAEX,4EAA4E;AAC5E,qBAAa,SAAU,SAAQ,KAAK;aAEhB,MAAM,EAAE,MAAM;aAEd,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAFzC,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,YAAA;CAK5D"}

package/dist/http/types.js

@@ -0,0 +1,40 @@
+/**
+ * Shared HTTP types.  Kept small and backend-agnostic: the Route DSL works
+ * only with these shapes, and the different backends (Fastify, BunServe,
+ * Express) translate to/from their native APIs.
+ */
+/** Named HTTP status codes for callers that don't want magic numbers. */
+export const Status = {
+    OK: 200,
+    Created: 201,
+    Accepted: 202,
+    NoContent: 204,
+    MovedPermanently: 301,
+    Found: 302,
+    NotModified: 304,
+    BadRequest: 400,
+    Unauthorized: 401,
+    Forbidden: 403,
+    NotFound: 404,
+    MethodNotAllowed: 405,
+    Conflict: 409,
+    UnsupportedMediaType: 415,
+    /** Used by the idempotency-key middleware when the same key is reused with a different body. */
+    UnprocessableEntity: 422,
+    TooManyRequests: 429,
+    InternalServerError: 500,
+    BadGateway: 502,
+    ServiceUnavailable: 503,
+};
+/** Error thrown from inside a handler to produce a 4xx/5xx with details. */
+export class HttpError extends Error {
+    status;
+    extra;
+    constructor(status, message, extra) {
+        super(message);
+        this.status = status;
+        this.extra = extra;
+        this.name = 'HttpError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/http/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,GAAG;IACd,gBAAgB,EAAE,GAAG;IACrB,KAAK,EAAE,GAAG;IACV,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;IACrB,QAAQ,EAAE,GAAG;IACb,oBAAoB,EAAE,GAAG;IACzB,gGAAgG;IAChG,mBAAmB,EAAE,GAAG;IACxB,eAAe,EAAE,GAAG;IACpB,mBAAmB,EAAE,GAAG;IACxB,UAAU,EAAE,GAAG;IACf,kBAAkB,EAAE,GAAG;CACf,CAAC;AAEX,4EAA4E;AAC5E,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEhB;IAEA;IAHlB,YACkB,MAAc,EAC9B,OAAe,EACC,KAAyC;QAEzD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QAEd,UAAK,GAAL,KAAK,CAAoC;QAGzD,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}