WebSockets

accept()

• Accepts the WebSocket connection and begins terminating requests for the WebSocket on Cloudflare’s global network. This effectively enables the Workers runtime to begin responding to and handling WebSocket requests.

addEventListener(eventWebSocketEvent, callbackFunctionFunction)

• Add callback functions to be executed when an event has occurred on the WebSocket.

event WebSocketEvent

• The WebSocket event (refer to Events) to listen to.

callbackFunction(message Message ) Function

• A function to be called when the WebSocket responds to a specific event.

close(codenumber, reasonstring)

• Close the WebSocket connection.

codeinteger optional

• An integer indicating the close code sent by the server. This should match an option from the list of status codes Open external link provided by the WebSocket spec.

reasonstring optional

• A human-readable string indicating why the WebSocket connection was closed.

send(messagestring | ArrayBuffer | ArrayBufferView)

• Send a message to the other WebSocket in this WebSocket pair.

messagestring

• The message to send down the WebSocket connection to the corresponding client. This should be a string or something coercible into a string; for example, strings and numbers will be simply cast into strings, but objects and arrays should be cast to JSON strings using JSON.stringify, and parsed in the client.

• This method is part of the Hibernatable WebSockets API.

• Keeps a copy of value in memory (not on disk) to survive hibernation. The value can be any type supported by the structured clone algorithm Open external link , which is true of most types.

• 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 Transactional Storage API and pass the corresponding key to this method so it can be retrieved later.

• This method is part of the Hibernatable WebSockets API.

• Retrieves the most recent value passed to serializeAttachment(), or null if none exists.

acceptWebSocket(wsWebSocket, tagsArray<string>optional) : void

• Adds a WebSocket to the set attached to this Durable Object. ws.accept() must not have been called separately. Once called, any incoming messages will be delivered by calling the Durable Object’s webSocketMessage() handler, and webSocketClose() will be invoked upon disconnect.

• After calling state.acceptWebSocket(ws), the WebSocket is accepted. Therefore, you can use its send() and close() methods to send messages. Its addEventListener() method will not ever receive any events as they will be delivered to the Durable Object.

• tags are optional string tags used to look up the WebSocket with getWebSockets(). Each tag is limited to 256 characters, and each WebSocket is limited to 10 tags associated with it.

• The Hibernatable WebSockets API permits a maximum of 32,768 WebSocket connections per Durable Object instance, but the CPU and memory usage of a given workload may further limit the practical number of simultaneous connections.

getWebSockets(tagstringoptional) : Array<WebSocket>

• Gets an array of accepted WebSockets matching the given tag. Disconnected WebSockets ¹ are automatically removed from the list. Calling getWebSockets() with no tag argument will return all WebSockets.

• ¹ getWebSockets() may still return websockets even after ws.close() has been called. For example, if your server-side WebSocket (the Durable Object) sends a close, but does not receive one back (and has not detected a disconnect from the client), then the connection is in the CLOSING “readyState”. The client might send more messages, so the WebSocket is technically not disconnected.

setWebSocketAutoResponse(webSocketRequestResponsePairWebSocketRequestResponsePairoptional): void

• Sets an application level auto response that does not wake hibernated WebSockets.

• state.setWebSocketAutoResponse receives WebSocketRequestResponsePair(requeststring, responsestring) as an argument, enabling any WebSocket that was accepted via state.acceptWebSocket() belonging to this Object to automatically reply with response when it receives the specified request.

• setWebSocketAutoResponse() is preferable to setting up a server for static ping/pong messages because setWebSocketAutoResponse() handles application level ping/pongs without waking the WebSocket from hibernation, preventing unnecessary duration charges.

• Both request and response are limited to 2,048 characters each.

• If state.setWebSocketAutoResponse() is set without any argument, it will remove any previously set auto-response configuration. Setting state.setWebSocketAutoResponse() without any argument will stop a Durable Object from replying with response for a request. It will also stop updating the last timestamp of a request, but if there was any auto-response timestamp set, it will remain accessible with state.getWebSocketAutoResponseTimestamp().

getWebSocketAutoResponse() : Object | null

• Gets the WebSocketRequestResponsePair(requeststring, responsestring) currently set, or null if there is none.

• Each WebSocketRequestResponsePair(requeststring, responsestring) Object provides methods for getRequest() and getResponse().

getWebSocketAutoResponseTimestamp(wsWebSocket) : Date | null

• Gets the most recent Date when the WebSocket received an auto-response request, or null if the given WebSocket never received an auto-response request.

webSocketMessage(wsWebSocket, messageString | ArrayBuffer) : void

• Called by the system when an accepted WebSocket receives a message.

• This method can be async.

• This method is not called for WebSocket control frames. The system will respond to an incoming WebSocket protocol ping Open external link automatically without interrupting hibernation.

webSocketClose(wsWebSocket, codenumber, reasonstring, wasCleanboolean) : void

• Called by the system when a WebSocket is closed. wasClean() is true if the connection closed cleanly, false otherwise.

• This method can be async.

webSocketError(wsWebSocket, errorany) : void

• Called by the system when any non-disconnection related errors occur.

• This method can be async.

close

• An event indicating the WebSocket has closed.

error

• An event indicating there was an error with the WebSocket.

message

• An event indicating a new message received from the client, including the data passed by the client.