Cloudflare Workflows のサガロールバック機能の構築方法について

Cloudflare Workflows を利用すれば、長期実行プロセスにわたる組み込みのリトライ機能と状態永続化を備えた、耐久性のある多ステップアプリケーションを構築できます。Workflow が実行されると、各ステップは外部システムを呼び出したり、失敗をリトライしたり、再起動間での状態を保持したりできます。しかし、1 つのステップで失敗が発生すると、完了したステップからの以前の作業が不整合または不完全な状態で残ってしまう可能性があります。 本日、Workflows に対してサガロールバック機能をリリースしました。これにより、失敗時に備えて各ステップ内でロールバックロジックを宣言できるようになります。 例えば、2 つの異なる銀行間での資金送金を行うワークフローを考えてみましょう： 銀行 A の口座から引き落とし 銀行 B の口座へ入金 両口座所有者に確認メールを送信 もしステップ 2、つまり銀行 B への入金が失敗した場合どうなるでしょうか？銀行 A での引き落としが成功すると、取引は確定し、資金はそのシステムから移動してしまいます。取引のオーケストレーターとして、銀行 A のシステムで単に操作を「元に戻す」ことはできません。代わりに、最初の操作を意味的に逆転させる新しい操作を通じて、資金を銀行 A の口座へ戻す必要があります。 ![image](https://cf-assets.www.cloudflare.com/zkvhlag99gkb/1j8xfDeKb3FCgE2Ktxf4fq/723e2b9e34189747d3c8eb65f906fb41/BLOG-3317_image6.png) この操作とその補償ロジックの組み合わせは、サガパターン（saga pattern）と呼ばれます。 今日まで、開発者は成功したものと失敗したもの、そして失敗時にどのアクションを取るべきかを追跡するために、ステップの直接定義の外側で独自の補償ロジックを実装する必要がありました。今では、各ステップに対して補償ロジックを定義できるようになりました。do() をステップ内の引数として使用することで、ロールバック時のワークフローの耐久性も維持できます。 // 何完了したか追跡して、何を元に戻すべきか知る let debitA; let creditB; try { debitA = await step.do("debit-bank-a", () => bankA.debit(from, amount)); creditB = await step.do("credit-bank-b", () => bankB.credit(to, amount)); await step.do("notify", () => notifyBoth(from, to, amount)); } catch (error) { // 逆順で元に戻す。各元に戻す操作はそれ自体が耐久性を持つステップであり、 // 冪等性を持たねばならず、一つでも失敗しても続行する必要がある。 if (creditB) { try { await step.do("reverse-credit-b", () => bankA.debit(to, amount, creditB.id)); } catch (e) { await alertOnCall("reverse-credit-b failed", e); } } if (debitA) { try { await step.do("refund-debit-a", () => bankA.credit(from, amount, debitA.id)); } catch (e) { await alertOnCall("refund-debit-a failed", e); } } throw error; } ロールバックなし // 各ステップには独自の元に戻す機能が備わっています。ステップを追加する際は、そのロールバックもここに追加してください。キャッチブロックの肥大化も、手動での順序付けも、再生ロジックも不要です。 await step.do("debit-bank-a", () => bankA.debit(from, amount), { rollback: async ({ output }) => bankA.credit(from, amount, output.id), }); await step.do("credit-bank-b", () => bankB.credit(to, amount), { rollback: async ({ output }) => bankB.debit(to, amount, output.id), }); await step.do("notify", () => notifyBoth(from, to, amount)); With rollbacks Try it out ロールバックを使用するには、step.do() の最後の引数として、ロールバック関数を含むオプションオブジェクトを渡すだけです。 const debit = await step.do( "debit-account-a", async () => { return await bankA.debit({ accountId: fromAccountId, amount, idempotencyKey: `${transferId}:debit-account-a`, }); }, { rollback: async () => { await bankA.credit({ accountId: fromAccountId, amount, idempotencyKey: `${transferId}:rollback-debit-account-a`, }); }, } ); // 二重実行防止キー（idempotency keys）により、転送を重複させることなく、前方操作とロールバック操作の両方を安全に再試行できます const credit = await step.do( "credit-account-b", async () => { return await bankB.credit({ accountId: toAccountId, amount, idempotencyKey: `${transferId}:credit-account-b`, }); }, { rollback: async ({ output }) => { if (output === undefined) { return; } await bankB.debit({ accountId: toAccountId, amount, idempotencyKey: `${transferId}:rollback-credit-account-b`, }); }, } ); // If we fail here, we may want to revert all previous payments. Users should not have to wrap their code in complex try-catch logic just to revert two small payments (see below) await step.do("send-confirmation", async () => { await sendTransferConfirmation({ ... }); }); Rollback functions should be idempotent, just like regular Workflow steps. If you refund a charge, use the payment provider's idempotency key. If you release inventory, make the release safe to call more than once. If any step fails, the rollback handlers will execute in reverse step-start order. It sounds simple: run the undo steps when something fails. In practice, there are a few details that make the API and execution model important. 1. The failed step may still need rollback. A failed step.do() can still be rollback-eligible if it registered a rollback handler. ロールバックは、ユーザーコードがエラーを捕捉してワークフローが継続する場合は開始されませんが、ステップエラーが捕捉された後にワークフローが別の理由で失敗した場合でも、以前に登録されたハンドラーに対してロールバックを実行できます。これらは、ステップ開始の逆順で実行されます。 なぜでしょうか？ステップは失敗する前に外部システムと部分的に相互作用している可能性があります。例えば、支払いプロバイダーが課金をキャプチャしたとしても、chargeId をワークフローに返す前にステップが失敗することがあります。そのため、ロールバックハンドラーには出力が渡されますが、出力が undefined の場合も処理できるようにする必要があります。 2. ロールバックは、ワークフローが失敗した場合のみ開始されます。ロールバックハンドラーを追加しても、すべてのステップエラーがロールバックを引き起こすわけではありません。ユーザーコードがエラーを捕捉して継続する場合、ワークフローは継続します。ロールバックは、ワークフロー自体が最終的に失敗しようとするときに開始されます。 ロールバックが開始されると、ワークフローは対象となる step.do() 呼び出しを検索し、それらのロールバックハンドラーを実行した後、最終的なワークフローの失敗を記録します。 3. 順序は予測可能でなければなりません。順次実行されるワークフローの場合、ロールバックの順序は明白に感じられます： 在庫を予約する。 カードを課金する。 出荷を作成する。 もし出荷作成が失敗した場合、カードへの返金を行い、在庫を解放します。 並列ステップではこの状況はより複雑になります。完了順序が始動順序と異なる可能性があるため、ワークフローは逆順の完了順序ではなく、逆順の開始順序を使用します。 実用的なルールは以下の通りです： ロールバックハンドラーを持つ開始済みまたは完了済みのすべてのステップが対象となります。 ロールバックハンドラーを登録している失敗した step.do() も対象となります。 ハンドラーは完了順ではなく、逆のステップ開始順序で実行されます。 API の設計方法について 期待する動作を把握した上で、この新しいパターンを Workflows API に追加する必要がありました。ロールバック機能については、最終的な「ロールバックオプション」にたどり着くまでにいくつかの試行錯誤が行われました。 なぜフラuent またはビルダー API ではないのか？ 最初のアプローチは fluent フォームでした：step.do(...).rollback(...) これは読みやすく、前方アクションと補償処理が隣り合わせに配置され、呼び出し箇所も通常の JavaScript のチェーンのように見えます。 問題は、step.do() がすでに重要な意味を持っていることです。これは永続的なステップを開始し、そのステップの出力に対する Promise を返します。Workers においては、Promise に似た値は特に重要であり、これは Cap'n Proto などのシステムから継承されたパターンである「プロミス・パイプライン」をサポートする Workers RPC のためです。 プロミス・パイプラインにより、コードは値が呼び出し元に完全に返される前に、その将来の値に対してメソッドを呼び出すことができます。例えば： const session = api.authenticate(apiKey); const name = await session.whoami(); ここで、session はまだ実際のセッションオブジェクトではありません。これはまもなく存在するセッションへのハンドルのようなものです。session.whoami() を呼び出すと、Workers はその呼び出しをリモート側に早期に送信し、「認証によってセッションが作成されたら、その上で whoami() を呼び出してください」と伝えることができます。 これにより往復通信が不要になります。呼び出し元は、whoami() を要求する前に authenticate() が完全に完了するまで待つ必要はありません。 私たちは流暢な API（fluent API）も検討しました： step.do("charge-card", chargeCard).rollback(refundCharge); 読者にとっては、「charge-card の結果に対して .rollback() を呼び出す」ように見えるかもしれません。しかし、rollback はステップの出力の一部ではありません。これはステップ開始前に登録される step.do() オプションの一部であり、後続のステップで失敗した場合にワークフローがそのステップを補償する方法を知るためです。 流暢な API では、ステップの実行タイミングを推論することが難しくなります。現在のところ、step.do() は呼び出された瞬間にステップを開始するため、開発者はステップを開始して他の処理を行い、後から最初のステップの完了を待機できます： const first = step.do("first", () => serviceA.call()); await step.do("second", () => serviceB.call()); await first; 現在の実行モデルでは、first は second よりも前に即座に開始されます。流暢な API を採用するとこれが複雑化します。ワークフローは、完全なステップ定義がわかるまで .rollback() が付与されるかどうかを待機する必要があり、その結果、エンジンへのステップ送信が遅れる可能性があります。 前述の例では、first は step.do("first", ...) の呼び出し時ではなく、await first 時点で開始され、second が既に完了した後に実行されます。 これにより、並行して実行されるワークフローの推論がより困難になります。ステップのタイミングは、step.do() が呼び出された場所だけでなく、返された Promise がいつ消費されるかにも依存することになるからです。 私たちはビルダー型 API も検討しました: const charge = await step .saga("charge") .do(() => chargeCard()) .rollback(() => refundCharge()) .run(); ビルダー API は Promise の曖昧さを回避します。また、将来のステップレベルでのオプションを追加するための明確な場所を提供し、フォワードアクションとロールバックアクションが同じサージステップに属していることを明確に示します。 しかし、これには儀式（形式）が増えるという欠点があります。すべてのステップで最終的に .run() が必要となり、.run() を忘れるのは容易であり、ツールがないと見つけるのが困難です。また、単純なワンステップケースが設定チェーンのように見え始めてしまいます。さらに、既存の step. パターンから逸脱する新しい step.saga() ビルダーを導入することになります。最も重要なのは、step.do() が古い API のように感じられ、ワークフローの主要なプリミティブではなくなってしまう点です。ロールバックの目的は、step.do() を置き換えるのではなく拡張することでした。 ステップメタデータとしてのロールバック step.do(..., { rollback }) 最終的に、ロールバックをステップのメタデータとする明示的な形式を採用しました。 このように、各ロールバックはフォワードステップ自体の中で定義されます。各ハンドラーは、ロールバック開始の原因となったエラー、ステップコンテキスト、および出力を受け取ります。出力とは、フォワードステップによって返された永続化値（未定義の場合あり）か、または値を永続化する前にステップが失敗した場合は未定義です。 ロールバックはライフサイクルイベントを発行するため、補償処理の開始、どのロールバックハンドラーが失敗したか、そしてロールバックが正常に完了したかどうかを確認できます。 重要なのは、元のワークフローの失敗は分離されたまま維持される点です。ロールバックは、失敗後にワークフローが行う処理であり、ワークフローが失敗した理由そのものではありません。 ステップ設定を通じて WorkflowStepConfig でカスタムのリトライおよびタイムアウト動作を定義できるのと同様に、rollbackConfig 内でロールバック固有の値を追加できます。 { rollback: async ({ output }) => { await bankA.credit({ accountId: fromAccountId, amount, transferId: `${transferId}-reversal` }); }, rollbackConfig: { retries: { limit: 10, delay: '30 seconds', backoff: 'exponential' }, timeout: '2 minutes', }, } これは、私たちが目指したライフサイクルイベントのメンタルモデルに合致しています。step.do() はすでに、ワークフローが記録し、リトライし、後でログに表示する永続的な作業単位を記述します。ロールバックは、同じ作業単位に対する別のライフサイクル動作です。これは別々のラッパーやビルダーに存在するのではなく、ステップ定義と一緒に移動すべきものです。 ステップは、step.do() が通常開始されるタイミングで依然として開始されます。 返されたプロミスは依然としてステップの出力を表します。 並行ワークフローコードは、同じ実行モデルを維持します。 ロールバックのリトライおよびタイムアウトオプションは、ロールバックハンドラーの隣に配置されます。 既存の step.do() 呼び出しは、今日と同じように正確に動作し続けます。 この形状は、流暢な API よりもやや明示的ですが、その明示性は有用です。操作とその補償は依然として一つの場所にあり、API は新しいステップビルダーや新しい種類のプロミスを導入しません。すでに step.do() を理解している開発者にとって、学ぶべきは追加のオプションオブジェクトのみです。 これは魔法のようなものではありませんが、採用が容易で、理解も明確です。 内部での仕組み ロールバックは小さな API の追加のように思えますが、ワークフローが各ステップについて記録する内容を変化させます。 通常の step.do() はすでに永続的な記録を持っています。ワークフローは、そのステップが開始されたか、完了したか、何を返したか、そして後でワークフローが再開された場合に繰り返し実行するのではなくスキップすべきかを記録します。 ロールバックはこの記録にさらに一つの要素を加えます：そのステップが補償ロジックを登録したかどうかです。 これは、ワークフローが失敗した場合に、ワークフローが二つの情報を統合しなければならないことを意味します。 第一は永続的なステップ履歴です。ワークフローエンジンは、何を実行したか、何が完了したか、どのような出力が保存されたか、そしてロールバックが登録されたかどうかを知るためにデータを保存します。 2 つ目はロールバックハンドラーそのもので、これはそのステップを補償するために記述された関数です。Workflows はこの関数のテキストデータを保存するのではなく、Workflow が実行されている間、ハンドラーへの呼び出し可能な参照を保持します。 Workers RPC では、このような呼び出し可能な参照はスタブと呼ばれます。スタブにより、システムの一方の部分がどこかで実行中のコードを呼び出すことが可能になります。また、スタブにはライフタイムがあり、呼び出しや実行コンテキストが終了した際に破棄されます。この時点以降もスタブを保持する必要がある場合、Workers RPC は dup() メソッドを提供しており、これにより同じターゲットへの別のハンドルを作成できます。 ロールバックにおいては、このモデルが有用です。永続的なステップ履歴は、何を補償すべきかを記録します。ロールバックスタブは Workflows に対して、補償コードを呼び出す手段を与えます。さらに、ロールバックハンドラーはそれらを登録した即座の step.do() 呼び出しよりも長く存続する必要がある場合があるため、Workflows はロールバックフェーズのためにハンドラー自体への独自の呼び出し可能な参照を保持します。 一般的なケースでは、Workflow が同じエンジンライフタイム内でロールバックに入る場合、Workflows はすでに必要なロールバックスタブを持っています。永続的なステップ履歴を使用して対象となるステップを見つけ、前方実行中に登録されたロールバックスタブを呼び出すことができます。 しかし、Workflows が再起動後に回復しなければならない場合は、この状況はより微妙になります。 エンジンがロールバックが必要な際に退去、クラッシュ、または再起動した場合でも、Workflows は永続的なステップ履歴を保持していますが、メモリ上のロールバック用スタブは失われている可能性があります。回復のために Workflows は再生（replay）を使用します。これは完了した前方ステップ本体を実行し直すことなく Workflow コードを再実行できる回復モードです。 再生が完了した step.do() に到達すると、Workflows はステップ本体を再度実行するのではなく、永続化された結果を読み取ります。ロールバック回復のためには、Workflows はロールバックが紐付けられておりロールバック対象となるステップに対してのみハンドラを再構築すれば十分です。これらの step.do() 呼び出しに遭遇する際、そのロールバックオプションは呼び出し可能なスタブを再度登録できます。 これにより、Workflows は元の外部副作用を重複させることなく必要なロールバックハンドラを回復できます。 ![image](https://cf-assets.www.cloudflare.com/zkvhlag99gkb/6F0SOtk10x2op5YxnKKnXM/54f7e763f4ada07e353e8bcac5549833/BLOG-3317_image5.png) これらの要素が整っていれば、ハンドラがメモリ上にまだ存在する場合でも、回復時に再構築が必要な場合でも、ロールバックは機能します。 ワークフローが失敗しようとする際、Workflows はアプリケーションに対して何が起きたかを再構築するよう求めません。すでにステップ履歴を保持しているからです。永続化された記録を確認し、重要な問いに答えることができます： どのステップが始まったか？ どのステップが完了したか？ 失敗したステップのうち、まだクリーンアップが必要なものはどれか？ どのステップがロールバックハンドラを登録したか？ 各ロールバックハンドラに渡すべき出力は何か？ 補償処理はどのような順序で実行すべきでしょうか？ その後、Workflows は各ロールバックスタブをロールバックコンテキスト（元のエラー、ステップのコンテキスト、および永続化された場合のステップ出力）と共に呼び出します。 この順序の詳細が重要です。通常の JavaScript、特に Promise.all() を使用する場合、完了順序は開始順序と必ずしも一致しません。ステップ A が最初に開始され、ステップ B が2番目に開始されたとしても、ステップ B が先に完了する可能性があります。ロールバックにおいては、Workflows は永続化された開始順序を安定した真実の源として用い、それを逆順で巻き戻します。 ロールバックハンドラもまた、Workflows の通常のステップ処理機構を通じて実行されます。つまり、補償処理には Workflows から期待される同じ運用特性が適用されます：リトライ、タイムアウト、ライフサイクルイベント、ログ、そして最終的に記録された結果です。もしロールバックハンドラが設定されたリトライ回数を超えても失敗し続ける場合、Workflows はロールバックの結果を「失敗」として記録し、残りのロールバックハンドラの実行を停止します。その結果、Workflow インスタンスは最終的に Errored 状態で終了します。 これがサガロールバックと catch ブロックの主な違いです。catch ブロックが把握できるのは、JavaScript 実行のその時点でのメモリ上に存在するものだけです。一方、Workflows のロールバックは永続化されたステップ履歴を用いて何が既に発生したかを判断し、一般的なケースではすでに用意されているスタブを呼び出し、回復時に必要な場合に不足しているスタブを安全に再構築します。 そのため、API はロールバックを step.do() 自体に配置しています。ロールバックは独立したグローバルエラーハンドラーではなく、Workflows がすでに理解している作業の永続単位に付随するメタデータです。 What's next ロールバックの最初のイテレーションには以下が含まれます: step.do() 用の明示的なステップ別ロールバックハンドラー 順次実行されるロールバック 補償のためのリトライおよびタイムアウト設定 次に、以下の探索を進めたいと考えています: waitForEvent に対するロールバックサポート 並列ロールバック実行のサポート Python Workflows に対するロールバックサポート 多ステップアプリケーションが途中で失敗した場合、最も難しい部分は、失敗したことに気づかないことではなく、すでに何が行われたか、そして次に何をすべきかを把握することです。 Saga ロールバックを使用すれば、その答えを各ステップのすぐそばに配置できます。Workflows で多ステップアプリケーションを構築している場合は、saga ロールバックを試していただき、次に必要な補償パターンについてご意見をお聞かせください。Workflows のドキュメントで始め、Cloudflare コミュニティフィードバックをご共有ください。

Cloudflare Workflows のサガロールバック機能の構築方法について

背景や根拠まで確認しますか？

このニュースを、実務の判断につなげる

調べる

選ぶ

サイト