Vercel Workflow SDK、トークンで冪等なワークフロー起動が可能に

何が発表されたか

• 11月4日、VercelはWorkflow SDKの start() が実行の受付とフックトークンの確保をアトミックに行えるようになったと発表した。
• 任意のトークン（注文ID、請求書ID、インポートID、リクエストIDなど）が冪等キーとして機能する。1つのトークンを所有できる実行は1つだけ。
• 同一トークンでの重複 start() は HookConflictError を投げ、所有側の conflictingRunId を含む。重複呼び出しは実行にならない。
• ワークフロー側がフックを開く必要はない。開かなかった場合も実行は通常どおり完了する。
• experimental_minRetention を設定すると、start() 時点から数えて実行終了後もトークンを予約し続け、遅れて来た重複も拒否できる。
• API面では、start() のオプションに experimental_hook: { token } を渡す。重複は HookConflictError.is(error) で判定し、resumeHook(token, payload) でトークン所有側の実行にペイロードを転送できる。ワークフロー内では同じトークンで createHook<T>({ token }) を呼ぶと、起動時に確保済みのフックへバインドされ、ステップは増えず getConflict() は null になる。
• 実行が受付された時点でフックは存在するため、実行開始前の resumeHook も機能する。早着ペイロードはバッファされ順序どおり配信される。
• workflow 5.4.0 以降が必要。

開発者への影響

• ECや受注系の案件でありがちな「Webhookの再送で同じ注文の処理が二重に走る」問題を、アプリ側のロック実装なしに塞げる。決済プロバイダーや在庫連携のWebhookは再送前提なので、効果が出やすい。
• 従来は getHookByToken() で確認してから start() していたため、その間に別のリクエストが入り込む競合があった。これがSDK側で解消されたので、自前のDBロックや分散ロックを外せるケースがある。
• experimental_ プレフィックスが付いたAPIなので、本番導入時は将来のシグネチャ変更を想定した薄いラッパーを挟んでおきたい。