refactor(hyperdrive): prepare edge credentials in the remote proxy session

Per review: `maybeStartOrUpdateRemoteProxySession()` is already awaited by
every consumer of a remote session, so it is a better home for the seeding
step than `buildMiniflareOptions`.

It now fetches each remote Hyperdrive binding's edge connection string once
per session and returns them on `RemoteProxySessionData`. `wrangler dev`
(single- and multi-worker) and `getPlatformProxy()` pass them straight
through to the binding builder, and the Vite plugin and vitest-pool-workers
— which already await the same call — can pick them up the same way.

This also takes the work off the config-reload path: seeding used to run
inside `buildMiniflareOptions`, which every reload goes through.

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

Author: mack-erel

packages/remote-bindings/src/maybe-start-or-update-session.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert";
 import { getBindingLocalSupport } from "@cloudflare/workers-utils";
 import { getRemoteBindingsAuthHook } from "./auth";
+import { seedRemoteHyperdriveBindings } from "./seed-hyperdrive-bindings";
 import { startRemoteProxySession } from "./start-remote-proxy-session";
 import type { RemoteBindingsLogger } from "./logger";
 import type { RemoteProxySession } from "./start-remote-proxy-session";
@@ -45,6 +46,15 @@ export type RemoteProxySessionData = {
 	session: RemoteProxySession;
 	remoteBindings: Record<string, Binding>;
 	auth?: AsyncHook<CfAccount>;
+	/**
+	 * Edge connection strings for remote Hyperdrive bindings, keyed by binding
+	 * name. The edge mints per-session credentials, so a database client has to
+	 * present *these* to authenticate through the proxy. Fetched here, once per
+	 * session, so that every consumer of a session — `wrangler dev`,
+	 * `getPlatformProxy()`, the Vite plugin, `vitest-pool-workers` — receives
+	 * usable credentials without repeating the setup.
+	 */
+	hyperdriveConnectionStrings: Map<string, string>;
 };
 
 export type RemoteBindingsContext = {
@@ -123,6 +133,10 @@ export async function maybeStartOrUpdateRemoteProxySession(
 		session: remoteProxySession,
 		remoteBindings,
 		auth,
+		hyperdriveConnectionStrings: await seedRemoteHyperdriveBindings(
+			workerConfigObject.bindings,
+			remoteProxySession.remoteProxyConnectionString
+		),
 	};
 }
 

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

@@ -22,10 +22,7 @@ import { logger } from "../../../logger";
 import { getSiteAssetPaths } from "../../../sites";
 import { dedent } from "../../../utils/dedent";
 import { getZoneFromRoute } from "../../../zones";
-import {
-	maybeStartOrUpdateRemoteProxySession,
-	seedRemoteHyperdriveBindings,
-} from "../../remoteBindings";
+import { maybeStartOrUpdateRemoteProxySession } from "../../remoteBindings";
 import { CacheStorage } from "./caches";
 import { ExecutionContext } from "./executionContext";
 // TODO: import from `@cloudflare/workers-utils` after migrating to `tsdown`
@@ -36,7 +33,10 @@ import type {
 	RawConfig,
 	RawEnvironment,
 } from "../../../../../workers-utils/src";
-import type { RemoteProxySession } from "../../remoteBindings";
+import type {
+	RemoteProxySession,
+	RemoteProxySessionData,
+} from "../../remoteBindings";
 import type { IncomingRequestCfProperties } from "@cloudflare/workers-types/experimental";
 import type {
 	RemoteProxyConnectionString,
@@ -183,21 +183,24 @@ export async function getPlatformProxy<
 		env,
 	});
 
-	let remoteProxySession: RemoteProxySession | undefined = undefined;
+	let remoteProxySessionData: RemoteProxySessionData | null = null;
 	if (config.configPath && options.remoteBindings !== false) {
-		remoteProxySession = (
+		remoteProxySessionData =
 			(await maybeStartOrUpdateRemoteProxySession({
 				path: config.configPath,
 				environment: env,
-			})) ?? {}
-		).session;
+			})) ?? null;
 	}
+	const remoteProxySession: RemoteProxySession | undefined =
+		remoteProxySessionData?.session;
 
 	const miniflareOptions = await getMiniflareOptionsFromConfig({
 		config,
 		options,
 		remoteProxyConnectionString:
 			remoteProxySession?.remoteProxyConnectionString,
+		hyperdriveConnectionStrings:
+			remoteProxySessionData?.hyperdriveConnectionStrings,
 	});
 
 	const mf = new Miniflare(convertV4MiniflareOptions(miniflareOptions));
