[miniflare] Close all open handles on dispose to prevent process hangs (#13515)

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: petebacondarwin

.changeset/close-runtime-dispatcher-pool.md

@@ -0,0 +1,14 @@
+---
+"miniflare": patch
+---
+
+fix: close all open handles on dispose to prevent process hangs
+
+Several resources were not being properly cleaned up during `Miniflare.dispose()`, which could leave the Node.js event loop alive and cause processes (particularly tests using `node --test`) to hang instead of exiting cleanly:
+
+- The internal undici `Pool` used to dispatch fetch requests to the workerd runtime was not closed. Lingering TCP sockets from this pool could keep the event loop alive indefinitely.
+- `WebSocketServer` instances for live reload and WebSocket proxying were never closed, leaving connected clients' sockets open.
+- The `InspectorProxy` was not closing its runtime WebSocket connection, relying on process death to break the connection.
+- `HyperdriveProxyController.dispose()` had a missing `return` in a `.map()` callback, causing `Promise.allSettled` to resolve immediately without waiting for `net.Server` instances to close.
+- `ProxyClientBridge` was not clearing its finalization batch `setTimeout` during disposal.
+- `InspectorProxyController.dispose()` was not calling `server.closeAllConnections()` before `server.close()`, so active HTTP keep-alive or WebSocket connections could prevent the close callback from firing.

.changeset/fix-esbuild-cleanup-race.md

@@ -0,0 +1,9 @@
+---
+"wrangler": patch
+---
+
+fix: ensure esbuild context is disposed during teardown
+
+The esbuild bundler cleanup function could race with the initial build. If `BundlerController.teardown()` ran before the initial `build()` completed, the `stopWatching` closure variable would still be `undefined`, so the esbuild context was never disposed. This left the esbuild child process running, keeping the Node.js event loop alive and causing processes to hang instead of exiting cleanly.
+
+The cleanup function now awaits the build promise before calling `stopWatching`, ensuring the esbuild context is always properly disposed.

fixtures/start-worker-node-test/package.json

@@ -6,7 +6,7 @@
 	"author": "",
 	"type": "module",
 	"scripts": {
-		"test:ci": "node --test"
+		"test:ci": "node --test --test-timeout=15000"
 	},
 	"devDependencies": {
 		"@cloudflare/workers-tsconfig": "workspace:*",

fixtures/start-worker-node-test/src/config-errors.test.js

@@ -50,6 +50,7 @@ describe("startWorker - configuration errors", () => {
 		const worker = await unstable_startWorker({
 			config: "wrangler.json",
 			dev: {
+				persist: false,
 				server: {
 					port: await getPort(),
 				},
@@ -76,6 +77,7 @@ describe("startWorker - configuration errors", () => {
 		const worker = await unstable_startWorker({
 			config: "wrangler.json",
 			dev: {
+				persist: false,
 				server: {
 					port: await getPort(),
 				},

fixtures/start-worker-node-test/src/index.test.js

@@ -9,7 +9,10 @@ describe("worker", () => {
 	let worker;
 
 	before(async () => {
-		worker = await unstable_startWorker({ config: "wrangler.json" });
+		worker = await unstable_startWorker({
+			config: "wrangler.json",
+			dev: { persist: false },
+		});
 	});
 
 	test("hello world", async () => {

packages/miniflare/package.json

@@ -87,7 +87,6 @@
 		"devalue": "^5.6.3",
 		"devtools-protocol": "^0.0.1182435",
 		"esbuild": "catalog:default",
-		"exit-hook": "2.2.1",
 		"expect-type": "^0.15.0",
 		"get-port": "^7.1.0",
 		"glob-to-regexp": "0.4.1",

packages/miniflare/src/exit-hook.ts

@@ -0,0 +1,96 @@
+/**
+ * Lightweight replacement for the `exit-hook` npm package.
+ *
+ * The third-party `exit-hook` registers process listeners (`exit`, `SIGINT`,
+ * `SIGTERM`, and `message`) that are never removed — even after every
+ * callback has been unregistered.  Those dangling listeners are harmless in
+ * long-running processes, but in short-lived child processes (e.g. those
+ * spawned by `node --test`) they can prevent clean exit by holding refs on
+ * handles such as the IPC channel.
+ *
+ * This module tracks the number of active registrations and removes **all**
+ * process listeners once the last registration is unregistered, so they
+ * cannot keep the event loop alive after dispose.
+ */
+
+const callbacks = new Set<() => void>();
+let registered = false;
+let called = false;
+
+function runCallbacks(): void {
+	if (called) {
+		return;
+	}
+	called = true;
+	for (const callback of callbacks) {
+		callback();
+	}
+}
+
+function onExit(): void {
+	runCallbacks();
+}
+
+function onSignalInt(): void {
+	runCallbacks();
+	// eslint-disable-next-line unicorn/no-process-exit -- intentional: replicate default SIGINT behavior
+	process.exit(128 + 2);
+}
+
+function onSignalTerm(): void {
+	runCallbacks();
+	// eslint-disable-next-line unicorn/no-process-exit -- intentional: replicate default SIGTERM behavior
+	process.exit(128 + 15);
+}
+
+function onMessage(message: unknown): void {
+	if (message === "shutdown") {
+		runCallbacks();
+		// eslint-disable-next-line unicorn/no-process-exit -- intentional: PM2 graceful shutdown
+		process.exit(0);
+	}
+}
+
+function addListeners(): void {
+	registered = true;
+	called = false;
+	process.on("exit", onExit);
+	process.on("SIGINT", onSignalInt);
+	process.on("SIGTERM", onSignalTerm);
+	// Only listen for IPC "shutdown" messages (PM2 support) when the process
+	// actually has an IPC channel.  Even without this guard the listener is
+	// harmless when there is no channel, but being explicit avoids any
+	// accidental ref of a future channel.
+	if (process.send !== undefined) {
+		process.on("message", onMessage);
+	}
+}
+
+function removeListeners(): void {
+	registered = false;
+	process.removeListener("exit", onExit);
+	process.removeListener("SIGINT", onSignalInt);
+	process.removeListener("SIGTERM", onSignalTerm);
+	process.removeListener("message", onMessage);
+}
+
+/**
+ * Register a callback to run when the process exits.  Returns a function
+ * that unregisters the callback.  When the last callback is unregistered,
+ * all underlying process listeners are removed so they cannot keep the
+ * event loop alive.
+ */
+export function exitHook(callback: () => void): () => void {
+	callbacks.add(callback);
+
+	if (!registered) {
+		addListeners();
+	}
+
+	return () => {
+		callbacks.delete(callback);
+		if (callbacks.size === 0 && registered) {
+			removeListeners();
+		}
+	};
+}

packages/miniflare/src/index.ts

@@ -11,7 +11,6 @@ import util from "node:util";
 import zlib from "node:zlib";
 import { checkMacOSVersion } from "@cloudflare/cli";
 import { removeDir, removeDirSync } from "@cloudflare/workers-utils";
-import exitHook from "exit-hook";
 import { $ as colors$, green } from "kleur/colors";
 import stoppable from "stoppable";
 import { getGlobalDispatcher, Pool } from "undici";
@@ -21,6 +20,7 @@ import SCRIPT_MINIFLARE_ZOD from "worker:shared/zod";
 import { WebSocketServer } from "ws";
 import { z } from "zod";
 import { fallbackCf, setupCf } from "./cf";
+import { exitHook } from "./exit-hook";
 import {
 	coupleWebSocket,
 	DispatchFetchDispatcher,
@@ -2408,6 +2408,9 @@ export class Miniflare {
 		}
 
 		if (previousEntryURL?.toString() !== this.#runtimeEntryURL.toString()) {
+			// Close the previous dispatcher if the entry URL changed, to avoid
+			// leaking sockets from the old Pool.
+			void this.#runtimeDispatcher?.close().catch(() => {});
 			this.#runtimeDispatcher = new Pool(this.#runtimeEntryURL, {
 				connect: { rejectUnauthorized: false },
 				// Disable timeouts for local dev — long-running responses (streaming,
@@ -2420,6 +2423,7 @@ export class Miniflare {
 		// Set up a direct dispatcher to the dev-registry-proxy socket so we can
 		// push registry updates without routing through the entry worker.
 		const devRegistryPort = maybeSocketPorts.get(SOCKET_DEV_REGISTRY);
+		void this.#devRegistryDispatcher?.close().catch(() => {});
 		if (devRegistryPort !== undefined) {
 			this.#devRegistryDispatcher = new Pool(
 				new URL(`http://127.0.0.1:${devRegistryPort}`)
@@ -3037,8 +3041,27 @@ export class Miniflare {
 			// Cleanup as much as possible even if `#init()` threw
 			await this.#proxyClient?.dispose();
 			await this.#runtime?.dispose();
+			// Close the undici Pool used for dispatching fetch requests to the
+			// runtime. This must happen after the runtime is disposed, so that
+			// in-flight connections are broken and close immediately. Without this,
+			// lingering sockets in the Pool can keep the Node.js event loop alive.
+			// The Pool may already be destroyed (e.g., if workerd was SIGKILL'd and
+			// all connections broke), so ignore ClientDestroyedError.
+			try {
+				await this.#runtimeDispatcher?.close();
+			} catch {}
+			// Also close the dev-registry dispatcher (same issue as above).
+			try {
+				await this.#devRegistryDispatcher?.close();
+			} catch {}
 
 			await this.#stopLoopbackServer();
+			// Close WebSocket servers so any connected clients are disconnected
+			// and their sockets don't keep the event loop alive. These use
+			// `noServer: true` so they don't own an HTTP server, but connected
+			// WebSocket clients still hold open sockets.
+			this.#liveReloadServer.close();
+			this.#webSocketServer.close();
 			// Best-effort cleanup: on Windows, workerd may not release file handles
 			// immediately after disposal, causing EBUSY errors. The temp directory
 			// lives in os.tmpdir() so the OS will clean it up eventually.

packages/miniflare/src/plugins/core/inspector-proxy/inspector-proxy-controller.ts

@@ -324,6 +324,10 @@ export class InspectorProxyController {
 		await Promise.all(this.#proxies.map((proxy) => proxy.dispose()));
 
 		const server = await this.#server;
+		// Force-close active connections so server.close() resolves immediately.
+		// Without this, active HTTP keep-alive or WebSocket connections prevent
+		// the close callback from firing, hanging the dispose.
+		server.closeAllConnections();
 		return new Promise((resolve, reject) => {
 			server.close((err) => (err ? reject(err) : resolve()));
 		});

packages/miniflare/src/plugins/core/inspector-proxy/inspector-proxy.ts

@@ -164,5 +164,6 @@ export class InspectorProxy {
 		clearInterval(this.#runtimeKeepAliveInterval);
 
 		this.#devtoolsWs?.close();
+		this.#runtimeWs?.close();
 	}
 }