vinext 1.4.2 → 1.4.3

package/dist/server/image-optimization.d.ts

@@ -64,6 +64,13 @@ export type ImageConfig = {
   contentDispositionType?: "inline" | "attachment";
   /** Content-Security-Policy header value. Default: "script-src 'none'; frame-src 'none'; sandbox;" */
   contentSecurityPolicy?: string;
+  /** Least max-age, in seconds, of an image served as-is. Default: 14400. */
+  minimumCacheTTL?: number;
+  /**
+   * Most bytes of a GIF, PNG or WebP source read for optimization before
+   * answering 413. Default: 50000000.
+   */
+  maximumResponseBody?: number;
 };
 /**
  * Next.js default device sizes and image sizes.
@@ -144,11 +151,6 @@ export declare function negotiateImageFormat(acceptHeader: string | null): strin
  * Optimized images are immutable because the URL encodes the transform params.
  */
 export declare const IMAGE_CACHE_CONTROL = "public, max-age=31536000, immutable";
-/**
- * Next.js's Cache-Control for an image whose source can change at its URL
- * (anything but a hashed build asset), at the default `images.minimumCacheTTL`.
- */
-export declare const MUTABLE_IMAGE_SOURCE_CACHE_CONTROL = "public, max-age=14400, must-revalidate";
 /**
  * Content-Security-Policy for image optimization responses.
  * Blocks script execution and framing to prevent XSS via SVG or other
@@ -156,6 +158,10 @@ export declare const MUTABLE_IMAGE_SOURCE_CACHE_CONTROL = "public, max-age=14400
  * Matches Next.js default: script-src 'none'; frame-src 'none'; sandbox;
  */
 export declare const IMAGE_CONTENT_SECURITY_POLICY = "script-src 'none'; frame-src 'none'; sandbox;";
+/** Next.js's 400 body for a source whose type it does not serve, such as SVG. */
+export declare const IMAGE_TYPE_NOT_ALLOWED_MESSAGE = "\"url\" parameter is valid but image type is not allowed";
+/** The image type Next.js detects from a source's first bytes, or null. */
+export declare function sniffImageContentType(bytes: Uint8Array): string | null;
 /**
  * Check if a Content-Type header value is a safe image type.
  * Returns false for SVG (unless dangerouslyAllowSVG is true), HTML, or any non-image type.
@@ -177,6 +183,20 @@ export declare function isSafeImageContentType(contentType: string | null, dange
  * go out without it. Only full image responses carry either header here too.
  */
 export declare const IMAGE_RESPONSE_CACHE_STATE = "MISS";
+/**
+ * Mark a source the host fetched from its `_next/static` build output, which
+ * is served immutably like Next.js' `isStatic` sources. A public file is never
+ * marked, whatever its path.
+ */
+export declare function markImageBuildAsset(response: Response): Response;
+/**
+ * Next.js's Cache-Control for a source it serves as-is: a build asset stays
+ * immutable, and any other source is revalidated after the larger of
+ * `images.minimumCacheTTL` and the source's own max-age. Next.js ignores the
+ * source's max-age when it falls back after a failed transform, so that
+ * fallback passes null.
+ */
+export declare function sourceImageCacheControl(isBuildAsset: boolean, upstreamCacheControl: string | null, config?: ImageConfig): string;
 /**
  * Handlers for image optimization I/O operations.
  * Workers provide these callbacks to adapt their specific bindings.

package/dist/server/image-optimization.js

@@ -1,5 +1,7 @@
 import { badRequestResponse } from "./http-error-responses.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
+import { isAnimatedImage } from "./image-animation.js";
+import { ImageSourceReader, ImageSourceTooLargeError } from "./image-source-reader.js";
 import { hasLocalMatch } from "./image-local-patterns.js";
 //#region src/server/image-optimization.ts
 /**
@@ -19,6 +21,9 @@ import { hasLocalMatch } from "./image-local-patterns.js";
 * spoofing. SVG content is blocked by default (following Next.js behavior).
 * When `dangerouslyAllowSVG` is enabled in next.config.js, SVGs are served
 * as-is (no transformation) with security headers applied.
+*
+* Like Next.js, formats it does not optimize (SVG, ICO, ICNS, BMP, JPEG XL,
+* HEIC) and animated images are served as-is too.
 */
 /** The pathname that triggers image optimization (matches Next.js). */
 const IMAGE_OPTIMIZATION_PATH = "/_next/image";
