[miniflare] Support remote Hyperdrive bindings in local dev

.changeset/hyperdrive-remote-bindings-local-dev.md

@@ -0,0 +1,21 @@
+---
+"@cloudflare/config": minor
+"miniflare": minor
+"wrangler": minor
+"@cloudflare/vite-plugin": minor
+"@cloudflare/workers-utils": minor
+---
+
+Support remote Hyperdrive bindings in local development
+
+```jsonc
+{
+	"hyperdrive": [
+		{
+			"binding": "HYPERDRIVE",
+			"id": "<your-hyperdrive-id>",
+			"remote": true,
+		},
+	],
+}
+```

packages/config/src/__tests__/convert.test.ts

@@ -394,6 +394,23 @@ describe("convertToWranglerConfig", () => {
 			]);
 		});
 
+		it("maps remote Hyperdrive without a local connection string", ({
+			expect,
+		}) => {
+			const result = convertToWranglerConfig({
+				worker: {
+					...baseWorker,
+					env: {
+						HD: { type: "hyperdrive", id: "h-1", dev: { remote: true } },
+					},
+				},
+				containers: [],
+			});
+			expect(result.hyperdrive).toEqual([
+				{ binding: "HD", id: "h-1", remote: true },
+			]);
+		});
+
 		it("maps pipeline.name to stream", ({ expect }) => {
 			const result = convertToWranglerConfig({
 				worker: {

packages/config/src/bindings.ts

@@ -253,7 +253,7 @@ export interface HyperdriveBindingOptions {
 	/** The ID of the Hyperdrive configuration. */
 	id: string;
 	/** Options that only apply during local development. */
-	dev?: {
+	dev?: BindingDevOptions & {
 		/** The database connection string used during local development. */
 		connectionString?: string;
 	};

packages/config/src/convert.ts

@@ -543,6 +543,7 @@ function convertBindingsAndAssets(
 					omitUndefined({
 						binding: name,
 						id: binding.id,
+						remote: binding.dev?.remote,
 						localConnectionString: binding.dev?.connectionString,
 					})
 				);

packages/config/src/schema.ts

@@ -99,7 +99,9 @@ export const FlagshipBindingSchema = z.strictObject({
 export const HyperdriveBindingSchema = z.strictObject({
 	type: z.literal("hyperdrive"),
 	id: z.string(),
-	dev: z.strictObject({ connectionString: z.string().optional() }).optional(),
+	dev: RemoteBindingDevSchema.extend({
+		connectionString: z.string().optional(),
+	}).optional(),
 });
 
 export const KnownBindingSchema = z.discriminatedUnion("type", [

packages/miniflare/src/config/schema.ts

@@ -181,8 +181,23 @@ const MiniflareBrowserBindingSchema = BrowserBindingSchema.extend({
 	headful: z.boolean().optional(),
 });
 
+/**
+ * Remote Hyperdrive bindings get their connection string from the proxy session.
+ */
 const MiniflareHyperdriveBindingSchema = HyperdriveBindingSchema.extend({
-	dev: z.strictObject({ connectionString: z.string() }),
+	dev: z.strictObject({
+		connectionString: z.string().optional(),
+		remote: z.boolean().optional(),
+	}),
+}).superRefine((value, ctx) => {
+	if (!value.dev.remote && value.dev.connectionString === undefined) {
+		ctx.addIssue({
+			code: "custom",
+			path: ["dev", "connectionString"],
+			message:
+				"A Hyperdrive binding requires a connection string unless it sets 'remote': true.",
+		});
+	}
 });
 
 /**

packages/miniflare/src/config/v4-convert.ts

@@ -704,10 +704,13 @@ function addProductBindings(
 		env[name] = { type: "analytics-engine-dataset", name: binding.dataset };
 	}
 	for (const [name, value] of Object.entries(worker.hyperdrives ?? {})) {
+		const isRemoteEntry = typeof value === "object" && !(value instanceof URL);
 		env[name] = {
 			type: "hyperdrive",
-			id: name,
-			dev: { connectionString: String(value) },
+			id: isRemoteEntry && value.id ? value.id : name,
+			dev: isRemoteEntry
+				? { remote: isRemote(value.remoteProxyConnectionString) }
+				: { connectionString: String(value) },
 		};
 	}
 	for (const [name, binding] of Object.entries(worker.ratelimits ?? {})) {

packages/miniflare/src/config/v4-schema.ts

@@ -278,7 +278,7 @@ const V4QueueConsumerOptionsSchema = z.object({
 	retryDelay: V4QueueMessageDelaySchema,
 });
 
-const V4HyperdriveSchema = z
+const V4HyperdriveConnectionSchema = z
 	.union([z.url(), z.instanceof(URL)])
 	.superRefine((value, ctx) => {
 		const url = typeof value === "string" ? new URL(value) : value;
@@ -323,6 +323,14 @@ const V4HyperdriveSchema = z
 		}
 	});
 
+const V4HyperdriveSchema = z.union([
+	V4HyperdriveConnectionSchema,
+	z.object({
+		id: z.string().optional(),
+		remoteProxyConnectionString: RemoteProxyConnectionStringSchema,
+	}),
+]);
+
 const V4PipelineSchema = z.union([
 	z.string(),
 	z.object({
@@ -867,7 +875,15 @@ export type V4WorkerOptionsShape = {
 				  })
 		  >
 		| string[];
-	hyperdrives?: Record<string, string | URL>;
+	hyperdrives?: Record<
+		string,
+		| string
+		| URL
+		| {
+				id?: string;
+				remoteProxyConnectionString: RemoteProxyConnectionString;
+		  }
+	>;
 	ratelimits?: Record<
 		string,
 		{ namespace_id: string; simple: { limit: number; period?: 10 | 60 } }

packages/miniflare/src/index.ts

@@ -879,7 +879,7 @@ export class Miniflare {
 	readonly #initPromise: Promise<void>;
 
 	// Aborted when dispose() is called
-	readonly #disposeController: AbortController;
+	readonly #disposeController = new AbortController();
 	#loopbackServer?: StoppableServer;
 	#loopbackHost?: string;
 	readonly #webSocketServer: WebSocketServer;
@@ -891,7 +891,7 @@ export class Miniflare {
 
 	#containerPrivilegesCache = new ContainerPrivilegesCache();
 	#hyperdriveProxyController: HyperdriveProxyController =
-		new HyperdriveProxyController();
+		new HyperdriveProxyController(this.#disposeController.signal);
 
 	// Set the first time the remote-bindings proxy CLIENT worker reports a
 	// Cloudflare Access 403 block on a request to the remote-bindings proxy
@@ -1028,7 +1028,6 @@ export class Miniflare {
 			this.#devRegistry.dispose();
 		});
 
-		this.#disposeController = new AbortController();
 		this.#runtimeMutex = new Mutex();
 		this.#initPromise = this.#runtimeMutex
 			.runWith(async () => {
@@ -2675,6 +2674,14 @@ export class Miniflare {
 		this.#hyperdriveProxyController.beginUpdate();
 		try {
 			await this.#assembleAndUpdateConfigInternal(reusePorts);
+		} catch (error) {
+			if (
+				!this.#disposeController.signal.aborted ||
+				!(error instanceof Error) ||
+				error.name !== "AbortError"
+			) {
+				throw error;
+			}
 		} finally {
 			// If assembly or runtime startup failed, keep the old listeners and
 			// close only the new candidates. A successful update already committed.
@@ -3433,7 +3440,10 @@ export class Miniflare {
 
 		// Populate bindings from each plugin
 		for (const [key, plugin] of this.#mergedPluginEntries) {
-			const pluginBindings = await plugin.getNodeBindings(workerOpts);
+			const pluginBindings = await plugin.getNodeBindings(workerOpts, {
+				hyperdriveProxyController: this.#hyperdriveProxyController,
+				workerIndex,
+			});
 			for (const [name, binding] of Object.entries(pluginBindings)) {
 				if (binding instanceof ProxyNodeBinding) {
 					const proxyBindingName = getProxyBindingName(key, workerName, name);
@@ -3955,8 +3965,7 @@ export class Miniflare {
 		// Unregister workers from dev registry and stop the file watcher
 		await this.#devRegistry.dispose();
 
-		// shutdown hyperdrive proxies if any exist
-		await this.#hyperdriveProxyController.dispose();
+		this.#hyperdriveProxyController.dispose();
 
 		// Remove from instance registry as last step in disposal, preserving the
 		// existing behavior when an earlier cleanup operation fails.