The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: Code updates |
| 3 | description: What happens to running Workers and Durable Objects when you deploy, how to choose when Durable Objects pick up new code, and how to write tests that see the code you just deployed. |
| 4 | --- |
| 5 | |
| 6 | When you deploy, new requests to your Worker run the new code within |
| 7 | seconds. A Durable Object that is already running is different: it |
| 8 | keeps running the code it started with until it is safe to switch. |
| 9 | Knowing when that happens tells you how to write code that survives |
| 10 | a deploy and tests that see what you just shipped. |
| 11 | |
| 12 | ## A Worker starts fresh on every deploy |
| 13 | |
| 14 | Each deploy runs in new isolates. The Construction phase runs again, |
| 15 | and anything the old isolate held in memory is gone: |
| 16 | |
| 17 | ```typescript |
| 18 | export default Cloudflare.Worker( |
| 19 | "Worker", |
| 20 | { main: import.meta.url }, |
| 21 | Effect.gen(function* () { |
| 22 | // Runs once per isolate, so again after every deploy |
| 23 | const counters = yield* Counter; |
| 24 | |
| 25 | return { |
| 26 | fetch: Effect.gen(function* () { |
| 27 | return HttpServerResponse.text("Hello from my Worker!"); |
| 28 | }), |
| 29 | }; |
| 30 | }), |
| 31 | ); |
| 32 | ``` |
| 33 | |
| 34 | The new version can take a few seconds to reach every location, so |
| 35 | retry the first request after a deploy. See |
| 36 | [Retry the first request](/testing/testing-a-stack#retry-the-first-request). |
| 37 | |
| 38 | ## A Durable Object keeps the code it started with |
| 39 | |
| 40 | Each object runs one copy of your code, the inner Effect, from the |
| 41 | moment it starts: |
| 42 | |
| 43 | ```typescript |
| 44 | export default class Counter extends Cloudflare.DurableObject<Counter>()( |
| 45 | "Counter", |
| 46 | Effect.gen(function* () { |
| 47 | const state = yield* Cloudflare.DurableObjectState; |
| 48 | |
| 49 | return Effect.gen(function* () { |
| 50 | // Runs each time the object starts |
| 51 | let count = (yield* state.storage.get<number>("count")) ?? 0; |
| 52 | |
| 53 | return { |
| 54 | increment: () => |
| 55 | Effect.gen(function* () { |
| 56 | count += 1; |
| 57 | yield* state.storage.put("count", count); |
| 58 | return count; |
| 59 | }), |
| 60 | }; |
| 61 | }); |
| 62 | }), |
| 63 | ) {} |
| 64 | ``` |
| 65 | |
| 66 | An object stops when it goes idle. It hibernates after about 10 |
| 67 | seconds without work, or is evicted after 70 to 140 seconds if |
| 68 | something keeps it from hibernating, such as a pending `setTimeout` |
| 69 | or an open outbound connection. Its next request starts it again on |
| 70 | the latest code. `count` is read back from storage, so it survives. |
| 71 | Anything kept only in memory does not. |
| 72 | |
| 73 | ## Deploys wait for objects to go idle |
| 74 | |
| 75 | By default an object that is busy during a deploy keeps running its |
| 76 | current code for up to 5 minutes while it waits to hibernate. Then |
| 77 | it resets onto the new code: |
| 78 | |
| 79 | ```typescript |
| 80 | { |
| 81 | main: import.meta.url, |
| 82 | // the default |
| 83 | codeUpdateStrategy: { mode: "deferred", maxDelay: "5 minutes" }, |
| 84 | } |
| 85 | ``` |
| 86 | |
| 87 | Requests in progress get time to finish, and |
| 88 | [hibernatable WebSockets](/cloudflare/compute/hibernatable-websockets) |
| 89 | stay connected when the object picks up the new code after |
| 90 | hibernating. |
| 91 | |
| 92 | ## Choose how long to wait |
| 93 | |
| 94 | Set `maxDelay` to anything from 0 to 24 hours: |
| 95 | |
| 96 | ```typescript |
| 97 | { |
| 98 | main: import.meta.url, |
| 99 | codeUpdateStrategy: { mode: "deferred", maxDelay: "1 minute" }, |
| 100 | } |
| 101 | ``` |
| 102 | |
| 103 | Waiting is best effort. An object can still reset sooner, for example |
| 104 | when Cloudflare updates the Workers runtime. |
| 105 | |
| 106 | ## Switch objects to new code right away |
| 107 | |
| 108 | Use `immediate` when every object must run the new code as soon as |
| 109 | the deploy finishes, such as when you ship a fix during an incident: |
| 110 | |
| 111 | ```typescript |
| 112 | { |
| 113 | main: import.meta.url, |
| 114 | codeUpdateStrategy: { mode: "immediate" }, |
| 115 | } |
| 116 | ``` |
| 117 | |
| 118 | Every running object resets. A request it was handling fails with |
| 119 | `Durable Object reset because its code was updated`. Data in |
| 120 | `state.storage` is kept; in-memory values are lost. |
| 121 | |
| 122 | ## The strategy applies to each deploy |
| 123 | |
| 124 | The strategy is not a setting stored on the Worker. It is sent with |
| 125 | each deploy. Changing only `codeUpdateStrategy` does not deploy |
| 126 | anything, because a redeploy would reset the objects it is meant to |
| 127 | protect. Your next deploy uses the new value. |
| 128 | |
| 129 | ## Old and new code run side by side |
| 130 | |
| 131 | While an object waits, a Worker running the new code can call an |
| 132 | object still running the old code. Calling a method the old code |
| 133 | doesn't have fails: |
| 134 | |
| 135 | ```diff lang="typescript" |
| 136 | // src/worker.ts |
| 137 | const counter = counters.getByName(name); |
| 138 | -const next = yield* counter.increment(); |
| 139 | +const next = yield* counter.incrementBy(5); // missing on objects still running the old code |
| 140 | ``` |
| 141 | |
| 142 | Ship the new method in one deploy and start calling it in the next, |
| 143 | once `maxDelay` has passed. Keep method arguments and return values |
| 144 | readable by both versions in the meantime. |
| 145 | |
| 146 | ## Write state as you go |
| 147 | |
| 148 | An object can reset at any time: on deploy, when `maxDelay` runs out, |
| 149 | or during a runtime update. Save each change to storage when it |
| 150 | happens, as `increment` does, rather than when the object stops. Make |
| 151 | operations safe to retry, so a caller can repeat a request that |
| 152 | failed during a reset. |
| 153 | |
| 154 | ## Gradual deployments assign objects to versions |
| 155 | |
| 156 | During a [gradual deployment](/cloudflare/compute/gradual-deployments), |
| 157 | Cloudflare assigns each object to one version. Raising the new |
| 158 | version's traffic moves more objects onto it. Only objects that move |
| 159 | wait for `maxDelay`; the rest keep running. |
| 160 | |
| 161 | ## Tests can see the old code |
| 162 | |
| 163 | A test that deploys and then calls a Durable Object can reach an |
| 164 | object an earlier deploy started. If that object stayed busy, it can |
| 165 | answer with the old code for up to 5 minutes. |
| 166 | |
| 167 | Deploy your test stages with `immediate`, so every object runs the |
| 168 | code the test just deployed: |
| 169 | |
| 170 | ```typescript |
| 171 | // src/worker.ts |
| 172 | import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 173 | import { Stack } from "alchemy/Stack"; |
| 174 | import * as Effect from "effect/Effect"; |
| 175 | import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 176 | import Counter from "./counter.ts"; |
| 177 | |
| 178 | export default Cloudflare.Worker( |
| 179 | "Worker", |
| 180 | Stack.useSync(({ stage }) => ({ |
| 181 | main: import.meta.url, |
| 182 | codeUpdateStrategy: stage === "prod" ? undefined : { mode: "immediate" }, |
| 183 | })), |
| 184 | Effect.gen(function* () { |
| 185 | const counters = yield* Counter; |
| 186 | |
| 187 | return { |
| 188 | fetch: Effect.gen(function* () { |
| 189 | return HttpServerResponse.text("Hello from my Worker!"); |
| 190 | }), |
| 191 | }; |
| 192 | }), |
| 193 | ); |
| 194 | ``` |
| 195 | |
| 196 | Or give each test its own object. A new object always starts on the |
| 197 | latest code: |
| 198 | |
| 199 | ```typescript |
| 200 | test( |
| 201 | "increment starts at 1", |
| 202 | Effect.gen(function* () { |
| 203 | const { url } = yield* stack; |
| 204 | const name = crypto.randomUUID(); |
| 205 | |
| 206 | const response = yield* HttpClient.post(`${url}/counter/${name}`); |
| 207 | expect(yield* response.text).toBe("1"); |
| 208 | }), |
| 209 | ); |
| 210 | ``` |
| 211 | |
| 212 | ## Where next |
| 213 | |
| 214 | - [Durable Objects](/cloudflare/compute/durable-objects) — define an |
| 215 | object, persist its state, and call it from a Worker. |
| 216 | - [Accept WebSockets](/cloudflare/compute/hibernatable-websockets) — |
| 217 | connections that stay open through hibernation and code updates. |
| 218 | - [Gradual deployments](/cloudflare/compute/gradual-deployments) — |
| 219 | roll a deploy out to a share of traffic. |
| 220 | - [Testing a Stack](/testing/testing-a-stack) — deploy once per suite |
| 221 | and drive the live URL. |
| 222 | - [Cloudflare's code updates docs](https://developers.cloudflare.com/durable-objects/deployments/durable-objects-code-updates/) |
| 223 | — the platform feature, including Wrangler's `--durable-objects-code-update-mode` flag. |
| 224 | - [Worker API reference](/providers/cloudflare/workers/worker) — |
| 225 | every prop, including `codeUpdateStrategy`. |