@@ -238,11 +243,13 @@ function negotiateImageFormat(acceptHeader) {
 * Optimized images are immutable because the URL encodes the transform params.
 */
 const IMAGE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** Next.js's default `images.minimumCacheTTL`, in seconds. */
+const DEFAULT_MINIMUM_CACHE_TTL = 14400;
 /**
-* Next.js's Cache-Control for an image whose source can change at its URL
-* (anything but a hashed build asset), at the default `images.minimumCacheTTL`.
+* Next.js's default `images.maximumResponseBody`: the most it reads of a
+* source before answering 413.
 */
-const MUTABLE_IMAGE_SOURCE_CACHE_CONTROL = "public, max-age=14400, must-revalidate";
+const DEFAULT_MAXIMUM_RESPONSE_BODY = 5e7;
 /**
 * Content-Security-Policy for image optimization responses.
 * Blocks script execution and framing to prevent XSS via SVG or other
@@ -263,16 +270,207 @@ const SAFE_IMAGE_CONTENT_TYPES = /* @__PURE__ */ new Set([
 	"image/avif",
 	"image/x-icon",
 	"image/vnd.microsoft.icon",
+	"image/x-icns",
 	"image/bmp",
-	"image/tiff"
+	"image/tiff",
+	"image/jxl",
+	"image/heic"
 ]);
 /**
+* Formats Next.js serves as-is instead of optimizing (`BYPASS_TYPES` in
+* packages/next/src/server/image-optimizer.ts), with ICO's registered name.
+*/
+const BYPASS_IMAGE_CONTENT_TYPES = /* @__PURE__ */ new Set([
+	"image/svg+xml",
+	"image/x-icon",
+	"image/vnd.microsoft.icon",
+	"image/x-icns",
+	"image/bmp",
+	"image/jxl",
+	"image/heic"
+]);
+/** Formats Next.js serves as-is when animated (`ANIMATABLE_TYPES`). */
+const ANIMATABLE_IMAGE_CONTENT_TYPES = /* @__PURE__ */ new Set([
+	"image/webp",
+	"image/png",
+	"image/gif"
+]);
+/** Next.js's 400 body for a source whose type it does not serve, such as SVG. */
+const IMAGE_TYPE_NOT_ALLOWED_MESSAGE = "\"url\" parameter is valid but image type is not allowed";
+function imageTypeNotAllowedResponse() {
+	return new Response(IMAGE_TYPE_NOT_ALLOWED_MESSAGE, { status: 400 });
+}
+function imageMediaType(contentType) {
+	return contentType?.split(";")[0].trim().toLowerCase() ?? "";
+}
+/**
+* Next.js's image signatures (`detectContentType` in
+* packages/next/src/server/image-optimizer.ts); a null byte matches any value.
+*/
+const IMAGE_SIGNATURES = [
+	["image/jpeg", [
+		255,
+		216,
+		255
+	]],
+	["image/png", [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]],
+	["image/gif", [
+		71,
+		73,
+		70,
+		56
+	]],
+	["image/webp", [
+		82,
+		73,
+		70,
+		70,
+		null,
+		null,
+		null,
+		null,
+		87,
+		69,
+		66,
+		80
+	]],
+	["image/svg+xml", [
+		60,
+		63,
+		120,
+		109,
+		108
+	]],
+	["image/svg+xml", [
+		60,
+		115,
+		118,
+		103
+	]],
+	["image/avif", [
+		null,
+		null,
+		null,
+		null,
+		102,
+		116,
+		121,
+		112,
+		97,
+		118,
+		105,
+		102
+	]],
+	["image/x-icon", [
+		0,
+		0,
+		1,
+		0
+	]],
+	["image/x-icns", [
+		105,
+		99,
+		110,
+		115
+	]],
+	["image/tiff", [
+		73,
+		73,
+		42,
+		0
+	]],
+	["image/bmp", [66, 77]],
+	["image/jxl", [255, 10]],
+	["image/jxl", [
+		0,
+		0,
+		0,
+		12,
+		74,
+		88,
+		76,
+		32,
+		13,
+		10,
+		135,
+		10
+	]],
+	["image/heic", [
+		null,
+		null,
+		null,
+		null,
+		102,
+		116,
+		121,
+		112,
+		104,
+		101,
+		105,
+		99
+	]]
+];
+const IMAGE_SIGNATURE_LENGTH = 12;
+/** The image type Next.js detects from a source's first bytes, or null. */
+function sniffImageContentType(bytes) {
+	for (const [type, signature] of IMAGE_SIGNATURES) if (signature.every((byte, i) => byte === null || bytes[i] === byte)) return type;
+	return null;
+}
+/**
+* Label a source that arrives without an image Content-Type by its first
+* bytes, as Next.js types every source. Workers static assets have no type for
+* some formats Next.js serves, such as ICNS.
+*/
+async function withSniffedImageContentType(source) {
+	if (!source.ok || !source.body || imageMediaType(source.headers.get("Content-Type")).startsWith("image/")) return source;
+	const reader = source.body.getReader();
+	const head = [];
+	const signature = new Uint8Array(IMAGE_SIGNATURE_LENGTH);
+	let length = 0;
+	while (length < IMAGE_SIGNATURE_LENGTH) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		head.push(value);
+		signature.set(value.subarray(0, IMAGE_SIGNATURE_LENGTH - length), length);
+		length += Math.min(value.byteLength, IMAGE_SIGNATURE_LENGTH - length);
+	}
+	const body = new ReadableStream({
+		start(controller) {
+			for (const chunk of head) controller.enqueue(chunk);
+		},
+		async pull(controller) {
+			const { done, value } = await reader.read();
+			if (done) controller.close();
+			else controller.enqueue(value);
+		},
+		cancel(reason) {
+			return reader.cancel(reason);
+		}
+	});
+	const headers = new Headers(source.headers);
+	const type = sniffImageContentType(signature.subarray(0, length));
+	if (type !== null) headers.set("Content-Type", type);
+	return new Response(body, {
+		status: source.status,
+		statusText: source.statusText,
+		headers
+	});
+}
+/**
 * Check if a Content-Type header value is a safe image type.
 * Returns false for SVG (unless dangerouslyAllowSVG is true), HTML, or any non-image type.
 */
 function isSafeImageContentType(contentType, dangerouslyAllowSVG = false) {
-	if (!contentType) return false;
-	const mediaType = contentType.split(";")[0].trim().toLowerCase();
+	const mediaType = imageMediaType(contentType);
 	if (SAFE_IMAGE_CONTENT_TYPES.has(mediaType)) return true;
 	if (dangerouslyAllowSVG && mediaType === "image/svg+xml") return true;
 	return false;
@@ -305,20 +503,65 @@ function setImageSecurityHeaders(headers, config) {
 */
 const IMAGE_RESPONSE_CACHE_STATE = "MISS";
 /** Headers shared by every successful image response, transformed or not. */
-function setImageResponseHeaders(headers, config) {
-	headers.set("Cache-Control", IMAGE_CACHE_CONTROL);
+function setImageResponseHeaders(headers, cacheControl, config) {
+	headers.set("Cache-Control", cacheControl);
 	headers.set("Vary", "Accept");
 	setImageSecurityHeaders(headers, config);
 	setCacheStateHeaders(headers, IMAGE_RESPONSE_CACHE_STATE);
 }
-function createPassthroughImageResponse(source, config) {
+/** The `s-maxage` or `max-age` of a Cache-Control value, like Next.js' getMaxAge. */
+function cacheControlMaxAge(cacheControl) {
+	const directives = /* @__PURE__ */ new Map();
+	for (const directive of cacheControl?.split(",") ?? []) {
+		const [key, value] = directive.trim().split("=", 2);
+		directives.set(key.toLowerCase(), value?.toLowerCase());
+	}
+	let age = directives.get("s-maxage") || directives.get("max-age") || "";
+	if (age.startsWith("\"") && age.endsWith("\"")) age = age.slice(1, -1);
+	const seconds = Number.parseInt(age, 10);
+	return Number.isNaN(seconds) ? 0 : seconds;
+}
+const IMAGE_BUILD_ASSET = Symbol.for("vinext.imageBuildAsset");
+/**
+* Mark a source the host fetched from its `_next/static` build output, which
+* is served immutably like Next.js' `isStatic` sources. A public file is never
+* marked, whatever its path.
+*/
+function markImageBuildAsset(response) {
+	Reflect.set(response, IMAGE_BUILD_ASSET, true);
+	return response;
+}
+function isImageBuildAsset(response) {
+	return Reflect.get(response, IMAGE_BUILD_ASSET) === true;
+}
+/**
+* Next.js's Cache-Control for a source it serves as-is: a build asset stays
+* immutable, and any other source is revalidated after the larger of
+* `images.minimumCacheTTL` and the source's own max-age. Next.js ignores the
+* source's max-age when it falls back after a failed transform, so that
+* fallback passes null.
+*/
+function sourceImageCacheControl(isBuildAsset, upstreamCacheControl, config) {
+	if (isBuildAsset) return IMAGE_CACHE_CONTROL;
+	return `public, max-age=${Math.max(config?.minimumCacheTTL ?? DEFAULT_MINIMUM_CACHE_TTL, cacheControlMaxAge(upstreamCacheControl))}, must-revalidate`;
+}
+function createPassthroughImageResponse(source, body, cacheControl, config, readLength = null) {
 	const headers = new Headers(source.headers);
-	setImageResponseHeaders(headers, config);
-	return new Response(source.body, {
+	setImageResponseHeaders(headers, cacheControl, config);
+	if (readLength !== null) headers.set("Content-Length", String(readLength));
+	return new Response(body, {
 		status: 200,
 		headers
 	});
 }
+/** Whether a source's Content-Length is more than `limit` bytes. */
+function declaresMoreThan(source, limit) {
+	return Number(source.headers.get("Content-Length") ?? NaN) > limit;
+}
+/** Next.js's 413 for a source larger than `images.maximumResponseBody`. */
+function sourceTooLargeResponse() {
+	return new Response("\"url\" parameter is valid but internal response is invalid", { status: 413 });
+}
 /**
 * Handle image optimization requests.
 *
@@ -330,36 +573,77 @@ async function handleImageOptimization(request, handlers, allowedWidths, imageCo
 	const params = parseImageParams(new URL(request.url), allowedWidths, imageConfig?.qualities, { localPatterns: imageConfig?.localPatterns });
 	if (!params) return badRequestResponse();
 	const { imageUrl, width, quality } = params;
-	const source = await handlers.fetchAsset(imageUrl, request);
+	const fetchedSource = await handlers.fetchAsset(imageUrl, request);
+	const isBuildAsset = isImageBuildAsset(fetchedSource);
+	const source = await withSniffedImageContentType(fetchedSource);
 	if (!source.ok || !source.body) return invalidImageSourceResponse();
 	const format = negotiateImageFormat(request.headers.get("Accept"));
 	const sourceContentType = source.headers.get("Content-Type");
-	if (!isSafeImageContentType(sourceContentType, imageConfig?.dangerouslyAllowSVG)) return new Response("The requested resource is not an allowed image type", { status: 400 });
-	if (sourceContentType?.split(";")[0].trim().toLowerCase() === "image/svg+xml") return createPassthroughImageResponse(source, imageConfig);
+	if (!isSafeImageContentType(sourceContentType, imageConfig?.dangerouslyAllowSVG)) return imageTypeNotAllowedResponse();
+	const sourceMediaType = imageMediaType(sourceContentType);
+	const sourceCacheControl = sourceImageCacheControl(isBuildAsset, source.headers.get("Cache-Control"), imageConfig);
+	if (BYPASS_IMAGE_CONTENT_TYPES.has(sourceMediaType)) {
+		const response = createPassthroughImageResponse(source, source.body, sourceCacheControl, imageConfig);
+		if (sourceMediaType === "image/vnd.microsoft.icon") response.headers.set("Content-Type", "image/x-icon");
+		return response;
+	}
+	const limit = imageConfig?.maximumResponseBody ?? DEFAULT_MAXIMUM_RESPONSE_BODY;
+	let reader = null;
 	if (handlers.transformImage) try {
-		const transformed = await handlers.transformImage(source.body, {
+		let body = source.body;
+		if (ANIMATABLE_IMAGE_CONTENT_TYPES.has(sourceMediaType)) {
+			if (declaresMoreThan(source, limit)) {
+				source.body.cancel().catch(() => {});
+				return sourceTooLargeResponse();
+			}
+			reader = new ImageSourceReader(source.body, limit);
+			const animated = await isAnimatedImage(reader);
+			let sourceBody = reader.body();
+			if (!sourceBody) {
+				reader.cancel();
+				const refetched = await handlers.fetchAsset(imageUrl, request);
+				if (!refetched.ok || !refetched.body) return invalidImageSourceResponse();
+				reader = new ImageSourceReader(refetched.body, limit);
+				sourceBody = reader.body();
+			}
+			if (animated) return createPassthroughImageResponse(source, sourceBody, sourceCacheControl, imageConfig, reader.completeLength);
+			body = sourceBody;
+		}
+		const transformed = await handlers.transformImage(body, {
 			width,
 			format,
 			quality
 		});
 		const headers = new Headers(transformed.headers);
-		setImageResponseHeaders(headers, imageConfig);
+		setImageResponseHeaders(headers, IMAGE_CACHE_CONTROL, imageConfig);
 		if (!isSafeImageContentType(headers.get("Content-Type"), imageConfig?.dangerouslyAllowSVG)) headers.set("Content-Type", format);
 		return new Response(transformed.body, {
 			status: 200,
 			headers
 		});
 	} catch (e) {
+		if (e instanceof ImageSourceTooLargeError || reader?.tooLarge) return sourceTooLargeResponse();
 		console.error("[vinext] Image optimization error:", e);
 	}
+	const fallbackCacheControl = handlers.transformImage ? sourceImageCacheControl(isBuildAsset, null, imageConfig) : sourceCacheControl;
+	const readLength = reader?.completeLength ?? null;
 	try {
-		return createPassthroughImageResponse(source, imageConfig);
+		return createPassthroughImageResponse(source, readLength !== null && reader?.body() || source.body, fallbackCacheControl, imageConfig, readLength);
 	} catch (e) {
 		console.error("[vinext] Image fallback error, refetching source image:", e);
-		const refetchedSource = await handlers.fetchAsset(imageUrl, request);
+		reader?.cancel();
+		const refetchedSource = await withSniffedImageContentType(await handlers.fetchAsset(imageUrl, request));
 		if (!refetchedSource.ok || !refetchedSource.body) return invalidImageSourceResponse();
-		if (!isSafeImageContentType(refetchedSource.headers.get("Content-Type"), imageConfig?.dangerouslyAllowSVG)) return new Response("The requested resource is not an allowed image type", { status: 400 });
-		return createPassthroughImageResponse(refetchedSource, imageConfig);
+		if (!isSafeImageContentType(refetchedSource.headers.get("Content-Type"), imageConfig?.dangerouslyAllowSVG)) return imageTypeNotAllowedResponse();
+		let body = refetchedSource.body;
+		if (reader) {
+			if (declaresMoreThan(refetchedSource, limit)) {
+				body.cancel().catch(() => {});
+				return sourceTooLargeResponse();
+			}
+			body = new ImageSourceReader(body, limit).body();
+		}
+		return createPassthroughImageResponse(refetchedSource, body, fallbackCacheControl, imageConfig);
 	}
 }
 const _IMAGE_OPTIMIZER_KEY = Symbol.for("vinext.imageOptimizer");
@@ -412,4 +696,4 @@ function handleConfiguredImageOptimization(request, fetchAsset, allowedWidths, i
 	}, allowedWidths, imageConfig);
 }
 //#endregion
-export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, DEFAULT_LOCAL_PATTERNS, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, IMAGE_RESPONSE_CACHE_STATE, INVALID_IMAGE_SOURCE_MESSAGE, MUTABLE_IMAGE_SOURCE_CACHE_CONTROL, VINEXT_IMAGE_OPTIMIZATION_PATH, getImageOptimizer, handleConfiguredImageOptimization, handleImageOptimization, invalidImageSourceResponse, isImageOptimizationPath, isImageSourceBodyStatus, isSafeImageContentType, markImageOptimizationSignal, negotiateImageFormat, parseImageParams, readImageOptimizationSignal, resolveDevImageRedirect, restoreImageOptimizationSignalFromTransport, serializeImageOptimizationSignalForTransport, setImageOptimizer };
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, DEFAULT_LOCAL_PATTERNS, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, IMAGE_RESPONSE_CACHE_STATE, IMAGE_TYPE_NOT_ALLOWED_MESSAGE, INVALID_IMAGE_SOURCE_MESSAGE, VINEXT_IMAGE_OPTIMIZATION_PATH, getImageOptimizer, handleConfiguredImageOptimization, handleImageOptimization, invalidImageSourceResponse, isImageOptimizationPath, isImageSourceBodyStatus, isSafeImageContentType, markImageBuildAsset, markImageOptimizationSignal, negotiateImageFormat, parseImageParams, readImageOptimizationSignal, resolveDevImageRedirect, restoreImageOptimizationSignalFromTransport, serializeImageOptimizationSignalForTransport, setImageOptimizer, sniffImageContentType, sourceImageCacheControl };

package/dist/server/image-source-reader.d.ts

@@ -0,0 +1,34 @@
+//#region src/server/image-source-reader.d.ts
+/**
+ * Streamed reads of an image source for the image optimization endpoint.
+ *
+ * Animation detection parses a GIF, PNG or WebP source as it streams in rather
+ * than buffering it, so a large source cannot exhaust a Worker isolate's
+ * memory. Only the source's first bytes are kept, to replay without a refetch.
+ */
+/** Thrown once a source grows past `images.maximumResponseBody`. */
+export declare class ImageSourceTooLargeError extends Error {
+  constructor();
+}
+export declare class ImageSourceReader {
+  #private;
+  constructor(body: ReadableStream<Uint8Array>, limit: number);
+  /** Whether the source has grown past the limit. */
+  get tooLarge(): boolean;
+  /** The source's length once it has all been read and held, else null. */
+  get completeLength(): number | null;
+  /** Stop reading the source without waiting on its cancellation. */
+  cancel(): void;
+  /** Up to `length` bytes at `offset`, fewer where the source ends. */
+  bytes(offset: number, length: number): Promise<Uint8Array>;
+  /** The byte at `offset`, or undefined past the source's end. */
+  byte(offset: number): Promise<number | undefined>;
+  /**
+   * The whole source as a stream, replaying the bytes already read, or null
+   * once they are no longer all held. An incompletely read source replays
+   * once; the rest streams from the source, still within the limit, and is
+   * held too while the whole source fits.
+   */
+  body(): ReadableStream<Uint8Array> | null;
+}
+//#endregion

package/dist/server/image-source-reader.js

@@ -0,0 +1,126 @@
+//#region src/server/image-source-reader.ts
+/**
+* Streamed reads of an image source for the image optimization endpoint.
+*
+* Animation detection parses a GIF, PNG or WebP source as it streams in rather
+* than buffering it, so a large source cannot exhaust a Worker isolate's
+* memory. Only the source's first bytes are kept, to replay without a refetch.
+*/
+/** Most bytes of a source kept to replay it after animation detection. */
+const HELD_SOURCE_LIMIT = 1048576;
+/** Thrown once a source grows past `images.maximumResponseBody`. */
+var ImageSourceTooLargeError = class extends Error {
+	constructor() {
+		super("Image source exceeds images.maximumResponseBody");
+	}
+};
+var ImageSourceReader = class {
+	#reader;
+	#limit;
+	#read = 0;
+	#done = false;
+	#tooLarge = false;
+	#window = [];
+	#windowStart = 0;
+	#windowEnd = 0;
+	#held = [];
+	#replayed = false;
+	constructor(body, limit) {
+		this.#reader = body.getReader();
+		this.#limit = limit;
+	}
+	/** Whether the source has grown past the limit. */
+	get tooLarge() {
+		return this.#tooLarge;
+	}
+	/** The source's length once it has all been read and held, else null. */
+	get completeLength() {
+		return this.#done && this.#held ? this.#read : null;
+	}
+	/** Stop reading the source without waiting on its cancellation. */
+	cancel() {
+		this.#reader.cancel().catch(() => {});
+	}
+	/** Up to `length` bytes at `offset`, fewer where the source ends. */
+	async bytes(offset, length) {
+		const end = offset + length;
+		await this.#reach(offset, end);
+		const available = Math.min(end, this.#windowEnd);
+		const bytes = new Uint8Array(Math.max(0, available - offset));
+		let start = this.#windowStart;
+		for (const chunk of this.#window) {
+			if (start >= available) break;
+			const from = Math.max(offset - start, 0);
+			const to = Math.min(available - start, chunk.byteLength);
+			if (from < to) bytes.set(chunk.subarray(from, to), start + from - offset);
+			start += chunk.byteLength;
+		}
+		return bytes;
+	}
+	/** The byte at `offset`, or undefined past the source's end. */
+	async byte(offset) {
+		return (await this.bytes(offset, 1))[0];
+	}
+	/**
+	* The whole source as a stream, replaying the bytes already read, or null
+	* once they are no longer all held. An incompletely read source replays
+	* once; the rest streams from the source, still within the limit, and is
+	* held too while the whole source fits.
+	*/
+	body() {
+		const held = this.#held;
+		if (held === null || this.#replayed && !this.#done) return null;
+		this.#replayed = true;
+		this.#window = [];
+		let index = 0;
+		return new ReadableStream({
+			pull: async (controller) => {
+				if (index < held.length) {
+					controller.enqueue(held[index++]);
+					return;
+				}
+				const chunk = await this.#next();
+				if (!chunk) return controller.close();
+				this.#hold(chunk);
+				index = held.length;
+				controller.enqueue(chunk);
+			},
+			cancel: (reason) => this.#reader.cancel(reason)
+		});
+	}
+	async #next() {
+		if (this.#done) return void 0;
+		const { done, value } = await this.#reader.read();
+		if (done) {
+			this.#done = true;
+			return;
+		}
+		this.#read += value.byteLength;
+		if (this.#read > this.#limit) {
+			this.#tooLarge = true;
+			this.cancel();
+			throw new ImageSourceTooLargeError();
+		}
+		return value;
+	}
+	#hold(chunk) {
+		if (!this.#held) return;
+		if (this.#read <= HELD_SOURCE_LIMIT) this.#held.push(chunk);
+		else this.#held = null;
+	}
+	/** Read until `end` is in the window, dropping chunks wholly before `offset`. */
+	async #reach(offset, end) {
+		if (offset < this.#windowStart) throw new Error("Image source reads must not move backwards");
+		for (;;) {
+			while (this.#window.length > 0 && this.#windowStart + this.#window[0].byteLength <= offset) this.#windowStart += this.#window.shift().byteLength;
+			if (this.#windowEnd >= end) return;
+			const chunk = await this.#next();
+			if (!chunk) return;
+			this.#hold(chunk);
+			this.#window.push(chunk);
+			this.#windowEnd += chunk.byteLength;
+		}
+	}
+};
+//#endregion
+export { ImageSourceReader, ImageSourceTooLargeError };

package/dist/server/metadata-route-response.d.ts

@@ -21,6 +21,11 @@ type MetadataRouteRequestOptions = {
   isrRouteKey?: (pathname: string) => string;
   isrSet?: MetadataRouteCacheSetter;
   makeThenableParams: MetadataRouteMakeThenableParams;
+  /**
+   * The pathname params are read from. A direct request passes its raw path
+   * here and its decoded path as `cleanPathname`; a rewrite passes its
+   * destination, still percent-encoded, as both.
+   */
   routePathname?: string;
   scheduleBackgroundRegeneration?: MetadataRouteBackgroundRegenerator;
 };
@@ -36,6 +41,6 @@ export type PrerenderableMetadataRoute = {
  */
 export declare function getPrerenderableMetadataRoutePaths(metadataRoutes: readonly MetadataRuntimeRoute[]): Promise<PrerenderableMetadataRoute[]>;
 export declare function isMetadataRouteRequestPath(metadataRoutes: readonly MetadataRuntimeRoute[], cleanPathname: string): boolean;
-export declare function handleMetadataRouteRequest(options: MetadataRouteRequestOptions): Promise<Response | null>;
+export declare function handleMetadataRouteRequest(requestOptions: MetadataRouteRequestOptions): Promise<Response | null>;
 //#endregion
 export {};