JA EN
shiichan

Durable Objects now defer code updates by default

Cloudflare Changelog ★★★★ View Markdown
#cloudflare#serverless#devops

Hi everyone, it's Shii-chan! There's a big behavior change for Durable Objects users.

Cloudflare Changelog developers.cloudflare.com

What was announced?

The Cloudflare Changelog announced that Durable Objects now defer code updates by default.

The story so far

Each Durable Object is globally unique, so it must run only one version of your code at a time. Previously, a deploy was applied immediately, which could interrupt in-flight work and terminate open connections.

What changes

After you deploy, an active Durable Object can keep running its current code for up to 5 minutes (300 seconds) while it waits to hibernate. That gives in-flight work time to finish, which helps long-running agents and long-lived WebSocket connections. WebSocket connections that use the Hibernation API remain connected when an object adopts new code after hibernating.

Dive Deep

The update flow for an active Durable Object:

  • You deploy, and the object can keep running its current code
  • If it hibernates before the delay ends, it starts on the new code on the next request
  • If the delay ends first, or immediate mode is selected, it resets and adopts the new code

Configuration details:

  • In Wrangler config, use code_update_strategy under durable_objects, with mode and max_delay
  • max_delay is in seconds, from 0 to 86400 (24 hours), with millisecond precision; the default is 300
  • To apply a single deployment immediately, pass a flag
npx wrangler versions deploy {VERSION_ID}@100% --durable-objects-code-update-mode immediate

This is meant for incidents, or when your deployment tooling calls a Durable Object right after deploying and needs the new code.

Keep in mind that deferral is best effort and does not guarantee every operation finishes. An object can also reset before max_delay, for example during a Cloudflare runtime update.

Wrap-up

  • Code updates are deferred by default, up to 300 seconds
  • Hibernation API WebSockets stay connected across hibernation
  • max_delay is tunable from 0 to 24 hours, and immediate mode is available
  • It is best effort, not a guarantee

This one is for anyone running agents or realtime apps on Durable Objects who used to hold their breath on every deploy!

Related posts