Support unbound durable objects

Author: penalosa

fixtures/unbound-durable-object/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@fixture/unbound-durable-object",
+	"private": true,
+	"scripts": {
+		"deploy": "wrangler deploy",
+		"start": "wrangler dev",
+		"test:ci": "vitest"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "catalog:default",
+		"vitest": "catalog:default",
+		"wrangler": "workspace:*"
+	},
+	"volta": {
+		"extends": "../../package.json"
+	}
+}

fixtures/unbound-durable-object/src/index.ts

@@ -0,0 +1,60 @@
+import { DurableObject } from "cloudflare:workers";
+
+export class Counter extends DurableObject {
+	async getCounterValue() {
+		let value = (await this.ctx.storage.get("value")) || 0;
+		return value;
+	}
+
+	async increment(amount = 1) {
+		let value = (await this.ctx.storage.get<number>("value")) || 0;
+		value += amount;
+		await this.ctx.storage.put("value", value);
+		return value;
+	}
+
+	async decrement(amount = 1) {
+		let value = (await this.ctx.storage.get<number>("value")) || 0;
+		value -= amount;
+		await this.ctx.storage.put("value", value);
+		return value;
+	}
+}
+
+export default {
+	async fetch(
+		request: Request,
+		_env: never,
+		ctx: ExecutionContext
+	): Promise<Response> {
+		let url = new URL(request.url);
+		let name = url.searchParams.get("name");
+		if (!name) {
+			return new Response(
+				"Select a Durable Object to contact by using" +
+					" the `name` URL query string parameter, for example, ?name=A"
+			);
+		}
+
+		let stub = ctx.exports.Counter.getByName(name);
+
+		// Send a request to the Durable Object using RPC methods, then await its response.
+		let count = null;
+		switch (url.pathname) {
+			case "/increment":
+				count = await stub.increment();
+				break;
+			case "/decrement":
+				count = await stub.decrement();
+				break;
+			case "/":
+				// Serves the current value.
+				count = await stub.getCounterValue();
+				break;
+			default:
+				return new Response("Not found", { status: 404 });
+		}
+
+		return new Response(`count: ${count}`);
+	},
+};

fixtures/unbound-durable-object/tests/index.test.ts

@@ -0,0 +1,32 @@
+import { join, resolve } from "path";
+import { afterAll, beforeAll, describe, it } from "vitest";
+import { unstable_startWorker } from "wrangler";
+
+const basePath = resolve(__dirname, "..");
+
+describe("Unbound DO is available through `ctx.exports`", () => {
+	let worker: Awaited<ReturnType<typeof unstable_startWorker>>;
+
+	beforeAll(async () => {
+		worker = await unstable_startWorker({
+			config: join(basePath, "wrangler.jsonc"),
+		});
+	});
+
+	afterAll(async () => {
+		await worker.dispose();
+	});
+
+	it("storage operations don't throw", async ({ expect }) => {
+		const doName = crypto.randomUUID();
+		let response = await worker.fetch(`http://example.com?name=${doName}`);
+		let content = await response.text();
+		expect(content).toMatchInlineSnapshot(`"count: 0"`);
+
+		response = await worker.fetch(
+			`http://example.com/increment?name=${doName}`
+		);
+		content = await response.text();
+		expect(content).toMatchInlineSnapshot(`"count: 1"`);
+	});
+});

fixtures/unbound-durable-object/tests/tsconfig.json

@@ -0,0 +1,7 @@
+{
+	"extends": "@cloudflare/workers-tsconfig/tsconfig.json",
+	"compilerOptions": {
+		"types": ["node"]
+	},
+	"include": ["**/*.ts"]
+}

fixtures/unbound-durable-object/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"target": "es2021",
+		"lib": ["es2021"],
+		"module": "es2022",
+		"types": ["@cloudflare/workers-types/experimental"],
+		"noEmit": true,
+		"isolatedModules": true,
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"skipLibCheck": true
+	}
+}

fixtures/unbound-durable-object/wrangler.jsonc

@@ -0,0 +1,21 @@
+{
+	"name": "unbound-durable-object",
+	"main": "src/index.ts",
+	"compatibility_date": "2025-01-01",
+	"compatibility_flags": ["experimental"],
+	// This DO intentionally doesn't have a binding
+	// "durable_objects": {
+	// 	"bindings": [
+	// 		{
+	// 			"name": "COUNTER",
+	// 			"class_name": "Counter",
+	// 		},
+	// 	],
+	// },
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["Counter"],
+		},
+	],
+}

packages/miniflare/src/index.ts

