stratal 0.0.27 → 0.1.0

package/dist/response-headers-BqA57S_X.mjs

@@ -0,0 +1,158 @@
+//#region src/response-cache/cached-entrypoint.ts
+/** Methods Workers Caching will ever store. Everything else always runs inline. */
+const CACHEABLE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+/**
+* Whether the gateway should forward this request into the cached entrypoint.
+*
+* Anything that returns `false` runs inline in the gateway and never reaches
+* the cached entrypoint at all — which is what keeps RFC 9111 heuristic
+* freshness (a `200` with no `Cache-Control` cached for two hours) away from
+* un-annotated routes.
+*/
+function shouldLoopback(method, cacheable) {
+	if (!cacheable) return false;
+	return CACHEABLE_METHODS.has(method.toUpperCase());
+}
+//#endregion
+//#region src/response-cache/representation.ts
+/**
+* Folding a response's *representation* into the cache key.
+*
+* A route may answer one URL with more than one body — an HTML document and a
+* JSON payload for the same page, say — chosen from a request header. HTTP's
+* answer is `Vary`, and Workers Caching documents it as honoured, so a
+* response that declares `Vary: X-Inertia` should be stored once per distinct
+* value of that header.
+*
+* Measured, it is not reliable: on a URL carrying a query string, a variant
+* stored for one value of the header is served to a request sending another,
+* so a browser navigation receives the JSON meant for a client-side visit.
+* `Vary` is a matching pass applied to an entry that has already been located
+* by key; `ctx.props` IS part of the key, and Cloudflare documents it as
+* impossible to bypass — the same property that makes it the mechanism for
+* per-caller partitioning.
+*
+* So the representation goes in the key. Two representations become two
+* entries, and nothing downstream has to match correctly for the right one to
+* come back. `Vary` is still emitted, because it is what tells the *browser*
+* cache the same thing and the Inertia protocol requires it — it is simply no
+* longer load-bearing here.
+*/
+/**
+* The `ctx.props` key the representation is carried under.
+*
+* `$`-prefixed so it cannot collide with a partition name: partitions are
+* referenced from `partitionBy: ['user']` and are written as identifiers, and
+* `assertPartitionNames` rejects the prefix outright rather than letting a
+* collision silently overwrite one or the other.
+*/
+const REPRESENTATION_PROP = "$representation";
+/**
+* Headers the platform varies on by itself, which therefore need no key of
+* ours.
+*
+* Compression is negotiated and stored by Cloudflare independently of the
+* response body the Worker returns, so `Vary: Accept-Encoding` — which almost
+* every framework and proxy emits — describes something already handled. Left
+* out of this list it would make nearly every response uncacheable.
+*/
+const PLATFORM_HANDLED = /* @__PURE__ */ new Set(["accept-encoding"]);
+/**
+* The request's values for `keyBy`, as one deterministic string.
+*
+* Names are lowercased and sorted so that reordering `keyBy` does not
+* re-partition a live cache, and each value is carried as `null` when the
+* header is absent — a header that is missing and one sent empty are different
+* requests and must not collapse onto one entry.
+*
+* Returns `undefined` when nothing is declared, so the common case adds no
+* prop at all and leaves the key exactly as it was.
+*/
+function representationOf(headers, keyBy) {
+	if (!keyBy || keyBy.length === 0) return void 0;
+	const names = [...new Set(keyBy.map((name) => name.toLowerCase()))].sort();
+	return JSON.stringify(names.map((name) => [name, headers.get(name)]));
+}
+/**
+* The names a response says it varies on that are NOT in the cache key.
+*
+* Each one is a way for two different bodies to share one entry, so a response
+* naming any of them is refused rather than stored — see `CacheabilityService`.
+* `*` counts as unkeyed: Cloudflare treats `Vary: *` as uncacheable anyway, and
+* it cannot be satisfied from request headers by definition.
+*/
+function unkeyedVary(varyHeader, keyBy) {
+	if (!varyHeader) return [];
+	const keyed = new Set((keyBy ?? []).map((name) => name.toLowerCase()));
+	return varyHeader.split(",").map((name) => name.trim().toLowerCase()).filter(Boolean).filter((name) => !keyed.has(name) && !PLATFORM_HANDLED.has(name));
+}
+//#endregion
+//#region src/response-cache/response-headers.ts
+/**
+* Set (or delete, via `null`) one or more headers on a `Response`, mutating
+* in place whenever the header list allows it.
+*
+* A `Response`'s header list has a "guard" — per the Fetch spec, plain
+* `Response`s (anything built with `new Response(...)`, which is what every
+* Stratal controller returns) get guard `"response"`, which is mutable.
+* `.set()`/`.delete()` only throw for guard `"immutable"`, which shows up for
+* responses obtained from a `fetch()` subrequest or otherwise already handed
+* off — not for a response this Worker constructed itself. That's the
+* overwhelming majority of what flows through this function, so mutating in
+* place avoids cloning the response (and re-wrapping its body stream) on
+* every request just to add a `Cache-Control` header.
+*
+* Falls back to reconstructing the `Response` only when a `.set()`/`.delete()`
+* call actually throws. Skips touching the response entirely outside the
+* `[200, 599]` status range: the `Response` constructor throws a `RangeError`
+* for a status outside that range (notably `101`), and — for a `101`
+* WebSocket-upgrade response specifically — reconstructing would drop
+* Cloudflare's `webSocket`/`cf` init fields the original carried, which
+* `{ status, statusText, headers }` alone can't reproduce.
+*/
+function setResponseHeaders(response, headers) {
+	if (response.status < 200 || response.status > 599) return response;
+	try {
+		for (const [name, value] of Object.entries(headers)) if (value === null) response.headers.delete(name);
+		else response.headers.set(name, value);
+		return response;
+	} catch {
+		const merged = new Headers(response.headers);
+		for (const [name, value] of Object.entries(headers)) if (value === null) merged.delete(name);
+		else merged.set(name, value);
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: merged
+		});
+	}
+}
+/** `public` as a whole directive, not the substring inside `no-cache="public"` or a field name. */
+const PUBLIC_DIRECTIVE = /(?:^|,)\s*public\s*(?:,|$)/;
+/**
+* Whether a SHARED cache is permitted to store this response and serve it to a
+* different caller.
+*
+* `public` and `s-maxage` are the two directives that say so outright (RFC 9111
+* §5.2.2). Everything else is treated as not shared-cacheable: `private` and
+* `no-store` say so explicitly, and a response with no `Cache-Control` at all
+* never reaches a caller in a Stratal app without one — `createNoStoreFallback\
+Middleware` stamps it first.
+*
+* `CDN-Cache-Control` is read the same way and counts on its own. It is the
+* header a CDN honours in preference to `Cache-Control`, so a response can be
+* stored and replayed to other callers on the strength of it alone — reading
+* only `Cache-Control` would call such a response private and leave whatever
+* this guards, per-caller headers included, to be served to everyone.
+*/
+function isSharedCacheable(response) {
+	const says = (header) => {
+		const directives = response.headers.get(header)?.toLowerCase() ?? "";
+		return PUBLIC_DIRECTIVE.test(directives) || directives.includes("s-maxage");
+	};
+	return says("Cache-Control") || says("CDN-Cache-Control");
+}
+//#endregion
+export { unkeyedVary as a, representationOf as i, setResponseHeaders as n, shouldLoopback as o, REPRESENTATION_PROP as r, isSharedCacheable as t };
+
+//# sourceMappingURL=response-headers-BqA57S_X.mjs.map

