fix(hyperdrive): seed remote bindings on every dev path and stop leaking bridges

Addresses three issues raised in review:

- Seeding ran only in `LocalRuntimeController`, so `getPlatformProxy()`,
  the Vite plugin and multi-worker dev built the binding with placeholder
  credentials (and a `mysql` scheme even for Postgres) and failed to
  authenticate at the edge, silently. Seeding now happens inside
  `buildMiniflareOptions` and `getMiniflareOptionsFromConfig`, covering
  every async dev path; `buildMiniflareBindingOptions` takes the seeded
  values as an argument and warns when they are absent, so the remaining
  synchronous entry point fails visibly rather than silently.

- `seedRemoteHyperdriveBindings` mutated binding objects that are shared
  by reference with the record the remote proxy session keeps for change
  detection, so every hot reload compared unequal and tore down the
  session. It now returns the seeded values instead of mutating.

- The remote TCP bridge was re-registered under the same key on each
  reload without closing the previous listener, leaking it and its live
  edge relays for the session's lifetime.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015GDyTfEa62t3bSe5wWn8Mt

Author: mack-erel

packages/miniflare/src/plugins/hyperdrive/hyperdrive-proxy.ts

@@ -275,6 +275,10 @@ export class HyperdriveProxyController {
 				}
 			});
 		});
+		// `getServices` re-runs on every `setOptions` (i.e. every dev reload), so
+		// close the bridge from the previous round before replacing it — otherwise
+		// the old listener and its live edge relays leak for the session's lifetime.
+		this.#servers.get(`remote:${name}`)?.close();
 		this.#servers.set(`remote:${name}`, server);
 		return port;
 	}

packages/remote-bindings/src/seed-hyperdrive-bindings.ts

