WebSockets

WebSockets を使うと、Cloudflare Workers のサーバーレス関数とリアルタイムに通信できます。完全な例は Using the WebSockets API を参照してください。

// { 0: <WebSocket>, 1: <WebSocket> }
let websocketPair = new WebSocketPair();

このコンストラクターが返す WebSocketPair はオブジェクトで、キー 0 と 1 に 2 つの WebSocket があります。

これらの WebSocket は、一般に client と server と呼ばれます。次の例では Object.values と ES6 の分割代入を組み合わせ、WebSocket を client と server として取り出します。

let [client, server] = Object.values(new WebSocketPair());

• accept(options?)
  • WebSocket 接続を受け入れ、Cloudflare のグローバルネットワーク上でその WebSocket 向けリクエストの終端を開始します。これで Workers ランタイムが WebSocket リクエストへの応答と処理を開始できます。

• options object optional

  • 次のプロパティを持つ省略可能な設定オブジェクトです。

    • allowHalfOpen boolean optional — true のとき、ピアから Close フレームを受け取っても、ランタイムは自動では対向の Close フレームを送りません。代わりに、明示的に close() を呼ぶまで readyState は CLOSING のままです。WebSocket プロキシ で、プロキシの両側のクローズを調整したい場合に便利です。デフォルトは false です。

• addEventListener(eventWebSocketEvent, callbackFunctionFunction)
  • WebSocket でイベントが起きたときに実行するコールバック関数を追加します。

• event WebSocketEvent

  • 待ち受ける WebSocket イベントです（Events を参照）。

• callbackFunction(messageMessage) Function

  • 特定のイベントに WebSocket が応答したときに呼ばれる関数です。

• close(codenumber, reasonstring)
  • WebSocket 接続を閉じます。

• codeinteger optional

  • サーバーが送るクローズコードを示す整数です。WebSocket 仕様の ステータスコード一覧 ↗ のいずれかに合わせてください。

• reasonstring optional

  • WebSocket 接続が閉じられた理由を示す、人が読める文字列です。

• send(messagestring | ArrayBuffer | ArrayBufferView)
  • この WebSocket ペアのもう一方の WebSocket へメッセージを送ります。

• messagestring
  • 対応するクライアントへ WebSocket 接続経由で送るメッセージです。文字列、または文字列に変換できる値にしてください。文字列と数値はそのまま文字列になります。オブジェクトと配列は JSON.stringify で JSON 文字列にし、クライアント側でパースします。

• readyState number

  • WebSocket 接続の現在の状態を返します。取りうる値は次のとおりです。

    定数	値	説明
    WebSocket.CONNECTING	0	接続はまだ開いていません。
    WebSocket.OPEN	1	接続は開いており、通信できます。
    WebSocket.CLOSING	2	接続は閉じる途中です。
    WebSocket.CLOSED	3	接続は閉じています。

• binaryType string

  • この WebSocket で受け取ったバイナリフレームを、message イベントへどう渡すかを制御します。有効な値は "blob" と "arraybuffer" です。値は受信した各バイナリフレームをディスパッチするときに参照されるため、新しい値の代入は以降のメッセージにだけ影響します。デフォルトは websocket_standard_binary_type 互換性フラグで決まります。詳しくは バイナリメッセージ を参照してください。

• close
  • WebSocket が閉じたことを示すイベントです。CloseEvent には code（number）、reason（string）、wasClean（boolean）プロパティがあります。
• error
  • WebSocket でエラーが起きたことを示すイベントです。
• message
  • クライアントから新しいメッセージを受け取ったことを示すイベントです。クライアントが渡したデータを含みます。

• data any - ペアのもう一方の WebSocket から返されたデータです。
• type string - デフォルトは message です。

web_socket_auto_reply_to_close 互換性フラグ（互換性日付が 2026-04-07 以降ではデフォルトで有効）では、Workers ランタイムはピアから Close フレームを受け取ると、対向の Close フレームを自動送信します。close イベントが発火する前に readyState は CLOSED へ遷移します。これは WebSocket 仕様 ↗ と標準ブラウザーの動作に合わせています。

close イベントハンドラー内で close() を呼んでも、その呼び出しは黙って無視されます。Close フレームへ手動で応答する既存コードは、変更なしで動き続けます。