package/dist/response-headers-BqA57S_X.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-headers-BqA57S_X.mjs","names":[],"sources":["../src/response-cache/cached-entrypoint.ts","../src/response-cache/representation.ts","../src/response-cache/response-headers.ts"],"sourcesContent":["import type { CacheableOptions } from './types'\n\n/** Methods Workers Caching will ever store. Everything else always runs inline. */\nconst CACHEABLE_METHODS = new Set(['GET', 'HEAD'])\n\n/**\n * Whether the gateway should forward this request into the cached entrypoint.\n *\n * Anything that returns `false` runs inline in the gateway and never reaches\n * the cached entrypoint at all — which is what keeps RFC 9111 heuristic\n * freshness (a `200` with no `Cache-Control` cached for two hours) away from\n * un-annotated routes.\n */\nexport function shouldLoopback(method: string, cacheable: CacheableOptions | undefined): boolean {\n  if (!cacheable) return false\n  return CACHEABLE_METHODS.has(method.toUpperCase())\n}\n","/**\n * Folding a response's *representation* into the cache key.\n *\n * A route may answer one URL with more than one body — an HTML document and a\n * JSON payload for the same page, say — chosen from a request header. HTTP's\n * answer is `Vary`, and Workers Caching documents it as honoured, so a\n * response that declares `Vary: X-Inertia` should be stored once per distinct\n * value of that header.\n *\n * Measured, it is not reliable: on a URL carrying a query string, a variant\n * stored for one value of the header is served to a request sending another,\n * so a browser navigation receives the JSON meant for a client-side visit.\n * `Vary` is a matching pass applied to an entry that has already been located\n * by key; `ctx.props` IS part of the key, and Cloudflare documents it as\n * impossible to bypass — the same property that makes it the mechanism for\n * per-caller partitioning.\n *\n * So the representation goes in the key. Two representations become two\n * entries, and nothing downstream has to match correctly for the right one to\n * come back. `Vary` is still emitted, because it is what tells the *browser*\n * cache the same thing and the Inertia protocol requires it — it is simply no\n * longer load-bearing here.\n */\n\n/**\n * The `ctx.props` key the representation is carried under.\n *\n * `$`-prefixed so it cannot collide with a partition name: partitions are\n * referenced from `partitionBy: ['user']` and are written as identifiers, and\n * `assertPartitionNames` rejects the prefix outright rather than letting a\n * collision silently overwrite one or the other.\n */\nexport const REPRESENTATION_PROP = '$representation'\n\n/**\n * Headers the platform varies on by itself, which therefore need no key of\n * ours.\n *\n * Compression is negotiated and stored by Cloudflare independently of the\n * response body the Worker returns, so `Vary: Accept-Encoding` — which almost\n * every framework and proxy emits — describes something already handled. Left\n * out of this list it would make nearly every response uncacheable.\n */\nconst PLATFORM_HANDLED = new Set(['accept-encoding'])\n\n/**\n * The request's values for `keyBy`, as one deterministic string.\n *\n * Names are lowercased and sorted so that reordering `keyBy` does not\n * re-partition a live cache, and each value is carried as `null` when the\n * header is absent — a header that is missing and one sent empty are different\n * requests and must not collapse onto one entry.\n *\n * Returns `undefined` when nothing is declared, so the common case adds no\n * prop at all and leaves the key exactly as it was.\n */\nexport function representationOf(\n  headers: Headers,\n  keyBy: readonly string[] | undefined,\n): string | undefined {\n  if (!keyBy || keyBy.length === 0) return undefined\n\n  const names = [...new Set(keyBy.map((name) => name.toLowerCase()))].sort()\n\n  return JSON.stringify(names.map((name) => [name, headers.get(name)]))\n}\n\n/**\n * The names a response says it varies on that are NOT in the cache key.\n *\n * Each one is a way for two different bodies to share one entry, so a response\n * naming any of them is refused rather than stored — see `CacheabilityService`.\n * `*` counts as unkeyed: Cloudflare treats `Vary: *` as uncacheable anyway, and\n * it cannot be satisfied from request headers by definition.\n */\nexport function unkeyedVary(\n  varyHeader: string | null,\n  keyBy: readonly string[] | undefined,\n): string[] {\n  if (!varyHeader) return []\n\n  const keyed = new Set((keyBy ?? []).map((name) => name.toLowerCase()))\n\n  return varyHeader\n    .split(',')\n    .map((name) => name.trim().toLowerCase())\n    .filter(Boolean)\n    .filter((name) => !keyed.has(name) && !PLATFORM_HANDLED.has(name))\n}\n","/**\n * Set (or delete, via `null`) one or more headers on a `Response`, mutating\n * in place whenever the header list allows it.\n *\n * A `Response`'s header list has a \"guard\" — per the Fetch spec, plain\n * `Response`s (anything built with `new Response(...)`, which is what every\n * Stratal controller returns) get guard `\"response\"`, which is mutable.\n * `.set()`/`.delete()` only throw for guard `\"immutable\"`, which shows up for\n * responses obtained from a `fetch()` subrequest or otherwise already handed\n * off — not for a response this Worker constructed itself. That's the\n * overwhelming majority of what flows through this function, so mutating in\n * place avoids cloning the response (and re-wrapping its body stream) on\n * every request just to add a `Cache-Control` header.\n *\n * Falls back to reconstructing the `Response` only when a `.set()`/`.delete()`\n * call actually throws. Skips touching the response entirely outside the\n * `[200, 599]` status range: the `Response` constructor throws a `RangeError`\n * for a status outside that range (notably `101`), and — for a `101`\n * WebSocket-upgrade response specifically — reconstructing would drop\n * Cloudflare's `webSocket`/`cf` init fields the original carried, which\n * `{ status, statusText, headers }` alone can't reproduce.\n */\nexport function setResponseHeaders(response: Response, headers: Record<string, string | null>): Response {\n  if (response.status < 200 || response.status > 599) return response\n\n  try {\n    for (const [name, value] of Object.entries(headers)) {\n      if (value === null) response.headers.delete(name)\n      else response.headers.set(name, value)\n    }\n    return response\n  } catch {\n    const merged = new Headers(response.headers)\n    for (const [name, value] of Object.entries(headers)) {\n      if (value === null) merged.delete(name)\n      else merged.set(name, value)\n    }\n    return new Response(response.body, {\n      status: response.status,\n      statusText: response.statusText,\n      headers: merged,\n    })\n  }\n}\n\n/** `public` as a whole directive, not the substring inside `no-cache=\"public\"` or a field name. */\nconst PUBLIC_DIRECTIVE = /(?:^|,)\\s*public\\s*(?:,|$)/\n\n/**\n * Whether a SHARED cache is permitted to store this response and serve it to a\n * different caller.\n *\n * `public` and `s-maxage` are the two directives that say so outright (RFC 9111\n * §5.2.2). Everything else is treated as not shared-cacheable: `private` and\n * `no-store` say so explicitly, and a response with no `Cache-Control` at all\n * never reaches a caller in a Stratal app without one — `createNoStoreFallback\\\nMiddleware` stamps it first.\n *\n * `CDN-Cache-Control` is read the same way and counts on its own. It is the\n * header a CDN honours in preference to `Cache-Control`, so a response can be\n * stored and replayed to other callers on the strength of it alone — reading\n * only `Cache-Control` would call such a response private and leave whatever\n * this guards, per-caller headers included, to be served to everyone.\n */\nexport function isSharedCacheable(response: Response): boolean {\n  const says = (header: string): boolean => {\n    const directives = response.headers.get(header)?.toLowerCase() ?? ''\n    return PUBLIC_DIRECTIVE.test(directives) || directives.includes('s-maxage')\n  }\n\n  return says('Cache-Control') || says('CDN-Cache-Control')\n}\n"],"mappings":";;AAGA,MAAM,oCAAoB,IAAI,IAAI,CAAC,OAAO,MAAM,CAAC;;;;;;;;;AAUjD,SAAgB,eAAe,QAAgB,WAAkD;CAC/F,IAAI,CAAC,WAAW,OAAO;CACvB,OAAO,kBAAkB,IAAI,OAAO,YAAY,CAAC;AACnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACgBA,MAAa,sBAAsB;;;;;;;;;;AAWnC,MAAM,mCAAmB,IAAI,IAAI,CAAC,iBAAiB,CAAC;;;;;;;;;;;;AAapD,SAAgB,iBACd,SACA,OACoB;CACpB,IAAI,CAAC,SAAS,MAAM,WAAW,GAAG,OAAO,KAAA;CAEzC,MAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,MAAM,KAAK,SAAS,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK;CAEzE,OAAO,KAAK,UAAU,MAAM,KAAK,SAAS,CAAC,MAAM,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC;AACtE;;;;;;;;;AAUA,SAAgB,YACd,YACA,OACU;CACV,IAAI,CAAC,YAAY,OAAO,CAAC;CAEzB,MAAM,QAAQ,IAAI,KAAK,SAAS,CAAC,EAAA,CAAG,KAAK,SAAS,KAAK,YAAY,CAAC,CAAC;CAErE,OAAO,WACJ,MAAM,GAAG,CAAC,CACV,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CACxC,OAAO,OAAO,CAAC,CACf,QAAQ,SAAS,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,iBAAiB,IAAI,IAAI,CAAC;AACrE;;;;;;;;;;;;;;;;;;;;;;;;;AClEA,SAAgB,mBAAmB,UAAoB,SAAkD;CACvG,IAAI,SAAS,SAAS,OAAO,SAAS,SAAS,KAAK,OAAO;CAE3D,IAAI;EACF,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,OAAO,GAChD,IAAI,UAAU,MAAM,SAAS,QAAQ,OAAO,IAAI;OAC3C,SAAS,QAAQ,IAAI,MAAM,KAAK;EAEvC,OAAO;CACT,QAAQ;EACN,MAAM,SAAS,IAAI,QAAQ,SAAS,OAAO;EAC3C,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,OAAO,GAChD,IAAI,UAAU,MAAM,OAAO,OAAO,IAAI;OACjC,OAAO,IAAI,MAAM,KAAK;EAE7B,OAAO,IAAI,SAAS,SAAS,MAAM;GACjC,QAAQ,SAAS;GACjB,YAAY,SAAS;GACrB,SAAS;EACX,CAAC;CACH;AACF;;AAGA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;AAkBzB,SAAgB,kBAAkB,UAA6B;CAC7D,MAAM,QAAQ,WAA4B;EACxC,MAAM,aAAa,SAAS,QAAQ,IAAI,MAAM,CAAC,EAAE,YAAY,KAAK;EAClE,OAAO,iBAAiB,KAAK,UAAU,KAAK,WAAW,SAAS,UAAU;CAC5E;CAEA,OAAO,KAAK,eAAe,KAAK,KAAK,mBAAmB;AAC1D"}

