fix(miniflare): Fix Durable Object RPC calls from Node.js blocking the event loop (#11663)

* Add Miniflare logic to mark DO stubs as async

* Added tests to check for blocking DO stubs

* Added changeset

* Minor `blockedOn` RPC method refactoring

Co-authored-by: Pete Bacon Darwin <pete@bacondarwin.com>

* Improved DO "complete when unblocked" RPC tests timeouts

* Fixed DO RPC calls timeout test

* Minor DO RPC calls timeout test tweaks

* Updated `release` method to be synchronous

* Updated changset description

* Shorten commit sha links

Co-authored-by: Dario Piotrowicz <dario@cloudflare.com>

---------

Co-authored-by: Pete Bacon Darwin <pete@bacondarwin.com>
Co-authored-by: Dario Piotrowicz <dario@cloudflare.com>

Author: 3 people

.changeset/hip-clouds-build.md

@@ -0,0 +1,7 @@
+---
+"miniflare": patch
+---
+
+Fix Durable Object RPC calls from Node.js blocking the event loop, preventing `Promise.race()` and timeouts from working correctly.
+
+Previously, RPC calls from Node.js to Durable Objects would block the Node.js event loop, causing `Promise.race()` with timeouts to never resolve. This fix ensures that RPC calls properly yield control back to the event loop, allowing concurrent operations and timeouts to work as expected.

packages/miniflare/src/plugins/core/proxy/client.ts

@@ -12,6 +12,7 @@ import {
 	CoreHeaders,
 	createHTTPReducers,
 	createHTTPRevivers,
+	isDurableObjectStub,
 	isFetcherFetch,
 	isR2ObjectWriteHttpMetadata,
 	parseWithReadableStreams,
@@ -628,6 +629,10 @@ class ProxyStubHandler<T extends object>
 		);
 		if (
 			knownAsync ||
+			// Durable Object stub RPC calls should always be async to avoid blocking
+			// the Node.js event loop with `Atomics.wait()`. This allows Promise.race()
+			// and timeouts to work correctly when racing against DO method calls.
+			isDurableObjectStub(targetName) ||
 			// We assume every call with `ReadableStream`/`Blob` arguments is async.
 			// Note that you can't consume `ReadableStream`/`Blob` synchronously: if
 			// you tried a similar trick to `SynchronousFetcher`, blocking the main

packages/miniflare/src/workers/core/constants.ts

@@ -97,3 +97,11 @@ export function isR2ObjectWriteHttpMetadata(targetName: string, key: string) {
 export function isImagesInput(targetName: string, key: string) {
 	return targetName === "ImagesBindingImpl" && key === "input";
 }
+
+// Durable Object stub RPC calls should always be async to avoid blocking the
+// Node.js event loop. The internal names are "DurableObject" and "WorkerRpc".
+// https://github.com/cloudflare/workerd/blob/62b9ceee/src/workerd/api/actor.h#L86
+// https://github.com/cloudflare/workerd/blob/62b9ceee/src/workerd/api/worker-rpc.h#L30
+export function isDurableObjectStub(targetName: string) {
+	return targetName === "DurableObject" || targetName === "WorkerRpc";
+}

packages/miniflare/src/workers/core/proxy.worker.ts

@@ -236,6 +236,7 @@ export class ProxyServer implements DurableObject {
 		let status = 200;
 		let result: unknown;
 		let unbufferedRest: ReadableStream | undefined;
+		let rpcAwaited = false;
 		if (opHeader === ProxyOps.GET) {
 			// If no key header is specified, just return the target
 			result = keyHeader === null ? target : target[keyHeader];
@@ -317,6 +318,8 @@ export class ProxyServer implements DurableObject {
 				} else if (["RpcProperty", "RpcStub"].includes(func.constructor.name)) {
 					// let's resolve RpcPromise instances right away (to support serialization)
 					result = await func(...args);
+					// Mark that we've awaited this RPC call, so we set the Promise header below
+					rpcAwaited = true;
 				} else {
 					result = func.apply(target, args);
 				}
@@ -334,7 +337,7 @@ export class ProxyServer implements DurableObject {
 		}
 
 		const headers = new Headers();
-		if (allowAsync && result instanceof Promise) {
+		if (allowAsync && (result instanceof Promise || rpcAwaited)) {
 			// Note we only resolve `Promise`s if we're allowing async operations.
 			// Otherwise, we'll treat the `Promise` as a native target. This allows
 			// us to use regular HTTP status/headers to indicate whether the `Promise`

packages/miniflare/test/plugins/do/index.spec.ts

@@ -603,3 +603,88 @@ test("multiple workers with DO useSQLite true and undefined does not cause optio
 		});
 	});
 });
+
+const BLOCKING_DO_SCRIPT = `
+import { DurableObject } from 'cloudflare:workers';
+
+export class BlockingDO extends DurableObject {
+	locks = new Map();
+
+	blockedOp(n, lock) {
+		return new Promise((resolve) => {
+			this.locks.set(lock, () => resolve(lock));
+		}).then(() =>  n + 2);
+	}
+
+	release(lock) {
+		const releaseFn = this.locks.get(lock);
+		if (releaseFn) {
+			releaseFn();
+			this.locks.delete(lock);
+		}
+	}
+}
+
+export default {
+	fetch() { return new Response("OK"); }
+}
+`;
+
+test("Durable Object RPC calls do not block Node.js event loop", async (t) => {
+	const mf = new Miniflare({
+		durableObjects: { BLOCKING_DO: "BlockingDO" },
+		modules: true,
+		script: BLOCKING_DO_SCRIPT,
+	});
+
+	t.teardown(() => mf.dispose());
+
+	const namespace = await mf.getDurableObjectNamespace("BLOCKING_DO");
+	const stubId = namespace.idFromName("test");
+	const stub = namespace.get(stubId) as unknown as {
+		blockedOp: (n: number, lock: string) => Promise<number>;
+		release: (lock: string) => Promise<void>;
+	};
+
+	const blockedPromise = stub.blockedOp(5, "lock-1");
+
+	const raced = await Promise.race([
+		blockedPromise.then((result) => ({ type: "resolved", result })),
+		setTimeout(100).then(() => ({ type: "timeout" })),
+	]);
+
+	// If the event loop wasn't blocked, the timeout should win
+	t.deepEqual(raced, { type: "timeout" });
+});
+
+test("Durable Object RPC calls complete when unblocked", async (t) => {
+	const mf = new Miniflare({
+		durableObjects: { BLOCKING_DO: "BlockingDO" },
+		modules: true,
+		script: BLOCKING_DO_SCRIPT,
+	});
+
+	t.teardown(() => mf.dispose());
+
+	const namespace = await mf.getDurableObjectNamespace("BLOCKING_DO");
+	const stubId = namespace.idFromName("test");
+	const stub = namespace.get(stubId) as unknown as {
+		blockedOp: (n: number, lock: string) => Promise<number>;
+		release: (lock: string) => Promise<void>;
+	};
+
+	const blockedPromise = stub.blockedOp(10, "lock-2");
+
+	// Race the blocked operation against a timeout, releasing the lock as part of the race.
+	// The release should cause `blockedPromise` to resolve before the timeout.
+	// Use a generous timeout (5s) to avoid flakiness in CI environments.
+	const raced = await Promise.race([
+		blockedPromise.then((result) => ({ type: "resolved", result })),
+		stub
+			.release("lock-2")
+			.then(() => setTimeout(5_000))
+			.then(() => ({ type: "timeout" })),
+	]);
+
+	t.deepEqual(raced, { type: "resolved", result: 12 });
+});