vinext 1.0.0 → 1.1.0

package/dist/server/request-pipeline.js

@@ -3,7 +3,7 @@ import { getUnconsumedMiddlewareRequestHeaders } from "../utils/middleware-reque
 import { hasBasePath, removeTrailingSlash, stripBasePath } from "../utils/base-path.js";
 import { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS } from "./headers.js";
 import { forbiddenResponse, methodNotAllowedResponse, notFoundResponse } from "./http-error-responses.js";
-import { isOpenRedirectShaped } from "./open-redirect.js";
+import { getRepeatedSlashRedirect, isOpenRedirectShaped, repeatedSlashRedirectResponse, sendRepeatedSlashRedirect } from "./open-redirect.js";
 import { createStaticFileSignal } from "./static-file-signal.js";
 //#region src/server/request-pipeline.ts
 const PATHNAME_CANONICALIZATION_BASE = new URL("http://vinext.invalid/");
@@ -52,10 +52,21 @@ function canonicalizeRequestUrlPathname(url) {
 * Backslashes are equivalent to forward slashes in the URL spec
 * (e.g. `/\evil.com` is treated as `//evil.com` by browsers).
 *
-* Next.js returns 404 for these paths. We check the RAW pathname before
-* normalization so the guard fires before normalizePath collapses `//`.
+* Like Next.js, any raw path containing a literal backslash or a repeated
+* slash first gets a 308 to the collapsed path (`//evil.com` → `/evil.com`,
+* `//` → `/`); see `getRepeatedSlashRedirect`. We check the RAW
+* pathname before normalization so this fires before normalizePath collapses
+* `//`.
 *
-* Percent-encoded variants are also blocked because:
+* Request-based (Worker) entries only see `request.url` after WHATWG URL
+* parsing, which has already turned `\` into `/`; the raw request target is
+* not available there. `/\evil.com` still redirects (it arrives as
+* `//evil.com`), but a lone backslash such as `/foo\bar` arrives as
+* `/foo/bar` and is routed without the redirect. On Cloudflare, requests that
+* match a static asset are also answered by the asset layer before the
+* Worker runs. Node entries (dev and `vinext start`) check the raw target.
+*
+* Percent-encoded variants get a 404, as in Next.js, because:
 *   - `%5C` decodes to `\` (browsers treat `/\evil.com` as `//evil.com`).
 *   - `%2F` decodes to `/` (so `/%2F/evil.com` effectively becomes `//evil.com`).
 * These forms survive segment-wise decoding that re-encodes path delimiters
@@ -64,9 +75,12 @@ function canonicalizeRequestUrlPathname(url) {
 * `isOpenRedirectShaped` for the full list of rejected leading-segment forms.
 *
 * @param rawPathname - The raw pathname from the URL, before any normalization
-* @returns A 404 Response if the path is protocol-relative, or null to continue
+* @param search - The raw query string (including `?`), kept in the 308 Location
+* @returns A 308 or 404 Response, or null to continue
 */
-function guardProtocolRelativeUrl(rawPathname) {
+function guardProtocolRelativeUrl(rawPathname, search = "") {
+	const slashRedirect = repeatedSlashRedirectResponse(rawPathname + search);
+	if (slashRedirect) return slashRedirect;
 	if (isOpenRedirectShaped(rawPathname)) return notFoundResponse();
 	return null;
 }
@@ -418,4 +432,4 @@ function cloneRequestWithUrl(request, url) {
 	return attachRequestCfMetadata(cloned, request);
 }
 //#endregion
-export { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, attachRequestCfMetadata, canonicalizeRequestPathname, canonicalizeRequestUrlPathname, cloneRequestWithHeaders, cloneRequestWithUrl, createStaticFileSignal, filterInternalHeaders, guardProtocolRelativeUrl, hasBasePath, isOpenRedirectShaped, isOriginAllowed, normalizeTrailingSlash, normalizeTrailingSlashPathname, processMiddlewareHeaders, resolvePublicFileRoute, stripBasePath, validateCsrfOrigin, validateServerActionPayload };
+export { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, attachRequestCfMetadata, canonicalizeRequestPathname, canonicalizeRequestUrlPathname, cloneRequestWithHeaders, cloneRequestWithUrl, createStaticFileSignal, filterInternalHeaders, getRepeatedSlashRedirect, guardProtocolRelativeUrl, hasBasePath, isOpenRedirectShaped, isOriginAllowed, normalizeTrailingSlash, normalizeTrailingSlashPathname, processMiddlewareHeaders, resolvePublicFileRoute, sendRepeatedSlashRedirect, stripBasePath, validateCsrfOrigin, validateServerActionPayload };

package/dist/server/response-compression.d.ts

@@ -0,0 +1,43 @@
+import { NegotiatedEncoding } from "./accept-encoding.js";
+import { IncomingMessage } from "node:http";
+//#region src/server/response-compression.d.ts
+/**
+ * Whether a Content-Type is compressible, matching `compressible()`. This
+ * covers `text/x-component` (RSC payloads) through the `text/` rule.
+ */
+export declare function isCompressibleContentType(contentType: string | null | undefined): boolean;
+/** Whether a Cache-Control value forbids content codings (`no-transform`). */
+export declare function hasNoTransform(cacheControl: string | null | undefined): boolean;
+/** Responses whose known length is below this many bytes are sent uncompressed. */
+export declare const COMPRESS_THRESHOLD = 1024;
+export type ResponseCompressionHeaders = {
+  contentType: string | null | undefined;
+  cacheControl: string | null | undefined;
+  contentEncoding: string | null | undefined;
+  /**
+   * Body length in bytes when it is known before the headers are written (a
+   * Content-Length header, or a buffered or empty body). Undefined for
+   * streamed bodies, which are compressed regardless of size.
+   */
+  contentLength: number | undefined;
+};
+export type ResponseCompression = {
+  /** Whether the response must carry `Vary: Accept-Encoding`. */
+  varyAcceptEncoding: boolean;
+  /** The coding to apply. `identity` sends the body as is. */
+  encoding: NegotiatedEncoding;
+};
+/**
+ * Decide how to compress a response, in the middleware's order: the
+ * Content-Type filter and `Cache-Control: no-transform` skip compression
+ * without `Vary`; every other response gets `Vary: Accept-Encoding`, then is
+ * sent uncompressed when it is under the size threshold, already encoded, or
+ * a HEAD response, or when the client accepts no supported coding.
+ *
+ * Unlike the middleware, which offers only gzip and deflate, negotiation also
+ * offers zstd and br (see negotiateEncoding).
+ */
+export declare function resolveResponseCompression(req: IncomingMessage, compress: boolean, headers: ResponseCompressionHeaders): ResponseCompression;
+/** Parse a Content-Length header value the way the middleware compares it. */
+export declare function parseContentLengthHeader(value: string | null | undefined): number | undefined;
+//#endregion

package/dist/server/response-compression.js

@@ -0,0 +1,111 @@
+import { negotiateEncoding } from "./accept-encoding.js";
+//#region src/server/response-compression.ts
+/**
+* Response compression rules for the Node production server, ported from the
+* `compression` middleware that `next start` installs for every response
+* unless `compress: false` (next/dist/compiled/compression, see
+* packages/next/src/server/lib/router-server.ts).
+*/
+const EXTRACT_TYPE_REGEXP = /^\s*([^;\s]*)(?:;|\s|$)/;
+const COMPRESSIBLE_TYPE_REGEXP = /^text\/|\+(?:json|text|xml)$/i;
+/**
+* mime-db entries marked `compressible: true` that COMPRESSIBLE_TYPE_REGEXP
+* does not match, taken from the mime-db bundled with Next.js's compression
+* middleware. That mime-db marks no type `compressible: false` that the
+* regexp matches, so this set plus the regexp reproduces `compressible()`.
+*/
+const MIME_DB_COMPRESSIBLE_TYPES = /* @__PURE__ */ new Set([
+	"application/dart",
+	"application/ecmascript",
+	"application/javascript",
+	"application/json",
+	"application/postscript",
+	"application/raml+yaml",
+	"application/rtf",
+	"application/tar",
+	"application/toml",
+	"application/vnd.dart",
+	"application/vnd.ms-fontobject",
+	"application/vnd.ms-opentype",
+	"application/wasm",
+	"application/x-httpd-php",
+	"application/x-javascript",
+	"application/x-ns-proxy-autoconfig",
+	"application/x-sh",
+	"application/x-tar",
+	"application/x-virtualbox-hdd",
+	"application/x-virtualbox-ova",
+	"application/x-virtualbox-ovf",
+	"application/x-virtualbox-vbox",
+	"application/x-virtualbox-vdi",
+	"application/x-virtualbox-vhd",
+	"application/x-virtualbox-vmdk",
+	"application/x-www-form-urlencoded",
+	"application/xml",
+	"application/xml-dtd",
+	"font/otf",
+	"font/ttf",
+	"image/bmp",
+	"image/vnd.adobe.photoshop",
+	"image/x-icon",
+	"image/x-ms-bmp",
+	"message/rfc822",
+	"model/gltf-binary",
+	"x-shader/x-fragment",
+	"x-shader/x-vertex"
+]);
+/**
+* Whether a Content-Type is compressible, matching `compressible()`. This
+* covers `text/x-component` (RSC payloads) through the `text/` rule.
+*/
+function isCompressibleContentType(contentType) {
+	if (!contentType) return false;
+	const match = EXTRACT_TYPE_REGEXP.exec(contentType);
+	const mime = match ? match[1].toLowerCase() : "";
+	return MIME_DB_COMPRESSIBLE_TYPES.has(mime) || COMPRESSIBLE_TYPE_REGEXP.test(mime);
+}
+const NO_TRANSFORM_REGEXP = /(?:^|,)\s*?no-transform\s*?(?:,|$)/;
+/** Whether a Cache-Control value forbids content codings (`no-transform`). */
+function hasNoTransform(cacheControl) {
+	return !!cacheControl && NO_TRANSFORM_REGEXP.test(cacheControl);
+}
+/** Responses whose known length is below this many bytes are sent uncompressed. */
+const COMPRESS_THRESHOLD = 1024;
+const NO_COMPRESSION = {
+	varyAcceptEncoding: false,
+	encoding: "identity"
+};
+/**
+* Decide how to compress a response, in the middleware's order: the
+* Content-Type filter and `Cache-Control: no-transform` skip compression
+* without `Vary`; every other response gets `Vary: Accept-Encoding`, then is
+* sent uncompressed when it is under the size threshold, already encoded, or
+* a HEAD response, or when the client accepts no supported coding.
+*
+* Unlike the middleware, which offers only gzip and deflate, negotiation also
+* offers zstd and br (see negotiateEncoding).
+*/
+function resolveResponseCompression(req, compress, headers) {
+	if (!compress) return NO_COMPRESSION;
+	if (!isCompressibleContentType(headers.contentType)) return NO_COMPRESSION;
+	if (hasNoTransform(headers.cacheControl)) return NO_COMPRESSION;
+	const identity = {
+		varyAcceptEncoding: true,
+		encoding: "identity"
+	};
+	if (headers.contentLength !== void 0 && headers.contentLength < 1024) return identity;
+	if ((headers.contentEncoding || "identity") !== "identity") return identity;
+	if (req.method === "HEAD") return identity;
+	return {
+		varyAcceptEncoding: true,
+		encoding: negotiateEncoding(req)
+	};
+}
+/** Parse a Content-Length header value the way the middleware compares it. */
+function parseContentLengthHeader(value) {
+	if (value === null || value === void 0) return void 0;
+	const length = Number(value);
+	return Number.isNaN(length) ? void 0 : length;
+}
+//#endregion
+export { COMPRESS_THRESHOLD, hasNoTransform, isCompressibleContentType, parseContentLengthHeader, resolveResponseCompression };

package/dist/server/response-stage-cacheability.js

@@ -34,7 +34,7 @@ async function withResponseStageCacheability(options, render) {
 	const response = options.policyHeadersAppliedBeforeRender ? rendered : cacheability.applyResponseStageCachePolicy(rendered, context, options.policyHeaders);
 	const complete = (candidate) => cacheability.finalizeWorkerCacheabilityResponse(candidate, context);
 	const route = state?.route;
-	if (!options.probeMode && state?.admission?.policy !== "manifest" && (route?.kind === "app-page" || route?.kind === "pages-page")) {
+	if (!options.probeMode && state?.admission?.policy !== "manifest" && (route?.kind === "app-page" || route?.kind === "pages-page") && !(route.kind === "pages-page" && state?.outcome?.cacheable === false)) {
 		const deferred = adapter.deferCompletedPageResponseAdmission?.(response, complete);
 		if (deferred) return deferred;
 	}

package/dist/server/seed-cache.js

@@ -70,8 +70,11 @@ async function seedMemoryCacheFromPrerender(serverDir, options) {
 		const expireSeconds = typeof route.expire === "number" ? route.expire : void 0;
 		const staleSeconds = typeof route.stale === "number" && route.stale >= 0 ? route.stale : void 0;
 		const tags = buildAppPageCacheTags(cachePathname, route.tags ?? []);
-		if (await seedHtml(writeAppPageEntry, prerenderDir, htmlKey, artifactPathname, trailingSlash, route.headers, revalidateSeconds, expireSeconds, staleSeconds, tags)) {
-			await seedRsc(writeAppPageEntry, prerenderDir, rscKey, artifactPathname, revalidateSeconds, expireSeconds, staleSeconds, tags);
+		const status = route.responseStatus;
+		const location = route.headers?.location;
+		const rscHeaders = status !== void 0 && location !== void 0 ? { location } : void 0;
+		if (await seedHtml(writeAppPageEntry, prerenderDir, htmlKey, artifactPathname, trailingSlash, route.headers, status, revalidateSeconds, expireSeconds, staleSeconds, tags)) {
+			await seedRsc(writeAppPageEntry, prerenderDir, rscKey, artifactPathname, rscHeaders, status, revalidateSeconds, expireSeconds, staleSeconds, tags);
 			seeded++;
 		}
 	}
@@ -107,7 +110,7 @@ function createDefaultAppPageEntryWriter() {
 * Seed the HTML cache entry for a single route.
 * Returns true if the file existed and was seeded.
 */
-async function seedHtml(writeAppPageEntry, prerenderDir, key, pathname, trailingSlash, headers, revalidateSeconds, expireSeconds, staleSeconds, tags) {
+async function seedHtml(writeAppPageEntry, prerenderDir, key, pathname, trailingSlash, headers, status, revalidateSeconds, expireSeconds, staleSeconds, tags) {
 	const relPath = getOutputPath(pathname, trailingSlash);
 	const fullPath = path.join(prerenderDir, relPath);
 	if (!fs.existsSync(fullPath)) return false;
@@ -117,7 +120,7 @@ async function seedHtml(writeAppPageEntry, prerenderDir, key, pathname, trailing
 		rscData: void 0,
 		headers,
 		postponed: void 0,
-		status: void 0
+		status
 	}, {
 		expireSeconds,
 		revalidateSeconds,
@@ -130,7 +133,7 @@ async function seedHtml(writeAppPageEntry, prerenderDir, key, pathname, trailing
 * Seed the RSC cache entry for a single route.
 * No-op if the .rsc file doesn't exist on disk.
 */
-async function seedRsc(writeAppPageEntry, prerenderDir, key, pathname, revalidateSeconds, expireSeconds, staleSeconds, tags) {
+async function seedRsc(writeAppPageEntry, prerenderDir, key, pathname, headers, status, revalidateSeconds, expireSeconds, staleSeconds, tags) {
 	const relPath = getRscOutputPath(pathname);
 	const fullPath = path.join(prerenderDir, relPath);
 	if (!fs.existsSync(fullPath)) return;
@@ -139,9 +142,9 @@ async function seedRsc(writeAppPageEntry, prerenderDir, key, pathname, revalidat
 		kind: "APP_PAGE",
 		html: "",
 		rscData: rscBuffer.buffer.slice(rscBuffer.byteOffset, rscBuffer.byteOffset + rscBuffer.byteLength),
-		headers: void 0,
+		headers,
 		postponed: void 0,
-		status: void 0
+		status
 	}, {
 		expireSeconds,
 		revalidateSeconds,

package/dist/server/socket-error-backstop.d.ts

@@ -23,6 +23,20 @@ export declare function peerDisconnectCode(err: unknown): string | undefined;
  * Exported for unit testing in isolation.
  */
 export declare function isBenignAssetImportError(err: unknown): boolean;
+/**
+ * Pure predicate: returns `true` when `err` is Node's
+ * `Readable.toWeb()` adapter enqueueing into a request body stream that was
+ * already cancelled. `pull()` calls `req.resume()`, which schedules `flow()`
+ * on `nextTick`; if the body is cancelled before that tick runs, `flow()`
+ * still emits the chunks already buffered in `req` and the adapter's
+ * `onData` throws inside the `nextTick` callback. srvx (used by
+ * `@vitejs/plugin-rsc` in dev) builds `request.body` this way, so any
+ * cancelled request body, e.g. an oversized Server Action, can crash the
+ * dev server. Node main drops that data instead (`if (wasCanceled) return;`
+ * in `onData`), so absorbing it matches upstream behaviour. Exported for
+ * unit testing in isolation.
+ */
+export declare function isCancelledRequestBodyEnqueueError(err: unknown): boolean;
 /**
  * Test-only: returns whether the backstop has been installed in this
  * process. Used by the unit test to assert idempotent install via the

package/dist/server/socket-error-backstop.js

@@ -15,9 +15,10 @@
 * `uncaughtException`, where this listener filters it.
 *
 * Filters strictly on peer-disconnect codes (ECONNRESET / EPIPE /
-* ECONNABORTED) plus benign static-asset `import()` rejections (see
-* `isBenignAssetImportError`), and synchronously re-throws everything
-* else, preserving Node's default crash semantics for genuine bugs.
+* ECONNABORTED), benign static-asset `import()` rejections (see
+* `isBenignAssetImportError`) and Node's cancelled-request-body enqueue
+* race (see `isCancelledRequestBodyEnqueueError`), and synchronously
+* re-throws everything else, preserving Node's default crash semantics for genuine bugs.
 * This is more conservative than Next.js's equivalent
 * (`router-server.ts`'s log-only handler), which silently swallows
 * every uncaught — vinext keeps real bugs surfacing.
@@ -153,6 +154,24 @@ function isBenignAssetImportError(err) {
 	return false;
 }
 /**
+* Pure predicate: returns `true` when `err` is Node's
+* `Readable.toWeb()` adapter enqueueing into a request body stream that was
+* already cancelled. `pull()` calls `req.resume()`, which schedules `flow()`
+* on `nextTick`; if the body is cancelled before that tick runs, `flow()`
+* still emits the chunks already buffered in `req` and the adapter's
+* `onData` throws inside the `nextTick` callback. srvx (used by
+* `@vitejs/plugin-rsc` in dev) builds `request.body` this way, so any
+* cancelled request body, e.g. an oversized Server Action, can crash the
+* dev server. Node main drops that data instead (`if (wasCanceled) return;`
+* in `onData`), so absorbing it matches upstream behaviour. Exported for
+* unit testing in isolation.
+*/
+function isCancelledRequestBodyEnqueueError(err) {
+	if (err === null || typeof err !== "object") return false;
+	const { code, message, stack } = err;
+	return code === "ERR_INVALID_STATE" && typeof message === "string" && message.includes("Controller is already closed") && typeof stack === "string" && /\.onData \(node:internal\/webstreams\/adapters:\d+/.test(stack);
+}
+/**
 * Test-only: returns whether the backstop has been installed in this
 * process. Used by the unit test to assert idempotent install via the
 * Symbol.for guard. Not part of the public API.
@@ -183,6 +202,10 @@ function installSocketErrorBackstop() {
 			if (debug) console.warn(`[vinext] absorbed uncaughtException ${code}`);
 			return;
 		}
+		if (isCancelledRequestBodyEnqueueError(err)) {
+			if (debug) console.warn("[vinext] absorbed uncaughtException ERR_INVALID_STATE (cancelled request body)");
+			return;
+		}
 		throw err;
 	});
 	process.on("unhandledRejection", (reason) => {
@@ -197,4 +220,4 @@ function installSocketErrorBackstop() {
 	});
 }
 //#endregion
-export { installSocketErrorBackstop, isBenignAssetImportError, isSocketErrorBackstopInstalled, peerDisconnectCode };
+export { installSocketErrorBackstop, isBenignAssetImportError, isCancelledRequestBodyEnqueueError, isSocketErrorBackstopInstalled, peerDisconnectCode };

package/dist/server/worker-revalidation-context.d.ts

@@ -1,6 +1,7 @@
+import { VinextRequestStageContext } from "./multi-stage.js";
 import { ExecutionContextLike } from "../shims/request-context.js";
 //#region src/server/worker-revalidation-context.d.ts
-type PlatformExecutionContext = Partial<ExecutionContextLike>;
+type PlatformExecutionContext = Partial<ExecutionContextLike> & VinextRequestStageContext;
 /**
  * Add a request-local, in-process Pages revalidation dispatcher to a Worker
  * execution context. Re-entering with the derived internal context preserves

package/dist/server/worker-revalidation-context.js

@@ -10,6 +10,7 @@ function deriveExecutionContext(base, dispatchPagesRevalidate, isInternalPagesRe
 		} } : {},
 		hostRuntime: base?.hostRuntime ?? defaultHostRuntime,
 		...base?.cache === void 0 ? {} : { cache: base.cache },
+		...base?.assets === void 0 ? {} : { assets: base.assets },
 		...base?.trustedRevalidateOrigin === void 0 ? {} : { trustedRevalidateOrigin: base.trustedRevalidateOrigin },
 		dispatchPagesRevalidate,
 		isInternalPagesRevalidation

package/dist/server/workers-tracing.d.ts

@@ -1,7 +1,18 @@
 import { FrameworkTracingIntegration } from "./framework-tracer.js";
 //#region src/server/workers-tracing.d.ts
 export type WorkersTracingException = string | {
+  code: string | number;
+  name?: string;
+  message?: string;
+  stack?: string;
+} | {
+  code?: string | number;
   name: string;
+  message?: string;
+  stack?: string;
+} | {
+  code?: string | number;
+  name?: string;
   message: string;
   stack?: string;
 };
@@ -9,9 +20,15 @@ export type WorkersTracingSpan = {
   readonly isTraced: boolean;
   recordException?(exception: WorkersTracingException): void;
   setAttribute(key: string, value: boolean | number | string): void;
+  setStatus?(status: {
+    code: "error";
+    message?: string;
+  }): void;
+  updateName?(name: string): void;
 };
 export type WorkersTracing = {
   enterSpan<T>(name: string, callback: (span: WorkersTracingSpan) => T): T;
+  getActiveSpan?(): WorkersTracingSpan | undefined;
 };
 export declare function createWorkersTracingIntegration(tracing: WorkersTracing): FrameworkTracingIntegration;
 //#endregion

package/dist/server/workers-tracing.js

@@ -1,20 +1,60 @@
 //#region src/server/workers-tracing.ts
+function readExceptionField(error, key) {
+	try {
+		return Reflect.get(error, key);
+	} catch {
+		return;
+	}
+}
 function normalizeException(error) {
 	if (typeof error === "string") return error;
-	if (error instanceof Error) return {
-		message: error.message,
-		name: error.name,
-		...error.stack ? { stack: error.stack } : {}
-	};
-	return String(error);
+	if (error && typeof error === "object") {
+		const code = readExceptionField(error, "code");
+		const name = readExceptionField(error, "name");
+		const message = readExceptionField(error, "message");
+		const stack = readExceptionField(error, "stack");
+		const details = {
+			...typeof name === "string" ? { name } : {},
+			...typeof message === "string" ? { message } : {},
+			...typeof stack === "string" ? { stack } : {}
+		};
+		if (typeof code === "string" || typeof code === "number") return {
+			...details,
+			code
+		};
+		if (typeof name === "string") return {
+			...details,
+			name
+		};
+		if (typeof message === "string") return {
+			...details,
+			message
+		};
+	}
+	try {
+		return String(error);
+	} catch {
+		return "Unknown exception";
+	}
 }
 function createWorkersTracingIntegration(tracing) {
 	const backendSpan = (span) => ({
-		recordException: (error) => span.recordException?.(normalizeException(error)),
-		setAttribute: (key, value) => span.setAttribute(key, value)
+		recordException: (error) => {
+			if (span.isTraced) span.recordException?.(normalizeException(error));
+		},
+		setAttribute: (key, value) => span.setAttribute(key, value),
+		setErrorStatus: (message) => span.setStatus?.({
+			code: "error",
+			message
+		}),
+		updateName: (name) => span.updateName?.(name)
 	});
 	return {
 		id: "cloudflare-workers",
+		getActiveSpan() {
+			const span = tracing.getActiveSpan?.();
+			return span ? backendSpan(span) : void 0;
+		},
 		enterSpan(descriptor, callback) {
 			return tracing.enterSpan(descriptor.name, (span) => {
 				for (const [key, value] of Object.entries(descriptor.attributes)) span.setAttribute(key, value);

package/dist/shims/cache-adapter-instantiate.d.ts

@@ -0,0 +1,50 @@
+//#region src/shims/cache-adapter-instantiate.d.ts
+/**
+ * Instantiate a declaratively configured cache adapter from its module's
+ * default export. The generated `virtual:vinext-cache-adapters` module calls
+ * this for both the `cache.data` and `cache.cdn` slots, so every router and
+ * runtime (Node.js dev/prod server and Cloudflare Workers) uses the same rule.
+ *
+ * Contract: the default export must be a function, and it receives one
+ * `{ env, options }` argument.
+ *
+ * - A `class` (class syntax, as Vite and every current toolchain emit it) is
+ *   invoked with `new`. It is recognised by the source text that
+ *   `Function.prototype.toString` must return for class syntax, which starts
+ *   with `class`, on a function that has [[Construct]].
+ * - Any other function is called as a factory, with plain-call semantics
+ *   (`this`, `new.target` and bound receivers are what a call gives them).
+ *   Existing factories therefore behave exactly as before, whatever their
+ *   `prototype` looks like (frozen, decorated, or inherited).
+ * - A constructor that is not class syntax (an ES5-compiled class, or a
+ *   bound or Proxy-wrapped class, whose source text is not observable) is
+ *   structurally indistinguishable from a factory without invoking it, so the
+ *   module states it explicitly by exporting a factory that constructs it:
+ *   `export default (args) => new Adapter(args)`.
+ *
+ * Classification never invokes the export, matches no error messages and
+ * never retries, so the export runs exactly once.
+ *
+ * The produced value must be an adapter (an object or a function, not a
+ * Promise) with the slot's required members; anything else throws an error
+ * naming what is wrong.
+ */
+export type CacheAdapterFactoryArgs = {
+  env: unknown;
+  options: unknown;
+};
+export type CacheAdapterSlot = "data" | "cdn";
+/**
+ * Whether `value` has a [[Construct]] internal method. A Proxy is
+ * constructible exactly when its target is; its no-op `construct` trap
+ * answers without running the export or reading any of its properties.
+ */
+export declare function isConstructor(value: unknown): boolean;
+/**
+ * Whether an export is class syntax and must be invoked with `new`. The
+ * [[Construct]] check excludes methods named `class`, whose source text
+ * also starts with that word.
+ */
+export declare function isClassExport(value: unknown): boolean;
+export declare function instantiateCacheAdapter<T>(exported: unknown, args: CacheAdapterFactoryArgs, slot: CacheAdapterSlot): T;
+//#endregion

package/dist/shims/cache-adapter-instantiate.js

@@ -0,0 +1,118 @@
+//#region src/shims/cache-adapter-instantiate.ts
+const REQUIREMENTS = {
+	data: {
+		methods: [
+			"get",
+			"set",
+			"revalidateTag"
+		],
+		booleans: [],
+		description: "A data cache adapter implements get, set and revalidateTag."
+	},
+	cdn: {
+		methods: [
+			"get",
+			"set",
+			"revalidateTag",
+			"buildResponseHeaders"
+		],
+		booleans: ["ownsBackgroundRevalidation"],
+		description: "A CDN cache adapter implements get, set, revalidateTag and buildResponseHeaders, and sets ownsBackgroundRevalidation to a boolean."
+	}
+};
+/**
+* Whether `value` has a [[Construct]] internal method. A Proxy is
+* constructible exactly when its target is; its no-op `construct` trap
+* answers without running the export or reading any of its properties.
+*/
+function isConstructor(value) {
+	if (typeof value !== "function") return false;
+	try {
+		new new Proxy(value, { construct: () => ({}) })();
+		return true;
+	} catch {
+		return false;
+	}
+}
+const CLASS_SOURCE = /^class\b/;
+/**
+* Whether an export is class syntax and must be invoked with `new`. The
+* [[Construct]] check excludes methods named `class`, whose source text
+* also starts with that word.
+*/
+function isClassExport(value) {
+	if (!isConstructor(value)) return false;
+	try {
+		return CLASS_SOURCE.test(Function.prototype.toString.call(value));
+	} catch {
+		return false;
+	}
+}
+function describeValue(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "object") return "an object";
+	return typeof value === "undefined" ? "undefined" : `a ${typeof value}`;
+}
+const ignore = () => {};
+/**
+* Attach a no-op rejection handler with the intrinsic `Promise.prototype.then`,
+* which throws on a non-Promise before reading anything from it. Returns the
+* derived promise, which a Promise subclass's species constructor chooses.
+*/
+function handleRejection(promise) {
+	return Promise.prototype.then.call(promise, void 0, ignore);
+}
+/**
+* Whether `value` is a Promise, judged by its internal slot or this realm's
+* Promise prototype chain, never by a `then` member: adapter contracts are
+* structural and do not reserve `then`, so an adapter's own `then` method is
+* never read or invoked.
+*
+* A Promise from any realm passes the intrinsic `then`'s brand check, which
+* also attaches a no-op rejection handler, so the discarded result cannot
+* become an unhandled rejection. The derived promise that call returns is
+* handled too, since a subclass's species constructor may return a rejected
+* one.
+*
+* Known limitation: when a Promise subclass's `constructor` or
+* `Symbol.species` lookup throws, that call fails after the brand check, and
+* no handler can be attached (every way of observing a Promise goes through
+* that lookup or its `then`). Such a Promise is still rejected when it comes
+* from this realm, the one adapter modules are evaluated in; one from another
+* realm is judged by its members like any other value.
+*/
+function markHandledIfPromise(value) {
+	let derived;
+	try {
+		derived = handleRejection(value);
+	} catch {
+		try {
+			return value instanceof Promise;
+		} catch {
+			return false;
+		}
+	}
+	try {
+		handleRejection(derived);
+	} catch {}
+	return true;
+}
+function instantiateCacheAdapter(exported, args, slot) {
+	const label = `cache.${slot} adapter`;
+	const requirements = REQUIREMENTS[slot];
+	if (typeof exported !== "function") {
+		const hint = exported !== null && typeof exported === "object" ? " To use an adapter object directly, export a factory that returns it: `export default () => adapter`." : exported === void 0 ? " Check that the module has a default export." : "";
+		throw new TypeError(`${label}: the module's default export must be a factory function or a class that receives { env, options }, got ${describeValue(exported)}.${hint}`);
+	}
+	const adapter = isClassExport(exported) ? new exported(args) : exported(args);
+	const isObjectLike = adapter !== null && typeof adapter === "object" || typeof adapter === "function";
+	if (isObjectLike && markHandledIfPromise(adapter)) throw new TypeError(`${label}: the default export returned a Promise. Adapter factories must return the adapter synchronously; defer async setup to the adapter's methods.`);
+	if (!isObjectLike) throw new TypeError(`${label}: the default export must produce an adapter object, got ${describeValue(adapter)}. ${requirements.description}`);
+	const record = adapter;
+	const problems = [...requirements.methods.filter((method) => typeof record[method] !== "function").map((method) => `method ${method}`), ...requirements.booleans.filter((property) => typeof record[property] !== "boolean").map((property) => `boolean ${property}`)];
+	if (problems.length > 0) throw new TypeError(`${label}: the adapter produced by the default export is missing ${problems.join(", ")}. ${requirements.description}`);
+	return adapter;
+}
+//#endregion
+export { instantiateCacheAdapter, isClassExport, isConstructor };