server.addEventListener("close", (event) => {
  // readyState is already CLOSED — no need to call server.close().
  console.log(server.readyState); // WebSocket.CLOSED
  console.log(event.code);        // 1000
  console.log(event.wasClean);    // true
});

自動クローズ動作は WebSocket プロキシの妨げになることがあります。Worker がクライアントとバックエンドの間に入り、両側のクローズを独立して調整する必要がある場合です。この用途では、accept() に { allowHalfOpen: true } を渡します。

server.accept({ allowHalfOpen: true });

server.addEventListener("close", (event) => {
  // readyState is still CLOSING here, giving you time
  // to coordinate the close on the other side.
  console.log(server.readyState); // WebSocket.CLOSING

  // Manually close when ready.
  server.close(event.code, "done");
});

互換性日付が 2026-04-07 より前（または web_socket_manual_reply_to_close フラグあり）では、Close フレームを受け取っても WebSocket は CLOSING のままで、ハンドシェイクを完了するにはコード側で close() を呼ぶ必要があります。呼ばないと、クライアント側で 1006 の異常クローズエラーになることがあります。

WebSocket フレームはテキストまたはバイナリのペイロードを運び、どちらにするかはフレーム送信時に送信側が決めます。テキストフレームは、常に JavaScript の文字列として message イベントへ届きます。バイナリフレームは、WebSocket の binaryType に応じて Blob ↗ または ArrayBuffer ↗ として届きます。

websocket_standard_binary_type 互換性フラグ（互換性日付が 2026-03-17 以降ではデフォルトで有効）では、binaryType のデフォルトは "blob" で、バイナリフレームは Blob オブジェクトとして届きます。これは WebSocket 仕様 ↗ と標準ブラウザーの動作に合わせています。フラグがない場合、binaryType のデフォルトは "arraybuffer" で、バイナリフレームは ArrayBuffer として届きます。これはランタイムの従来の動作です。

binaryType プロパティ自体は常に使えます。1 つの WebSocket だけ ArrayBuffer 配信に戻すには、accept() を呼ぶ前に binaryType を代入します。

const resp = await fetch("https://example.com", {
  headers: { Upgrade: "websocket" },
});
const ws = resp.webSocket;

// Opt back into ArrayBuffer delivery for this WebSocket.
ws.binaryType = "arraybuffer";
ws.accept();

ws.addEventListener("message", (event) => {
  if (typeof event.data === "string") {
    // Text frame.
  } else {
    // event.data is an ArrayBuffer because we set binaryType above.
  }
});

受信したバイナリフレームは、binaryType に関係なく、message イベントが発火する前にすべてバッファされます。Blob と ArrayBuffer の違いは、フレームをいつ・受け取るかではなく、バイトへのアクセス方法だけです。

• "arraybuffer" のとき、event.data は ArrayBuffer ↗ です。サイズの確認とバイトの読み取りは同期的にできます（例: new Uint8Array(event.data)）。
• "blob" のとき、event.data は Blob ↗ です。バイトの読み取りは非同期です（例: await event.data.arrayBuffer() または await event.data.bytes()）。

新しいデフォルトでは、バイナリメッセージのハンドラーでペイロードを読むには async にする必要があります。既存の同期ハンドラーを維持したい場合は、その WebSocket の binaryType を "arraybuffer" にします。

WebSocket 仕様 ↗ どおり、binaryType は変更できます。値は各バイナリフレームを message イベントへディスパッチする瞬間に参照されるため、新しい値の代入は以降のメッセージにだけ影響します。1 つの WebSocket 上のすべてのバイナリメッセージを同じ型で受け取りたい場合は、accept() を呼ぶ前に binaryType を代入します。ランタイムが受信フレームのディスパッチを始める前に、設定が確実に入ります。

移行の準備ができておらず、Worker 内のすべての WebSocket で ArrayBuffer をデフォルトのままにしたい場合は、Wrangler 設定ファイル に no_websocket_standard_binary_type フラグを追加します。個々の WebSocket は、binaryType を代入してデフォルトを上書きできます。

• Mozilla Developer Network（MDN）の WebSocket クラスのドキュメント ↗
• Workers 上で WebSockets を使うアプリケーション向けの WebSocket テンプレート ↗