Cloudflare voegt retries voor Durable Objects toe — en weegt de kosten van fouten af

Als een aanroep van een Durable Object eindigde door een netwerkfout, moesten ontwikkelaars vroeger vaak zelf beslissen of ze de aanroep opnieuw moesten versturen. Sinds 5 november 2026 voert de Cloudflare-runtime een deel van die retries uit: hij probeert bepaalde mislukte aanroepen van fetch() en RPC via een stub automatisch opnieuw. Voor applicatiecode is de kernvraag nu specifieker: kan een bepaalde methode veilig een tweede keer worden uitgevoerd?

Het antwoord hangt af van het punt waarop de verbinding wegviel. De runtime probeert sommige aanroepen automatisch opnieuw, terwijl dubbele uitvoering standaard wordt voorkomen. Bij onzekere aflevering gebruikt de runtime dezelfde aanvraag-ID; het object wijst de retry af als het de eerste poging al heeft ontvangen. Een expliciet als retryable() gemarkeerde methode gedraagt zich anders: die kan opnieuw worden uitgevoerd, zelfs als de eerste poging het object al heeft bereikt. Markeer een methode daarom alleen zo als de bewerking veilig kan worden herhaald, zowel voor de toestand als voor neveneffecten.

Wat de runtime precies opnieuw probeert

Volgens de aankondiging van Cloudflare van 5 november gelden retries voor aanroepen van fetch() en RPC naar een Durable Object vanuit een Worker of een ander Durable Object. Voor aanroepen via een stub zijn standaard een eerste poging en maximaal vier retries ingesteld. Na het begin van de aanroep starten er niet later dan tien seconden nieuwe pogingen.

De voorwaarde is een fout met de aanduiding .retryable. Een verzoek heeft het object bijvoorbeeld mogelijk niet bereikt omdat het opnieuw werd gestart of verplaatst. De runtime kan ook een nieuwe poging doen als de verbinding wegviel en niet duidelijk is of het object het verzoek heeft ontvangen. Heeft het object het verzoek al ontvangen, dan wordt de retry met dezelfde ID afgewezen. De runtime probeert geen fouten opnieuw die door de code van het Durable Object zijn gegenereerd, fouten met .overloaded of HTTP-antwoorden zoals 500: dat is een antwoord van de handler, geen afleverfout.

Waarom een retry voor aflevering niet hetzelfde is als een bewerking opnieuw uitvoeren

Een verzoek opnieuw verzenden betekent op zichzelf niet dat de methode een tweede keer wordt uitgevoerd. Bij een onzeker resultaat verstuurt de runtime het verzoek met dezelfde ID; als het object de eerste poging heeft ontvangen, wijst het de retry af. Zo wordt voorkomen dat een methode in de normale modus opnieuw wordt uitgevoerd, bijvoorbeeld dat een betaling nogmaals wordt afgeschreven of dat door één netwerkfout een tweede record wordt aangemaakt.

Die grens verschuift wanneer een methode is gemarkeerd met retryable() uit cloudflare:durable-objects. Het object mag de methode dan opnieuw uitvoeren als de eerste poging mogelijk al is begonnen. Cloudflare noemt twee voorbeelden: een product op een opgegeven aantal instellen is idempotent; het aantal met één verhogen niet. Bij herhaling van de eerste handeling wordt dezelfde waarde ingesteld, terwijl de tweede handeling er nog een eenheid bij optelt.

Controleer niet alleen de uiteindelijke toestand van de opslag, maar ook alle effecten van de methode. Als een retry een extra betaling aanmaakt, een bericht verstuurt of een externe actie start, maakt een identieke toestand binnen het Durable Object de retry niet veilig. Markeer een methode alleen als herhaling de betekenis van het resultaat niet verandert en geen neveneffecten dupliceert.

Wanneer expliciete idempotentie nuttig is

Een waarde instellen, een momentopname van de toestand opslaan of een veld op een bekende waarde zetten levert vaak bij herhaling hetzelfde resultaat op. Voor zulke methoden kan retryable() ervoor zorgen dat een aanroep alsnog slaagt na een verbroken verbinding die pas optrad nadat de verwerking was begonnen.

Voor bewerkingen als ‘verhogen’, ‘nog een aanmaken’, ‘afschrijven’ en ‘versturen’ is doorgaans een andere bescherming nodig. Controleer voordat je een nieuwe uitvoering toestaat of de bedrijfsbewerking duplicaten herkent of zo is ingericht dat herhaling geen tweede effect veroorzaakt. De functienaam biedt geen garantie: controleer alle toestandswijzigingen en externe acties in de methode.

retryable() heeft een beperkte functie: het staat toe een methode opnieuw uit te voeren wanneer niet kan worden vastgesteld of de eerste aanroep het object heeft bereikt. Het verandert niet welke fouten de runtime opnieuw probeert en verhoogt het aantal pogingen niet. De markering geldt voor de functie; een overschreven of ingepakte versie van een methode erft die niet automatisch en moet zelf ook expliciet worden gemarkeerd.

Wat je in een bestaand project moet controleren

De meest voor de hand liggende plek voor een controle zijn eigen retry-lussen rond aanroepen van Durable Objects. Elke poging kan nu ook retries van de runtime omvatten, waardoor het totale aantal aanroepen hoger kan uitvallen dan alleen de applicatie instelt. Cloudflare raadt aan het aantal eigen pogingen te verlagen of maxRetries: 0 voor de stub in te stellen als je code zelf de retries beheert.

Je stelt limieten voor een specifieke stub in bij de aanroep van get() of getByName(). De parameter maxRetries bepaalt nul tot tien retries na de eerste poging; timeoutMs bepaalt de periode waarna geen nieuwe pogingen meer starten, van 500 tot 60.000 milliseconden. Deze instellingen gelden voor aanroepen via die stub. Voor retryable() en het object retry is Wrangler 4.158.0 of hoger vereist.

Een nuttige controle begint met drie vragen voor elke aanroep: kan die de toestand meer dan één keer wijzigen? Herhaalt die externe neveneffecten? Heeft de applicatie een eigen retrybeleid? Bepaal vervolgens of de betreffende stub de standaardwaarden of eigen limieten moet gebruiken. Voor idempotente methoden kun je afzonderlijk overwegen een expliciete markering toe te voegen; laat bij andere methoden de bescherming staan en controleer hoe fouten worden afgehandeld wanneer het resultaat van de eerste poging onbekend is.

Gevolg: de verantwoordelijkheid verschuift naar de methodegrens

Automatische retries halen een deel van de netwerklogica uit applicatiecode, maar de beslissing of een methode opnieuw mag worden uitgevoerd blijft bij de bewerking zelf liggen. De runtime kan het verzoek veilig opnieuw verzenden en stoppen als niet duidelijk is of de aanroep al is uitgevoerd. De ontwikkelaar kan een methode opnieuw laten uitvoeren door expliciet te bevestigen dat dit geen dubbele toestandswijzigingen of neveneffecten veroorzaakt.

Lees deze update daarom als een wijziging van het contract tussen de transportlaag en de handler. Controleer eerst eigen retry-lussen en de herhaalbaarheid van neveneffecten; stel daarna limieten in voor de benodigde stubs. Zo combineer je ingebouwde veerkracht tegen korte storingen met controle over bewerkingen waarbij een tweede uitvoering echte kosten met zich meebrengt.