Workflows binding (#7012)

* start from workflows branch, squashed

* add Workflow support to `wrangler types`

* update fixture

* add (skipped) e2e test

* mark validation as TODO + remove commented code

Co-authored-by: Luís Duarte <[email protected]>

Author: RamIdeas

.changeset/green-parrots-lick.md

@@ -0,0 +1,22 @@
+---
+"wrangler": minor
+---
+
+Add support for Workflow bindings (in deployments, not yet in local dev)
+
+To bind to a workflow, add a `workflows` section in your wrangler.toml:
+
+```toml
+[[workflows]]
+binding = "WORKFLOW"
+name = "my-workflow"
+class_name = "MyDemoWorkflow"
+```
+
+and export an entrypoint (e.g. `MyDemoWorkflow`) in your script:
+
+```typescript
+import { WorkflowEntrypoint } from "cloudflare:workers";
+
+export class MyDemoWorkflow extends WorkflowEntrypoint<Env, Params> {...}
+```

fixtures/workflow/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "my-workflow",
+	"private": true,
+	"scripts": {
+		"deploy": "wrangler deploy",
+		"start": "wrangler dev --x-dev-env"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20241011.0",
+		"wrangler": "workspace:*"
+	},
+	"volta": {
+		"extends": "../../package.json"
+	}
+}

fixtures/workflow/src/index.ts

@@ -0,0 +1,50 @@
+import {
+	WorkerEntrypoint,
+	Workflow,
+	WorkflowEvent,
+	WorkflowStep,
+} from "cloudflare:workers";
+
+type Params = {
+	name: string;
+};
+export class Demo extends Workflow<{}, Params> {
+	async run(events: Array<WorkflowEvent<Params>>, step: WorkflowStep) {
+		const { timestamp, payload } = events[0];
+		const result = await step.do("First step", async function () {
+			return {
+				output: "First step result",
+			};
+		});
+
+		await step.sleep("Wait", "1 minute");
+
+		const result2 = await step.do("Second step", async function () {
+			return {
+				output: "Second step result",
+			};
+		});
+
+		return {
+			result,
+			result2,
+			timestamp,
+			payload,
+		};
+	}
+}
+
+type Env = {
+	WORKFLOW: {
+		create: (id: string) => {
+			pause: () => {};
+		};
+	};
+};
+export default class extends WorkerEntrypoint<Env> {
+	async fetch() {
+		const handle = await this.env.WORKFLOW.create(crypto.randomUUID());
+		await handle.pause();
+		return new Response();
+	}
+}

fixtures/workflow/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"target": "es2021",
+		"lib": ["es2021"],
+		"module": "es2022",
+		"types": ["@cloudflare/workers-types/experimental"],
+		"noEmit": true,
+		"isolatedModules": true,
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"skipLibCheck": true
+	}
+}

fixtures/workflow/worker-configuration.d.ts

@@ -0,0 +1,5 @@
+// Generated by Wrangler by running `wrangler types`
+
+interface Env {
+	WORKFLOW: Workflow;
+}

fixtures/workflow/wrangler.toml

@@ -0,0 +1,9 @@
+#:schema node_modules/wrangler/config-schema.json
+name = "my-workflow-demo"
+main = "src/index.ts"
+compatibility_date = "2024-10-11"
+
+[[workflows]]
+binding = "WORKFLOW"
+name = "my-workflow"
+class_name = "Demo"

packages/wrangler/e2e/dev-with-resources.test.ts

@@ -528,6 +528,47 @@ describe.sequential.each(RUNTIMES)("Bindings: $flags", ({ runtime, flags }) => {
 		await worker.readUntil(/✉️/);
 	});
 
+	// TODO: enable for remove dev once realish preview supports it
+	// TODO: enable for local dev once implemented
+	it.skip("exposes Workflow bindings", async () => {
+		await helper.seed({
+			"wrangler.toml": dedent`
+                name = "my-workflow-demo"
+                main = "src/index.ts"
+                compatibility_date = "2024-10-11"
+
+                [[workflows]]
+                binding = "WORKFLOW"
+                name = "my-workflow"
+                class_name = "Demo"
+            `,
+			"src/index.ts": dedent`
+                import { WorkflowEntrypoint } from "cloudflare:workers";
+
+                export default {
+                    async fetch(request, env, ctx) {
+                        if (env.WORKFLOW === undefined) {
+                            return new Response("env.WORKFLOW is undefined");
+                        }
+
+                        return new Response("env.WORKFLOW is available");
+                    }
+                }
+
+                export class Demo extends WorkflowEntrypoint {
+                    run() {
+                        // blank
+                    }
+                }
+            `,
+		});
+		const worker = helper.runLongLived(`wrangler dev ${flags}`);
+		const { url } = await worker.waitForReady();
+		const res = await fetch(url);
+
+		await expect(res.text()).resolves.toBe("env.WORKFLOW is available");
+	});
+
 	// TODO(soon): implement E2E tests for other bindings
 	it.todo("exposes hyperdrive bindings");
 	it.skipIf(isLocal).todo("exposes send email bindings");

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

@@ -131,6 +131,7 @@ describe("normalizeAndValidateConfig()", () => {
 			placement: undefined,
 			tail_consumers: undefined,
 			pipelines: [],
+			workflows: [],
 		});
 		expect(diagnostics.hasErrors()).toBe(false);
 		expect(diagnostics.hasWarnings()).toBe(false);

packages/wrangler/src/__tests__/navigator-user-agent.test.ts

@@ -116,6 +116,7 @@ describe("defineNavigatorUserAgent is respected", () => {
 				serveLegacyAssetsFromWorker: false,
 				mockAnalyticsEngineDatasets: [],
 				doBindings: [],
+				workflowBindings: [],
 				define: {},
 				alias: {},
 				checkFetch: false,
@@ -175,6 +176,7 @@ describe("defineNavigatorUserAgent is respected", () => {
 				moduleCollector: noopModuleCollector,
 				serveLegacyAssetsFromWorker: false,
 				doBindings: [],
+				workflowBindings: [],
 				define: {},
 				alias: {},
 				mockAnalyticsEngineDatasets: [],

packages/wrangler/src/__tests__/type-generation.test.ts

@@ -164,6 +164,7 @@ const bindingsConfigMock: Omit<
 			},
 		],
 	},
+	workflows: [],
 	r2_buckets: [
 		{
 			binding: "R2_BUCKET_BINDING",