Инициализация клиента

После установки библиотеки клиента Socket.IO вы можете начать инициализацию клиента. Полный список опций представлен ниже.

В примерах ниже объект io получен либо из:

• импорта <script>

<script src="/socket.io/socket.io.js"></script>

• NPM

// ES6 import or TypeScript
import { io } from "socket.io-client";
// CommonJS
const io = require("socket.io-client");

Из одного домена

Если ваш фронтенд размещен на том же домене, что и сервер, вы можете использовать:

const socket = io();

Адрес сервера будет определен из объекта window.location.

С другого домена

Если ваш фронтенд размещен на другом домене, чем сервер, вам необходимо передать URL вашего сервера.

const socket = io("https://server-domain.com");

В этом случае убедитесь, что на сервере включена обработка Cross-Origin Resource Sharing (CORS).

Примечание: Вы можете использовать либо https или wss (соответственно, http или ws).

// the following forms are similar
const socket = io("https://server-domain.com");
const socket = io("wss://server-domain.com");
const socket = io("server-domain.com"); // only in the browser when the page is served over https (will not work in Node.js)

Пользовательский namespace

В примерах выше клиент подключается к основному namespace. Для большинства случаев использования достаточно основного namespace, но вы можете указать namespace с помощью:

// same origin version
const socket = io("/admin");
// cross origin version
const socket = io("https://server-domain.com/admin");

Дополнительную информацию о namespace вы найдете здесь.

Опции

• Опции фабрики IO
  • forceNew
  • multiplex
• Опции низкоуровневого движка
  • transports
  • upgrade
  • rememberUpgrade
  • path
  • query
  • extraHeaders
  • withCredentials
  • forceBase64
  • timestampRequests
  • timestampParam
  • Специфичные для Node.js опции (например, agent, cert или rejectUnauthorized)
• Опции менеджера
  • reconnection
  • reconnectionAttempts
  • reconnectionDelay
  • reconnectionDelayMax
  • randomizationFactor
  • timeout
  • autoConnect
  • parser
• Опции сокета
  • auth

Опции фабрики IO

forceNew

Значение по умолчанию: false

Создавать новый экземпляр менеджера.

Экземпляр менеджера отвечает за низкоуровневое подключение к серверу (установленное с помощью HTTP long-polling или WebSocket). Он обрабатывает логику повторного подключения.

Экземпляр сокета — интерфейс, используемый для отправки событий на сервер и получения событий с сервера. Он принадлежит определенному namespace.

Один менеджер может быть прикреплен к нескольким экземплярам сокетов.

Следующий пример повторно использует один и тот же экземпляр менеджера для 3 экземпляров сокетов (одно единственное WebSocket-подключение):

const socket = io("https://example.com"); // the main namespace
const productSocket = io("https://example.com/product"); // the "product" namespace
const orderSocket = io("https://example.com/order"); // the "order" namespace

Следующий пример создаст 3 различных экземпляра менеджеров (и, следовательно, 3 отдельных WebSocket-соединения):

const socket = io("https://example.com"); // the main namespace
const productSocket = io("https://example.com/product", { forceNew: true }); // the "product" namespace
const orderSocket = io("https://example.com/order", { forceNew: true }); // the "order" namespace

Повторное использование существующего namespace также каждый раз создаст новый менеджер:

const socket1 = io(); // 1st manager
const socket2 = io(); // 2nd manager
const socket3 = io("/admin"); // reuse the 1st manager
const socket4 = io("/admin"); // 3rd manager

multiplex

Значение по умолчанию: true

Обратное forceNew: использовать существующий экземпляр менеджера.

Опции низкоуровневого движка

Примечание: эти настройки будут использоваться всеми экземплярами сокетов, присоединёнными к одному менеджеру.

transports

Значение по умолчанию: ["polling", "websocket"]

Низкоуровневое подключение к серверу Socket.IO может быть установлено с помощью:

• HTTP long-polling: последовательные HTTP-запросы (POST для записи, GET для чтения)
• WebSocket

Следующий пример отключает транспорт HTTP long-polling:

const socket = io("https://example.com", { transports: ["websocket"] });

Примечание: в этом случае «липкие сессии» на стороне сервера не требуются (подробности здесь).

upgrade

Значение по умолчанию: true

Попытать ли клиенту выполнить апгрейд транспорта с HTTP long-polling на что-то более совершенное.

