durable objects: clarify behavior for WebSocket attachments #26924
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
TimoWilhelm
requested review from
a team,
Oxyjun,
elithrar,
harshil1712,
joshthoward,
mikenomitch and
vy-ton
as code owners
github-actions
bot
added
the
product:durable-objects
TimoWilhelm
changed the title
| - <code>serializeAttachment(value <Type text="any" />)</code>: <Type text="void" /> | ||
|
|
||
| - 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - 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 the value needs to be durable even if the [Durable Object is evicted](/durable-objects/concepts/durable-object-lifecycle/), please use [Durable Object Storage](/durable-objects/api/sqlite-storage-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. |
Contributor
There was a problem hiding this comment.
Or instead of adding the sentence I added above, add it here.
Contributor
Author
There was a problem hiding this comment.
I added another section here to cover instance eviction. I tried to avoid the phrase "durable" as I think it could be confusing between hibernation and eviction. I also added clarification that the connections are closed in case the instance is evicted.
lambrospetrou
approved these changes
Dec 4, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Clarifies the lifetime of attachments for the Durable Object Hibernation WebSocket API