@@ -44,22 +44,32 @@ async function fetchEdgeConnectionString(
 }
 
 /**
- * Seeds every remote Hyperdrive binding's `localConnectionString` with the
- * connection string of its edge session, so that the local binding presents
- * credentials the edge Hyperdrive proxy will accept.
+ * Fetches the edge session's connection string for every remote Hyperdrive
+ * binding, so that the local binding can present credentials the edge
+ * Hyperdrive proxy will accept.
  *
  * `buildMiniflareBindingOptions` is synchronous, so this async step must run
  * once the remote proxy session is ready and before miniflare options are
- * built. The passed `bindings` objects are mutated in place.
+ * built.
  *
- * No-op when there is no remote proxy session or no remote Hyperdrive bindings.
+ * The seeded values are *returned* rather than written onto the passed
+ * `bindings`: those binding objects are shared by reference with the record the
+ * remote proxy session keeps for change detection (`pickRemoteBindings` copies
+ * the record, not the objects). Mutating them would make the next reload's
+ * freshly-loaded config compare unequal to the stored, seeded one, tearing down
+ * and re-establishing the remote session on every file save.
+ *
+ * Returns an empty map when there is no remote proxy session or no remote
+ * Hyperdrive bindings.
  */
 export async function seedRemoteHyperdriveBindings(
 	bindings: Record<string, Binding> | undefined,
 	remoteProxyConnectionString: RemoteProxyConnectionString | undefined
-): Promise<void> {
+): Promise<Map<string, string>> {
+	const seeded = new Map<string, string>();
+
 	if (!remoteProxyConnectionString || !bindings) {
-		return;
+		return seeded;
 	}
 
 	const remoteHyperdrives = Object.entries(bindings).filter(
@@ -74,13 +84,14 @@ export async function seedRemoteHyperdriveBindings(
 	);
 
 	await Promise.all(
-		remoteHyperdrives.map(async ([name, binding]) => {
+		remoteHyperdrives.map(async ([name]) => {
 			const connectionString = await fetchEdgeConnectionString(
 				remoteProxyConnectionString,
 				name
 			);
-			(binding as { localConnectionString?: string }).localConnectionString =
-				connectionString;
+			seeded.set(name, connectionString);
 		})
 	);
+
+	return seeded;
 }

packages/wrangler/src/__tests__/dev/miniflare-hyperdrive.test.ts

@@ -10,7 +10,8 @@ const remoteProxyConnectionString = new URL(
 
 function buildHyperdriveOptions(
 	binding: Extract<Binding, { type: "hyperdrive" }>,
-	connectionString?: RemoteProxyConnectionString
+	connectionString?: RemoteProxyConnectionString,
+	seededConnectionStrings?: ReadonlyMap<string, string>
 ) {
 	const { bindingOptions } = buildMiniflareBindingOptions(
 		{
@@ -26,11 +27,14 @@ function buildHyperdriveOptions(
 			containerBuildId: undefined,
 			enableContainers: false,
 		},
-		connectionString
+		connectionString,
+		seededConnectionStrings
 	);
 	return bindingOptions.hyperdrives;
 }
 
+const SEEDED_CONNECTION_STRING = "postgres://edge-user:edge-pass@edge:5432/db";
+
 describe("hyperdrive bindings in local dev", () => {
 	const std = mockConsoleMethods();
 
@@ -47,9 +51,35 @@ describe("hyperdrive bindings in local dev", () => {
 		expect(std.warn).toBe("");
 	});
 
-	it("hands miniflare the remote proxy connection string for a remote binding", ({
+	it("hands miniflare the remote proxy connection string and the seeded edge credentials for a remote binding", ({
 		expect,
 	}) => {
+		expect(
+			buildHyperdriveOptions(
+				{
+					type: "hyperdrive",
+					id: "hyperdrive-id",
+					remote: true,
+				},
+				remoteProxyConnectionString,
+				new Map([["HYPERDRIVE", SEEDED_CONNECTION_STRING]])
+			)
+		).toEqual({
+			HYPERDRIVE: {
+				localConnectionString: SEEDED_CONNECTION_STRING,
+				remoteProxyConnectionString,
+			},
+		});
+		expect(std.warn).toBe("");
+	});
+
+	it("warns when a remote binding's edge credentials could not be seeded", ({
+		expect,
+	}) => {
+		// Reached from dev entry points that cannot seed (the binding builder is
+		// synchronous), e.g. `unstable_getMiniflareWorkerOptions`. Without the
+		// warning the binding would silently fall back to placeholder credentials
+		// and fail to authenticate at the edge.
 		expect(
 			buildHyperdriveOptions(
 				{
@@ -65,7 +95,9 @@ describe("hyperdrive bindings in local dev", () => {
 				remoteProxyConnectionString,
 			},
 		});
-		expect(std.warn).toBe("");
+		expect(std.warn).toContain(
+			`The Hyperdrive binding "HYPERDRIVE" is configured with "remote": true, but its edge credentials could not be seeded in this context`
+		);
 	});
 
 	it("explains how to fix a remote binding that has neither a session nor a local database", ({

packages/wrangler/src/api/integrations/platform/index.ts

@@ -21,7 +21,10 @@ import { logger } from "../../../logger";
 import { getSiteAssetPaths } from "../../../sites";
 import { dedent } from "../../../utils/dedent";
 import { getZoneFromRoute } from "../../../zones";
-import { maybeStartOrUpdateRemoteProxySession } from "../../remoteBindings";
+import {
+	maybeStartOrUpdateRemoteProxySession,
+	seedRemoteHyperdriveBindings,
+} from "../../remoteBindings";
 import { CacheStorage } from "./caches";
 import { ExecutionContext } from "./executionContext";
 // TODO: import from `@cloudflare/workers-utils` after migrating to `tsdown`
@@ -297,7 +300,10 @@ async function getMiniflareOptionsFromConfig(args: {
 			containerBuildId: undefined,
 			enableContainers: config.dev.enable_containers,
 		},
-		remoteProxyConnectionString
+		remoteProxyConnectionString,
+		// Remote Hyperdrive bindings authenticate with the edge session's
+		// credentials, which have to be fetched before this synchronous builder.
+		await seedRemoteHyperdriveBindings(bindings, remoteProxyConnectionString)
 	);
 
 	let processedAssetOptions: AssetsOptions | undefined;

packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts

@@ -310,11 +310,8 @@ export class LocalRuntimeController extends RuntimeController {
 			if (data.config.dev?.remote !== false) {
 				// note: remote bindings use (transitively) LocalRuntimeController, so we need to import
 				// from the module lazily in order to avoid circular dependency issues
-				const {
-					maybeStartOrUpdateRemoteProxySession,
-					pickRemoteBindings,
-					seedRemoteHyperdriveBindings,
-				} = await import("../remoteBindings");
+				const { maybeStartOrUpdateRemoteProxySession, pickRemoteBindings } =
+					await import("../remoteBindings");
 
 				const remoteBindings = pickRemoteBindings(configBundle.bindings ?? {});
 
@@ -331,15 +328,6 @@ export class LocalRuntimeController extends RuntimeController {
 								undefined
 							: data.config.dev.auth
 					);
-
-				// Remote Hyperdrive bindings need the edge session's connection
-				// string seeded into their local config before miniflare options are
-				// built (that step is synchronous). No-op unless a remote proxy
-				// session is running and there are remote Hyperdrive bindings.
-				await seedRemoteHyperdriveBindings(
-					configBundle.bindings ?? undefined,
-					this.#remoteProxySessionData?.session?.remoteProxyConnectionString
-				);
 			}
 
 			// Bail out if a newer bundle arrived while we were setting up

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

@@ -343,7 +343,8 @@ function pipelineEntry(
 }
 function hyperdriveEntry(
 	hyperdrive: CfHyperdrive,
-	remoteProxyConnectionString?: RemoteProxyConnectionString
+	remoteProxyConnectionString?: RemoteProxyConnectionString,
+	seededConnectionStrings?: ReadonlyMap<string, string>
 ):
 	| [string, string]
 	| [
@@ -360,10 +361,25 @@ function hyperdriveEntry(
 	// `connectionString`; miniflare uses `remoteProxyConnectionString` to stand
 	// up the local TCP bridge.
 	if (hyperdrive.remote && remoteProxyConnectionString) {
+		const seededConnectionString = seededConnectionStrings?.get(
+			hyperdrive.binding
+		);
+		if (seededConnectionString === undefined) {
+			// Seeding is what makes a database client authenticate through the edge
+			// proxy; without it miniflare falls back to placeholder credentials (and
+			// a `mysql` scheme even for Postgres) and the login is rejected. Warn
+			// rather than throw, so dev paths that cannot seed — the entry points
+			// below are synchronous — stay usable and fail visibly instead of
+			// silently.
+			logger.once.warn(
+				`The Hyperdrive binding "${hyperdrive.binding}" is configured with "remote": true, but its edge credentials could not be seeded in this context, so connections through it will likely fail to authenticate. Remote Hyperdrive bindings are currently supported in \`wrangler dev\` and \`getPlatformProxy()\`.`
+			);
+		}
 		return [
 			hyperdrive.binding,
 			{
-				localConnectionString: hyperdrive.localConnectionString,
+				localConnectionString:
+					seededConnectionString ?? hyperdrive.localConnectionString,
 				remoteProxyConnectionString,
 			},
 		];
@@ -560,7 +576,11 @@ type MiniflareBindingsConfig = Pick<
 //  each plugin options schema and use those
 export function buildMiniflareBindingOptions(
 	config: MiniflareBindingsConfig,
-	remoteProxyConnectionString: RemoteProxyConnectionString | undefined
+	remoteProxyConnectionString: RemoteProxyConnectionString | undefined,
+	// Edge connection strings for remote Hyperdrive bindings, keyed by binding
+	// name (see `seedRemoteHyperdriveBindings`). Fetching them is async, so
+	// callers seed before calling this synchronous builder.
+	seededHyperdriveConnectionStrings?: ReadonlyMap<string, string>
 ): {
 	bindingOptions: WorkerOptionsBindings;
 	externalWorkers: V4WorkerOptions[];
@@ -931,7 +951,11 @@ export function buildMiniflareBindingOptions(
 		),
 		hyperdrives: Object.fromEntries(
 			hyperdrives.map((hyperdrive) =>
-				hyperdriveEntry(hyperdrive, remoteProxyConnectionString)
+				hyperdriveEntry(
+					hyperdrive,
+					remoteProxyConnectionString,
+					seededHyperdriveConnectionStrings
+				)
 			)
 		),
 		analyticsEngineDatasets: Object.fromEntries(
@@ -1197,9 +1221,19 @@ export async function buildMiniflareOptions(
 			: undefined;
 
 	const { sourceOptions } = await buildSourceOptions(config);
+	// Remote Hyperdrive bindings need the edge session's credentials before the
+	// (synchronous) binding builder runs. Doing it here covers every dev path
+	// that goes through this function.
+	const { seedRemoteHyperdriveBindings } =
+		await import("../../api/remoteBindings");
+	const seededHyperdriveConnectionStrings = await seedRemoteHyperdriveBindings(
+		config.bindings ?? undefined,
+		remoteProxyConnectionString
+	);
 	const { bindingOptions, externalWorkers } = buildMiniflareBindingOptions(
 		config,
-		remoteProxyConnectionString
+		remoteProxyConnectionString,
+		seededHyperdriveConnectionStrings
 	);
 	if (bindingOptions.browserRendering && getBrowserRenderingHeadfulFromEnv()) {
 		bindingOptions.browserRendering.headful = true;