Add cross-Worker Workflow bindings to the experimental configuration API (#15877)

Author: jamesopstad

.changeset/curvy-workflows-connect.md

@@ -0,0 +1,7 @@
+---
+"@cloudflare/config": minor
+---
+
+Add cross-Worker Workflow bindings to the experimental configuration API
+
+Workflow bindings can now identify a Workflow by name and reference the Worker and exported `WorkflowEntrypoint` class that define it.

packages/config/src/__tests__/config-loader.test.ts

@@ -181,6 +181,48 @@ describe("resolveAndParseConfig", () => {
 		}
 	});
 
+	it("resolves a Worker reference in a Workflow binding", async ({
+		expect,
+	}) => {
+		const workflowWorker = defineWorker({
+			name: "workflow-worker",
+			compatibilityDate,
+			exports: {
+				GreetingWorkflow: workerExports.workflow({ name: "greeting" }),
+			},
+		});
+		const config = defineConfig({
+			worker: defineWorker({
+				name: "web",
+				compatibilityDate,
+				env: {
+					GREETING: bindings.workflow({
+						name: "greeting",
+						worker: workflowWorker,
+						exportName: "GreetingWorkflow",
+					}),
+				},
+			}),
+		});
+
+		const result = await resolveAndParseConfig(config, {
+			isPreview: false,
+			mode: undefined,
+		});
+
+		expect(result.success).toBe(true);
+		if (result.success) {
+			expect(result.data.worker?.env).toMatchObject({
+				GREETING: {
+					type: "workflow",
+					name: "greeting",
+					worker: "workflow-worker",
+					exportName: "GreetingWorkflow",
+				},
+			});
+		}
+	});
+
 	it("allows a cross-project Worker factory to use an explicit context", async ({
 		expect,
 	}) => {

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

@@ -726,6 +726,32 @@ describe("convertToWranglerConfig", () => {
 			});
 		});
 
