@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 225 lines 7.12 KB
Raw
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`.