Workflows — 耐久性のある多段処理

データ取得 → 20 秒待機 → 加工、という 3 段の Workflow を作り、ローカルで起動して status の変化を観察します。所要時間は 15 分程度です。

1. Worker プロジェクトを作成します。質問には「Hello World example」「Worker only」「TypeScript」、デプロイは「No」を選びます。

   npm create cloudflare@latest -- my-workflow
   cd my-workflow

2. src/workflow.ts を新規作成し、Workflow 本体を定義します。

   import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
   import type { WorkflowEvent } from "cloudflare:workers";
   
   type Params = { name?: string };
   type IPResponse = { result: { ipv4_cidrs: string[] } };
   
   export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
   	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
   		const data = await step.do("fetch data", async () => {
   			const response = await fetch(
   				"https://api.cloudflare.com/client/v4/ips",
   			);
   			return await response.json<IPResponse>();
   		});
   
   		await step.sleep("pause", "20 seconds");
   
   		const result = await step.do(
   			"process data",
   			{ retries: { limit: 3, delay: "5 seconds", backoff: "linear" } },
   			async () => {
   				return {
   					name: event.payload.name ?? "World",
   					ipCount: data.result.ipv4_cidrs.length,
   				};
   			},
   		);
   		return result;
   	}
   }

3. wrangler.jsonc に workflows 設定を追加します。class_name はエクスポートしたクラス名、binding はコードから参照する変数名です。

   {
   	"$schema": "node_modules/wrangler/config-schema.json",
   	"name": "my-workflow",
   	"main": "src/index.ts",
   	"compatibility_date": "2026-08-10",
   	"observability": { "enabled": true },
   	"workflows": [
   		{
   			"name": "my-workflow",
   			"binding": "MY_WORKFLOW",
   			"class_name": "MyWorkflow"
   		}
   	]
   }

4. src/index.ts を、instance の作成と status 照会を行う fetch ハンドラに置き換えます。

   export { MyWorkflow } from "./workflow";
   
   export default {
   	async fetch(request: Request, env: Env): Promise<Response> {
   		const url = new URL(request.url);
   		const instanceId = url.searchParams.get("instanceId");
   		if (instanceId) {
   			const instance = await env.MY_WORKFLOW.get(instanceId);
   			return Response.json(await instance.status());
   		}
   		const instance = await env.MY_WORKFLOW.create();
   		return Response.json({ instanceId: instance.id });
   	},
   } satisfies ExportedHandler<Env>;

5. バインディングの型を生成してから、ローカル開発サーバーを起動します。

   npx wrangler types
   npx wrangler dev

6. 別ターミナルから instance を作成し、返ってきた ID で status を数回確認します。

   curl http://localhost:8787
   # {"instanceId":"abc-123-def"}
   
   curl "http://localhost:8787?instanceId=abc-123-def"
   # {"status":"running", ...}

sleep の 20 秒が明けると status が complete になり、output に process data step の戻り値（name と ipCount）が入っていれば成功です。

最初の 2 回はわざと失敗し 3 回目で成功する step を追加して、Workflows が自動リトライする様子を wrangler workflows instances describe で観測します。所要時間は 10 分程度です。

1. src/workflow.ts の step.sleep の直後（process data の前）に、失敗する step を追加します。コールバックの第 1 引数 ctx（WorkflowStepContext）の attempt には現在の試行回数（1 始まり）が入ります。

   const flaky = await step.do(
   	"flaky step",
   	{ retries: { limit: 3, delay: "3 seconds", backoff: "constant" } },
   	async (ctx) => {
   		if (ctx.attempt < 3) {
   			throw new Error(`attempt ${ctx.attempt} failed on purpose`);
   		}
   		return { succeededOnAttempt: ctx.attempt };
   	},
   );

2. wrangler dev が再読み込みされたら、curl http://localhost:8787 で新しい instance を作成します。
3. 20 秒の sleep が明けた頃に、別ターミナルから最新 instance の詳細を表示します。

   npx wrangler workflows instances describe my-workflow latest --local

出力には step ごとの成否・リトライ・エラーが並びます。flaky step の欄で「1・2 回目の試行が attempt N failed on purpose というエラーで失敗し、約 3 秒間隔をおいた 3 回目で成功している」こと、そして先行する fetch data は再実行されていないことを確認してください。これが「最後に成功した step から再開する」durable execution の動きです。ちなみにこのエラーが NonRetryableError だった場合はリトライされず、instance は即座に errored になります。

Workflow を外部イベント（人間の承認）が届くまで待機させ、CLI からイベントを送って再開させます。所要時間は 10 分程度です。

1. src/workflow.ts の return result; の直前に、承認待ちの step を追加します。

   let approved = false;
   try {
   	const approval = await step.waitForEvent(
   		"wait for approval",
   		{ type: "approval", timeout: "15 minutes" },
   	);
   	// sendEvent で送られた payload が approval.payload に入る
   	approved = (approval.payload as { approved?: boolean }).approved === true;
   } catch (e) {
   	// タイムアウト: 承認が来なかった場合もここで拾って続行できる
   	approved = false;
   }

2. curl http://localhost:8787 で新しい instance を作成し、20 秒の sleep とリトライが終わった頃に status を確認します。イベント待ちに入った instance は waiting になります。
3. 別ターミナルから、waitForEvent の type と一致する --type approval でイベントを送信します（<INSTANCE_ID> は手順 2 の ID に置き換えます。latest でも指定できます）。

   npx wrangler workflows instances send-event my-workflow <INSTANCE_ID> \
     --type approval --payload '{"approved":true}' --local

4. 再度 status を確認し、complete になっていれば成功です。

Worker のコードからは instance.sendEvent({ type: "approval", payload }) で同じことができ、Stripe などの Webhook を受けて Workflow を進める構成が組めます。なお、instance が作成済みであれば waitForEvent に到達する前に届いたイベントもバッファされ、対応する step に到達した時点で消費されます。