Клиентский API

Ввод/вывод

Выставляется как пространство имён io в автономном сборке или в результате вызова require('socket.io-client').

<script src="/socket.io/socket.io.js"></script><script>  const socket = io('http://localhost');</script>

const io = require('socket.io-client');// or with import syntaximport io from 'socket.io-client';

io.protocol

• (Число)

Номер версии протокола (в настоящее время: 4).

Протокол определяет формат пакетов, обмениваемых между клиентом и сервером. Клиент и сервер должны использовать одну и ту же версию для понимания друг друга.

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

io([url][, options])

• url (Строка) (по умолчанию window.location)
• options (Объект)
  • forceNew (Булево), нужно ли повторно использовать существующее соединение
• Возвращает Socket

Создаёт новый Manager для заданного URL и пытается повторно использовать существующий Manager для последующих вызовов, если опция multiplex не передана со значением false. Передача этой опции эквивалентна передаче 'force new connection': true или forceNew: true.

Возвращается новый экземпляр Socket для пространства имён, указанного в пути URL, по умолчанию /. Например, если url это http://localhost/users, будет установлено транспортное соединение с http://localhost и соединение Socket.IO с /users.

Параметры запроса также могут быть предоставлены, либо в опции query или напрямую в URL (пример: http://localhost/users?token=abc).

const io = require("socket.io-client");const socket = io("ws://example.com/my-namespace", {  reconnectionDelayMax: 10000,  query: {    auth: "123"  }});

является сокращённой формой:

const { Manager } = require("socket.io-client");const manager = new Manager("ws://example.com", {  reconnectionDelayMax: 10000});const socket = manager.socket("/my-namespace", {  query: {    auth: "123"  }});

См. new Manager(url[, options]) для списка доступных options.

Примеры инициализации

С множественным подключением

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

const socket = io();const adminSocket = io('/admin');// a single connection will be established

Это поведение можно отключить с помощью опции forceNew.

const socket = io();const adminSocket = io('/admin', { forceNew: true });// will create two distinct connections

Примечание: повторное использование одного и того же пространства имён также создаст два подключения

const socket = io();const socket2 = io();// will also create two distinct connections

С настраиваемым path

const socket = io('http://localhost', {  path: '/myownpath'});// server-sideconst io = require('socket.io')({  path: '/myownpath'});

URL запросов будут выглядеть так: localhost/myownpath/?EIO=3&transport=polling&sid=<id>.

const socket = io('http://localhost/admin', {  path: '/mypath'});

Здесь сокет подключается к пространству имён admin, с настраиваемым путём mypath.

URL запросов будут выглядеть так: localhost/mypath/?EIO=3&transport=polling&sid=<id> (пространство имён передаётся как часть полезной нагрузки).

С параметрами запроса

const socket = io('http://localhost?token=abc');// server-sideconst io = require('socket.io')();// middlewareio.use((socket, next) => {  let token = socket.handshake.query.token;  if (isValid(token)) {    return next();  }  return next(new Error('authentication error'));});// thenio.on('connection', (socket) => {  let token = socket.handshake.query.token;  // ...});

С опцией запроса

const socket = io({  query: {    token: 'cde'  }});

Содержание запроса также может быть обновлено при повторном подключении:

socket.on('reconnect_attempt', () => {  socket.io.opts.query = {    token: 'fgh'  }});

С extraHeaders

Это работает только если транспорт polling включен (что является значением по умолчанию). Настраиваемые заголовки не будут добавлены при использовании websocket в качестве транспорта. Это происходит потому, что рукопожатие WebSocket не учитывает настраиваемые заголовки. (Для справки см. RFC протокола WebSocket)

const socket = io({  transportOptions: {    polling: {      extraHeaders: {        'x-clientid': 'abc'      }    }  }});// server-sideconst io = require('socket.io')();// middlewareio.use((socket, next) => {  let clientId = socket.handshake.headers['x-clientid'];  if (isValid(clientId)) {    return next();  }  return next(new Error('authentication error'));});

Только с транспортом websocket

По умолчанию сначала устанавливается соединение с помощью долгого опроса, а затем происходит его модернизация до «лучших» транспортов (например, WebSocket). Если вы хотите рискнуть, эту часть можно пропустить:

const socket = io({  transports: ['websocket']});// on reconnection, reset the transports option, as the Websocket// connection may have failed (caused by proxy, firewall, browser, ...)socket.on('reconnect_attempt', () => {  socket.io.opts.transports = ['polling', 'websocket'];});

С настраиваемым парсером

По умолчанию парсер повышает совместимость (поддержка Blob, File, проверка двоичных данных) в ущерб производительности. Настраиваемый парсер может быть предоставлен для соответствия потребностям вашего приложения. Пример см. здесь.

const parser = require('socket.io-msgpack-parser'); // or require('socket.io-json-parser')const socket = io({  parser: parser});// the server-side must have the same parser, to be able to communicateconst io = require('socket.io')({  parser: parser});

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

// server-sideconst fs = require('fs');const server = require('https').createServer({  key: fs.readFileSync('server-key.pem'),  cert: fs.readFileSync('server-cert.pem')});const io = require('socket.io')(server);server.listen(3000);// client-sideconst socket = io({  // option 1  ca: fs.readFileSync('server-cert.pem'),  // option 2. WARNING: it leaves you vulnerable to MITM attacks!  rejectUnauthorized: false});

Менеджер

Manager управляет экземпляром клиента Engine.IO клиента, который является низкоуровневым движком, устанавливающим соединение с сервером (с помощью транспортов, таких как WebSocket или HTTP-опрос с длительным ожиданием).

Manager обрабатывает логику повторного подключения.

Один Manager может использоваться несколькими сокетами. Дополнительную информацию об этой функции множественного использования можно найти здесь.

Обратите внимание, что в большинстве случаев вы не будете использовать Manager напрямую, а будете использовать экземпляр Socket вместо этого.

new Manager(url[, options])

• url (Строка)
• options (Объект)
• Возвращает Manager

Доступные опции:

Доступные опции для базового клиента Engine.IO:

Опции Node.js только для подлежащего клиенту Engine.IO:

manager.reconnection([value])

• value (Булево)
• Возвращает Manager|Boolean

Устанавливает опцию reconnection, или возвращает её, если параметры не переданы.

manager.reconnectionAttempts([value])

• value (Число)
• Возвращает Manager|Number

Устанавливает опцию reconnectionAttempts, или возвращает её, если параметры не переданы.

manager.reconnectionDelay([value])

• value (Число)
• Возвращает Manager|Number

Устанавливает опцию reconnectionDelay, или возвращает её, если параметры не переданы.

manager.reconnectionDelayMax([value])

• value (Число)
• Возвращает Manager|Number

Устанавливает опцию reconnectionDelayMax, или возвращает её, если параметры не переданы.

manager.timeout([value])

• value (Число)
• Возвращает Manager|Number

Устанавливает опцию timeout, или возвращает её, если параметры не переданы.

manager.open([callback])

• callback (Функция)
• Возвращает Manager

Если менеджер был инициализирован с autoConnect в false, запускает новую попытку подключения.

Аргумент callback необязателен и будет вызван, как только попытка завершится/успешно.

manager.connect([callback])

Синоним manager.open([callback]).

manager.socket(nsp, options)

• nsp (Строка)
• options (Объект)
• Возвращает Socket

Создаёт новый Socket для заданного пространства имён.

Event: ‘connect_error’

• error (Объект) объект ошибки

Вызывается при ошибке соединения.

Event: ‘connect_timeout’

Вызывается при таймауте соединения.

Event: ‘reconnect’

• attempt (Число) номер попытки повторного подключения

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

Event: ‘reconnect_attempt’

• attempt (Число) номер попытки повторного подключения

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

Event: ‘reconnecting’

• attempt (Число) номер попытки повторного подключения

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

Event: ‘reconnect_error’

• error (Объект) объект ошибки

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

Event: ‘reconnect_failed’

Вызывается, когда повторное подключение не удалось в течение reconnectionAttempts.

Event: ‘ping’

Вызывается при отправке пакета ping на сервер.

Event: ‘pong’

• ms (Число) число мс, прошедших с момента отправки пакета ping (т.е.: задержка).

Вызывается при получении ответа pong от сервера.

Socket

A Socket — это базовый класс для взаимодействия с сервером. A Socket принадлежит определённому Пространству имён (по умолчанию /) и использует подлежащий Менеджер для связи.

A Socket по сути, EventEmitter, который отправляет события на сервер и принимает события с сервера по сети.

socket.emit('hello', { a: 'b', c: [] });socket.on('hey', (...args) => {  // ...});

socket.id

• (Строка)

Уникальный идентификатор сессии сокета. Устанавливается после срабатывания события connect, и обновляется после события reconnect.

const socket = io('http://localhost');console.log(socket.id); // undefinedsocket.on('connect', () => {  console.log(socket.id); // 'G5p5...'});

socket.connected

• (Булево)

Соединено ли соединение сокета с сервером.

const socket = io('http://localhost');socket.on('connect', () => {  console.log(socket.connected); // true});

socket.disconnected

• (Булево)

Отсоединено ли соединение сокета от сервера.

const socket = io('http://localhost');socket.on('connect', () => {  console.log(socket.disconnected); // false});

socket.open()

• Возвращает Socket

Вручную открывает сокет.

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

Его также можно использовать для ручного повторного подключения:

socket.on('disconnect', () => {  socket.open();});

socket.connect()

Синоним socket.open().

socket.send([…args][, ack])

• args
• ack (Функция)
• Возвращает Socket

Отправляет событие message. См. socket.emit(eventName[, …args][, ack]).

socket.emit(eventName[, …args][, ack])

• eventName (Строка)
• args
• ack (Функция)
• Возвращает Socket

Отправляет событие на сокет, идентифицированный строковым именем. Можно передать дополнительные параметры. Поддерживаются все сериализуемые структуры данных, включая Buffer.

socket.emit('hello', 'world');socket.emit('with-binary', 1, '2', { 3: '4', 5: Buffer.from([6, 7, 8]) });

Аргумент ack — необязательный и будет вызван с ответом сервера.

socket.emit('ferret', 'tobi', (data) => {  console.log(data); // data will be 'woot'});// server://  io.on('connection', (socket) => {//    socket.on('ferret', (name, fn) => {//      fn('woot');//    });//  });

socket.on(eventName, callback)

• eventName (Строка)
• callback (Функция)
• Возвращает Socket

Регистрирует обработчик для заданного события.

socket.on('news', (data) => {  console.log(data);});// with multiple argumentssocket.on('news', (arg1, arg2, arg3, arg4) => {  // ...});// with callbacksocket.on('news', (cb) => {  cb(0);});

Сокет на самом деле наследует все методы класса Emitter, такие как hasListeners, once или off (для удаления обработчика события).

socket.compress(value)

• value (Булево)
• Возвращает Socket

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

socket.compress(false).emit('an event', { some: 'data' });

socket.binary(value)

Указывает, содержит ли отправляемые данные двоичные данные. Увеличивает производительность при указании. Может быть true или false.

socket.binary(false).emit('an event', { some: 'data' });

socket.close()

• Возвращает Socket

Ручное отключение сокета.

socket.disconnect()

Синоним socket.close().

События

Экземпляр Socket излучает все события, отправленные его базовым Manager, которые связаны со статусом соединения с сервером.

Также излучаются события, связанные со статусом соединения с Namespace:

• connect,
• disconnect
• error.

Событие: ‘connect’

Срабатывает при подключении к Namespace (включая успешное повторное подключение).

socket.on('connect', () => {  // ...});// note: you should register event handlers outside of connect,// so they are not registered again on reconnectionsocket.on('myevent', () => {  // ...});

Событие: ‘disconnect’

• reason (Строка)

Срабатывает при отключении. Список возможных причин отключения:

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

socket.on('disconnect', (reason) => {  if (reason === 'io server disconnect') {    // the disconnection was initiated by the server, you need to reconnect manually    socket.connect();  }  // else the socket will automatically try to reconnect});

Событие: ‘error’

• error (Объект) объект ошибки

Срабатывает при возникновении ошибки.

socket.on('error', (error) => {  // ...});

Событие: ‘connect_error’

• error (Объект) объект ошибки

Срабатывает при ошибке подключения.

socket.on('connect_error', (error) => {  // ...});

Событие: ‘connect_timeout’

Срабатывает при истечении срока ожидания подключения.

socket.on('connect_timeout', (timeout) => {  // ...});

Событие: ‘reconnect’

• attempt (Число) номер попытки повторного подключения

Срабатывает при успешном повторном подключении.

socket.on('reconnect', (attemptNumber) => {  // ...});

Событие: ‘reconnect_attempt’

• attempt (Число) номер попытки повторного подключения

Срабатывает при попытке повторного подключения.

socket.on('reconnect_attempt', (attemptNumber) => {  // ...});

Событие: ‘reconnecting’

• attempt (Число) номер попытки повторного подключения

Срабатывает при попытке повторного подключения.

socket.on('reconnecting', (attemptNumber) => {  // ...});

Событие: ‘reconnect_error’

• error (Объект) объект ошибки

Срабатывает при ошибке попытки повторного подключения.

socket.on('reconnect_error', (error) => {  // ...});

Событие: ‘reconnect_failed’

Срабатывает, когда клиент не смог подключиться в течение reconnectionAttempts.

socket.on('reconnect_failed', () => {  // ...});

Событие: ‘ping’

Срабатывает при отправке запроса ping серверу.

socket.on('ping', () => {  // ...});

Событие: ‘pong’

• ms (Число) количество мс, прошедших с момента отправки пакета ping (т.е.: задержка).

Срабатывает при получении ответа pong от сервера.

socket.on('pong', (latency) => {  // ...});