Cloudflare Workflows
Next.js と同じプロジェクトで Cloudflare Workflows を作成し、ダッシュボードから操作します。
Cloudflare Workflows は、Arkor のプロジェクトで利用できます。事前の有効化申請は不要です。
ネイティブの WorkflowEntrypoint クラスで、永続化されるステップ、リトライ、スリープ、
イベント待機を利用できます。"use workflow" と "use step" を使う既存の
Workflow SDK 対応とは別の機能です。
クラスは Next.js と同じプロジェクトに置けます。ページ配信用 Worker とは別にビルドし、 通常のページリクエストにワークフローの検索や実行を追加しません。
登録とデプロイ
- バインディング で Cloudflare Workflow を追加し、名前を
JOBSにします。 - モジュールのパス を
src/workflows/process.ts、エクスポートするクラス をProcessWorkflowにします。パスはアプリケーションのルートからの相対パスです。 - 次のクラスを追加してデプロイします。公開が成功するまでは デプロイ待ち です。 定義の変更は、次のデプロイに反映されます。
import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from 'cloudflare:workers';
export interface Job {
name: string;
}
export class ProcessWorkflow extends WorkflowEntrypoint<{}, Job> {
async run(event: WorkflowEvent<Job>, step: WorkflowStep) {
const message = await step.do('prepare', async () => `Hello, ${event.payload.name}`);
await step.sleep('short-wait', '1 second');
const approval = await step.waitForEvent<{ approved: boolean }>('approval', {
type: 'approved',
timeout: '1 hour',
});
return { message, approved: approval.payload.approved };
}
}ネイティブ Worker、Hono、対応する SSR プロジェクトも同じ方法で登録し、Worker の環境から バインディングを参照できます。クラスは名前付きでエクスポートしてください。
Next.js から開始する
独自の名前には SDK の名前付きアクセサーを使います。入力の型だけをインポートしても、 クラスがページ配信用 Worker に含まれることはありません。
import { workflow } from '@stayingupwind/sdk';
import type { Job } from '@/workflows/process';
export async function POST(request: Request) {
const jobs = workflow<Job>('JOBS');
if (!jobs) return Response.json({ error: 'JOBS is not bound' }, { status: 503 });
const input = (await request.json()) as Job;
const instance = await jobs.create({ id: crypto.randomUUID(), params: input });
return Response.json({ id: instance.id }, { status: 202 });
}一つのバインディングには import workflow from '@stayingupwind/sdk/workflow' も使えます。
SDK は create()、get() と、インスタンスの status()、pause()、resume()、
restart()、terminate()、sendEvent() を公開します。アプリケーションの操作用ルートでは
呼び出し元を認証・認可してください。作成の応答が不明な場合は、同じ ID で再試行します。
const instance = await jobs.get(instanceId);
await instance.sendEvent({ type: 'approved', payload: { approved: true } });
const state = await instance.status();ダッシュボードと API
ワークフロー → Cloudflare Workflows で本番またはブランチ環境とバインディングを 選びます。既存の Workflow SDK は別タブにあり、従来の実行 URL も使えます。
一覧は新しい順で 50 件ずつ表示し、状態の絞り込みとページ移動ができます。詳細には状態、 時刻、入出力のプレビュー、エラー、ロールバック結果、ステップの試行を表示します。 ステップ出力は必要なときだけ取得し、プロバイダーの非表示指定を維持します。 進行中の詳細は、タブが表示されている間、5 秒ごとに更新します。
全メンバーが参照できます。オーナーと管理者は開始、一時停止、再開、最初または指定 ステップからの再実行、ロールバックを選択した終了、JSON イベント送信を行えます。 再実行は状態をリセットしますが、以前の外部への変更は戻りません。終了後は再開できません。 応答が不明な操作は、現在の状態を確認してから再試行してください。イベント送信や 再実行を繰り返すと処理が重複する場合があります。
公開 API の操作パスは
/v1/projects/{projectId}/cloudflare-workflows/environments/{environment}/{bindingId}/instances
です。Cloudflare Workflows が読み取りのトークンは参照、読み書きのトークンは操作ができます。バインディング一覧の ID と、
発行された preview:bpe_… 環境を使ってください。ブランチ名は指定できません。
分離とリソースの互換性
本番と各ブランチの実行は分離します。新しいデプロイを公開しても、既存の実行は開始時の コードとリソース割り当てを保持します。バインディングを削除すると新しい実行を 直ちに停止し、既存の実行の管理と保持は継続します。プロジェクトや支出上限の停止中は、 開始・再開・再実行・イベント送信を行えません。管理者は一時停止や終了を行えます。
ステップは this.env から認可済みリソースを参照します。スコープ付き
アダプターを使います。Durable Objects の getByName や遅延 ID による
get(idFromName(...)) は利用できますが、遅延 ID の同期的な toString() は未対応です。
ネイティブの名前空間 ID 文字列が必要なコードに、そのまま渡さないでください。
実際の ID が必要な場合は await idFromName(name).resolve() を使います。
newUniqueId() の結果を get() に渡す前には await unique.resolve() を実行してください。
異なるバインディングや jurisdiction の遅延 ID を equals() で比較する場合は、同じ名前空間を指す別名の可能性があるため、先に両方の .resolve() を実行してください。
ワークフローの CPU と接続処理の費用は、現在 Arkor が負担します。実装で利用している プロバイダーのテレメトリーからは、インスタンスごとの正確な CPU 課金量を取得できないため、 この費用をインスタンスには課金しません。ステップで使うリソースとサービスには、 従来の料金と支出上限を適用します。
最新のネイティブ API と上限は、Cloudflare の Workers API と Workflow limits を参照してください。