Implement support for ctx.props. (#8640)

* Implement support for ctx.props.

In `wrangler.toml` you can declare a service binding with props:

```
[[services]]
binding = "MY_SERVICE"
service = "some-worker"
props = { foo = 123, bar = 456 }
```

Unfortunately, it currently doesn't work when wrangler is running different workers in different processes, as `props` cannot be sent to a remote `workerd`. Fixing this would require `workerd` changes, but since we are moving away from the multi-process mode anyway, perhaps it's not worth it.

Note: I used Claude Code to find my way around the codebase. It wrote most of the PR. It was not able to figure out that changes were needed under `packages/miniflare`, and I myself had a pretty hard time figuring out where to edit.

* Add changeset for props support

---------

Co-authored-by: Greg Brimble <[email protected]>

Author: 2 people

.changeset/curly-groups-scream.md

@@ -0,0 +1,32 @@
+---
+"miniflare": minor
+"wrangler": minor
+---
+
+Add support for defining `props` on a Service binding.
+
+In your configuration file, you can define a service binding with props:
+
+```json
+{
+	"services": [
+		{
+			"binding": "MY_SERVICE",
+			"service": "some-worker",
+			"props": { "foo": 123, "bar": "value" }
+		}
+	]
+}
+```
+
+These can then be accessed by the callee:
+
+```ts
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+export default class extends WorkerEntrypoint {
+	fetch() {
+		return new Response(JSON.stringify(this.ctx.props));
+	}
+}
+```

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

@@ -255,6 +255,7 @@ function getCustomServiceDesignator(
 ): ServiceDesignator {
 	let serviceName: string;
 	let entrypoint: string | undefined;
+	let props: { json: string } | undefined;
 	if (typeof service === "function") {
 		// Custom `fetch` function
 		serviceName = getCustomServiceName(workerIndex, kind, name);
@@ -268,6 +269,9 @@ function getCustomServiceDesignator(
 				serviceName = getUserServiceName(service.name);
 			}
 			entrypoint = service.entrypoint;
+			if (service.props) {
+				props = { json: JSON.stringify(service.props) };
+			}
 		} else {
 			// Builtin workerd service: network, external, disk
 			serviceName = getBuiltinServiceName(workerIndex, kind, name);
@@ -282,7 +286,7 @@ function getCustomServiceDesignator(
 		// Regular user worker
 		serviceName = getUserServiceName(service);
 	}
-	return { name: serviceName, entrypoint };
+	return { name: serviceName, entrypoint, props };
 }
 
 function maybeGetCustomServiceService(

packages/miniflare/src/plugins/core/services.ts

@@ -90,6 +90,7 @@ export const ServiceDesignatorSchema = z.union([
 	z.object({
 		name: z.union([z.string(), z.literal(kCurrentWorker)]),
 		entrypoint: z.ostring(),
+		props: z.record(z.unknown()).optional(),
 	}),
 	z.object({ network: NetworkSchema }),
 	z.object({ external: ExternalServerSchema }),

packages/miniflare/src/runtime/config/workerd.ts

@@ -46,6 +46,7 @@ export type Service = {
 export interface ServiceDesignator {
 	name?: string;
 	entrypoint?: string;
+	props?: { json: string };
 }
 
 export type Worker = (

packages/wrangler/e2e/multiworker-dev.test.ts

@@ -67,6 +67,10 @@ describe("multiworker", () => {
 							await counter.increment(2)
 							await counter.increment(3)
 							return new Response(String(await counter.value))
+                        }
+                        if (url.pathname === "/props") {
+                            const props = await env.COUNTER.getProps()
+                            return new Response(JSON.stringify(props))
                         }
 						return env.BEE.fetch(req);
 					},
@@ -129,6 +133,9 @@ describe("multiworker", () => {
 					async newCounter() {
 						return new Counter();
 					}
+					async getProps() {
+						return this.ctx.props;
+					}
 				}
 				export default{
 					async fetch(req, env) {
@@ -193,6 +200,7 @@ describe("multiworker", () => {
 						binding = "COUNTER"
 						service = '${workerName2}'
 						entrypoint = 'CounterService'
+						props = { foo = 123, bar = { baz = "hello from props" } }
 				`,
 			});
 		});
@@ -232,6 +240,26 @@ describe("multiworker", () => {
 			);
 		});
 
+		it("can access service props through a binding", async () => {
+			const workerA = helper.runLongLived(
+				`wrangler dev -c wrangler.toml -c ${b}/wrangler.toml`,
+				{ cwd: a }
+			);
+			const { url } = await workerA.waitForReady(5_000);
+
+			await vi.waitFor(
+				async () => {
+					const response = await fetch(`${url}/props`);
+					const props = await response.json();
+					expect(props).toEqual({
+						foo: 123,
+						bar: { baz: "hello from props" },
+					});
+				},
+				{ interval: 1000, timeout: 10_000 }
+			);
+		});
+
 		it("shows error on startup with non-existent service", async () => {
 			await baseSeed(a, {
 				"wrangler.toml": dedent`

packages/wrangler/src/__tests__/deploy.test.ts

@@ -8893,6 +8893,45 @@ addEventListener('fetch', event => {});`
 				expect(std.err).toMatchInlineSnapshot(`""`);
 				expect(std.warn).toMatchInlineSnapshot(`""`);
 			});
+
+			it("should support service bindings with props", async () => {
+				writeWranglerConfig({
+					services: [
+						{
+							binding: "FOO",
+							service: "foo-service",
+							props: { foo: 123, bar: { baz: "hello from props" } },
+						},
+					],
+				});
+				writeWorkerSource();
+				mockSubDomainRequest();
+				mockUploadWorkerRequest({
+					expectedBindings: [
+						{
+							type: "service",
+							name: "FOO",
+							service: "foo-service",
+							props: { foo: 123, bar: { baz: "hello from props" } },
+						},
+					],
+				});
+
+				await runWrangler("deploy index.js");
+				expect(std.out).toMatchInlineSnapshot(`
+					"Total Upload: xx KiB / gzip: xx KiB
+					Worker Startup Time: 100 ms
+					Your worker has access to the following bindings:
+					- Services:
+					  - FOO: foo-service
+					Uploaded test-name (TIMINGS)
+					Deployed test-name triggers (TIMINGS)
+					  https://test-name.test-sub-domain.workers.dev
+					Current Version ID: Galaxy-Class"
+				`);
+				expect(std.err).toMatchInlineSnapshot(`""`);
+				expect(std.warn).toMatchInlineSnapshot(`""`);
+			});
 		});
 
 		describe("[analytics_engine_datasets]", () => {

packages/wrangler/src/config/environment.ts

@@ -684,6 +684,8 @@ export interface EnvironmentNonInheritable {
 				environment?: string;
 				/** Optionally, the entrypoint (named export) of the service to bind to. */
 				entrypoint?: string;
+				/** Optional properties that will be made available to the service via ctx.props. */
+				props?: Record<string, unknown>;
 		  }[]
 		| undefined;
 

packages/wrangler/src/deployment-bundle/create-worker-upload-form.ts

@@ -386,13 +386,14 @@ export function createWorkerUploadForm(worker: CfWorkerInit): FormData {
 	);
 
 	bindings.services?.forEach(
-		({ binding, service, environment, entrypoint }) => {
+		({ binding, service, environment, entrypoint, props }) => {
 			metadataBindings.push({
 				name: binding,
 				type: "service",
 				service,
 				...(environment && { environment }),
 				...(entrypoint && { entrypoint }),
+				...(props && { props }),
 			});
 		}
 	);

packages/wrangler/src/deployment-bundle/worker.ts

@@ -217,6 +217,7 @@ export interface CfService {
 	service: string;
 	environment?: string;
 	entrypoint?: string;
+	props?: Record<string, unknown>;
 }
 
 export interface CfAnalyticsEngineDataset {

packages/wrangler/src/dev/miniflare.ts

@@ -444,6 +444,7 @@ export function buildMiniflareBindingOptions(config: MiniflareBindingsConfig): {
 			serviceBindings[service.binding] = {
 				name: service.service,
 				entrypoint: service.entrypoint,
+				props: service.props,
 			};
 			continue;
 		}
@@ -507,6 +508,9 @@ export function buildMiniflareBindingOptions(config: MiniflareBindingsConfig): {
 				}
 			}
 
+			// BUG: We have no way to pass `props` across an external socket, so we
+			// drop them. We are planning to move away from the multi-process model
+			// anyway, which will solve the problem.
 			serviceBindings[service.binding] = {
 				external: {
 					address,