Cloudflare ajoute des tentatives pour Durable Objects et distingue les coûts d’une erreur

Lorsqu’un appel à un Durable Object échouait à cause d’un problème réseau, les développeurs devaient souvent décider s’il fallait le renvoyer. Depuis le 5 novembre 2026, le runtime Cloudflare prend en charge une partie de ces tentatives : il réessaie automatiquement certains appels fetch() et RPC via un stub. Pour le code applicatif, la question est désormais plus précise : une méthode donnée peut-elle être exécutée une seconde fois sans risque ?

La réponse dépend de l’endroit où la connexion a été interrompue. Le runtime réessaie automatiquement certains appels tout en empêchant par défaut les doubles exécutions. En cas d’incertitude sur la livraison, il réutilise le même identifiant de requête, et l’objet rejette la nouvelle tentative s’il a déjà reçu la première. Une méthode explicitement marquée avec retryable() suit un autre comportement : elle peut être relancée, même si la première tentative est déjà parvenue à l’objet. Cette annotation ne convient donc qu’aux opérations qui peuvent être répétées sans risque pour l’état ni pour les effets de bord.

Ce que le runtime réessaie exactement

D’après l’annonce de Cloudflare du 5 novembre, les tentatives concernent les appels fetch() et RPC vers un Durable Object, effectués par un Worker ou un autre Durable Object. Pour les appels via un stub, les valeurs par défaut prévoient une première tentative et jusqu’à quatre nouvelles tentatives ; aucune nouvelle tentative ne commence plus de 10 secondes après le début de l’appel.

La condition est une erreur portant l’indicateur .retryable. Par exemple, la requête peut ne pas avoir atteint l’objet parce que celui-ci redémarrait ou était déplacé. Le runtime peut également réessayer si la connexion est interrompue et qu’il est impossible de savoir si l’objet a reçu la requête. Si l’objet l’a déjà reçue, la nouvelle tentative avec le même identifiant est rejetée. Le runtime ne réessaie pas les erreurs levées par le code du Durable Object, celles portant .overloaded ni les réponses HTTP telles que 500 : il s’agit d’une réponse du gestionnaire, et non d’une erreur de livraison.

Pourquoi une nouvelle livraison n’équivaut pas à une nouvelle exécution

Renvoyer une requête ne signifie pas à lui seul que la méthode sera exécutée une seconde fois. En cas d’incertitude sur le résultat, le runtime renvoie la requête avec le même identifiant ; si l’objet a reçu la tentative initiale, il rejette la nouvelle. En fonctionnement normal, cela évite de réexécuter la méthode — et, par exemple, de débiter à nouveau un compte ou de créer un doublon — à la suite d’un seul problème réseau.

La limite change lorsque la méthode est annotée avec retryable() depuis cloudflare:durable-objects. L’objet est alors autorisé à réexécuter la méthode si la première tentative a peut-être déjà commencé. Cloudflare donne deux exemples : attribuer à un produit une quantité déterminée est idempotent ; augmenter cette quantité d’une unité ne l’est pas. Répéter la première action rétablit la même valeur, tandis que répéter la seconde ajoute une unité supplémentaire.

Il faut examiner non seulement l’état final du stockage, mais aussi tous les effets de la méthode. Si une nouvelle exécution déclenche un autre paiement, envoie un message ou lance une action externe, le fait que l’état interne du Durable Object soit identique ne la rend pas sûre. L’annotation convient lorsque la répétition ne change pas le résultat et ne duplique pas les effets de bord.

Quand l’idempotence explicite est utile

Définir une valeur, enregistrer un instantané de l’état ou mettre à jour un champ vers une valeur connue produit souvent le même résultat en cas de répétition. Pour ces méthodes, retryable() peut permettre à un appel d’aboutir après une coupure de connexion survenue une fois le traitement commencé.

Les opérations « ajouter », « en créer un autre », « débiter » et « envoyer » nécessitent généralement une autre forme de protection. Avant d’autoriser une nouvelle exécution, vérifiez que l’opération métier sait reconnaître les doublons ou qu’elle est conçue de manière à ce qu’une répétition ne crée pas un second effet. Le nom d’une fonction ne garantit rien : examinez toutes les modifications d’état et actions externes qu’effectue la méthode.

retryable() a un rôle précis : il autorise une nouvelle exécution lorsque l’on ne peut pas déterminer si le premier appel est arrivé à destination. Il ne modifie ni la liste des erreurs auxquelles le runtime réagit ni le nombre de tentatives. L’annotation s’applique à la fonction ; une méthode redéfinie ou enveloppée ne l’hérite pas automatiquement et doit elle aussi être annotée explicitement.

Ce qu’il faut vérifier dans un projet existant

Les boucles de tentatives personnalisées autour des appels aux Durable Objects sont l’endroit le plus évident à examiner. Chaque tentative peut désormais inclure les nouvelles tentatives du runtime, de sorte que le nombre total d’appels peut dépasser celui défini par l’application seule. Cloudflare recommande de réduire le nombre de tentatives internes ou de définir maxRetries: 0 pour le stub si votre code gère lui-même les tentatives.

Les limites d’un stub donné se définissent lors de l’appel à get() ou getByName(). Le paramètre maxRetries définit de zéro à dix nouvelles tentatives après la première ; timeoutMs définit l’intervalle au-delà duquel aucune nouvelle tentative ne démarre, entre 500 et 60 000 millisecondes. Ces paramètres s’appliquent aux appels effectués via ce stub. retryable() et l’objet retry nécessitent Wrangler 4.158.0 ou une version ultérieure.

Pour chaque appel, un audit utile consiste à poser trois questions : peut-il modifier l’état plus d’une fois ? Peut-il répéter des effets de bord externes ? L’application applique-t-elle sa propre politique de tentatives ? Décidez ensuite si le stub concerné doit utiliser les valeurs par défaut ou des limites personnalisées. Pour les méthodes idempotentes, vous pouvez évaluer séparément l’intérêt d’une annotation explicite ; pour les autres, conservez la protection et vérifiez comment l’erreur est traitée lorsque le résultat de la première tentative est inconnu.

Conséquence : la responsabilité se déplace vers la méthode

Les nouvelles tentatives automatiques retirent une partie de la logique réseau du code applicatif, mais la décision d’autoriser une nouvelle exécution reste liée à l’opération. Le runtime peut réessayer la livraison sans risque et s’arrêter s’il ne sait pas si l’appel a été exécuté. Le développeur peut autoriser une nouvelle exécution de la méthode en confirmant explicitement qu’elle ne duplique ni les modifications d’état ni les effets de bord.

Cette mise à jour doit donc être considérée comme un changement de contrat entre la couche de transport et le gestionnaire. Commencez par examiner vos propres boucles de tentatives et les effets de bord répétables, puis configurez les limites sur les stubs concernés. Vous pourrez ainsi associer la résilience intégrée aux pannes brèves au contrôle des opérations pour lesquelles une deuxième exécution a un coût réel.