Michael JohnsonWenn ein Aufruf eines Durable Objects mit einem Netzwerkfehler endete, mussten Entwickler bisher oft entscheiden, ob sie ihn erneut senden sollten. Seit dem 5. November 2026 übernimmt die Cloudflare-Laufzeitumgebung einen Teil dieser Wiederholungen: Sie wiederholt automatisch bestimmte fehlgeschlagene Aufrufe von fetch() und RPC-Aufrufe über einen Stub. Für den Anwendungscode stellt sich nun eine präzisere Frage: Kann eine bestimmte Methode sicher ein zweites Mal ausgeführt werden?
Die Antwort hängt davon ab, an welcher Stelle die Verbindung abgebrochen ist. Die Laufzeitumgebung wiederholt bestimmte Aufrufe automatisch und schützt standardmäßig vor doppelter Ausführung. Bei unklarer Zustellung verwendet sie dieselbe Anfrage-ID; das Objekt weist die Wiederholung zurück, wenn es den ersten Versuch bereits erhalten hat. Eine ausdrücklich mit retryable() gekennzeichnete Methode verhält sich anders: Sie kann erneut gestartet werden, selbst wenn der erste Versuch das Objekt bereits erreicht hat. Die Kennzeichnung eignet sich deshalb nur für Operationen, deren Wiederholung sowohl für den Zustand als auch für Nebenwirkungen sicher ist.
Was die Laufzeitumgebung genau wiederholt
Laut der Ankündigung von Cloudflare vom 5. November umfassen die Wiederholungen Aufrufe von fetch() und RPC an ein Durable Object, die von einem Worker oder einem anderen Durable Object ausgehen. Für Aufrufe über einen Stub sind standardmäßig ein erster Versuch und bis zu vier Wiederholungen vorgesehen. Neue Versuche beginnen nicht später als zehn Sekunden nach Beginn des Aufrufs.
Voraussetzung ist ein Fehler mit dem Merkmal .retryable. Beispielsweise kann eine Anfrage das Objekt möglicherweise nicht erreicht haben, weil es neu gestartet oder verschoben wurde. Die Laufzeitumgebung kann den Versuch auch wiederholen, wenn die Verbindung abbricht und unklar ist, ob das Objekt die Anfrage angenommen hat. Hat das Objekt die Anfrage bereits erhalten, wird eine Wiederholung mit derselben ID abgewiesen. Die Laufzeitumgebung wiederholt keine Fehler, die vom Code des Durable Objects ausgelöst werden, keine Fehler mit .overloaded und keine HTTP-Antworten wie 500: Das ist eine Antwort des Handlers und kein Zustellungsfehler.
Warum eine erneute Zustellung nicht dasselbe ist wie eine erneute Ausführung
Die erneute Übertragung einer Anfrage bedeutet für sich genommen nicht, dass die Methode ein zweites Mal ausgeführt wird. Bei einem unklaren Ergebnis sendet die Laufzeitumgebung die Anfrage mit derselben ID. Hat das Objekt den ursprünglichen Versuch angenommen, weist es die Wiederholung zurück. Das verhindert im Normalfall, dass eine Methode erneut ausgeführt wird – etwa dass eine Abbuchung wiederholt oder ein Datensatz wegen eines einzigen Netzwerkfehlers doppelt angelegt wird.
Diese Grenze verschiebt sich, wenn eine Methode mit retryable() aus cloudflare:durable-objects gekennzeichnet ist. Dann darf das Objekt die Methode erneut ausführen, wenn der erste Versuch möglicherweise bereits begonnen hat. Cloudflare nennt zwei Beispiele: Einem Produkt eine bestimmte Menge zuzuweisen ist idempotent; die Menge um eins zu erhöhen ist es nicht. Bei der Wiederholung der ersten Aktion wird derselbe Wert gesetzt, bei der Wiederholung der zweiten kommt eine weitere Einheit hinzu.
Zu prüfen sind nicht nur die endgültigen Speicherwerte, sondern auch alle Auswirkungen der Methode. Löst eine Wiederholung eine weitere Zahlung aus, sendet sie eine zusätzliche Nachricht oder startet sie eine externe Aktion, wird sie nicht dadurch sicher, dass der Zustand innerhalb des Durable Objects gleich bleibt. Die Kennzeichnung eignet sich, wenn die Wiederholung die Bedeutung des Ergebnisses nicht verändert und keine Nebenwirkungen dupliziert.
Wann ausdrückliche Idempotenz hilfreich ist
Das Setzen eines Werts, das Speichern eines Zustands-Snapshots oder das Aktualisieren eines Felds auf einen bekannten Wert führt bei einer Wiederholung häufig zum selben Ergebnis. Für solche Methoden kann retryable() dazu beitragen, dass ein Aufruf nach einem Verbindungsabbruch erfolgreich abgeschlossen wird, der erst nach Beginn der Verarbeitung aufgetreten ist.
Operationen wie „erhöhen“, „ein weiteres erstellen“, „abbuchen“ und „senden“ erfordern normalerweise einen anderen Schutz. Bevor Sie eine erneute Ausführung zulassen, stellen Sie sicher, dass die Geschäftsoperation Duplikate erkennt oder so gestaltet ist, dass eine Wiederholung keine zweite Wirkung auslöst. Der Funktionsname allein bietet keine Garantie: Prüfen Sie alle Zustandsänderungen und externen Aktionen innerhalb der Methode.
retryable() hat eine eng umrissene Funktion: Es erlaubt eine erneute Ausführung, wenn unklar ist, ob der erste Aufruf angekommen ist. Es ändert weder die Fehlerarten, auf die die Laufzeitumgebung reagiert, noch erhöht es die Zahl der Versuche. Die Kennzeichnung gilt für die Funktion; eine überschriebene oder umschlossene Version der Methode übernimmt sie nicht automatisch und muss ebenfalls ausdrücklich gekennzeichnet werden.
Was Sie in einem bestehenden Projekt prüfen sollten
Am ehesten sollten Sie eigene Wiederholungsschleifen rund um Aufrufe von Durable Objects überprüfen. Jeder solche Versuch kann nun Wiederholungen durch die Laufzeitumgebung einschließen, sodass die Gesamtzahl der Aufrufe höher ausfallen kann, als es die Anwendung allein vorgibt. Cloudflare empfiehlt, die Zahl eigener Versuche zu reduzieren oder für den Stub maxRetries: 0 festzulegen, wenn Ihr Code die Wiederholungen selbst steuert.
Für einen bestimmten Stub lassen sich die Grenzwerte beim Aufruf von get() oder getByName() festlegen. Der Parameter maxRetries bestimmt null bis zehn Wiederholungen nach dem ersten Versuch; timeoutMs legt das Intervall fest, nach dem keine neuen Versuche mehr gestartet werden, und kann zwischen 500 und 60.000 Millisekunden liegen. Diese Einstellungen gelten für Aufrufe über den jeweiligen Stub. Für retryable() und das Objekt retry ist Wrangler 4.158.0 oder neuer erforderlich.
Eine sinnvolle Überprüfung umfasst für jeden Aufruf drei Fragen: Kann er den Zustand mehr als einmal ändern? Wiederholt er externe Nebenwirkungen? Verwendet die Anwendung eine eigene Wiederholungsrichtlinie? Entscheiden Sie anschließend, ob der betreffende Stub die Standardwerte oder eigene Grenzwerte verwenden soll. Bei idempotenten Methoden können Sie eine ausdrückliche Kennzeichnung gesondert prüfen; bei den übrigen sollten Sie den Schutz beibehalten und die Fehlerbehandlung für den Fall kontrollieren, dass das Ergebnis des ersten Versuchs unbekannt ist.
Die Folge: Die Verantwortung verlagert sich an die Methodengrenze
Automatische Wiederholungen nehmen dem Anwendungscode einen Teil der Netzwerklogik ab. Ob eine erneute Ausführung zulässig ist, bleibt jedoch eine Eigenschaft der jeweiligen Operation. Die Laufzeitumgebung kann die Übertragung sicher wiederholen und abbrechen, wenn sie nicht weiß, ob der Aufruf ausgeführt wurde. Entwickler können eine erneute Ausführung der Methode zulassen, indem sie ausdrücklich bestätigen, dass dadurch keine Zustandsänderungen oder Nebenwirkungen dupliziert werden.
Das Update sollte daher als Änderung des Vertrags zwischen Transportebene und Handler verstanden werden. Prüfen Sie zuerst eigene Wiederholungsschleifen und die Wiederholbarkeit von Nebenwirkungen; konfigurieren Sie anschließend die Grenzwerte für die gewünschten Stubs. So lässt sich die eingebaute Widerstandsfähigkeit gegen kurze Ausfälle mit der Kontrolle über Operationen verbinden, bei denen ein zweiter Durchlauf echte Kosten verursacht.