+		it("maps Workflow binding to workflows", ({ expect }) => {
+			const result = convertToWranglerConfig({
+				worker: {
+					...baseWorker,
+					env: {
+						WORKFLOW: {
+							type: "workflow",
+							name: "greeting",
+							worker: "workflow-worker",
+							exportName: "GreetingWorkflow",
+						},
+					},
+				},
+				containers: [],
+			});
+
+			expect(result.workflows).toEqual([
+				{
+					binding: "WORKFLOW",
+					name: "greeting",
+					class_name: "GreetingWorkflow",
+					script_name: "workflow-worker",
+				},
+			]);
+		});
+
 		it("maps logfwdr binding to logfwdr.bindings", ({ expect }) => {
 			const result = convertToWranglerConfig({
 				worker: {

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

@@ -293,6 +293,29 @@ describe("InputWorkerSchema", () => {
 		});
 	});
 
+	describe("workflow bindings", () => {
+		const workflowBinding = {
+			type: "workflow",
+			name: "greeting",
+			worker: "workflow-worker",
+			exportName: "GreetingWorkflow",
+		} as const;
+
+		it("accepts a cross-Worker Workflow binding", ({ expect }) => {
+			expect(BindingSchema.safeParse(workflowBinding).success).toBe(true);
+		});
+
+		it.for(["name", "worker", "exportName"] as const)(
+			"requires %s",
+			(field, { expect }) => {
+				const binding: Record<string, unknown> = { ...workflowBinding };
+				delete binding[field];
+
+				expect(BindingSchema.safeParse(binding).success).toBe(false);
+			}
+		);
+	});
+
 	describe("entrypoint", () => {
 		it("accepts a string entrypoint and passes it through unchanged", ({
 			expect,

packages/config/src/__tests__/worker-references.test-d.ts

@@ -1,8 +1,16 @@
-import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
+import {
+	DurableObject,
+	WorkerEntrypoint,
+	WorkflowEntrypoint,
+} from "cloudflare:workers";
 import { bindings } from "../bindings";
 import { defineWorker } from "../definition";
 import { exports as workerExports } from "../exports";
-import type { DurableObjectBinding, WorkerBinding } from "../bindings";
+import type {
+	DurableObjectBinding,
+	WorkerBinding,
+	WorkflowBinding,
+} from "../bindings";
 import type { InferEnv, UnwrapConfig } from "../inference";
 
 class Admin extends WorkerEntrypoint {
@@ -17,10 +25,13 @@ class Counter extends DurableObject {
 	}
 }
 
+class GreetingWorkflow extends WorkflowEntrypoint {}
+
 const entrypoint = {
 	default: { fetch: () => new Response() },
 	Admin,
 	Counter,
+	GreetingWorkflow,
 };
 
 const auxiliary = defineWorker({
@@ -29,6 +40,7 @@ const auxiliary = defineWorker({
 	entrypoint,
 	exports: {
 		Counter: workerExports.durableObject({ storage: "sqlite" }),
+		GreetingWorkflow: workerExports.workflow({ name: "greeting" }),
 	},
 });
 
@@ -56,6 +68,11 @@ const config = defineWorker({
 			worker: auxiliary,
 			exportName: "Counter",
 		}),
+		GREETING: bindings.workflow({
+			name: "greeting",
+			worker: auxiliary,
+			exportName: "GreetingWorkflow",
+		}),
 		DIRECT_ADMIN: {
 			type: "worker",
 			worker: auxiliary,
@@ -80,6 +97,13 @@ bindings.durableObject({
 	exportName: "Admin",
 });
 
+bindings.workflow({
+	name: "greeting",
+	worker: auxiliary,
+	// @ts-expect-error Only configured Workflow exports are accepted.
+	exportName: "Admin",
+});
+
 type Equal<T, U> =
 	(<V>() => V extends T ? 1 : 2) extends <V>() => V extends U ? 1 : 2
 		? true
@@ -94,10 +118,15 @@ export type WorkerExportNameTest = Assert<
 export type DurableObjectExportNameTest = Assert<
 	Equal<DurableObjectBinding<Auxiliary>["exportName"], "Counter">
 >;
+export type WorkflowExportNameTest = Assert<
+	Equal<WorkflowBinding<Auxiliary>["exportName"], "GreetingWorkflow">
+>;
 // @ts-expect-error Worker binding export names come from the referenced Worker.
 export type InvalidWorkerExportNameTest = WorkerBinding<Auxiliary, "Counter">;
 // @ts-expect-error Durable Object export names come from the referenced Worker.
 export type InvalidDoExportNameTest = DurableObjectBinding<Auxiliary, "Admin">;
+// @ts-expect-error Workflow export names come from the referenced Worker.
+export type InvalidWorkflowExportNameTest = WorkflowBinding<Auxiliary, "Admin">;
 export type AdminBindingTest = Assert<Equal<Env["ADMIN"], Fetcher<Admin>>>;
 export type DefaultBindingTest = Assert<Equal<Env["DEFAULT"], Fetcher>>;
 export type FactoryAdminBindingTest = Assert<
@@ -109,4 +138,7 @@ export type DirectAdminBindingTest = Assert<
 export type CounterBindingTest = Assert<
 	Equal<Env["COUNTER"], DurableObjectNamespace<Counter>>
 >;
+export type GreetingBindingTest = Assert<
+	Env["GREETING"] extends Workflow ? true : false
+>;
 export type ExternalBindingTest = Assert<Equal<Env["EXTERNAL"], Fetcher>>;

packages/config/src/bindings.ts

@@ -635,16 +635,18 @@ interface WorkflowBindingOptions<
 	TWorker extends WorkerReference = WorkerReference,
 	TExportName extends WorkflowExportName<TWorker> = WorkflowExportName<TWorker>,
 > {
+	/** The name of the Workflow. */
+	name: string;
 	/** The name or config of the Worker that defines the Workflow. */
 	worker: TWorker;
 	/** The exported class name of the Workflow. */
 	exportName: TExportName;
 }
 
 /**
- * Binding to a Workflow. `worker` is the name or config of the Worker that
- * defines the Workflow; `exportName` is the exported `WorkflowEntrypoint`
- * class name.
+ * Binding to a Workflow. `name` identifies the Workflow, `worker` is the name
+ * or config of the Worker that defines it, and `exportName` is the exported
+ * `WorkflowEntrypoint` class name.
  */
 export interface WorkflowBinding<
 	TWorker extends WorkerReference = WorkerReference,
@@ -851,13 +853,17 @@ export interface Bindings {
 	): WorkerBinding<TWorker, NoInfer<TExportName>>;
 	/** Binding to a Worker Loader. */
 	workerLoader(): WorkerLoaderBinding;
-	// TODO: re-enable when workflow bindings return.
-	// /**
-	//  * Create a Workflow binding.
-	//  * `worker` may be a Worker config reference or a Worker name.
-	//  * `exportName` must be a valid `WorkflowEntrypoint` export for the given Worker.
-	//  */
-	// workflow(options: WorkflowBindingOptions): WorkflowBinding;
+	/**
+	 * Create a Workflow binding.
+	 * `worker` may be a Worker config reference or a Worker name.
+	 * `exportName` must be a valid `WorkflowEntrypoint` export for the given Worker.
+	 */
+	workflow<
+		TWorker extends WorkerReference,
+		TExportName extends WorkflowExportName<TWorker>,
+	>(
+		options: WorkflowBindingOptions<TWorker, TExportName>
+	): WorkflowBinding<TWorker, NoInfer<TExportName>>;
 }
 
 export const bindings = {
@@ -907,6 +913,5 @@ export const bindings = {
 	vpcNetwork: (options) => ({ type: "vpc-network", ...options }),
 	worker: (options) => ({ type: "worker", ...options }),
 	workerLoader: () => ({ type: "worker-loader" }),
-	// TODO: re-enable when workflow bindings return.
-	// workflow: (options) => ({ type: "workflow", ...options }),
+	workflow: (options) => ({ type: "workflow", ...options }),
 } as Bindings;

packages/config/src/convert.ts

@@ -725,17 +725,15 @@ function convertBindingsAndAssets(
 				workerLoaders.push({ binding: name });
 				break;
 			}
-			// TODO: re-enable when workflow bindings return.
-			// case "workflow": {
-			// 	workflows.push(
-			// 		omitUndefined({
-			// 			binding: name,
-			// 			class_name: binding.exportName,
-			// 			script_name: binding.worker,
-			// 		})
-			// 	);
-			// 	break;
-			// }
+			case "workflow": {
+				workflows.push({
+					binding: name,
+					name: binding.name,
+					class_name: binding.exportName,
+					script_name: binding.worker,
+				});
+				break;
+			}
 		}
 	}
 

packages/config/src/index.ts

@@ -30,6 +30,7 @@ export {
 	validateSingletonBindings,
 	WorkerBindingSchema,
 	WorkerEntrypointExportSchema,
+	WorkflowBindingSchema,
 	WorkflowExportSchema,
 } from "./schema";
 export { generateTypes } from "./generate";

packages/config/src/schema.ts

@@ -35,6 +35,13 @@ export const WorkerBindingSchema = z.strictObject({
 	dev: RemoteBindingDevSchema.optional(),
 });
 
+export const WorkflowBindingSchema = z.strictObject({
+	type: z.literal("workflow"),
+	name: z.string(),
+	worker: z.string(),
+	exportName: z.string(),
+});
+
 export const D1BindingSchema = z.strictObject({
 	type: z.literal("d1"),
 	name: z.string().optional(),
@@ -230,12 +237,7 @@ export const KnownBindingSchema = z.discriminatedUnion("type", [
 		),
 	WorkerBindingSchema,
 	z.strictObject({ type: z.literal("worker-loader") }),
-	// TODO: support Workflows
-	// z.strictObject({
-	// 	type: z.literal("workflow"),
-	// 	worker: z.string(),
-	// 	exportName: z.string(),
-	// }),
+	WorkflowBindingSchema,
 ]);
 
 export const UnsafeBindingSchema = z.looseObject({

packages/config/src/types.ts

@@ -42,8 +42,7 @@ import type {
 	VpcServiceBinding,
 	WorkerBinding,
 	WorkerLoaderBinding,
-	// TODO: re-enable when workflow bindings return.
-	// WorkflowBinding,
+	WorkflowBinding,
 } from "./bindings";
 import type { ConfigInput } from "./definition";
 import type {
@@ -124,9 +123,8 @@ type Binding =
 	| VpcNetworkBinding
 	| VpcServiceBinding
 	| WorkerBinding
-	| WorkerLoaderBinding;
-// TODO: re-enable when workflow bindings return.
-// | WorkflowBinding;
+	| WorkerLoaderBinding
+	| WorkflowBinding;
 
 /**
  * Union of all trigger definitions accepted in `triggers`.