INTEGRITY Документация

← Cloudflare Workers / workers / runtime-apis

WebSockets

Контекст

WebSockets позволяют обмениваться данными в режиме реального времени с бессерверными функциями Cloudflare Workers. Полный пример см. в Использование WebSockets API.

Конструктор

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

WebSocketPair, возвращаемый этим конструктором, представляет собой Object с двумя WebSocket по ключам 0 и 1.

Такие WebSocket обычно называют client и server. Пример ниже объединяет Object.values и деструктуризацию ES6, чтобы получить WebSocket как client и server:

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

Методы

принять

Параметры

addEventListener

Параметры

закрыть

Параметры

отправить

Параметры

Свойства

readyState

binaryType

События

Типы

Сообщение

Поведение при закрытии

С web_socket_auto_reply_to_close флаг совместимости (включён по умолчанию при дате совместимости от 2026-04-07), среда выполнения Workers автоматически отправляет ответный кадр Close при получении кадра Close от другой стороны. После этого readyState переходит в CLOSED перед close событие срабатывает. Это соответствует Спецификация 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
});

Режим half-open для проксирования

Автоматическое закрытие соединения может мешать проксированию WebSocket, когда Worker находится между клиентом и бэкендом и должен независимо координировать закрытие с обеих сторон. Чтобы поддержать этот сценарий, передайте { allowHalfOpen: true } к accept():

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() чтобы завершить handshake. Если этого не сделать, это может привести к 1006 ошибки аномального закрытия соединения на стороне клиента.

Двоичные сообщения

Фреймы WebSocket содержат либо текстовые, либо двоичные данные, и выбор между ними делает отправитель в момент отправки фрейма. Текстовые фреймы всегда доставляются в message событие в виде строк JavaScript. Бинарные фреймы доставляются либо как Blob ↗ или как ArrayBuffer ↗, в зависимости от WebSocket binaryType.

С websocket_standard_binary_type флаг совместимости (включён по умолчанию при дате совместимости от 2026-03-17), binaryType по умолчанию равно "blob" и бинарные фреймы передаются в виде Blob объекты. Это соответствует Спецификация WebSocket ↗ и стандартным поведением браузера. Без этого флага binaryType по умолчанию равно "arraybuffer" и бинарные фреймы передаются в виде ArrayBuffer, соответствуя историческому поведению runtime.

binaryType свойство само по себе доступно всегда. Чтобы вернуться к ArrayBuffer доставку для одного WebSocket, назначьте binaryType перед вызовом accept():

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.
  }
});

Чтение двоичных данных

Входящий двоичный кадр полностью буферизуется перед тем, как message событие срабатывает, независимо от binaryType. Выбор между Blob и ArrayBuffer не влияет на то, когда и будет ли получен фрейм: она влияет только на то, как вы получаете доступ к его байтам:

Согласно новому поведению по умолчанию обработчик бинарных сообщений должен быть async чтобы прочитать полезную нагрузку. Если хотите сохранить существующий синхронный обработчик, задайте binaryType к "arraybuffer" для WebSocket.

Когда значение вступает в силу

Согласно Спецификация WebSocket ↗, binaryType является изменяемым: значение считывается в момент отправки каждого бинарного фрейма в message событие, поэтому присвоение нового значения влияет только на последующие сообщения. Если вы хотите, чтобы все двоичные сообщения WebSocket доставлялись в одном и том же типе, присвойте binaryType перед вызовом accept(). Это гарантирует, что настройка вступит в силу до того, как среда выполнения начнёт обрабатывать входящие фреймы.

Отказ на уровне всего Worker

Если вы ещё не готовы к переходу и хотите оставить ArrayBuffer по умолчанию для каждого WebSocket в вашем Worker, добавьте no_websocket_standard_binary_type флаг в ваш конфигурационный файл Wrangler. Отдельные WebSocket-соединения всё же могут переопределить значение по умолчанию, присвоив binaryType.