Michael JohnsonDurable Objectへの呼び出しがネットワーク障害で失敗したとき、これまでは再送するかどうかを開発者が判断することがよくありました。2026年11月5日からは、Cloudflareのランタイムがこうした再試行の一部を担います。fetch()やstub経由のRPC呼び出しのうち、特定の失敗を自動で再試行します。アプリケーションコードで問うべきことは、より明確になりました。つまり、特定のメソッドを2回実行しても安全かどうかです。
答えは、通信がどの時点で途切れたかによって変わります。ランタイムは、二重実行を防ぐ既定の保護を維持しながら、一部の呼び出しを自動で再試行します。リクエストが届いたかどうか分からない場合は、同じリクエストIDを使います。オブジェクトが最初の試行をすでに受け取っていれば、再試行は拒否されます。明示的にretryable()を指定したメソッドは挙動が異なり、最初の試行がオブジェクトに届いていても再実行される可能性があります。そのため、この指定は状態と副作用の両面で再実行が安全な操作に限るべきです。
ランタイムが再試行するもの
11月5日のCloudflareの発表によると、再試行の対象は、Workerまたは別のDurable Objectから行うDurable Objectへのfetch()とRPC呼び出しです。stub経由の呼び出しでは、既定で初回の試行に加えて最大4回再試行します。新たな試行は、呼び出し開始から10秒を過ぎると開始されません。
対象となるのは、.retryableの性質を持つエラーです。たとえば、オブジェクトの再起動中や移動中で、リクエストが届かなかった場合があります。また、接続が切れてオブジェクトがリクエストを受け取ったかどうか分からない場合にも、ランタイムは再試行できます。オブジェクトがすでにリクエストを受け取っていれば、同じIDでの再試行は拒否されます。Durable Objectのコードが投げたエラー、.overloadedエラー、500などのHTTPレスポンスは再試行されません。これらは配信エラーではなく、ハンドラーからの応答だからです。
リクエストの再送は、操作の再実行とは異なる
リクエストの再送は、それだけでメソッドの2回目の実行を意味するわけではありません。結果が不明な場合、ランタイムは同じIDでリクエストを送ります。オブジェクトが最初の試行を受け取っていれば、再送を拒否します。これにより、通常の動作では、1回のネットワーク障害で二重に課金したり、レコードを重複作成したりすることを防ぎます。
cloudflare:durable-objectsのretryable()でメソッドを指定すると、この境界が変わります。最初の試行がすでに始まっていた可能性があっても、オブジェクトはメソッドを再実行できます。Cloudflareは2つの例を挙げています。商品の数量を指定した値に設定するのは冪等ですが、数量を1増やすのは冪等ではありません。前者を再実行すると同じ値が設定されますが、後者ではさらに1個増えます。
確認すべきなのは、ストレージの最終状態だけではなく、メソッドが引き起こすすべての効果です。再実行によって追加の決済が発生したり、メッセージが送信されたり、外部の処理が開始されたりするなら、Durable Object内部の状態が同じになるとしても、安全な再試行とはいえません。再実行しても結果の意味が変わらず、副作用も重複しない場合に限って指定してください。
明示的な冪等性が役立つ場面
値の設定、状態のスナップショットの記録、フィールドを既知の値に更新する処理は、繰り返しても同じ結果になることがよくあります。こうしたメソッドでは、retryable()を指定することで、処理開始後に通信が途切れた場合でも呼び出しを成功させられる可能性があります。
「加算する」「もう1つ作成する」「課金する」「送信する」といった操作には、通常、別の保護策が必要です。再実行を許可する前に、業務処理が重複を認識できるか、または再実行しても効果が重複しない構造になっているかを確認してください。関数名だけでは安全性は判断できません。メソッド内の状態変更と外部への処理をすべて確認しましょう。
retryable()の役割は限定的です。最初の呼び出しが届いたかどうか分からない場合に、実行の再試行を許可します。ランタイムが対応するエラーの種類を変えたり、試行回数を増やしたりするものではありません。この指定は関数に適用されます。メソッドをオーバーライドしたりラップしたりした場合、明示的に指定しなければ、指定は自動的に引き継がれません。
既存プロジェクトで確認すべきこと
まず見直したいのは、Durable Objectsの呼び出しを囲む独自の再試行ループです。今後は各試行にランタイムの再試行が加わる可能性があるため、アプリケーション側の設定だけで想定する回数より、呼び出し回数が増えることがあります。Cloudflareは、独自の再試行回数を減らすか、コード側で再試行を管理する場合はstubにmaxRetries: 0を指定することを推奨しています。
特定のstubに対する上限は、get()またはgetByName()を呼び出すときに設定します。maxRetriesは初回の試行後に行う再試行の回数で、0回から10回まで指定できます。timeoutMsは新たな試行を開始しない期限で、500ミリ秒から60,000ミリ秒まで設定できます。これらの設定は、そのstub経由の呼び出しに適用されます。retryable()とretryオブジェクトを利用するには、Wrangler 4.158.0以降が必要です。
有効な見直し方法は、呼び出しごとに次の3点を確認することです。状態が複数回変更される可能性はあるか、外部への副作用も再実行されるか、アプリケーション独自の再試行ポリシーがあるか。そのうえで、そのstubに既定値を使うか、独自の上限を設定するかを決めます。冪等なメソッドでは明示的な指定を個別に検討し、それ以外では保護を維持し、最初の試行結果が不明な場合のエラー処理を確認してください。
変わるのは、責任の所在ではなくメソッドの境界
自動再試行により、ネットワーク処理の一部をアプリケーションコードから切り離せます。しかし、再実行が許されるかどうかは、引き続き操作の性質によって決まります。ランタイムは、リクエストの再送を安全に行い、呼び出しが実行されたか分からない場合は再実行を止められます。開発者は、状態変更や副作用が重複しないと明示的に確認したうえで、メソッドの再実行を許可できます。
したがって、この更新はトランスポート層とハンドラーの間の契約変更として捉えるべきです。まず独自の再試行ループと副作用の再実行可能性を確認し、次に必要なstubの上限を設定します。そうすれば、短時間の障害への耐性を組み込みの仕組みに任せつつ、2回目の実行に実質的なコストが伴う操作は自分で制御できます。
