Написание приложений-клиентов WebSocket

Приложения-клиенты WebSocket используют API WebSocket, чтобы взаимодействовать с серверами WebSocket с помощью протокола WebSocket.

Для взаимодействия с помощью протокола WebSocket вам необходимо создать объект WebSocket; это автоматически попытается открыть подключение к серверу.

Конструктор WebSocket принимает один обязательный и один необязательный параметр:

webSocket = new WebSocket(url, protocols);

url

URL для подключения; это должен быть URL, на который сервер WebSocket ответит. Он должен использовать схему URL wss://, хотя некоторые программы могут позволить вам использовать небезопасную схему ws:// для локального подключения. В современных версиях браузеров также разрешены относительные значения URL и схемы https:// и http://.

protocols Необязательно

Строка или массив строк протоколов. Эти строки используются для обозначения подпротоколов, так что один сервер может реализовать несколько подпротоколов WebSocket (например, вы можете захотеть, чтобы один сервер мог обрабатывать различные типы взаимодействий в зависимости от указанного protocol). Если вы не указываете строку протокола, предполагается пустая строка.

Конструктор выбросит SecurityError если целевой ресурс не позволяет доступ. Это может произойти, если вы попытаетесь использовать небезопасное соединение (большинство браузеров сейчас требуют защищенное соединение для всех подключений WebSocket, если они не на одном устройстве или, возможно, в одной сети).

Если при попытке подключения произошла ошибка, событие error сначала отправляется объекту WebSocket (тем самым вызывая любые обработчики), за которым следует событие close, указывающее причину закрытия подключения.

Браузер также может вывести в консоль более подробное сообщение об ошибке, а также код закрытия, как определено в RFC 6455, Раздел 7.4 через CloseEvent.

В этом простом примере создается новый WebSocket, подключающийся к серверу по адресу wss://www.example.com/socketserver. В этом примере в запросе для сокета указывается пользовательский протокол "protocolOne", хотя это можно опустить.

const exampleSocket = new WebSocket(
  "wss://www.example.com/socketserver",
  "protocolOne",
);

По возвращении exampleSocket.readyState равно CONNECTING. readyState станет OPEN после того, как соединение будет готово к передаче данных.

Если вы хотите открыть соединение и гибко относитесь к поддерживаемым протоколам, вы можете указать массив протоколов:

const exampleSocket = new WebSocket("wss://www.example.com/socketserver", [
  "protocolOne",
  "protocolTwo",
]);

После установления соединения (то есть readyState равно OPEN), exampleSocket.protocol укажет, какой протокол выбрал сервер.

Установление WebSocket полагается на механизм обновления HTTP, поэтому запрос на обновление протокола неявный, когда мы обращаемся к веб-серверу как к ws://www.example.com или wss://www.example.com.

После открытия подключения вы можете начать передачу данных на сервер. Для этого вызовите метод send() объекта WebSocket для каждого сообщения, которое вы хотите отправить:

exampleSocket.send("Here's some text that the server is urgently awaiting!");

Вы можете отправлять данные в виде строки, Blob или ArrayBuffer.

Поскольку установление соединения является асинхронным и подвержено ошибкам, нет гарантии, что вызов метода send() сразу после создания объекта WebSocket будет успешным. Мы можем быть уверены, что попытка отправки данных происходит только после установления соединения, определив обработчик события onopen для выполнения этой задачи:

exampleSocket.onopen = (event) => {
  exampleSocket.send("Here's some text that the server is urgently awaiting!");
};

Полезно использовать JSON для отправки достаточно сложных данных на сервер. Например, программа чата может взаимодействовать с сервером с помощью протокола, реализованного с помощью пакетов данных, закодированных в JSON:

// Send text to all users through the server
function sendText() {
  // Construct a msg object containing the data the server needs to process the message from the chat client.
  const msg = {
    type: "message",
    text: document.getElementById("text").value,
    id: clientID,
    date: Date.now(),
  };

  // Send the msg object as a JSON-formatted string.
  exampleSocket.send(JSON.stringify(msg));

  // Blank the text input element, ready to receive the next line of text from the user.
  document.getElementById("text").value = "";
}

WebSockets — это событийно-управляемый API; при получении сообщений событие message отправляется объекту WebSocket. Для обработки добавьте обработчик событий message или используйте обработчик событий onmessage. Для начала прослушивания входящих данных можно сделать следующее:

exampleSocket.onmessage = (event) => {
  console.log(event.data);
};

Рассмотрим сначала приложение-клиент чата, упомянутое в Использовании JSON для передачи объектов. Клиент может получать различные типы пакетов данных, такие как:

• Приветствие при входе в систему
• Текстовые сообщения
• Обновления списков пользователей

Код, интерпретирующий эти входящие сообщения, может выглядеть так:

exampleSocket.onmessage = (event) => {
  const f = document.getElementById("chat-box").contentDocument;
  let text = "";
  const msg = JSON.parse(event.data);
  const time = new Date(msg.date);
  const timeStr = time.toLocaleTimeString();

  switch (msg.type) {
    case "id":
      clientID = msg.id;
      setUsername();
      break;
    case "username":
      text = `User <em>${msg.name}</em> signed in at ${timeStr}<br>`;
      break;
    case "message":
      text = `(${timeStr}) ${msg.name} : ${msg.text} <br>`;
      break;
    case "reject-username":
      text = `Your username has been set to <em>${msg.name}</em> because the name you chose is in use.<br>`;
      break;
    case "user-list":
      document.getElementById("user-list-box").innerText = msg.users.join("\n");
      break;
  }

  if (text.length) {
    f.write(text);
    document.getElementById("chat-box").contentWindow.scrollByPages(1);
  }
};

Здесь мы используем JSON.parse() для преобразования объекта JSON обратно в исходный объект, затем исследуем и обрабатываем его содержимое.

Текстовые данные, полученные через подключение WebSocket, имеют формат UTF-8.

После завершения использования подключения WebSocket вызовите метод WebSocket close():

exampleSocket.close();

Полезно проверить атрибут bufferedAmount сокета перед закрытием подключения, чтобы определить, не осталось ли данных, которые еще предстоит передать в сети. Если это значение не равно 0, существуют ожидающие данные, поэтому вы можете подождать, прежде чем закрыть соединение.

WebSocket не следует использовать в смешанной среде; то есть вы не должны открывать небезопасное подключение WebSocket из страницы, загруженной с использованием HTTPS, и наоборот. Сейчас большинство браузеров допускают только безопасные подключения WebSocket и больше не поддерживают их использование в небезопасных контекстах.