WebSockets

背景

WebSocketsは、クライアントとサーバー間で双方向のリアルタイム通信を可能にする長寿命のTCP接続です。

Durable Objectsは、Workers Runtime WebSocket APIをサポートしています。あなたのDurable Objectは、WebSocketセッションの単一の調整ポイントとして機能し、クライアントとの間で送受信されるメッセージを完全に制御できるため、チャットルームやマルチプレイヤーゲームのようなアプリケーションを構築することができます。

APIリファレンス以外の詳細については、WebSocketサーバーの構築の例を参照してください。

WebSocket休止API

Workers WebSocket APIに加えて、Durable Objects WebSocket休止APIには、標準WebSocket API、状態メソッド、およびハンドラーメソッドへの以下の拡張が含まれています。

WebSocket休止APIは、現在イベントハンドラー（WebSocketメッセージの処理、HTTPリクエスト、またはアラームなど）を実行していないDurable Objectをメモリから削除し、WebSocketを接続したままにすることを可能にします（「休止」）。これにより、非アクティブな期間中に発生する可能性のある料金を削減できます。

WebSocket休止について詳しくは、WebSocket休止を使用したWebSocketサーバーの構築の例を参照してください。

WebSocket APIへの拡張

serializeAttachment

serializeAttachment(valueany) : void
- 休止から生き残るために、メモリ内にvalueのコピーを保持します（ディスク上には保存されません）。値は、構造化クローンアルゴリズム ↗によってサポートされる任意のタイプであることができます。これはほとんどのタイプに当てはまります。
- このメソッドを呼び出した後にvalueを変更した場合、その変更はこのメソッドを再度呼び出さない限り保持されません。valueのシリアライズサイズは2,048バイトに制限されており、それを超えるとこのメソッドはエラーをスローします。休止から生き残るためにより大きな値が必要な場合は、トランザクショナルストレージAPIを使用し、対応するキーをこのメソッドに渡して後で取得できるようにします。

deserializeAttachment

deserializeAttachment() : any
- serializeAttachment()に渡された最も最近の値を取得します。存在しない場合はnullを返します。

状態メソッド

acceptWebSocket

acceptWebSocket(wsWebSocket, tagsArray<string>optional) : void
- このDurable Objectに添付されたWebSocketのセットにWebSocketを追加します。ws.accept()は別途呼び出されてはいけません。一度呼び出されると、受信したメッセージはDurable ObjectのwebSocketMessage()ハンドラーによって配信され、切断時にはwebSocketClose()が呼び出されます。
- state.acceptWebSocket(ws)を呼び出した後、WebSocketは受け入れられます。したがって、そのsend()およびclose()メソッドを使用してメッセージを送信できます。addEventListener()メソッドは、イベントを受信することはありません。イベントはDurable Objectに配信されます。
- tagsは、state.getWebSockets()でWebSocketを検索するために使用されるオプションの文字列タグです。各タグは256文字に制限され、各WebSocketには最大10個の関連付けられたタグがあります。
- WebSocket休止APIは、Durable Objectインスタンスごとに最大32,768のWebSocket接続を許可しますが、特定のワークロードのCPUおよびメモリ使用量が同時接続の実際の数をさらに制限する可能性があります。

getWebSockets

getWebSockets(tagstringoptional) : Array<WebSocket>
- 指定されたタグに一致する受け入れられたWebSocketの配列を取得します。切断されたWebSocket¹は自動的にリストから削除されます。tag引数なしでstate.getWebSockets()を呼び出すと、すべてのWebSocketが返されます。
- ¹ state.getWebSockets()は、ws.close()が呼び出された後でもWebSocketを返す場合があります。たとえば、サーバー側のWebSocket（Durable Object）がクローズを送信しますが、クライアントからの応答を受け取らない場合（切断を検出していない場合）、接続はCLOSINGの「readyState」にあります。クライアントはさらにメッセージを送信する可能性があるため、WebSocketは技術的には切断されていません。