package/dist/rolldown-runtime-D7D4PA-g.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/route-cache-binding-CrLh8tB6.mjs

@@ -0,0 +1,390 @@
+import { _ as defineMetadata, v as getMetadata } from "./di-DQ3xbjgf.mjs";
+import { u as ROUTE_METADATA_KEYS } from "./exception-context-CdnGTQNF.mjs";
+import { r as ResponseCacheConfigError } from "./response-cache.error-B4D0zy9W.mjs";
+//#region src/response-cache/gateway-binding.ts
+/**
+* Look up the configured cached entrypoint on `ctx.exports`, failing loudly if
+* it isn't there.
+*
+* A typo in `gateway: { entrypoint: 'Cachd' }`, a missing `export const
+* Cached = ...`, or a missing `enable_ctx_exports` compatibility flag would
+* otherwise all present identically: every partitioned route quietly runs
+* inline in the gateway forever, never caching, with no signal anywhere. The
+* whole point of `partitionBy` refusing to boot without a gateway is that a
+* declared partition is either honoured or it is an error — so this is an
+* error too.
+*
+* @throws {ResponseCacheConfigError} `ctx.exports` is unavailable, or carries
+*   no export under `name`.
+*/
+function resolveCachedEntrypoint(ctx, name) {
+	let exports;
+	try {
+		exports = ctx?.exports;
+	} catch (error) {
+		throw new ResponseCacheConfigError(`reading \`ctx.exports\` failed (${error instanceof Error ? error.message : String(error)}), so the cached entrypoint "${name}" cannot be reached. Add "enable_ctx_exports" to \`compatibility_flags\` in your Wrangler config.`);
+	}
+	if (typeof exports !== "object" || exports === null) throw new ResponseCacheConfigError(`\`ctx.exports\` is unavailable on this entrypoint, so the cached entrypoint "${name}" configured via \`ResponseCacheModule.forRoot({ gateway: { entrypoint } })\` cannot be reached. Add "enable_ctx_exports" to \`compatibility_flags\` in your Wrangler config, and set \`compatibility_date\` to 2026-07-06 or later.`);
+	const binding = exports[name];
+	if (binding === void 0 || binding === null) {
+		const available = Object.keys(exports);
+		throw new ResponseCacheConfigError(`the cached entrypoint "${name}" is not exported by this Worker. \`ResponseCacheModule.forRoot({ gateway: { entrypoint } })\` must name a top-level export — \`export const ${name} = cachedEntrypoint(stratal)\` — that is also declared in your Wrangler \`exports\` block with \`cache: { enabled: true }\`. Exports visible on \`ctx.exports\`: ${available.length > 0 ? available.join(", ") : "(none)"}.`);
+	}
+	return binding;
+}
+/**
+* A `WorkersCache` that purges through the cached entrypoint over RPC.
+*
+* Handed to `ResponseCacheService.purge()` in place of the gateway's own
+* `ctx.cache` whenever a gateway is configured and this request is running as
+* the gateway. See `cachedEntrypoint` for why that redirection is required
+* rather than merely tidy.
+*/
+function createLoopbackPurgeTarget(ctx, name) {
+	return { purge: async (spec) => resolveCachedEntrypoint(ctx, name).purge(spec) };
+}
+//#endregion
+//#region src/response-cache/response-cache.tokens.ts
+const RESPONSE_CACHE_TOKENS = {
+	Options: Symbol.for("stratal:response-cache:options"),
+	ResponseCacheService: Symbol.for("stratal:response-cache:service"),
+	CacheabilityService: Symbol.for("stratal:response-cache:cacheability"),
+	PartitionResolverService: Symbol.for("stratal:response-cache:partition-resolver"),
+	GatewayPrimerService: Symbol.for("stratal:response-cache:gateway-primer"),
+	GatewayPrimers: Symbol.for("stratal:response-cache:gateway-primers"),
+	GatewayRouteTable: Symbol.for("stratal:response-cache:gateway-route-table")
+};
+//#endregion
+//#region src/response-cache/decorators/cacheable.decorator.ts
+const KEY$1 = ROUTE_METADATA_KEYS.CACHEABLE;
+/**
+* Mark a route's response as cacheable by Cloudflare Workers Caching.
+*
+* Only `GET` and `HEAD` are ever cached. Omitted fields fall back to the
+* module's `defaults` block; an explicit value always wins.
+*
+* @example
+* ```typescript
+* @Get('/blog/:slug')
+* @Cacheable({ ttl: 300, swr: 60, tags: ['post:{param.slug}'] })
+* async show(ctx: RouterContext) { ... }
+* ```
+*
+* Module defaults fill in whatever the route leaves out:
+*
+* @example
+* ```typescript
+* ResponseCacheModule.forRoot({ defaults: { ttl: 300, swr: 60 } })
+*
+* @Get('/pricing')
+* @Cacheable()                       // ttl 300, swr 60
+* async pricing(ctx: RouterContext) { ... }
+* ```
+*
+* **A guarded route needs a `partitionBy`.** A guarded route's response differs
+* per caller, so caching it under one shared entry would serve one user's
+* response to another. `@Cacheable` on a route carrying `@UseGuards` is a boot
+* error unless it declares a non-empty `partitionBy` (or inherits one from
+* `defaults.partitionBy`) — and per-caller keying additionally requires
+* `ResponseCacheModule.forRoot({ gateway: { entrypoint } })`, without which
+* `partitionBy` itself is rejected at boot.
+*
+* @example
+* ```typescript
+* @Get('/dashboard')
+* @UseGuards(AuthGuard)
+* @Cacheable({ ttl: 60, partitionBy: ['user'] })
+* async dashboard(ctx: RouterContext) { ... }
+* ```
+*/
+function Cacheable(options = {}) {
+	return (target, propertyKey) => {
+		defineMetadata(KEY$1, options, target, propertyKey);
+	};
+}
+/** Read the `@Cacheable` options for a method. Returns `undefined` when absent. */
+function getCacheable(target, methodName) {
+	return getMetadata(KEY$1, target, methodName);
+}
+//#endregion
+//#region src/response-cache/decorators/purges-cache.decorator.ts
+const KEY = ROUTE_METADATA_KEYS.PURGES_CACHE;
+/**
+* Invalidate cached responses after this route mutates data.
+*
+* Runs after the handler returns a 2xx or 3xx. `pathPrefixes` matches the
+* request path only, so `['/blog']` also clears `/blog?page=2`.
+*
+* @example
+* ```typescript
+* @Post('/posts/:slug/publish')
+* @PurgesCache({ tags: ['post:{param.slug}', 'category:{data.post.categoryId}'] })
+* async publish(ctx: RouterContext) { ... }
+* ```
+*/
+function PurgesCache(options) {
+	const hasTargets = (options.tags?.length ?? 0) > 0 || (options.pathPrefixes?.length ?? 0) > 0;
+	if (options.purgeEverything && hasTargets) throw new ResponseCacheConfigError("@PurgesCache: `purgeEverything` is exclusive — remove `tags` and `pathPrefixes`.");
+	if (!options.purgeEverything && !hasTargets) throw new ResponseCacheConfigError("@PurgesCache: specify at least one of `tags`, `pathPrefixes`, or `purgeEverything`.");
+	return (target, propertyKey) => {
+		defineMetadata(KEY, options, target, propertyKey);
+	};
+}
+/** Read the `@PurgesCache` options for a method. Returns `undefined` when absent. */
+function getPurgesCache(target, methodName) {
+	return getMetadata(KEY, target, methodName);
+}
+//#endregion
+//#region src/response-cache/boot-check.ts
+/**
+* Why this entrypoint cannot cache, or `undefined` when it can.
+*
+* A Worker cannot read its own Wrangler configuration, but the presence of
+* `ctx.cache` tells us whether Workers Caching is enabled for this entrypoint.
+*
+* Reported rather than thrown, and the distinction is the whole point. The
+* hazard is a route stamping `public, max-age=…` while nothing stores the
+* response: a claim the app makes and no layer honours. Refusing to make that
+* claim removes the hazard — the response falls through to
+* `createNoStoreFallbackMiddleware` and is stamped `private, no-store`, which
+* is both true and visible in the response itself. Failing the request
+* removes it too, but takes down every route in the isolate to do it,
+* including the ones that never asked to be cached.
+*
+* The answer belongs to an entrypoint rather than to the app, because a
+* gateway topology runs two of them — one with `cache.enabled` false by
+* design, one with it true — inside a single isolate.
+*/
+function cachingUnavailableReason(cacheableRouteCount, cache) {
+	if (cacheableRouteCount === 0) return void 0;
+	if (cache) return void 0;
+	return `${cacheableRouteCount} route(s) declare @Cacheable, but Workers Caching is not available on this entrypoint, so their responses are served uncached and stamped \`private, no-store\`. Set \`"cache": { "enabled": true }\` in your Wrangler config, use Wrangler >= 4.69.0, and set \`compatibility_date\` to 2026-07-06 or later.`;
+}
+/**
+* The one export name a gateway can never forward to: its own.
+*
+* `ctx.exports.default` is the default export — the `Stratal` instance whose
+* `fetch` marks the context as the gateway and dispatches. Forwarding there
+* re-enters the gateway, which marks the *new* context and forwards again,
+* recursing until the runtime's subrequest limit kills the request. Rejecting
+* it at boot is what makes "the cached entrypoint never re-dispatches, so no
+* loop is possible" true rather than merely true-if-configured-correctly.
+*/
+const SELF_ENTRYPOINT = "default";
+/**
+* Validate the configured entrypoint name itself.
+*
+* Split from the reachability check in `resolveCachedEntrypoint` because this
+* part needs no runtime: a name that is empty, or names the gateway itself, is
+* wrong on inspection and should never reach a first request.
+*/
+function assertValidGatewayEntrypoint(options) {
+	const gateway = options.gateway;
+	if (!gateway) return;
+	const entrypoint = gateway.entrypoint;
+	if (typeof entrypoint !== "string" || entrypoint.trim() === "") throw new ResponseCacheConfigError("ResponseCacheModule: `gateway.entrypoint` must be a non-empty export name, e.g. `gateway: { entrypoint: 'Cached' }` matching `export const Cached = cachedEntrypoint(stratal)`.");
+	if (entrypoint === SELF_ENTRYPOINT) throw new ResponseCacheConfigError("ResponseCacheModule: `gateway.entrypoint` cannot be \"default\" — that is the gateway itself. Forwarding to it would re-enter the gateway, which would forward again, recursing until the Worker hits its subrequest limit. Export a separate cached entrypoint (`export const Cached = cachedEntrypoint(stratal)`) and name that instead, with `cache: { enabled: false }` on `default` and `true` on the named export.");
+}
+/**
+* Keep partition names out of the `$`-prefixed space the framework reserves.
+*
+* Partitions and the representation both become `ctx.props` entries, and props
+* is a flat object — a partition named `$representation` would overwrite the
+* representation or be overwritten by it, either way silently collapsing two
+* cache keys into one. The prefix is rejected wholesale rather than just the
+* one name in use today, so a later reserved key cannot break an app that had
+* already shipped a partition called it.
+*/
+function assertPartitionNames(options) {
+	const reserved = Object.keys(options.partitions ?? {}).filter((name) => name.startsWith("$"));
+	if (reserved.length > 0) throw new ResponseCacheConfigError(`ResponseCacheModule: partition name(s) ${reserved.join(", ")} start with "$", which is reserved for values the framework puts in \`ctx.props\` itself. Rename them.`);
+}
+/**
+* Reject the two module options only the gateway entrypoint can act on, when
+* no gateway entrypoint is configured.
+*
+* `partitions` is looked up by `partitionBy`, which `bindRouteCache` rejects
+* under the same condition; `primers` is read only by `GatewayPrimerService`,
+* which the dispatch middleware is the sole caller of. Without
+* `gateway.entrypoint` neither is ever consulted, and accepting them silently
+* is the "option a consumer sets that does nothing" failure this feature is
+* otherwise careful to avoid — an author would reasonably read a configured
+* `partitions` block as proof that per-user keying is in effect. Fail at boot
+* instead, in the same breath as `partitionBy`.
+*
+* Validates the entrypoint name first, so `gateway: { entrypoint: '' }` is
+* reported as the malformed name it is rather than falling through to a
+* "you need a gateway" message about the wrong thing.
+*/
+function assertNoGatewayOptions(options) {
+	assertValidGatewayEntrypoint(options);
+	assertPartitionNames(options);
+	if (options.gateway !== void 0) return;
+	if (Object.keys(options.partitions ?? {}).length > 0) throw new ResponseCacheConfigError("ResponseCacheModule: `partitions` requires `gateway: { entrypoint }`. Partition resolvers only run in the gateway, which forwards partitioned reads to a cached entrypoint over `ctx.exports` — without one, the resolvers configured here would never be called and every `partitionBy` route would cache publicly. Add `gateway: { entrypoint: 'Cached' }` and `export const Cached = cachedEntrypoint(stratal)`, or remove `partitions` (and any `partitionBy`).");
+	if ((options.primers?.length ?? 0) > 0) throw new ResponseCacheConfigError("ResponseCacheModule: `primers` requires `gateway: { entrypoint }`. Primers exist to populate the request container before partition resolution runs in the gateway — without a cached entrypoint nothing would ever run them, including `AUTH_GATEWAY_PRIMERS`. Add `gateway: { entrypoint }`, or remove `primers`.");
+}
+//#endregion
+//#region src/response-cache/resolve-cacheable.ts
+/**
+* Fold module defaults into a route's `@Cacheable` options.
+*
+* `partitionBy` replaces rather than merges: a route must be able to declare
+* itself public (`[]`) or re-partition without inheriting a stale default.
+* Reading the route alone must be enough to know how it is keyed.
+*/
+function resolveCacheable(route, defaults, context) {
+	const where = `${context.controller}.${context.method}`;
+	const ttl = route.ttl ?? defaults.ttl;
+	if (ttl === void 0) throw new ResponseCacheConfigError(`${where}: @Cacheable needs a \`ttl\`, either on the route or via ResponseCacheModule.forRoot({ defaults: { ttl } }).`);
+	if (ttl <= 0 || !Number.isFinite(ttl)) throw new ResponseCacheConfigError(`${where}: @Cacheable \`ttl\` must be a positive number of seconds.`);
+	const browserTtl = route.browserTtl ?? defaults.browserTtl ?? ttl;
+	if (browserTtl < 0 || !Number.isFinite(browserTtl)) throw new ResponseCacheConfigError(`${where}: @Cacheable \`browserTtl\` must be a non-negative finite number of seconds.`);
+	const swr = route.swr ?? defaults.swr;
+	if (swr !== void 0 && (swr < 0 || !Number.isFinite(swr))) throw new ResponseCacheConfigError(`${where}: @Cacheable \`swr\` must be a non-negative finite number of seconds.`);
+	const partitionBy = route.partitionBy ?? defaults.partitionBy ?? [];
+	if (context.guarded && partitionBy.length === 0) throw new ResponseCacheConfigError(context.gatewayConfigured ? `${where}: @Cacheable on a guarded route needs a non-empty \`partitionBy\`. A guarded route's response differs per caller, so caching it under one shared entry would serve one user's response to another. Declare the partitions it varies by (\`@Cacheable({ partitionBy: ['user'] })\`), or set a module-level \`defaults.partitionBy\`. \`partitionBy: []\` is not accepted here even explicitly.` : `${where}: @Cacheable cannot be used on a guarded route without a gateway entrypoint. A guarded route's response differs per caller, so caching it would serve one user's response to another. Per-caller cache keying needs \`ResponseCacheModule.forRoot({ gateway: { entrypoint } })\` plus a \`partitionBy\` — configure both, or remove @Cacheable from this route.`);
+	return {
+		ttl,
+		browserTtl,
+		swr,
+		tags: route.tags ?? [],
+		partitionBy,
+		vary: [.../* @__PURE__ */ new Set([...defaults.vary ?? [], ...route.vary ?? []])]
+	};
+}
+//#endregion
+//#region src/response-cache/services/route-cache-binding.ts
+/** Matches a `{body.*}` cache tag placeholder (any path under the `body` scope). */
+const BODY_SCOPE_TAG = /\{body\.[^}]+\}/;
+/**
+* Reject any tag that reads the `{body.*}` scope: the HTTP router never
+* populates `TagScopes.body` (see `RouteRegistrationService.buildTagScopes`)
+* — the parsed request body isn't cheaply available at the point tags are
+* rendered, and re-parsing it on every request just to support a rarely used
+* tag scope was deliberately rejected. A `{body.*}` tag can therefore never
+* resolve.
+*
+* Left unchecked, this doesn't fail quietly: on a `@PurgesCache` route,
+* `buildPurgeSpec(...)` is evaluated as an *argument* to `purge(...)`, so
+* `renderTags` throwing `InvalidCacheTagError` happens before `purge`'s own
+* try/catch exists — and `applyCacheDecision` has no catch of its own either,
+* so the request 500s *after* its mutation already committed. Catching it
+* here, at registration, turns a request-time failure the author only
+* discovers in production into a boot-time error they see before deploying.
+*/
+function assertNoBodyScopeTags(tags, decorator, context) {
+	const offending = tags?.find((tag) => BODY_SCOPE_TAG.test(tag));
+	if (!offending) return;
+	throw new ResponseCacheConfigError(`${context.controller}.${context.method}: ${decorator} tag "${offending}" uses the \`{body.*}\` scope, which can never resolve — the parsed request body is not available when cache tags are rendered. Use \`{param.*}\`, \`{query.*}\`, or \`{data.*}\` instead.`);
+}
+/** Matches a `{param.X}` cache tag placeholder, capturing the param name `X`. */
+const PARAM_SCOPE_TAG = /\{param\.([^}.]+)/g;
+/**
+* Reject a `{param.X}` tag whose `X` is not one of this route's own path
+* parameters.
+*
+* Unlike `{query.*}`/`{data.*}` — which depend on what a given *request*
+* happens to send, and so can only fail per-request — a route's path pattern
+* is fixed the moment it is registered. Whether `{param.id}` can ever resolve
+* is therefore knowable right now: if the route's path has no `:id` segment,
+* it never will, on any request. Left unchecked, this fails the exact same
+* way as `{body.*}` — `renderTags` throws mid-`purge(...)` call, after the
+* mutation already committed. Catching it here turns that into a boot-time
+* error instead.
+*
+* No-ops when `context.routeParams` is `undefined` — the caller didn't supply
+* the route's path, so there is nothing to validate against.
+*/
+function assertParamTagsResolvable(tags, decorator, context) {
+	if (!tags?.length || context.routeParams === void 0) return;
+	const routeParams = context.routeParams;
+	for (const tag of tags) for (const match of tag.matchAll(PARAM_SCOPE_TAG)) {
+		const param = match[1];
+		if (routeParams.includes(param)) continue;
+		const available = routeParams.length > 0 ? routeParams.join(", ") : "(none)";
+		throw new ResponseCacheConfigError(`${context.controller}.${context.method}: ${decorator} tag "${tag}" references \`{param.${param}}\`, but this route's path has no ":${param}" segment, so it can never resolve — available params: ${available}. Use one of those, or a \`{query.*}\`/\`{data.*}\` tag instead.`);
+	}
+}
+/** Matches a `{partition.X}` cache tag placeholder, capturing the partition name `X`. */
+const PARTITION_SCOPE_TAG = /\{partition\.([^}.]+)/g;
+/**
+* Reject a `{partition.X}` tag whose `X` is not one of this route's own
+* declared partitions.
+*
+* Knowable at boot for the same reason `{param.X}` is: `partitionBy` is fixed
+* when the route registers. A partition the route does not declare is not in
+* the cache key, so a tag naming it would describe an entry by something that
+* did not key it — and on `@PurgesCache` it throws mid-purge, after the
+* mutation committed.
+*
+* Only checked on `@Cacheable`, which is where `partitionBy` is declared. A
+* `@PurgesCache` route runs inline in the gateway, which resolves no
+* partitions of its own, so `{partition.*}` can never render there.
+*/
+function assertPartitionTagsResolvable(tags, partitionBy, decorator, context) {
+	if (!tags?.length) return;
+	for (const tag of tags) for (const match of tag.matchAll(PARTITION_SCOPE_TAG)) {
+		const partition = match[1];
+		if (decorator === "@Cacheable" && partitionBy.includes(partition)) continue;
+		const available = partitionBy.length > 0 ? partitionBy.join(", ") : "(none)";
+		throw new ResponseCacheConfigError(decorator === "@PurgesCache" ? `${context.controller}.${context.method}: @PurgesCache tag "${tag}" references \`{partition.${partition}}\`, but a mutation runs inline in the gateway, which resolves no partitions — so it can never resolve. Purge by a \`{param.*}\`/\`{query.*}\`/\`{data.*}\` tag the cached route also carries.` : `${context.controller}.${context.method}: @Cacheable tag "${tag}" references \`{partition.${partition}}\`, but this route does not declare that partition, so it is not in the cache key and can never resolve — declared: ${available}. Add it to \`partitionBy\`, or use one of those.`);
+	}
+}
+/**
+* Reject a `pathPrefixes` entry that looks like it expects interpolation.
+*
+* `ResponseCacheService.buildPurgeSpec` copies `pathPrefixes` through
+* verbatim — only `tags` go through `renderTags`. So
+* `pathPrefixes: ['/blog/{param.slug}']` is sent to `ctx.cache.purge()` as
+* that literal string, which matches no request path: the purge "succeeds",
+* nothing is invalidated, and the author is never told. Same class of silent
+* miss as a `{body.*}` tag, so it gets the same boot-time treatment.
+*/
+function assertNoTemplatedPathPrefixes(pathPrefixes, context) {
+	const offending = pathPrefixes?.find((prefix) => prefix.includes("{") || prefix.includes("}"));
+	if (offending === void 0) return;
+	throw new ResponseCacheConfigError(`${context.controller}.${context.method}: @PurgesCache \`pathPrefixes\` entry "${offending}" contains \`{\`/\`}\`, but path prefixes are not interpolated — only \`tags\` are. It would be purged as that literal string and match nothing. Use a static prefix (\`/blog\`), or move the dynamic part into a \`{param.*}\`/\`{query.*}\`/\`{data.*}\` cache tag.`);
+}
+/**
+* Fold a route's decorators and the module defaults into the config the request
+* path uses. Runs once per route at registration, never per request.
+*
+* Returns `undefined` when the route declares neither decorator, so the hot path
+* can skip all cache work with a single truthiness check.
+*
+* @throws {ResponseCacheConfigError} On a non-empty `partitionBy` when no
+*   `gateway.entrypoint` is configured. Placing a partition in the cache key
+*   requires the gateway to forward the read to a cached entrypoint over
+*   `ctx.exports`. Accepting the option and ignoring it would give every
+*   visitor a single shared entry for a route the author explicitly marked
+*   per-user.
+* @throws {ResponseCacheConfigError} On a `{body.*}` tag in either decorator's
+*   `tags` — see `assertNoBodyScopeTags`.
+* @throws {ResponseCacheConfigError} On a `{param.X}` tag whose `X` is not a
+*   `:param` in this route's own path (when `context.routeParams` is
+*   supplied) — see `assertParamTagsResolvable`.
+* @throws {ResponseCacheConfigError} On a `{`/`}` in `@PurgesCache`'s
+*   `pathPrefixes` — see `assertNoTemplatedPathPrefixes`.
+*/
+function bindRouteCache(cacheable, purges, defaults, context) {
+	if (!cacheable && !purges) return void 0;
+	assertNoBodyScopeTags(cacheable?.tags, "@Cacheable", context);
+	assertNoBodyScopeTags(purges?.tags, "@PurgesCache", context);
+	assertParamTagsResolvable(cacheable?.tags, "@Cacheable", context);
+	assertParamTagsResolvable(purges?.tags, "@PurgesCache", context);
+	assertPartitionTagsResolvable(purges?.tags, [], "@PurgesCache", context);
+	assertNoTemplatedPathPrefixes(purges?.pathPrefixes, context);
+	const binding = {};
+	if (purges) binding.purges = purges;
+	if (cacheable) {
+		const declared = cacheable.partitionBy ?? defaults.partitionBy ?? [];
+		assertPartitionTagsResolvable(cacheable.tags, declared, "@Cacheable", context);
+		if (declared.length > 0 && !context.gatewayConfigured) throw new ResponseCacheConfigError(`${context.controller}.${context.method}: \`partitionBy\` requires a gateway entrypoint. Placing a partition in the cache key means forwarding the read to a cached entrypoint over \`ctx.exports\`, so the option cannot be honored without one — and a route marked per-caller that quietly shared a single cache entry would serve one visitor's response to everyone. Configure \`ResponseCacheModule.forRoot({ gateway: { entrypoint: 'Cached' }, partitions: { … } })\` and \`export const Cached = cachedEntrypoint(stratal)\`, or remove \`partitionBy\`.`);
+		binding.cacheable = resolveCacheable(cacheable, defaults, context);
+	}
+	return binding;
+}
+//#endregion
+export { PurgesCache as a, getCacheable as c, resolveCachedEntrypoint as d, cachingUnavailableReason as i, RESPONSE_CACHE_TOKENS as l, assertNoGatewayOptions as n, getPurgesCache as o, assertValidGatewayEntrypoint as r, Cacheable as s, bindRouteCache as t, createLoopbackPurgeTarget as u };
+
+//# sourceMappingURL=route-cache-binding-CrLh8tB6.mjs.map