From d1838cb0c163e9b7d7a437208de5fb625dc0ec92 Mon Sep 17 00:00:00 2001 From: Timo Wilhelm Date: Thu, 4 Dec 2025 14:49:30 +0100 Subject: [PATCH 1/2] clarify behavior for DO WebSocket serializeAttachment --- .../docs/durable-objects/best-practices/websockets.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index 7cd6f82eb535294..afe230698441ec3 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -170,11 +170,15 @@ The following are methods available on the **Native Durable Object WebSocket API #### `WebSocket.serializeAttachment()` -- {" "}serializeAttachment(value ): +- serializeAttachment(value ): - - Keeps a copy of `value` associated with the WebSocket to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. If the value needs to be durable please use [Durable Object Storage](/durable-objects/api/sqlite-storage-api/). + - Keeps a copy of `value` associated with the WebSocket connection. Serialized attachments are available as long as their attached WebSocket connection is healthy, even after hibernation. If any side of the connection is closed, the attachments will be lost. - - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/sqlite-storage-api/) and pass the corresponding key to this method so it can be retrieved later. + - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. + + - The `value` can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types and the serialized size is limited to 2,048 bytes, otherwise this method will throw an error. + + - If you need to store larger values, use the [Storage API](/durable-objects/api/sqlite-storage-api/) and store the corresponding key as an attachment so it can be retrieved later. #### `WebSocket.deserializeAttachment()` From 6ce0b3af7c5c674670f859836fbf36c5f7688cd9 Mon Sep 17 00:00:00 2001 From: Timo Wilhelm Date: Thu, 4 Dec 2025 17:36:24 +0100 Subject: [PATCH 2/2] add ecivtion note --- src/content/docs/durable-objects/best-practices/websockets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index afe230698441ec3..973d6fc07e85323 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -178,7 +178,7 @@ The following are methods available on the **Native Durable Object WebSocket API - The `value` can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types and the serialized size is limited to 2,048 bytes, otherwise this method will throw an error. - - If you need to store larger values, use the [Storage API](/durable-objects/api/sqlite-storage-api/) and store the corresponding key as an attachment so it can be retrieved later. + - If you need to store larger values, or want to persist values even if the Durable Object instance is evicted and the WebSocket connections are closed, use the [Storage API](/durable-objects/api/sqlite-storage-api/) and store the corresponding key as an attachment so it can be retrieved later. #### `WebSocket.deserializeAttachment()`