@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, 06:00 UTC

main
mdx 699 lines 21.8 KB
Raw
1 ---
2 title: Accept WebSockets
3 description: Accept WebSocket connections in a Durable Object, broadcast between peers, and survive Cloudflare's hibernation.
4 sidebar:
5 order: 8
6 ---
7
8 The `Counter` Durable Object you added in the previous part holds
9 state per key but only over plain HTTP. Now you'll build `Room` — a
10 chat Durable Object that accepts WebSocket connections, broadcasts
11 messages between peers, and **survives hibernation**.
12
13 Cloudflare can evict an idle Durable Object from memory while
14 keeping its WebSocket connections open. When a message arrives the
15 DO is reconstructed from scratch, your constructor Effect runs again, and
16 your `webSocketMessage` handler is invoked. Any per-instance state
17 you held in JavaScript variables is gone — you have to put it back.
18
19 ## Accept a connection
20
21 Start with the smallest possible Room — just enough to complete
22 the WebSocket handshake. Create `src/room.ts`:
23
24 ```typescript
25 // src/room.ts
26 import * as Cloudflare from "@alchemy.run/cloudflare";
27 import * as Effect from "effect/Effect";
28
29 export default class Room extends Cloudflare.DurableObject<Room>()(
30 "Rooms",
31 Effect.gen(function* () {
32 return Effect.gen(function* () {
33 return {
34 fetch: Effect.gen(function* () {
35 const [response, socket] = yield* Cloudflare.upgrade();
36 return response;
37 }),
38 };
39 });
40 }),
41 ) {}
42 ```
43
44 `Cloudflare.upgrade()` does two things in one call: it builds a
45 `101 Switching Protocols` response with the right headers, and it
46 hands you a `Socket` you can `send` / `close` /
47 `serializeAttachment` on. Returning the response from `fetch` is
48 what tells Cloudflare to hijack the TCP connection and complete the
49 handshake.
50
51 This compiles and accepts connections, but messages go nowhere yet.
52
53 ## Remember who's connected
54
55 Add a `sessions` map and stash the new socket into it on every
56 upgrade. Tag each socket with an id so we know which session sent
57 what later:
58
59 ```diff lang="typescript"
60 // src/room.ts
61 import * as Cloudflare from "@alchemy.run/cloudflare";
62 import * as Effect from "effect/Effect";
63
64 export default class Room extends Cloudflare.DurableObject<Room>()(
65 "Rooms",
66 Effect.gen(function* () {
67 return Effect.gen(function* () {
68 + const sessions = new Map<string, Cloudflare.WebSocket>();
69
70 return {
71 fetch: Effect.gen(function* () {
72 const [response, socket] = yield* Cloudflare.upgrade();
73 + const id = crypto.randomUUID();
74 + socket.serializeAttachment({ id });
75 + sessions.set(id, socket);
76 return response;
77 }),
78 };
79 });
80 }),
81 ) {}
82 ```
83
84 `socket.serializeAttachment({ id })` persists a structured-cloneable value
85 **alongside the socket itself**. Cloudflare keeps it across
86 hibernation, so when the DO wakes back up the socket still
87 remembers which session it belongs to. We'll need that in the next
88 two steps.
89
90 ## Handle incoming messages
91
92 Add a `webSocketMessage` handler. Cloudflare invokes it every time
93 a peer sends data; we look up the sender's session id from the
94 attachment, prefix each message with a short label, and fan it out
95 to everyone in the room:
96
97 ```diff lang="typescript"
98 return {
99 fetch: Effect.gen(function* () {
100 const [response, socket] = yield* Cloudflare.upgrade();
101 const id = crypto.randomUUID();
102 socket.serializeAttachment({ id });
103 sessions.set(id, socket);
104 return response;
105 }),
106 + webSocketMessage: Effect.fn(function* (
107 + socket: Cloudflare.WebSocket,
108 + message: string | ArrayBuffer,
109 + ) {
110 + const attachment = socket.deserializeAttachment<{ id: string }>();
111 + if (!attachment) return;
112 + const text =
113 + typeof message === "string"
114 + ? message
115 + : new TextDecoder().decode(message);
116 + const label = attachment.id.slice(0, 8);
117 + for (const peer of sessions.values()) {
118 + yield* peer.send(`[${label}] ${text}`);
119 + }
120 + }),
121 };
122 ```
123
124 `Effect.fn` lets you write a generator function with
125 arbitrary parameters. The Cloudflare runtime calls it with the
126 socket and the inbound payload (which can be a string or an
127 `ArrayBuffer` depending on how the client sent it).
128
129 ## Clean up on disconnect
130
131 When a peer disconnects, drop them from the `sessions` map so we
132 don't try to send to a dead socket:
133
134 ```diff lang="typescript"
135 return {
136 fetch: /* ... */,
137 webSocketMessage: /* ... */,
138 + webSocketClose: Effect.fn(function* (
139 + ws: Cloudflare.WebSocket,
140 + code: number,
141 + reason: string,
142 + ) {
143 + const attachment = ws.deserializeAttachment<{ id: string }>();
144 + if (attachment) sessions.delete(attachment.id);
145 + yield* ws.close(code, reason);
146 + }),
147 + webSocketError: Effect.fn(function* (
148 + ws: Cloudflare.WebSocket,
149 + error: unknown,
150 + ) {
151 + // Cloudflare closes an errored socket after this handler runs; only
152 + // the session bookkeeping is ours to clean up.
153 + const attachment = ws.deserializeAttachment<{ id: string }>();
154 + if (attachment) sessions.delete(attachment.id);
155 + }),
156 };
157 ```
158
159 `webSocketError` fires when the connection fails instead of closing
160 cleanly (a network reset, a protocol error). The runtime closes the
161 socket afterwards, so the handler only has to drop the peer's state.
162
163 ## Restore sessions after hibernation
164
165 Here's the catch. Cloudflare can evict an idle DO from memory
166 while keeping its WebSockets open. When the next message arrives,
167 the DO is reconstructed: the inner `Effect.gen` runs again, and
168 your `sessions` map starts empty — but the open sockets are still
169 there.
170
171 Resolve `Cloudflare.DurableObjectState` in the **outer** Effect,
172 then rehydrate the map at the top of the inner constructor by reading
173 every attached socket back from the runtime:
174
175 ```diff lang="typescript"
176 Effect.gen(function* () {
177 + const state = yield* Cloudflare.DurableObjectState;
178 return Effect.gen(function* () {
179 const sessions = new Map<string, Cloudflare.WebSocket>();
180
181 + for (const socket of yield* state.getWebSockets()) {
182 + const data = socket.deserializeAttachment<{ id: string }>();
183 + if (data) sessions.set(data.id, socket);
184 + }
185
186 return {
187 fetch: /* ... */,
188 webSocketMessage: /* ... */,
189 webSocketClose: /* ... */,
190 };
191 });
192 });
193 ```
194
195 `state.getWebSockets()` returns every still-attached socket on the
196 current instance, and `deserializeAttachment` recovers the
197 `{ id }` we stashed in the upgrade step. Without this loop the
198 first message after hibernation would broadcast to nobody.
199
200 :::note
201 The `state` *reference* is resolved in the outer (Construction) Effect, but
202 `state.getWebSockets()` is
203 [colored with `RuntimeContext`](/infrastructure-as-effects/layers#the-types-hold-the-boundary),
204 so it can only run in the inner (runtime) Effect — which is exactly
205 where it needs to be, since it must re-run every time Cloudflare
206 reconstructs the instance after hibernation.
207 :::
208
209 ## Define the session data
210
211 You can save session data on a WebSocket and validate it when reading it
212 back—even after the Durable Object wakes from hibernation. First, define
213 what a valid session contains:
214
215 ```typescript
216 import * as Schema from "effect/Schema";
217
218 const Session = Schema.Struct({
219 id: Schema.String,
220 joinedAt: Schema.DateFromString,
221 });
222 ```
223
224 `id` is a string. `joinedAt` is a `Date` in your code; this schema converts
225 it to a string for storage and back to a `Date` when you read it.
226
227 ## Save session data on a socket
228
229 Replace the `serializeAttachment` call in `fetch` with:
230
231 ```typescript
232 const joinedAt = yield* Effect.sync(() => new Date());
233 yield* socket.setAttachment(Session, { id, joinedAt });
234 ```
235
236 This saves the session on this connection, so it survives hibernation.
237 Cloudflare must be able to serialize the stored value, and the serialized
238 attachment must fit within 16,384 bytes, including serialization overhead.
239
240 ## Read the session back
241
242 ```typescript
243 const session = yield* socket.getAttachment(Session);
244
245 session.id; // string
246 session.joinedAt; // Date
247 ```
248
249 `getAttachment` checks the saved data against `Session`. Missing or invalid
250 data fails with `WebSocketAttachmentError` instead of returning an invalid
251 session. The existing `serializeAttachment` and `deserializeAttachment`
252 methods remain available if you do not want schema validation.
253
254 ## Validate attachments after hibernation
255
256 Use `getAttachment` in the restoration loop to validate surviving sockets:
257
258 ```typescript
259 for (const socket of yield* state.getWebSockets()) {
260 yield* socket.getAttachment(Session).pipe(
261 Effect.tap((session) =>
262 Effect.sync(() => sessions.set(session.id, socket)),
263 ),
264 Effect.catchTag("WebSocketAttachmentError", () =>
265 socket.close(1008, "Invalid session"),
266 ),
267 );
268 }
269 ```
270
271 This example closes connections whose sessions are missing or invalid,
272 including older sessions without `joinedAt`. Your code chooses this behavior;
273 `getAttachment` does not close the connection for you.
274
275 For diagnostics, `WebSocketAttachmentError.reason` identifies `encode`,
276 `decode`, `missing`, `read`, or `write`; `cause` contains the original error.
277 A stored `null` or `undefined` counts as missing.
278
279 ## Choose an attachment error policy
280
281 A handler can instead ignore an invalid attachment:
282
283 ```typescript
284 const session = yield* socket.getAttachment(Session).pipe(
285 Effect.catchTag("WebSocketAttachmentError", () =>
286 Effect.succeed(undefined),
287 ),
288 );
289 if (session === undefined) return;
290 ```
291
292 Omit `catchTag` to propagate the typed failure, or handle it at your normal
293 Effect boundary. These helpers are for application-owned attachments, not
294 the internal serializer metadata of WebSocket RPC connections.
295
296 ## Address groups of sockets with tags
297
298 To message a subset of the room, tag sockets when you accept them
299 instead of tracking group membership yourself:
300
301 ```typescript
302 const [response, socket] = yield* Cloudflare.upgrade({
303 tags: [`user:${userId}`, "role:admin"],
304 });
305 ```
306
307 `state.getWebSockets("role:admin")` then returns only the sockets
308 with that tag, and `state.getTags(socket.ws)` reads a socket's tags.
309 The runtime stores tags with the socket, so both work after
310 hibernation without rebuilding any in-memory state. Cloudflare allows
311 at most 10 tags per socket, each at most 256 characters.
312
313 ## Extract a broadcast helper
314
315 Before wiring this up, pull the broadcast loop into a reusable
316 `broadcast` function — we'll need it again when we add scheduled
317 reminders below:
318
319 ```diff lang="typescript"
320 Effect.gen(function* () {
321 const state = yield* Cloudflare.DurableObjectState;
322 return Effect.gen(function* () {
323 const sessions = new Map<string, Cloudflare.WebSocket>();
324
325 for (const socket of yield* state.getWebSockets()) {
326 const data = socket.deserializeAttachment<{ id: string }>();
327 if (data) sessions.set(data.id, socket);
328 }
329
330 + const broadcast = (text: string) =>
331 + Effect.gen(function* () {
332 + for (const peer of sessions.values()) {
333 + yield* peer.send(text);
334 + }
335 + });
336
337 return {
338 fetch: /* ... */,
339 webSocketMessage: Effect.fn(function* (socket, message) {
340 const attachment = socket.deserializeAttachment<{ id: string }>();
341 if (!attachment) return;
342 const text = typeof message === "string"
343 ? message
344 : new TextDecoder().decode(message);
345 - for (const peer of sessions.values()) {
346 - yield* peer.send(`[${attachment.id.slice(0, 8)}] ${text}`);
347 - }
348 + yield* broadcast(`[${attachment.id.slice(0, 8)}] ${text}`);
349 }),
350 webSocketClose: /* ... */,
351 + broadcast,
352 };
353 });
354 });
355 ```
356
357 Returning `broadcast` from the inner Effect makes it callable as an
358 RPC method — handy when other resources (a Workflow, a Container)
359 want to push messages into the room.
360
361 ## Wire the Room into the Worker
362
363 The Worker forwards any `Upgrade: websocket` request on `/room/:id`
364 to the matching DO instance:
365
366 ```diff lang="typescript"
367 // src/worker.ts
368 import * as Cloudflare from "@alchemy.run/cloudflare";
369 import * as Effect from "effect/Effect";
370 +import { HttpServerRequest } from "effect/http/HttpServerRequest";
371 import * as HttpServerResponse from "effect/http/HttpServerResponse";
372 +import Room from "./room.ts";
373
374 export default Cloudflare.Worker(
375 "Worker",
376 { main: import.meta.url },
377 Effect.gen(function* () {
378 + const rooms = yield* Room;
379
380 return {
381 fetch: Effect.gen(function* () {
382 + const request = yield* HttpServerRequest;
383 +
384 + if (request.url.startsWith("/room/")) {
385 + if (request.headers.upgrade !== "websocket") {
386 + return HttpServerResponse.text(
387 + "Expected Upgrade: websocket",
388 + { status: 426 },
389 + );
390 + }
391 + const id = request.url.split("/").pop()!;
392 + return yield* rooms.getByName(id).fetch(request);
393 + }
394 +
395 return HttpServerResponse.text("Hello from my Worker!");
396 }),
397 };
398 }),
399 );
400 ```
401
402 `rooms.getByName(id).fetch(request)` is the typed equivalent of
403 "forward this HTTP request to the DO". Because the DO returned a
404 `fetch` field with the upgrade response, the runtime hijacks the
405 TCP connection — the Worker's response **is** the WebSocket
406 handshake.
407
408 ## Deploy
409
410 ```sh
411 bun alchemy deploy
412 ```
413
414 ## Connect from a test
415
416 The integration test connects to the deployed Worker over a real
417 WebSocket using Effect's native [`Socket`](https://effect.website/docs/platform/socket/)
418 module. Unlike the raw `WebSocket` global, `Socket` is fully
419 Effect-aware: the connection lifecycle is tied to a `Scope`,
420 incoming frames flow through a `Queue`, and the open handshake is
421 signalled with a `Deferred`.
422
423 Start the test file with the imports and a `stack` deployed once
424 per run:
425
426 ```typescript
427 // test/integ.test.ts
428 import * as Cloudflare from "@alchemy.run/cloudflare";
429 import * as Test from "@alchemy.run/test/Bun";
430 import { expect } from "bun:test";
431 import * as Deferred from "effect/Deferred";
432 import * as Effect from "effect/Effect";
433 import * as Queue from "effect/Queue";
434 import * as Socket from "effect/socket/Socket";
435 import Stack from "../alchemy.run.ts";
436
437 const { test, beforeAll, deploy } = Test.make({
438 providers: Cloudflare.providers(),
439 state: Cloudflare.state(),
440 });
441
442 const stack = beforeAll(deploy(Stack));
443 ```
444
445 `beforeAll(deploy(Stack))` deploys your Worker + Room once and
446 exposes the result (including the public `url`) as an `Effect`
447 the tests can `yield*`.
448
449 ## Open the socket and acquire a writer
450
451 We want each test to say "give me a connected client" and get back
452 something with `send` and `next` methods. Start by opening the
453 socket and grabbing a writer for sending frames:
454
455 ```typescript
456 const connect = (url: string) =>
457 Effect.gen(function* () {
458 const socket = yield* Socket.makeWebSocket(url);
459 const send = yield* socket.writer;
460
461 return {
462 send: (msg: string) => send(msg),
463 };
464 });
465 ```
466
467 `Socket.makeWebSocket(url)` builds a `Socket` resource. It needs a
468 `WebSocketConstructor` in context, which we'll provide at the test
469 boundary. `socket.writer` returns a function for sending frames —
470 acquiring it once is more efficient than re-deriving it per send.
471
472 ## Drain inbound frames into a queue
473
474 To let the test consume incoming messages, push each frame into an
475 unbounded `Queue` and expose a `next` accessor that pulls one off:
476
477 ```diff lang="typescript"
478 const connect = (url: string) =>
479 Effect.gen(function* () {
480 const socket = yield* Socket.makeWebSocket(url);
481 + const messages = yield* Queue.unbounded<string>();
482 const send = yield* socket.writer;
483
484 + yield* Effect.forkScoped(
485 + socket.runString((msg) => Queue.offer(messages, msg)),
486 + );
487 +
488 return {
489 send: (msg: string) => send(msg),
490 + next: Queue.take(messages),
491 };
492 });
493 ```
494
495 `socket.runString` consumes inbound text frames and hands each one
496 to your callback. `Effect.forkScoped` runs the read loop in the
497 background, tied to the surrounding scope — when the test scope
498 closes, the loop is interrupted and the socket is closed.
499
500 ## Wait for the open handshake
501
502 Returning before the socket is actually open lets the caller race
503 the handshake — `send` could fire before the server is ready. Block
504 on a `Deferred` that the `onOpen` hook fulfils:
505
506 ```diff lang="typescript"
507 const connect = (url: string) =>
508 Effect.gen(function* () {
509 const socket = yield* Socket.makeWebSocket(url);
510 const messages = yield* Queue.unbounded<string>();
511 const send = yield* socket.writer;
512 + const opened = yield* Deferred.make<void>();
513
514 yield* Effect.forkScoped(
515 - socket.runString((msg) => Queue.offer(messages, msg)),
516 + socket.runString((msg) => Queue.offer(messages, msg), {
517 + onOpen: Deferred.succeed(opened, undefined),
518 + }),
519 );
520 + yield* Deferred.await(opened);
521
522 return {
523 send: (msg: string) => send(msg),
524 next: Queue.take(messages),
525 };
526 });
527 ```
528
529 `Deferred.await(opened)` blocks the helper until `onOpen` fires, so
530 the caller can `send` immediately on return without racing the
531 handshake.
532
533 ## Write the test body
534
535 Open two clients to the same room, have one send `"hello bob"`,
536 and assert the other receives the broadcast. Wrap the whole effect
537 in `Effect.scoped` so the test scope closes when it finishes:
538
539 ```typescript
540 test(
541 "Room broadcasts messages between peers",
542 Effect.gen(function* () {
543 const { url } = yield* stack;
544 const wsUrl = url.replace(/^http/, "ws") + "/room/test";
545
546 const alice = yield* connect(wsUrl);
547 const bob = yield* connect(wsUrl);
548
549 yield* alice.send("hello bob");
550
551 const received = yield* bob.next;
552 expect(received).toMatch(/hello bob$/);
553 }).pipe(Effect.scoped),
554 { timeout: 30_000 },
555 );
556 ```
557
558 `Effect.scoped` closes the scope at the end of the test, which
559 interrupts every forked read loop in `connect` and closes both
560 sockets.
561
562 ## Provide the WebSocket constructor
563
564 `Socket.makeWebSocket` doesn't know how to actually open a
565 connection by itself — it depends on a `WebSocketConstructor`
566 service. Provide the global one:
567
568 ```diff lang="typescript"
569 test(
570 "Room broadcasts messages between peers",
571 Effect.gen(function* () {
572 // ...
573 }).pipe(
574 Effect.scoped,
575 + Effect.provide(Socket.layerWebSocketConstructorGlobal),
576 ),
577 { timeout: 30_000 },
578 );
579 ```
580
581 `layerWebSocketConstructorGlobal` supplies the runtime's global
582 `WebSocket` constructor. On Bun and Node 22+ this picks up the
583 built-in `WebSocket`.
584
585 Run it:
586
587 ```sh
588 bun test test/integ.test.ts
589 ```
590
591 Alice's `"hello bob"` arrives at the Room as a `webSocketMessage`,
592 the broadcast loop sends `"[<alice-id>] hello bob"` to every peer,
593 and Bob's `next` resolves with it from the queue.
594
595 ## Register a reminder callback
596
597 Durable Objects have **alarms** — single-shot timers backed by the
598 DO's storage. `Alchemy.makeCallback` uses SQLite and native alarms to
599 persist typed jobs across hibernation. Register a reminder handler in
600 the inner Effect, after restoring sessions and defining `broadcast`:
601
602 ```diff lang="typescript"
603 // src/room.ts
604 +import * as Alchemy from "alchemy";
605
606 // Inside the inner Effect, after defining broadcast:
607 +const onReminder = yield* Alchemy.makeCallback(
608 + "reminder",
609 + Effect.fn(function* (payload: { message: string }) {
610 + yield* broadcast(`[reminder] ${payload.message}`);
611 + }),
612 +);
613 ```
614
615 The inner Effect registers this handler again after each hibernation.
616 Alchemy invokes it when a persisted job is due, so this example does
617 not need a custom `alarm` handler.
618
619 ## Schedule a future broadcast (alarms)
620
621 Recognise `/remind <seconds> <message>` inside `webSocketMessage`
622 and schedule a job using the callback handle:
623
624 ```diff lang="typescript"
625 webSocketMessage: Effect.fn(function* (socket, message) {
626 const attachment = socket.deserializeAttachment<{ id: string }>();
627 if (!attachment) return;
628 const text = typeof message === "string"
629 ? message
630 : new TextDecoder().decode(message);
631
632 + const remindMatch = text.match(/^\/remind\s+(\d+)\s+(.+)$/);
633 + if (remindMatch) {
634 + const delaySec = parseInt(remindMatch[1], 10);
635 + const reminder = remindMatch[2];
636 + const id = yield* Effect.sync(() => crypto.randomUUID());
637 + yield* onReminder.schedule(id, {
638 + after: `${delaySec} seconds`,
639 + payload: { message: reminder },
640 + });
641 + yield* socket.send(`[system] Reminder scheduled in ${delaySec}s`);
642 + return;
643 + }
644
645 yield* broadcast(`[${attachment.id.slice(0, 8)}] ${text}`);
646 }),
647 ```
648
649 Each random ID creates an independent reminder in this Room. Reusing
650 an ID would replace its pending reminder; `onReminder.cancel(id)`
651 cancels it. The payload is typed by the registered handler.
652
653 :::caution[Broadcasts can repeat]
654 Callback delivery is at least once. If a broadcast reaches some peers
655 and then fails, a retry can send the reminder again. For deduplicated
656 messages, include a stable message ID and have clients ignore IDs they
657 have already received. This example delivers to the peers connected
658 when it runs; it does not queue messages for disconnected users.
659 :::
660
661 If you previously deployed this tutorial using `scheduleEvent`, keep
662 your existing `alarm` handler and `processScheduledEvents` call until
663 those jobs drain. Old rows are preserved, not converted to callbacks.
664 See [upgrading existing schedules](/cloudflare/compute/durable-objects#upgrade-existing-schedules)
665 and the [native alarm retry limitation](/cloudflare/compute/durable-objects#retry-failed-callbacks).
666
667 ## Verify the reminder
668
669 Add a test that sends `/remind 1 hello` and waits for the callback's
670 broadcast:
671
672 ```typescript
673 // test/integ.test.ts (additions)
674 test(
675 "Room schedules a reminder broadcast",
676 Effect.gen(function* () {
677 const { url } = yield* stack;
678 const wsUrl = url.replace(/^http/, "ws") + "/room/reminders";
679
680 const peer = yield* connect(wsUrl);
681 yield* peer.send("/remind 1 hello");
682
683 // First message back is the [system] confirmation;
684 // the second is the [reminder] broadcast a second later.
685 yield* peer.next;
686 const reminder = yield* peer.next;
687 expect(reminder).toContain("[reminder] hello");
688 }).pipe(
689 Effect.scoped,
690 Effect.provide(Socket.layerWebSocketConstructorGlobal),
691 ),
692 { timeout: 30_000 },
693 );
694 ```
695
696 You now have an interesting backend. Next you'll
697 [add a React SPA](/cloudflare/frontend/vite-spa) so users have a UI
698 to talk to it — frontend and backend deploying together from the
699 same `alchemy.run.ts`.