getTags

getTags(wsWebSocket) : Array<string>
- 指定されたWebSocketに関連付けられたタグの配列を返します。指定されたWebSocketに対してstate.acceptWebSocket()を呼び出していない場合はエラーをスローします。

setWebSocketAutoResponse

setWebSocketAutoResponse(webSocketRequestResponsePairWebSocketRequestResponsePairoptional): void
- 休止中のWebSocketを起こさないアプリケーションレベルの自動応答を設定します。
- state.setWebSocketAutoResponseは、WebSocketRequestResponsePair(requeststring, responsestring)を引数として受け取り、state.acceptWebSocket()を介して受け入れられたこのオブジェクトに属するWebSocketが、指定されたrequestを受信したときに自動的にresponseで応答することを可能にします。
- state.setWebSocketAutoResponse()は、静的なping/pongメッセージのためにサーバーを設定するよりも好ましいです。なぜなら、state.setWebSocketAutoResponse()は、WebSocketを休止から起こさずにアプリケーションレベルのping/pongを処理し、不必要な料金を防ぐからです。
- requestとresponseはそれぞれ2,048文字に制限されています。
- 引数なしでstate.setWebSocketAutoResponse()が設定されると、以前に設定された自動応答構成が削除されます。引数なしでstate.setWebSocketAutoResponse()を設定すると、Durable Objectはrequestに対してresponseで応答しなくなります。また、requestの最終タイムスタンプの更新も停止しますが、以前に自動応答タイムスタンプが設定されていた場合は、state.getWebSocketAutoResponseTimestamp()でアクセス可能なままになります。

getWebSocketAutoResponse

getWebSocketAutoResponse() : Object | null
- 現在設定されているWebSocketRequestResponsePair(requeststring, responsestring)を取得します。存在しない場合はnullを返します。
- 各WebSocketRequestResponsePair(requeststring, responsestring)オブジェクトは、getRequest()およびgetResponse()のメソッドを提供します。

getWebSocketAutoResponseTimestamp

getWebSocketAutoResponseTimestamp(wsWebSocket) : Date | null
- WebSocketが自動応答リクエストを受信した最も最近の日付を取得します。指定されたWebSocketが自動応答リクエストを受信したことがない場合はnullを返します。

setHibernatableWebSocketEventTimeout

setHibernatableWebSocketEventTimeout(timeoutnumberoptional) : void
- WebSocketイベント（以下のハンドラーメソッドを参照）が実行できる最大ミリ秒数を設定します。
- 0の場合、またはtimeoutに値が指定されていない場合は、以前に設定されたタイムアウト（あれば）が解除されます。
- timeoutの最大値は604,800,000 ms（7日）です。

getHibernatableWebSocketEventTimeout

getHibernatableWebSocketEventTimeout() : number | null
- state.setHibernatableWebSocketEventTimeout()で設定された場合、現在設定されている休止可能なWebSocketイベントタイムアウトを取得します。

ハンドラーメソッド

webSocketMessage

webSocketMessage(wsWebSocket, messageString | ArrayBuffer) : void
- 受け入れられたWebSocketがメッセージを受信したときにシステムによって呼び出されます。
- このメソッドはasyncにすることができます。
- このメソッドはWebSocket制御フレームには呼び出されません。システムは、受信したWebSocketプロトコルping ↗に自動的に応答し、休止を中断することはありません。

webSocketClose

webSocketClose(wsWebSocket, codenumber, reasonstring, wasCleanboolean) : void
- WebSocketが閉じられたときにシステムによって呼び出されます。wasClean()がtrueの場合、接続は正常に閉じられたことを示し、falseの場合はそうではありません。
- このメソッドはasyncにすることができます。

webSocketError

webSocketError(wsWebSocket, errorany) : void
- 切断に関連しないエラーが発生したときにシステムによって呼び出されます。
- このメソッドはasyncにすることができます。