Cloudflare přidala opakování volání Durable Objects — a rozlišila cenu chyby

Pokud volání Durable Object skončilo chybou sítě, vývojář dříve často musel rozhodnout, zda ho odeslat znovu. Od 5. listopadu 2026 část těchto opakování provádí runtime Cloudflare: automaticky opakuje některá neúspěšná volání fetch() a RPC přes stub. Pro aplikační kód je nyní klíčová přesnější otázka: může se konkrétní metoda bezpečně spustit podruhé?

Odpověď závisí na tom, kde se spojení přerušilo. Runtime automaticky opakuje některá volání a ve výchozím nastavení chrání před dvojím spuštěním. Při nejistém doručení používá stejné ID požadavku a objekt opakování odmítne, pokud už přijal první pokus. Metoda výslovně označená jako retryable() se chová jinak: může se spustit znovu, i když první pokus objektu už dorazil. Toto označení je proto vhodné jen pro operace, jejichž opakování je bezpečné jak pro stav, tak pro vedlejší účinky.

Co přesně runtime opakuje

Podle oznámení Cloudflare z 5. listopadu se opakování týká volání fetch() a RPC do Durable Object, která provádí Worker nebo jiný Durable Object. U volání přes stub je ve výchozím nastavení povolen první pokus a až čtyři opakování; nové pokusy se nezačnou později než 10 sekund po zahájení volání.

Podmínkou je chyba s příznakem .retryable. Požadavek například nemusel k objektu dorazit, protože se objekt restartoval nebo přesouval. Runtime může pokus opakovat také tehdy, když se spojení přerušilo a nelze určit, zda objekt požadavek stihl přijmout. Pokud objekt požadavek už přijal, opakování se stejným ID odmítne. Runtime neopakuje chyby vyvolané kódem Durable Object, chyby s příznakem .overloaded ani odpovědi HTTP, jako je 500: jde o odpověď obslužného programu, nikoli o chybu doručení.

Proč opakování doručení není opakováním operace

Opětovné odeslání požadavku samo o sobě neznamená, že se metoda spustí podruhé. Při nejistém výsledku runtime odešle požadavek se stejným ID; pokud objekt přijal původní pokus, opakování odmítne. Tím se v běžném režimu zabrání opětovnému spuštění metody, například druhému stržení platby nebo vytvoření záznamu kvůli jedinému výpadku sítě.

Hranice se změní, když je metoda označena pomocí retryable() z cloudflare:durable-objects. Objekt pak může metodu spustit znovu, i když první pokus už mohl začít. Cloudflare uvádí dva příklady: nastavit produktu konkrétní množství je idempotentní; zvýšit množství o jednu jednotku nikoli. Opakování první akce nastaví stejnou hodnotu, opakování druhé přidá další jednotku.

Kontrolovat je třeba nejen výsledný stav úložiště, ale také všechny účinky metody. Pokud opakování vytvoří další platbu, odešle zprávu nebo spustí externí akci, stejný stav uvnitř Durable Object neznamená, že je opakování bezpečné. Označení je vhodné tehdy, když opakování nemění význam výsledku ani neduplikuje vedlejší účinky.

Kde se hodí výslovná idempotence

Nastavení hodnoty, uložení snímku stavu nebo aktualizace pole na známou hodnotu často přinesou při opakování stejný výsledek. U takových metod může retryable() umožnit úspěšné dokončení volání po výpadku spojení, ke kterému došlo až po zahájení zpracování.

Operace „přičíst“, „vytvořit další“, „strhnout“ a „odeslat“ obvykle vyžadují jinou ochranu. Než povolíte opětovné spuštění, ujistěte se, že obchodní operace rozpoznává duplicity, nebo je navržena tak, aby opakování nevytvořilo druhý účinek. Samotný název funkce nic nezaručuje: zkontrolujte všechny změny stavu a externí akce uvnitř metody.

retryable() má úzce vymezenou roli: povoluje opětovné spuštění, když nelze určit, zda první volání dorazilo. Nemění seznam chyb, na které runtime reaguje, ani nezvyšuje počet pokusů. Příznak se vztahuje na funkci; přepsaná nebo obalená verze metody ho automaticky nepřebírá, pokud ji také výslovně neoznačíte.

Co zkontrolovat v již běžícím projektu

Nejpravděpodobnějším místem k revizi jsou vlastní smyčky opakování kolem volání Durable Objects. Každý takový pokus nyní může zahrnovat opakování runtime, takže celkový počet volání může být vyšší, než určuje samotná aplikace. Cloudflare doporučuje snížit vlastní počet pokusů nebo pro stub nastavit maxRetries: 0, pokud opakování řídí váš kód.

Limity pro konkrétní stub se nastavují při volání get() nebo getByName(). Parametr maxRetries určuje nula až deset opakování po prvním pokusu; timeoutMs určuje interval, po jehož uplynutí už nové pokusy nezačnou, v rozmezí 500 až 60 000 milisekund. Tato nastavení se vztahují na volání přes daný stub. Funkce retryable() a objekt retry vyžadují Wrangler 4.158.0 nebo novější.

Užitečná revize spočívá ve třech otázkách pro každé volání: může změnit stav více než jednou; zopakuje externí vedlejší účinky; má aplikace vlastní politiku opakování? Pak rozhodněte, zda má daný stub používat výchozí hodnoty, nebo vlastní limity. U idempotentních metod můžete samostatně zvážit výslovné označení; u ostatních ponechte ochranu a zkontrolujte zpracování chyby v případě, že výsledek prvního pokusu není znám.

Důsledek: odpovědnost se přesouvá na hranici metody

Automatické opakování odstraňuje část síťové logiky z aplikačního kódu, ale rozhodnutí, zda je opětovné spuštění přijatelné, zůstává vlastností operace. Runtime může bezpečně opakovat doručení a zastavit se, pokud neví, zda se volání provedlo. Vývojář může povolit opakování metody a výslovně tak potvrdit, že neduplikuje změny stavu ani vedlejší účinky.

Aktualizaci je proto třeba chápat jako změnu smlouvy mezi transportní vrstvou a obslužným programem. Nejprve zkontrolujte vlastní smyčky opakování a opakovatelnost vedlejších účinků; potom nastavte limity na potřebných stubích. Vestavěná odolnost vůči krátkým výpadkům se tak spojí s kontrolou nad operacemi, u nichž má druhé spuštění skutečnou cenu.