@@ -338,7 +338,7 @@ function getDurableObjectClassNames(
 		.flatMap((workerOpts) => {
 			const workerServiceName = getUserServiceName(workerOpts.core.name);
 
-			return Object.values(workerOpts.do.durableObjects ?? {}).map(
+			const boundDOs = Object.values(workerOpts.do.durableObjects ?? {}).map(
 				(workerDODesignator) => {
 					const doInfo = normaliseDurableObject(workerDODesignator);
 					if (doInfo.serviceName === undefined) {
@@ -351,6 +351,22 @@ function getDurableObjectClassNames(
 					};
 				}
 			);
+
+			const unboundDOs = (
+				workerOpts.do.additionalUnboundDurableObjects ?? []
+			).map((workerDODesignator) => {
+				const doInfo = normaliseDurableObject(workerDODesignator);
+				if (doInfo.serviceName === undefined) {
+					// Fallback to current worker service if name not defined
+					doInfo.serviceName = workerServiceName;
+				}
+				return {
+					doInfo,
+					workerRawName: workerOpts.core.name,
+				};
+			});
+
+			return [...boundDOs, ...unboundDOs];
 		})
 		// We sort the list of durable objects because we want the durable objects without a scriptName or a scriptName
 		// that matches the raw worker's name (meaning that they are defined within their worker) to be processed first

packages/miniflare/src/plugins/do/index.ts

@@ -18,32 +18,30 @@ export const DOContainerOptionsSchema = z.object({
 });
 export type DOContainerOptions = z.infer<typeof DOContainerOptionsSchema>;
 
-export const DurableObjectsOptionsSchema = z.object({
-	durableObjects: z
-		.record(
-			z.union([
-				z.string(),
-				z.object({
-					className: z.string(),
-					scriptName: z.string().optional(),
-					useSQLite: z.boolean().optional(),
-					// Allow `uniqueKey` to be customised. We use in Wrangler when setting
-					// up stub Durable Objects that proxy requests to Durable Objects in
-					// another `workerd` process, to ensure the IDs created by the stub
-					// object can be used by the real object too.
-					unsafeUniqueKey: z
-						.union([z.string(), z.literal(kUnsafeEphemeralUniqueKey)])
-						.optional(),
-					// Prevents the Durable Object being evicted.
-					unsafePreventEviction: z.boolean().optional(),
-					remoteProxyConnectionString: z
-						.custom<RemoteProxyConnectionString>()
-						.optional(),
-					container: z.custom<DOContainerOptions>().optional(),
-				}),
-			])
-		)
+const DurableObject = z.object({
+	className: z.string(),
+	scriptName: z.string().optional(),
+	useSQLite: z.boolean().optional(),
+	// Allow `uniqueKey` to be customised. We use in Wrangler when setting
+	// up stub Durable Objects that proxy requests to Durable Objects in
+	// another `workerd` process, to ensure the IDs created by the stub
+	// object can be used by the real object too.
+	unsafeUniqueKey: z
+		.union([z.string(), z.literal(kUnsafeEphemeralUniqueKey)])
+		.optional(),
+	// Prevents the Durable Object being evicted.
+	unsafePreventEviction: z.boolean().optional(),
+	remoteProxyConnectionString: z
+		.custom<RemoteProxyConnectionString>()
 		.optional(),
+	container: z.custom<DOContainerOptions>().optional(),
+});
+
+export const DurableObjectsOptionsSchema = z.object({
+	durableObjects: z.record(z.union([z.string(), DurableObject])).optional(),
+	// Not all DOs are configured as bindings! Include these in a different key
+	// These might just be configured via migrations, but should still be allocated storage for e..g ctx.exports support
+	additionalUnboundDurableObjects: z.array(DurableObject).optional(),
 });
 export const DurableObjectsSharedOptionsSchema = z.object({
 	durableObjectsPersist: PersistenceSchema,

packages/wrangler/src/dev/miniflare/index.ts

@@ -425,6 +425,7 @@ type WorkerOptionsBindings = Pick<
 	| "helloWorld"
 	| "workerLoaders"
 	| "unsafeBindings"
+	| "additionalUnboundDurableObjects"
 >;
 
 type MiniflareBindingsConfig = Pick<
@@ -647,6 +648,37 @@ export function buildMiniflareBindingOptions(
 		}
 	}
 
+	/**
+	 * The `durableObjects` variable contains all DO bindings. However, this
+	 * may not represent all DOs defined in the app, because DOs can be defined
+	 * without being bound (accessible via ctx.exports).
+	 * To get a list of all configured DOS, we need all DOs provisioned via migrations,
+	 * wich we already have in the form of `classNameToUseSQLite`
+	 * As such, this code extends the list of bound DOs with configured DOs that
+	 * aren't already referenced. The outcome is that `additionalUnboundDurableObjects` will
+	 * contain DOs configured via migrations that are not bound.
+	 */
+	const additionalUnboundDurableObjects: WorkerOptionsBindings["additionalUnboundDurableObjects"] =
+		[];
+
+	for (const [className, useSQLite] of classNameToUseSQLite) {
+		if (!durableObjects.find((d) => d.class_name === className)) {
+			additionalUnboundDurableObjects.push({
+				className,
+				scriptName: undefined,
+				useSQLite,
+				container:
+					config.containerDOClassNames?.size && config.enableContainers
+						? getImageNameFromDOClassName({
+								doClassName: className,
+								containerDOClassNames: config.containerDOClassNames,
+								containerBuildId: config.containerBuildId,
+							})
+						: undefined,
+			});
+		}
+	}
+
 	const bindingOptions: WorkerOptionsBindings = {
 		bindings: {
 			...bindings.vars,
@@ -822,6 +854,7 @@ export function buildMiniflareBindingOptions(
 				}
 			)
 		),
+		additionalUnboundDurableObjects,
 
 		ratelimits: Object.fromEntries(
 			bindings.unsafe?.bindings