rememberUpgrade

Значение по умолчанию: false

Если true и предыдущее WebSocket-соединение с сервером прошло успешно, попытка соединения пропустит обычный процесс апгрейда и сначала попытается использовать WebSocket. Попытка соединения после ошибки транспорта будет использовать обычный процесс апгрейда. Рекомендуется включить это только при использовании соединений SSL/TLS или если известно, что ваша сеть не блокирует вебсокеты.

path

Значение по умолчанию: /socket.io/

Имя пути, которое захватывается на стороне сервера.

Значения сервера и клиента должны совпадать (если вы не используете прокси для переписывания пути):

Клиент

import { io } from "socket.io-client";

const socket = io("https://example.com", {
  path: "/my-custom-path/"
});

Сервер

const httpServer = require("http").createServer();
const io = require("socket.io")(httpServer, {
  path: "/my-custom-path/"
});

Обратите внимание, что это отличается от пути в URI, который представляет namespace.

Пример:

import { io } from "socket.io-client";

const socket = io("https://example.com/order", {
  path: "/my-custom-path/"
});

• экземпляр Socket прикреплён к namespace “order”
• HTTP-запросы будут выглядеть так: GET https://example.com/my-custom-path/?EIO=4&transport=polling&t=ML4jUwU

query

Значение по умолчанию: -

Дополнительные параметры запроса (позже найдены в объекте socket.handshake.query на стороне сервера).

Пример:

Клиент

import { io } from "socket.io-client";

const socket = io({
  query: {
    x: 42
  }
});

Сервер

io.on("connection", (socket) => {
  console.log(socket.handshake.query); // prints { x: "42", EIO: "4", transport: "polling" }
});

Параметры запроса не могут быть обновлены в течение сессии, поэтому изменение query на стороне клиента будет эффективным только при закрытии текущей сессии и создании новой:

socket.io.on("reconnect_attempt", () => {
  socket.io.opts.query.x++;
});

Примечание: следующие параметры запроса зарезервированы и не могут быть использованы в вашем приложении:

• EIO: версия протокола (в настоящее время «4»)
• transport: имя транспорта («polling» или «websocket»)
• sid: идентификатор сессии
• j: если транспорт — polling, но требуется ответ JSONP
• t: хэшированный временной отметки для обхода кэша

extraHeaders

Значение по умолчанию: -

Дополнительные заголовки (позже найдены в объекте socket.handshake.headers на стороне сервера).

Пример:

Клиент

import { io } from "socket.io-client";

const socket = io({
  extraHeaders: {
    "my-custom-header": "1234"
  }
});

Сервер

io.on("connection", (socket) => {
  console.log(socket.handshake.headers); // an object containing "my-custom-header": "1234"
});

Некоторые замечания:

• это не сработает при использовании только WebSocket в браузере

import { io } from "socket.io-client";

const socket = io({
  transports: ["websocket"],
  extraHeaders: {
    "my-custom-header": "1234" // WARN: this will be ignored in a browser
  }
});

Однако это сработает в Node.js или React-Native.

• вы можете обновлять заголовки во время сессии, но это не будет отражено на стороне сервера (поскольку объект socket.handshake.headers содержит заголовки, отправленные во время рукопожатия Socket.IO).

const socket = io({
  extraHeaders: {
    count: 0
  }
});

setInterval(() => {
  socket.io.opts.extraHeaders.count++;
}, 1000);

withCredentials

Значение по умолчанию: false

Использовать ли учетные данные (например, куки, заголовки авторизации или сертификаты клиента TLS) для кросс-доменных запросов. Установка withCredentials не влияет на запросы в том же домене.

import { io } from "socket.io-client";

const socket = io({
  withCredentials: true
});

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

• XMLHttpRequest.withCredentials
• Обработка CORS

forceBase64

Значение по умолчанию: false

Принудительно использовать кодирование base64 для двоичного содержимого, отправляемого по WebSocket (всегда включено для HTTP long-polling).

timestampRequests

Значение по умолчанию: true

Добавлять ли параметр timestamp к каждому запросу (для обхода кэша).

timestampParam

Значение по умолчанию: "t"

Имя параметра запроса для использования в качестве ключа временной метки.

Опции, специфичные для Node.js

Поддерживаются следующие опции:

• agent
• pfx
• key
• passphrase
• cert
• ca
• ciphers
• rejectUnauthorized

