fix: prevent Worker hang on HEAD requests to static assets (#1126)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: alex-all3dp

.changeset/neat-buses-spend.md

@@ -0,0 +1,5 @@
+---
+"@opennextjs/cloudflare": patch
+---
+
+fix: prevent Worker hang on HEAD requests to static assets

packages/cloudflare/src/api/overrides/asset-resolver/index.spec.ts

@@ -1,7 +1,80 @@
-import { describe, expect, test } from "vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
 
 import { isUserWorkerFirst } from "./index.js";
 
+const mockAssetsFetch = vi.fn();
+
+vi.mock("../../cloudflare-context.js", () => ({
+	getCloudflareContext: () => ({
+		env: {
+			ASSETS: { fetch: mockAssetsFetch },
+		},
+	}),
+}));
+
+describe("maybeGetAssetResult", () => {
+	let resolver: typeof import("./index.js").default;
+
+	beforeEach(async () => {
+		vi.resetModules();
+		mockAssetsFetch.mockReset();
+		globalThis.__ASSETS_RUN_WORKER_FIRST__ = true;
+		resolver = (await import("./index.js")).default;
+	});
+
+	const makeEvent = (method: string, rawPath: string) =>
+		({
+			method,
+			rawPath,
+			headers: { accept: "*/*" },
+		}) as Parameters<typeof resolver.maybeGetAssetResult>[0];
+
+	test("GET request returns response body", async () => {
+		const body = new ReadableStream();
+		mockAssetsFetch.mockResolvedValue(new Response(body, { status: 200 }));
+
+		const result = await resolver.maybeGetAssetResult(makeEvent("GET", "/style.css"));
+
+		expect(result).toBeDefined();
+		expect(result!.statusCode).toBe(200);
+		expect(result!.body).not.toBeNull();
+	});
+
+	test("HEAD request returns null body", async () => {
+		mockAssetsFetch.mockResolvedValue(new Response(null, { status: 200 }));
+
+		const result = await resolver.maybeGetAssetResult(makeEvent("HEAD", "/style.css"));
+
+		expect(result).toBeDefined();
+		expect(result!.statusCode).toBe(200);
+		expect(result!.body).toBeNull();
+	});
+
+	test("returns undefined for 404 responses", async () => {
+		mockAssetsFetch.mockResolvedValue(new Response(null, { status: 404 }));
+
+		const result = await resolver.maybeGetAssetResult(makeEvent("GET", "/missing.css"));
+
+		expect(result).toBeUndefined();
+	});
+
+	test("returns undefined for POST requests", async () => {
+		const result = await resolver.maybeGetAssetResult(makeEvent("POST", "/style.css"));
+
+		expect(result).toBeUndefined();
+		expect(mockAssetsFetch).not.toHaveBeenCalled();
+	});
+
+	test("returns undefined when run_worker_first is false", async () => {
+		globalThis.__ASSETS_RUN_WORKER_FIRST__ = false;
+
+		const result = await resolver.maybeGetAssetResult(makeEvent("GET", "/style.css"));
+
+		expect(result).toBeUndefined();
+		expect(mockAssetsFetch).not.toHaveBeenCalled();
+	});
+});
+
 describe("isUserWorkerFirst", () => {
 	test("run_worker_first = false", () => {
 		expect(isUserWorkerFirst(false, "/test")).toBe(false);

packages/cloudflare/src/api/overrides/asset-resolver/index.ts

@@ -44,14 +44,33 @@ const resolver: AssetResolver = {
 			type: "core",
 			statusCode: response.status,
 			headers: Object.fromEntries(response.headers.entries()),
-			// Workers and Node types differ.
 			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			body: response.body || (new ReadableStream() as any),
+			body: getResponseBody(method, response) as any,
 			isBase64Encoded: false,
 		} satisfies InternalResult;
 	},
 };
 
+/**
+ * Returns the response body for an asset result.
+ *
+ * HEAD responses must return `null` because `response.body` is `null` per the HTTP spec
+ * and the `new ReadableStream()` fallback would create a stream that never closes, hanging the Worker.
+ *
+ * @param method - The HTTP method of the request.
+ * @param response - The response from the ASSETS binding.
+ * @returns The body to use in the internal result.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getResponseBody(method: string, response: Response): ReadableStream<any> | null {
+	if (method === "HEAD") {
+		return null;
+	}
+	// Workers and Node ReadableStream types differ.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	return response.body || (new ReadableStream() as any);
+}
+
 /**
  * @param runWorkerFirst `run_worker_first` config
  * @param pathname pathname of the request