@@ -233,6 +236,11 @@ async function getMiniflareOptionsFromConfig(args: {
 	config: Config;
 	options: GetPlatformProxyOptions;
 	remoteProxyConnectionString?: RemoteProxyConnectionString;
+	/**
+	 * Edge credentials for remote Hyperdrive bindings, prepared once when the
+	 * remote proxy session started.
+	 */
+	hyperdriveConnectionStrings?: ReadonlyMap<string, string>;
 }): Promise<V4MiniflareOptions> {
 	const { config, options, remoteProxyConnectionString } = args;
 
@@ -303,9 +311,9 @@ async function getMiniflareOptionsFromConfig(args: {
 			enableContainers: config.dev.enable_containers,
 		},
 		remoteProxyConnectionString,
-		// Remote Hyperdrive bindings authenticate with the edge session's
-		// credentials, which have to be fetched before this synchronous builder.
-		await seedRemoteHyperdriveBindings(bindings, remoteProxyConnectionString)
+		// Edge credentials for remote Hyperdrive bindings, prepared once when the
+		// remote proxy session started.
+		args.hyperdriveConnectionStrings
 	);
 
 	let processedAssetOptions: AssetsOptions | undefined;

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

@@ -417,7 +417,8 @@ export class LocalRuntimeController extends RuntimeController {
 						type: "devRegistryUpdate",
 						registry,
 					});
-				}
+				},
+				this.#remoteProxySessionData?.hyperdriveConnectionStrings
 			);
 			options.handleUncaughtError = this.dispatchRuntimeError;
 

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

@@ -235,7 +235,9 @@ export class MultiworkerRuntimeController extends LocalRuntimeController {
 						type: "devRegistryUpdate",
 						registry,
 					});
-				}
+				},
+				this.#remoteProxySessionsData.get(data.config.name)
+					?.hyperdriveConnectionStrings
 			);
 
 			// `handleUncaughtError` is a shared Miniflare option, and the

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

@@ -343,19 +343,6 @@ function pipelineEntry(
 		throw new Error("Pipeline must have either a stream");
 	}
 }
-/**
- * Whether any binding opts into a remote Hyperdrive configuration. Used to keep
- * the (async) credential seeding off the reload path of configs that have no
- * such binding — which is every config that does not use this feature.
- */
-function hasRemoteHyperdriveBinding(
-	bindings: StartDevWorkerInput["bindings"]
-): boolean {
-	return Object.values(bindings ?? {}).some(
-		(binding) => binding.type === "hyperdrive" && binding.remote === true
-	);
-}
-
 function hyperdriveEntry(
 	hyperdrive: CfHyperdrive,
 	remoteProxyConnectionString?: RemoteProxyConnectionString,
@@ -1210,35 +1197,21 @@ export async function buildMiniflareOptions(
 	config: Omit<ConfigBundle, "rules">,
 	proxyToUserWorkerAuthenticationSecret: UUID,
 	remoteProxyConnectionString: RemoteProxyConnectionString | undefined,
-	onDevRegistryUpdate?: (registry: WorkerRegistry) => void
+	onDevRegistryUpdate?: (registry: WorkerRegistry) => void,
+	// Edge credentials for remote Hyperdrive bindings, prepared once per remote
+	// proxy session (see `maybeStartOrUpdateRemoteProxySession`).
+	hyperdriveConnectionStrings?: ReadonlyMap<string, string>
 ): Promise<Options> {
 	const upstream =
 		typeof config.localUpstream === "string"
 			? `${config.upstreamProtocol}://${config.localUpstream}`
 			: 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.
-	//
-	// This runs on every reload, so the guard is a cheap synchronous check that
-	// stays out of the way of configs this feature has nothing to do with: no
-	// remote Hyperdrive binding means no seeding, no lazy module load (the import
-	// is lazy to avoid a circular dependency), and no extra await here.
-	const seededHyperdriveConnectionStrings =
-		remoteProxyConnectionString && hasRemoteHyperdriveBinding(config.bindings)
-			? await import("../../api/remoteBindings").then((m) =>
-					m.seedRemoteHyperdriveBindings(
-						config.bindings ?? undefined,
-						remoteProxyConnectionString
-					)
-				)
-			: undefined;
 	const { bindingOptions, externalWorkers } = buildMiniflareBindingOptions(
 		config,
 		remoteProxyConnectionString,
-		seededHyperdriveConnectionStrings
+		hyperdriveConnectionStrings
 	);
 	if (bindingOptions.browserRendering && getBrowserRenderingHeadfulFromEnv()) {
 		bindingOptions.browserRendering.headful = true;