Skip to content

Commit 8339c38

Browse files
[DO] Make deferred the default code update strategy, drop compatibility-date gating
1 parent 0a504cb commit 8339c38

1 file changed

Lines changed: 7 additions & 16 deletions

File tree

‎src/content/docs/durable-objects/deployments/durable-objects-code-updates.mdx‎

Lines changed: 7 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,7 @@ products:
1010

1111
import { WranglerConfig, PackageManagers } from "~/components";
1212

13-
{/* TODO: Confirm the compatibility date and launch date before publication.
14-
TODO: Confirm the `code_update_strategy` REST API field name and shape with the EWC/API
15-
team. The engineering spec still calls this field `durable_objects_hibernation_timeout`
16-
and uses a duration string. This page follows Brendan Irvine-Broque's proposal instead
17-
(`code_update_strategy` with `mode` and `max_delay`). Update this page once the spec and
18-
schema catch up. */}
13+
{/* TODO: Confirm the launch date for this feature before publication. */}
1914

2015
By default, Durable Objects delay applying Worker code deployments so in-flight requests can finish. Instead of resetting an active Durable Object immediately to apply a code update, Cloudflare applies the code update once the object is inactive (is hibernated).
2116

@@ -28,12 +23,9 @@ Deploy a Worker with `--durable-objects-code-update-mode immediate` to apply a c
2823
| `deferred` | 30 seconds | Cloudflare waits for an active Durable Object to hibernate before applying the update. If the object does not hibernate within `max_delay` (300 seconds maximum), Cloudflare resets it and applies the update. |
2924
| `immediate` | Not applicable | Cloudflare resets an active Durable Object and applies the update right away, without waiting for it to hibernate. |
3025

31-
Durable Objects code update strategy depends on your Workers compatibility date:
26+
`deferred` with a 30-second `max_delay` is the default code update strategy for all Workers — you do not need to set a compatibility date or change any configuration to get this behavior.
3227

33-
- Workers with a compatibility date **before** `COMPATIBILITY_DATE` default to `immediate`.
34-
- Workers with a compatibility date **on or after** `COMPATIBILITY_DATE` default to `deferred` with a 30-second `max_delay`.
35-
36-
An explicit `code_update_strategy` — whether in your Wrangler configuration, passed as a CLI flag, or sent through the REST API — always overrides the compatibility-date default.
28+
An explicit `code_update_strategy` — whether in your Wrangler configuration, passed as a CLI flag, or sent through the REST API — always overrides the default.
3729

3830
## How it works
3931

@@ -84,8 +76,7 @@ If a Durable Objects binding uses `script_name` to reference a class defined in
8476

8577
| `code_update_strategy` | Result |
8678
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
87-
| *(omitted)*, compatibility date before `COMPATIBILITY_DATE` | Defaults to `immediate`. |
88-
| *(omitted)*, compatibility date on or after `COMPATIBILITY_DATE` | Defaults to `deferred` with a 30-second `max_delay`. |
79+
| *(omitted)* | Defaults to `deferred` with a 30-second `max_delay`. |
8980
| `{ "mode": "deferred" }` | Cloudflare waits up to the default `max_delay` (30 seconds) for the object to hibernate. |
9081
| `{ "mode": "deferred", "max_delay": 0 }` | Valid, but Cloudflare waits zero seconds — behaves identically to `immediate`. |
9182
| `{ "mode": "deferred", "max_delay": 120 }` | Cloudflare waits up to 120 seconds for the object to hibernate before applying the update. |
@@ -117,7 +108,7 @@ Add `code_update_strategy` alongside `bindings` in the `durable_objects` object
117108

118109
</WranglerConfig>
119110

120-
`max_delay` is in seconds and only applies when `mode` is `deferred`. The maximum is `300` (five minutes). Omit `max_delay` to use the default for your compatibility date.
111+
`max_delay` is in seconds and only applies when `mode` is `deferred`. The maximum is `300` (five minutes). Omit `max_delay` to use the default (30 seconds).
121112

122113
If you're using [`ctx.exports`](/workers/runtime-apis/context/#exports) and don't need an explicit `bindings` entry, `code_update_strategy` still applies on its own:
123114

@@ -160,7 +151,7 @@ curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/scripts/
160151
}'
161152
```
162153

163-
Cloudflare returns the effective strategy in create, get, and list deployment responses, including the compatibility-date default when you omit the field. Use `GET /accounts/{account_id}/workers/scripts/{script_name}/deployments/{deployment_id}` to check the strategy Cloudflare applied to one deployment, or `GET /accounts/{account_id}/workers/scripts/{script_name}/deployments` to list deployment history:
154+
Cloudflare returns the effective strategy in create, get, and list deployment responses, including the default when you omit the field. Use `GET /accounts/{account_id}/workers/scripts/{script_name}/deployments/{deployment_id}` to check the strategy Cloudflare applied to one deployment, or `GET /accounts/{account_id}/workers/scripts/{script_name}/deployments` to list deployment history:
164155

165156
```json
166157
{
@@ -189,7 +180,7 @@ Wrangler resolves `mode` in this order:
189180

190181
1. The `--durable-objects-code-update-mode` flag.
191182
2. `durable_objects.code_update_strategy.mode` in your Wrangler configuration.
192-
3. The default for your compatibility date.
183+
3. The default (`deferred`).
193184

194185
A single-deployment override is most useful when waiting is worse than resetting. For example, set `code_update_strategy` to `{ "mode": "immediate" }` (or pass `--durable-objects-code-update-mode immediate`) when:
195186

0 commit comments

Comments
 (0)