Параметры клиента

Параметры фабрики IO

forceNew

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

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

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

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

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

Следующий пример повторно использует один и тот же экземпляр Manager для 3 экземпляров Socket (одно единственное 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 разных экземпляра Manager (и, следовательно, 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

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

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: повторно использовать существующий экземпляр Manager.

const socket = io(); // 1st manager
const adminSocket = io("/admin", { multiplex: false }); // 2nd manager

Параметры низкоуровневого движка

transports

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

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

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

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

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

Примечание: в этом случае на стороне сервера не нужны «sticky sessions» (подробнее здесь).

По умолчанию сначала устанавливается HTTP long-polling соединение, а затем происходит попытка обновления до WebSocket (объяснение здесь). Вы можете использовать WebSocket первым с помощью:

const socket = io("https://example.com", {
  transports: ["websocket", "polling"] // use WebSocket first, if available
});

socket.on("connect_error", () => {
  // revert to classic upgrade
  socket.io.opts.transports = ["polling", "websocket"];
});

Один из возможных недостатков заключается в том, что правильность вашей настройки CORS будет проверена только в случае неудачи при установлении 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/"
});

Сервер

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  path: "/my-custom-path/"
});

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

Пример:

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

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

• экземпляр Socket подключен к пространству имен "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"
});

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

const socket = io({
  transports: ["websocket"],
  extraHeaders: {
    "my-custom-header": "1234" // ignored
  }
});

Документация: API веб-сокетов

withCredentials

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

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

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

const socket = io("https://my-backend.com", {
  withCredentials: true
});

Серверу необходимо отправить правильные Access-Control-Allow-* заголовки, чтобы разрешить подключение:

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  cors: {
    origin: "https://my-frontend.com",
    credentials: true
  }
});

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

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

forceBase64

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

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

timestampRequests

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

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

timestampParam

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

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

closeOnBeforeunload

Добавлена в v4.1.0

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

Закрывать ли соединение (неявно) при возникновении события beforeunload в браузере.

При closeOnBeforeunload установлено в false, Socket-инстанс будет генерировать событие disconnect, когда пользователь перезагружает страницу в Firefox (но не в Chrome или Safari).

При closeOnBeforeunload установлено в true, все браузеры будут иметь одинаковое поведение (событие disconnect не будет генерироваться при перезагрузке страницы). Однако это может вызвать проблемы, если вы используете событие beforeunload в своем приложении.

protocols

Добавлена в v2.0.0

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

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

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

const socket = io({
  transports: ["websocket"],
  protocols: ["my-protocol-v1"]
});

Сервер:

io.on("connection", (socket) => {
  const transport = socket.conn.transport;
  console.log(transport.socket.protocol); // prints "my-protocol-v1"
});

Ссылки:

• https://datatracker.ietf.org/doc/html/rfc6455#section-1.9
• https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket

autoUnref

Добавлена в v4.0.0

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

Если autoUnref установлено в true, клиент Socket.IO позволит программе выйти, если в системе событий нет других активных таймеров/TCP-сокет (даже если клиент подключен):

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

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

См. также: https://nodejs.org/api/timers.html#timeoutunref

Параметры, специфичные для Node.js

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

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

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

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

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

Клиент

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

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

Сервер

import { readFileSync } from "fs";
import { createServer } from "https";
import { Server } from "socket.io";

const httpServer = createServer({
  cert: readFileSync("./cert.pem"),
  key: readFileSync("./key.pem")
});
const io = new Server(httpServer);

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

Клиент

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

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

Сервер

import { readFileSync } from "fs";
import { createServer } from "https";
import { Server } from "socket.io";

const httpServer = createServer({
  cert: readFileSync("./server-cert.pem"),
  key: readFileSync("./server-key.pem"),
  requestCert: true,
  ca: [
    readFileSync("client-cert.pem")
  ]
});
const io = new Server(httpServer);

Параметры Manager

reconnection

Значение по умолчанию: 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);

reconnectionAttempts

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

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

reconnectionDelay

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

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

reconnectionDelayMax

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

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

randomizationFactor

Значение по умолчанию: 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 мс

timeout

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

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

autoConnect

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

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

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

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

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

parser

Добавлено в v2.2.0

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

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

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

auth

Добавлено в v3.0.0

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

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

Пример:

Клиент

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

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

// or with a function
const socket = io({
  auth: (cb) => {
    cb({ token: localStorage.token })
  }
});

Сервер

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.auth.token = "efgh";
socket.disconnect().connect();