rust-idempotent-workflows

Rust の冪等なワークフロー

クライアントが再試行し、ワーカーがクラッシュし、リクエストが競合し、外部の副作用をロールバックできない場合に、Rust のワークフローの信頼性を高めるためにこのスキルを使用します。

コアワークフロー

1. コードを書く前に、障害発生時のシナリオを書き出します。データベースへの各書き込み後、および外部の副作用が発生した後にプロセスがクラッシュした場合に何が起きるかを列挙します。
2. 冪等性の境界を特定します。HTTP エンドポイント、コマンドハンドラー、キュージョブ、Webhook、外部コールバックなどです。
3. 冪等性の戦略を選択します。
   • 一意のビジネスキーによる自然な冪等性。
   • クライアントが指定する冪等性キーと保存して再送する方式。
   • サーバーが生成する重複排除キー。
   • 副作用のためのアウトボックスまたはキューテーブル。
4. 状態遷移と冪等性レコードの整合性を保つ必要がある場合は、同じトランザクションに含めます。
5. 同時に発生する重複リクエストの処理を予測可能にします。一意制約、ロック、シリアライズ可能トランザクション、または明示的な競合処理を使用します。
6. プロバイダーがそれ以上の保証をしていない限り、外部の副作用は少なくとも 1 回実行されるものとして扱います。再試行または照合に必要な状態を十分に保存します。
7. 重複リクエスト、タイムアウト後の再試行、同時リクエスト、可能であればクラッシュが起きるタイミング、ワーカーの再試行動作をテストに追加します。

冪等性キーのルール

冪等性キーまたは保存して再送する方式を追加する前に、references/idempotency.md を読みます。

• キーを認証済みユーザーまたはテナントに紐付けます。
• レスポンスを再送する場合は、リクエストペイロードのハッシュを保存します。
• 完全に同一の再送には、元のレスポンスを返します。
• 同じキーを異なるペイロードで再利用した場合は拒否します。
• プロダクトとプロバイダーの再試行期間が過ぎてからのみ、レコードを期限切れにします。

バックグラウンド処理のルール

キューテーブル、ポーリングワーカー、再試行、または外部の副作用を追加する場合は、references/background-workers.md を読みます。

• 外部への副作用を送信する前に、永続化される処理意図をコミットします。
• pending、in_progress、succeeded、failed の状態を意図的に使い分けます。
• 再試行回数、次回試行のタイムスタンプ、直近のエラー概要を保持します。
• 複数のプロセスで実行しても安全なワーカーにします。

並行処理のルール

重複リクエスト、ロック、分離レベル、一意制約が修正に関係する場合は、references/concurrency.md を読みます。

複数のアプリインスタンスが同じワークフローを処理する可能性がある場合、重複排除の信頼できる情報源としてデータベースを使用します。

参考ファイル

• references/idempotency.md：冪等性キー、保存して再送する方式、リクエストペイロードの紐付け。
• references/background-workers.md：キューテーブル、ワーカーループ、再試行の境界、アウトボックスの動作。
• references/concurrency.md：ロックの選択肢、トランザクション分離、重複リクエストのテスト。