WIP: [DO] Document delayed code updates - #32222
Draft
iglesiasbrandon wants to merge 7 commits into
Draft
Conversation
github-actions
Bot
added
product:durable-objects
github-actions
Bot
assigned
danlapid,
elithrar,
irvinebroque,
joshthoward,
lambrospetrou,
Oxyjun,
rita3ko and
vy-ton
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
|
Nimbus Preview URL: https://e9771dbd.preview.developers.cloudflare.com |
Contributor
|
Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant). |
vy-ton
reviewed
Aug 11, 2026
| ### Code updates | ||
|
|
||
| When your Durable Object code is updated, your Worker and Durable Objects are released globally in an eventually consistent manner. This will cause a Durable Object to shut down, with the behavior described above. Updates can also create a situation where a request reaches a new version of your Worker in one location, and calls to a Durable Object still running a previous version elsewhere. Refer to [Code updates](/durable-objects/platform/known-issues/#code-updates) for more information about handling this scenario. | ||
| Delayed code updates prevent deployments from immediately shutting down active Durable Objects. An active object continues serving existing and new requests on its current code until it hibernates. This lets in-flight HTTP and RPC requests finish, allows storage operations to complete, and keeps connections accepted with the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api) connected. |
Contributor
There was a problem hiding this comment.
Missing a section before here that describes the default deployment behavior. Should link to relevant sections in https://developers.cloudflare.com/workers/versions-and-deployments/#deployments and help DO user understand code deployment need to know just from this page.
vy-ton
reviewed
Aug 11, 2026
| When your Durable Object code is updated, your Worker and Durable Objects are released globally in an eventually consistent manner. This will cause a Durable Object to shut down, with the behavior described above. Updates can also create a situation where a request reaches a new version of your Worker in one location, and calls to a Durable Object still running a previous version elsewhere. Refer to [Code updates](/durable-objects/platform/known-issues/#code-updates) for more information about handling this scenario. | ||
| Delayed code updates prevent deployments from immediately shutting down active Durable Objects. An active object continues serving existing and new requests on its current code until it hibernates. This lets in-flight HTTP and RPC requests finish, allows storage operations to complete, and keeps connections accepted with the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api) connected. | ||
|
|
||
| The Worker deployment itself is not delayed. When the object hibernates, its in-memory state is discarded. The next request or event runs the constructor with the latest deployed code. Objects that are already hibernated or inactive also use the latest code when they next become active. |
Contributor
There was a problem hiding this comment.
Worker deployment itself is not delayed - confused by the wording. Are you saying the Worker deployment that defines the DO is separate?
iglesiasbrandon
force-pushed
the
durable-objects-graceful-code-updates
branch
from
August 13, 2026 21:32
e9771db to
06b20b1
Compare
Contributor
|
|
||
| Deploying a new Worker version used to reset every active Durable Object right away, dropping in-flight requests, closing WebSockets, and interrupting storage operations. Now you can set a deployment grace period so an active object keeps running its current code until it hibernates, then picks up the update on its own. | ||
|
|
||
| Add `deployment_grace_period` to `durable_objects` in your Wrangler configuration, or pass it as a flag for a single deployment: |
Contributor
There was a problem hiding this comment.
show me how to add it with wrangler.jsonc
| "class_name": "ChatRoom", | ||
| }, | ||
| ], | ||
| "deployment_grace_period": 30, |
Contributor
There was a problem hiding this comment.
by making this a string rather than an object:
- one-way door, can't extend it to support additional configuration later
- there can't be a way to just set it and use a default value — if you want to configure this, then you as the user have to set the value to
30
ex: below you say "the default is 30" - but i'm not sure what the meaning of a default is, if the user has to specify it
|
|
||
| </WranglerConfig> | ||
|
|
||
| The value is in seconds. The default is `30`. The maximum is `300` (five minutes). Set `deployment_grace_period` to `0` to reset active objects immediately, the same as every code update before this feature existed. |
Contributor
There was a problem hiding this comment.
relative time statement about "before this feature existed" doesn't really make sense to me in reference docs
if you want immediate updates, wouldn't you just remove deployment_grace_period?
| --- | ||
|
|
||
| Durable Objects may shut down at any time due to deployments, inactivity, or runtime decisions. Rather than relying on shutdown hooks (which are not provided), design your application to write state incrementally. | ||
| Durable Objects may shut down at any time due to forced code updates, inactivity, or runtime decisions. Rather than relying on shutdown hooks (which are not provided), design your application to write state incrementally. |
Contributor
There was a problem hiding this comment.
is this a reference to when customers update code or something else?
think there is opportunity here to get language right:
When you deploy a code change, a Durable Object is inactive, or when Cloudflare deploys a new version of the Workers Runtime, a Durable Object will shut down. This is similar to other compute environments, where compute instances do not live forever, and where applications must persist state back to a database or storage system. For example, if you use Durable Objects for a long-running task, you should write state incrementally as the task progresses, and not rely on keeping state entirely in-memory until the task completes.
|
|
||
| <PackageManagers type="exec" pkg="wrangler" args="versions deploy <VERSION_ID>@100% --durable-objects-deployment-grace-period 30" /> | ||
|
|
||
| The value is in seconds. The default is 30, and the maximum is 300 (five minutes). Set it to `0` to reset active objects immediately — useful when you need to ship a fix during an incident or force a busy object off old code. |
Contributor
There was a problem hiding this comment.
see comment later in here — I don't follow why we would tell people to set this to 0 as their way to deploy a change immediately? vs. just say wrangler deploy
|
|
||
| Keep your Worker and Durable Object code forward and backward compatible for as long as any version might still be running, not just for the length of the deployment. Refer to [Code updates](/durable-objects/platform/known-issues/#code-updates). | ||
|
|
||
| ## When to set a grace period to zero |
Contributor
There was a problem hiding this comment.
see other comments, not sure why it is "set this to zero" vs. omitting it, or saying something like:
wrangler deploy --immediate
Contributor
There was a problem hiding this comment.
omit would have to be default behavior, so need to define the default behavior (if its 60s then that cant be the break glass option) cc @iglesiasbrandon
|
|
||
| - A grace period is best-effort. Cloudflare does not guarantee an object keeps its old code for the full grace period, or that it resets exactly when the grace period ends. | ||
| - A grace period only delays resets caused by code updates. It does not delay resets caused by process sandbox migrations, resource limits, crashes, or other Workers runtime updates. | ||
| - An object might skip versions entirely if you deploy more than once while it is waiting to hibernate. |
Contributor
There was a problem hiding this comment.
Why is this a limitation?
| - A grace period is best-effort. Cloudflare does not guarantee an object keeps its old code for the full grace period, or that it resets exactly when the grace period ends. | ||
| - A grace period only delays resets caused by code updates. It does not delay resets caused by process sandbox migrations, resource limits, crashes, or other Workers runtime updates. | ||
| - An object might skip versions entirely if you deploy more than once while it is waiting to hibernate. | ||
| - A grace period does not make incompatible Worker and Durable Object versions safe to run together. Keep your interfaces compatible across versions. |
Contributor
There was a problem hiding this comment.
Why is this a limitation?
|
|
||
| ## Limitations | ||
|
|
||
| - A grace period is best-effort. Cloudflare does not guarantee an object keeps its old code for the full grace period, or that it resets exactly when the grace period ends. |
Contributor
There was a problem hiding this comment.
Why is this a limitation?
Co-authored-by: Brendan Irvine-Broque <brendanib@gmail.com>
…review feedback
- Replace deployment_grace_period (integer) with code_update_strategy
{ mode, max_delay } to match Brendan's proposal, keeping max_delay as
a plain integer (seconds) per Wrangler config convention rather than
a duration string.
- Add a table covering every mode/max_delay combination, including the
omitted-field default, the invalid immediate+max_delay case, and the
deferred+0 degenerate case.
- Add a CLI flag (--durable-objects-code-update-mode, mode-only) and
explain why it exists alongside Wrangler config.
- Add a Mermaid flowchart to Gradual deployments showing which objects
start waiting on a code update strategy.
- Remove remaining relative-time phrasing ("before this feature
existed") from the reference page.
- Rewrite working-without-shutdown-hooks.mdx to answer what triggers a
shutdown, previously never addressed.
- Add a Worker-deployment-vs-object-adoption clarification and a link
to versions-and-deployments in durable-object-lifecycle.mdx.
- Clean up the best-effort Limitations bullet.
- Rename the changelog entry to drop the now-inaccurate grace-period
slug.
…e flow Per in-person review with Vy: - Create a new Deployments sidebar section (durable-objects/deployments/) and move this page and the Gradual Deployments nav stub into it. Title and filename unchanged; only the URL path and sidebar grouping change. - Add a Default max_delay column to the Choose a code update strategy table and state the before/on-or-after compatibility-date default directly in that section, removing the now-redundant standalone Default behavior and compatibility dates section. - Reorder What each configuration does so deferred rows precede immediate rows, and split the omitted-field row into two explicit rows (before / on-or-after the compatibility date). - Generalize the gradual-deployments flowchart (drop version-percentage framing) and move it into How it works; Gradual deployments now links back to it instead of duplicating a diagram. - Reorder page sections into what/mechanism/how/why/reference order: Choose a strategy -> How it works -> Configure -> What each configuration does -> Override (CLI) -> REST API -> Apply an update immediately -> Gradual deployments -> Limitations -> Related resources.
Contributor
|
This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:
|
Drop 'Delay' in favor of 'Defer' to match the code_update_strategy mode value (deferred), and drop 'Durable Object' from the title since 'hibernation' already carries sufficient product-specific signal, matching sibling page titles in this section (Use WebSockets, Invoke methods, Error handling) that also omit it. Updated the 4 inbound link texts that quoted the old title verbatim.
…link - Update changelog title from 'Delay' to 'Defer code updates until active Durable Objects hibernate' to match the renamed reference page title. - Link 'code update strategy' in the shared working-without-shutdown-hooks partial to the reference page, giving rules-of-durable-objects.mdx (which had no other mention of this feature) a discovery path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the WIP Durable Objects behavior that lets active objects defer code updates until hibernation, reducing deployment-time interruptions to requests, storage operations, and hibernatable WebSockets.
Adds a changelog and updates lifecycle, WebSocket, storage, version-skew, and troubleshooting guidance. The final launch date, compatibility date, timeout contract, and Wrangler option remain marked as TODOs before review.
Documentation checklist