Обратитесь к документации Node.js:

• tls.connect(options[, callback])
• tls.createSecureContext([options])

Пример с самоподписанным сертификатом:

• Клиент

const fs = require("fs");
const socket = require("socket.io-client")("https://example.com", {
  ca: fs.readFileSync("./cert.pem")
});

• Сервер

const fs = require("fs");
const server = require("https").createServer({
  cert: fs.readFileSync("./cert.pem"),
  key: fs.readFileSync("./key.pem")
});
const io = require("socket.io")(server);

Пример с аутентификацией по клиентскому сертификату:

• Клиент

const fs = require("fs");
const socket = require("socket.io-client")("https://example.com", {
  ca: fs.readFileSync("./server-cert.pem"),
  cert: fs.readFileSync("./client-cert.pem"),
  key: fs.readFileSync("./client-key.pem"),
});

• Сервер

const fs = require("fs");
const server = require("https").createServer({
  cert: fs.readFileSync("./server-cert.pem"),
  key: fs.readFileSync("./server-key.pem"),
  requestCert: true,
  ca: [
    fs.readFileSync('client-cert.pem')
  ]
});
const io = require("socket.io")(server);

Важно: rejectUnauthorized — это опция, доступная только в Node.js, она не обойдет проверку безопасности в браузере:

Параметры менеджера

Примечание: Эти настройки будут использоваться всеми экземплярами Socket, подключёнными к одному Manager.

Подключение

Значение по умолчанию: true

Включить или отключить автоматическое подключение. Если установлено значение false, необходимо выполнить подключение вручную:

import { io } from "socket.io-client";

const socket = io({
  reconnection: false
});

const tryReconnect = () => {
  setTimeout(() => {
    socket.io.open((err) => {
      if (err) {
        tryReconnect();
      }
    });
  }, 2000);
}

socket.io.on("close", tryReconnect);

Попытки подключения

Значение по умолчанию: Infinity

Количество попыток подключения перед отказом.

Задержка при подключении

Значение по умолчанию: 1000

Начальная задержка перед повторным подключением в миллисекундах (зависит от значения randomizationFactor).

Максимальная задержка при подключении

Значение по умолчанию: 5000

Максимальная задержка между двумя попытками подключения. Каждая попытка увеличивает задержку в 2 раза.

Коэффициент рандомизации

Значение по умолчанию: 0.5

Коэффициент рандомизации, используемый при повторном подключении (чтобы клиенты не подключались в один и тот же момент после сбоя сервера, например).

Пример со значениями по умолчанию:

• Первая попытка подключения происходит между 500 и 1500 мс (1000 * 2^0 * (<something between -0.5 and 1.5>))
• Вторая попытка подключения происходит между 1000 и 3000 мс (1000 * 2^1 * (<something between -0.5 and 1.5>))
• Третья попытка подключения происходит между 2000 и 5000 мс (1000 * 2^2 * (<something between -0.5 and 1.5>))
• Следующие попытки подключения происходят через 5000 мс

Таймаут

Значение по умолчанию: 20000

Таймаут в миллисекундах для каждой попытки подключения.

Автоподключение

Значение по умолчанию: true

Включить или отключить автоматическое подключение при создании. Если установлено значение false, необходимо выполнить подключение вручную:

import { io } from "socket.io-client";

const socket = io({
  autoConnect: false
});

socket.connect();
// or
socket.io.open();

parser

Значение по умолчанию: require("socket.io-parser")

Парсер, используемый для сериализации/десериализации пакетов. Подробности см. здесь.

Параметры сокета

Примечание: Эти настройки специфичны для данного экземпляра Socket.

auth

Значение по умолчанию: -

Учётные данные, которые отправляются при доступе к пространству имён (см. также здесь).

Пример:

Клиент

import { io } from "socket.io-client";

const socket = io({
  auth: {
    token: "abcd"
  }
});

Сервер

io.on("connection", (socket) => {
  console.log(socket.handshake.auth); // prints { token: "abcd" }
});

Вы можете обновить карту auth при отказе в доступе к пространству имён:

socket.on("connect_error", (err) => {
  if (err.message === "invalid credentials") {
    socket.auth.token = "efgh";
    socket.connect();
  }
});

Или принудительно переподключить экземпляр Socket:

socket.auth.token = "efgh";
socket.disconnect().connect();