Серверный API

Сервер

Экспонируется require('socket.io').

новый Server(httpServer[, options])

• httpServer (http.Server) сервер для привязки.
• options (Объект)

Работает с new и без него:

const io = require('socket.io')();// orconst Server = require('socket.io');const io = new Server();

Доступные параметры:

Доступные параметры для сервера Engine.IO:

Среди этих параметров:

• Параметры pingTimeout и pingInterval повлияют на задержку, прежде чем клиент узнает, что сервер недоступен. Например, если базовое TCP-соединение не закрыто должным образом из-за проблемы с сетью, клиенту может потребоваться до pingTimeout + pingInterval мс, прежде чем он получит событие disconnect.

• Порядок массива transports важен. По умолчанию сначала устанавливается соединение long-polling, а затем, если возможно, переключается на WebSocket. Использование ['websocket'] означает, что отката не будет, если соединение WebSocket не может быть открыто.

const server = require('http').createServer();const io = require('socket.io')(server, {  path: '/test',  serveClient: false,  // below are engine.IO options  pingInterval: 10000,  pingTimeout: 5000,  cookie: false});server.listen(3000);

новый Server(port[, options])

• port (Число) порт для прослушивания (будет создан новый http.Server)
• options (Объект)

См. выше для списка доступных options.

const io = require('socket.io')(3000, {  path: '/test',  serveClient: false,  // below are engine.IO options  pingInterval: 10000,  pingTimeout: 5000,  cookie: false});

новый Server(options)

• options (Объект)

См. выше для списка доступных options.

const io = require('socket.io')({  path: '/test',  serveClient: false,});// eitherconst server = require('http').createServer();io.attach(server, {  pingInterval: 10000,  pingTimeout: 5000,  cookie: false});server.listen(3000);// orio.attach(3000, {  pingInterval: 10000,  pingTimeout: 5000,  cookie: false});

server.sockets

• (Пространство имён)

Псевдоним для стандартного (/) пространства имён.

io.sockets.emit('hi', 'everyone');// is equivalent toio.of('/').emit('hi', 'everyone');

server.serveClient([value])

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

Если value имеет значение true, присоединённый сервер (см. Server#attach) будет предоставлять файлы клиента. По умолчанию true. Этот метод не имеет эффекта после вызова attach. Если аргументы не указаны, этот метод возвращает текущее значение.

// pass a server and the `serveClient` optionconst io = require('socket.io')(http, { serveClient: false });// or pass no server and then you can call the methodconst io = require('socket.io')();io.serveClient(false);io.attach(http);

server.path([value])

• value (Строка)
• Возвращает Server|String

Устанавливает путь value, под которым engine.io и статические файлы будут предоставлены. По умолчанию /socket.io. Если аргументы не указаны, этот метод возвращает текущее значение.

const io = require('socket.io')();io.path('/myownpath');// client-sideconst socket = io({  path: '/myownpath'});

server.adapter([value])

• value (Адаптер)
• Возвращает Server|Adapter

Устанавливает адаптер value. По умолчанию экземпляр Adapter, поставляемый с socket.io, основанный на памяти. См. socket.io-adapter. Если аргументы не указаны, этот метод возвращает текущее значение.

const io = require('socket.io')(3000);const redis = require('socket.io-redis');io.adapter(redis({ host: 'localhost', port: 6379 }));

server.origins([value])

• value (Строка|Массив строк)
• Возвращает Server|String

Устанавливает разрешённые источники value. По умолчанию разрешены все источники. Если аргументы не указаны, этот метод возвращает текущее значение.

io.origins(['https://foo.example.com:443']);

server.origins(fn)

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

Предоставляет функцию, принимающую два аргумента origin:String и callback(error, success), где success - логическое значение, указывающее, разрешен ли источник или нет. Если success установлено в false, error должен быть предоставлен как строковое значение, которое будет добавлено к ответу сервера, например, “Origin not allowed”.

Возможные недостатки:

• в некоторых ситуациях, когда невозможно определить origin значение может быть *
• Поскольку эта функция будет выполняться для каждого запроса, рекомендуется сделать эту функцию максимально быстрой.
• Если socket.io используется вместе с Express, заголовки CORS будут изменены только для socket.io запросов. Для Express можно использовать cors.

io.origins((origin, callback) => {  if (origin !== 'https://foo.example.com') {    return callback('origin not allowed', false);  }  callback(null, true);});

server.attach(httpServer[, options])

• httpServer (http.Server) сервер для привязки
• options (Объект)

Присоединяет Server к экземпляру engine.io на httpServer с предоставленным options (по желанию).

server.attach(port[, options])

• port (Число) порт для прослушивания
• options (Объект)

Присоединяет Server к экземпляру engine.io на новом http.Server с предоставленным options (по желанию).

server.listen(httpServer[, options])

Синоним server.attach(httpServer[, options]).

server.listen(port[, options])

Синоним server.attach(port[, options]).

server.bind(engine)

• engine (engine.Server)
• Возвращает Server

Используется только в продвинутых случаях. Привязывает сервер к конкретному экземпляру engine.io Server (или совместимого API).

server.onconnection(socket)

• socket (engine.Socket)
• Возвращает Server

Только для расширенного использования. Создаёт нового socket.io клиента из входящего engine.io (или совместимого API) Socket.

server.of(nsp)

• nsp (Строка|Регулярное выражение|Функция)
• Возвращает Namespace

Инициализирует и возвращает заданный Namespace по его идентификатору пути nsp. Если пространство имён уже было инициализировано, оно возвращается сразу.

const adminNamespace = io.of('/admin');

Также можно указать регулярное выражение или функцию для динамического создания пространства имён:

const dynamicNsp = io.of(/^\/dynamic-\d+$/).on('connection', (socket) => {  const newNamespace = socket.nsp; // newNamespace.name === '/dynamic-101'  // broadcast to all clients in the given sub-namespace  newNamespace.emit('hello');});// client-sideconst socket = io('/dynamic-101');// broadcast to all clients in each sub-namespacedynamicNsp.emit('hello');// use a middleware for each sub-namespacedynamicNsp.use((socket, next) => { /* ... */ });

С помощью функции:

io.of((name, query, next) => {  // the checkToken method must return a boolean, indicating whether the client is able to connect or not.  next(null, checkToken(query.token));}).on('connection', (socket) => { /* ... */ });

server.close([callback])

• callback (Функция)

Закрывает сервер socket.io. Аргумент callback является необязательным и будет вызван, когда все подключения будут закрыты.

const Server = require('socket.io');const PORT   = 3030;const server = require('http').Server();const io = Server(PORT);io.close(); // Close current serverserver.listen(PORT); // PORT is free to useio = Server(server);

server.engine.generateId

Переопределяет метод по умолчанию для генерации собственного идентификатора сокета.

Функция вызывается с объектом запроса Node.js (http.IncomingMessage) в качестве первого параметра.

io.engine.generateId = (req) => {  return "custom:id:" + custom_id++; // custom id must be unique}

Пространство имён

Представляет собой набор сокетов, подключенных в заданном пространстве, идентифицируемом путём (например: /chat).

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

Для получения информации о «как» и «почему», пожалуйста, обратитесь к разделу: Комнаты и пространства имён.

namespace.name

• (Строка)

Свойство идентификатора пространства имён.

namespace.connected

• (Объект)

Хэш объектов Socket, подключённых к этому пространству имён, индексированный по id.

namespace.adapter

• (Adapter)

Adapter Adapter используемый для пространства имён. Полезно при использовании Adapter на основе Redis, поскольку он предоставляет методы для управления сокетами и комнатами в вашем кластере.

Примечание: адаптер основного пространства имён можно получить с помощью io.of('/').adapter.

namespace.to(room)

• room (Строка)
• Возвращает Namespace для цепочки вызовов

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

Для отправки события в несколько комнат, можно вызвать to несколько раз.

const io = require('socket.io')();const adminNamespace = io.of('/admin');adminNamespace.to('level1').emit('an event', { some: 'data' });

namespace.in(room)

Синоним namespace.to(room).

namespace.emit(eventName[, …args])

• eventName (Строка)
• args

Отправляет событие всем подключённым клиентам. Следующие два варианта эквивалентны:

const io = require('socket.io')();io.emit('an event sent to all connected clients'); // main namespaceconst chat = io.of('/chat');chat.emit('an event sent to all connected clients in chat namespace');

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

namespace.clients(callback)

• callback (Функция)

Получает список идентификаторов клиентов, подключенных к этому пространству имён (по всем узлам, если применимо).

const io = require('socket.io')();io.of('/chat').clients((error, clients) => {  if (error) throw error;  console.log(clients); // => [PZDoMHjiu8PYfRiKAAAF, Anw2LatarvGVVXEIAAAD]});

Пример получения всех клиентов в комнате пространства имён:

io.of('/chat').in('general').clients((error, clients) => {  if (error) throw error;  console.log(clients); // => [Anw2LatarvGVVXEIAAAD]});

По умолчанию, рассылка производится всем клиентам из основного пространства имён (‘/’):

io.clients((error, clients) => {  if (error) throw error;  console.log(clients); // => [6em3d4TJP8Et9EMNAAAA, G5p55dHhGgUnLUctAAAB]});

namespace.use(fn)

• fn (Функция)

Регистрирует middleware, которая является функцией, выполняемой для каждого входящего Socket, и получает в качестве параметров сокет и функцию для отложенного выполнения следующему зарегистрированному middleware.

Ошибки, переданные в обратные вызовы middleware, отправляются как специальные пакеты error клиентам.

io.use((socket, next) => {  if (socket.request.headers.cookie) return next();  next(new Error('Authentication error'));});

Событие: ‘connect’

• socket (Socket) подключение сокета с клиентом

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

io.on('connection', (socket) => {  // ...});io.of('/admin').on('connection', (socket) => {  // ...});

Событие: ‘connection’

Синоним Событие: ‘connect’.

Флаг: ‘volatile’

Устанавливает модификатор для последующей отправки события, что данные события могут быть потеряны, если клиенты не готовы получить сообщения (из-за медленной сети или других проблем, или потому что они подключены через длинное опроса и находятся в процессе цикла «запрос-ответ»).

io.volatile.emit('an event', { some: 'data' }); // the clients may or may not receive it

Флаг: ‘binary’

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

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

Флаг: ‘local’

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

io.local.emit('an event', { some: 'data' });

Сокет

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

Следует отметить, что Socket не имеет прямого отношения к фактическому подлежащему TCP/IP socket и это только название класса.

В каждом Namespace, вы также можете определить произвольные каналы (называемые room), к которым Socket может присоединиться и выйти. Это предоставляет удобный способ рассылки сообщения группе Socket (см. Socket#to ниже).

Класс Socket наследуется от EventEmitter. Класс Socket переопределяет метод emit, и не изменяет другие методы EventEmitter. Все описанные здесь методы, которые также присутствуют в методах EventEmitter, кроме emit, реализованы в EventEmitter, и документация для EventEmitter применима.

socket.id

• (Строка)

Уникальный идентификатор сессии, полученный от базового Client.

socket.rooms

• (Объект)

Хэш строк, идентифицирующих комнаты, в которых находится этот клиент, индексированный по имени комнаты.

io.on('connection', (socket) => {  socket.join('room 237', () => {    let rooms = Object.keys(socket.rooms);    console.log(rooms); // [ <socket.id>, 'room 237' ]  });});

socket.client

• (Клиент)

Ссылка на подлежащий объект Client.

socket.conn

• (engine.Socket)

Ссылка на подключение подлежащего транспорта Client (объект engine.io Socket). Это позволяет получить доступ к слою транспорта IO, который по-прежнему (в основном) абстрагирует фактический сокет TCP/IP.

socket.request

• (Запрос)

Прокси-свойство, возвращающее ссылку на request , который инициировал подлежащий engine.io Client. Полезно для доступа к заголовкам запроса, таким как Cookie или User-Agent.

const cookie = require('cookie');io.on('connection', (socket) => {  const cookies = cookie.parse(socket.request.headers.cookie || '');});

socket.handshake

• (Объект)

Детали рукопожатия:

{  headers: /* the headers sent as part of the handshake */,  time: /* the date of creation (as string) */,  address: /* the ip of the client */,  xdomain: /* whether the connection is cross-domain */,  secure: /* whether the connection is secure */,  issued: /* the date of creation (as unix timestamp) */,  url: /* the request URL string */,  query: /* the query object */}

Использование:

io.use((socket, next) => {  let handshake = socket.handshake;  // ...});io.on('connection', (socket) => {  let handshake = socket.handshake;  // ...});

socket.use(fn)

• fn (Функция)

Регистрирует middleware, которая является функцией, выполняемой для каждого входящего Packet и получает в качестве параметра пакет и функцию для отложенного выполнения следующему зарегистрированному middleware.

Ошибки, переданные в обратные вызовы middleware, отправляются как специальные пакеты error клиентам.

io.on('connection', (socket) => {  socket.use((packet, next) => {    if (packet.doge === true) return next();    next(new Error('Not a doge error'));  });});

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

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

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

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

(переопределяет EventEmitter.emit)

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

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

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

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

io.on('connection', (socket) => {  socket.emit('an event', { some: 'data' });  socket.emit('ferret', 'tobi', (data) => {    console.log(data); // data will be 'woot'  });  // the client code  // client.on('ferret', (name, fn) => {  //   fn('woot');  // });});

socket.on(eventName, callback)

(унаследовано от EventEmitter)

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

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

socket.on('news', (data) => {  console.log(data);});// with several argumentssocket.on('news', (arg1, arg2, arg3) => {  // ...});// or with acknowledgementsocket.on('news', (data, callback) => {  callback(0);});

socket.once(eventName, listener)

socket.removeListener(eventName, listener)

socket.removeAllListeners([eventName])

socket.eventNames()

Унаследовано от EventEmitter (вместе с другими методами, не упомянутыми здесь). Смотрите документацию Node.js для модуля events.

socket.join(room[, callback])

• room (Строка)
• callback (Функция)
• Возвращает Socket для цепочки вызовов

Добавляет клиента в room, и, необязательно, вызывает обратный вызов со err подписью (если указан).

io.on('connection', (socket) => {  socket.join('room 237', () => {    let rooms = Object.keys(socket.rooms);    console.log(rooms); // [ <socket.id>, 'room 237' ]    io.to('room 237').emit('a new user has joined the room'); // broadcast to everyone in the room  });});

Механизм присоединения к комнатам обрабатывается настроенным Adapter (см. Server#adapter выше), по умолчанию socket.io-adapter.

Для удобства каждый сокет автоматически присоединяется к комнате, идентифицируемой его id (см. Socket#id). Это упрощает рассылку сообщений другим сокетам:

io.on('connection', (socket) => {  socket.on('say to someone', (id, msg) => {    // send a private message to the socket with the given id    socket.to(id).emit('my message', msg);  });});

socket.join(rooms[, callback])

• rooms (Массив)
• callback (Функция)
• Возвращает Socket для цепочки вызовов

Добавляет клиента в список комнат и, необязательно, вызывает обратный вызов со err подписью (если указан).

io.on('connection', (socket) => {  socket.join(['room 237', 'room 238'], () => {    const rooms = Object.keys(socket.rooms);    console.log(rooms); // [ <socket.id>, 'room 237', 'room 238' ]    io.to('room 237').to('room 238').emit('a new user has joined the room'); // broadcast to everyone in both rooms  });});

socket.leave(room[, callback])

• room (Строка)
• callback (Функция)
• Возвращает Socket для цепочки вызовов

Удаляет клиента из room, и, необязательно, вызывает обратный вызов со err подписью (если указан).

io.on('connection', (socket) => {  socket.leave('room 237', () => {    io.to('room 237').emit(`user ${socket.id} has left the room`);  });});

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

socket.to(room)

• room (Строка)
• Возвращает Socket для цепочки вызовов

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

Для отправки в несколько комнат, вы можете вызвать to несколько раз.

io.on('connection', (socket) => {  // to one room  socket.to('others').emit('an event', { some: 'data' });  // to multiple rooms  socket.to('room1').to('room2').emit('hello');  // a private message to another socket  socket.to(/* another socket id */).emit('hey');  // WARNING: `socket.to(socket.id).emit()` will NOT work, as it will send to everyone in the room  // named `socket.id` but the sender. Please use the classic `socket.emit()` instead.});

Примечание: подтверждения не поддерживаются при рассылке.

socket.in(room)

Синоним socket.to(room).

socket.compress(value)

• value (Булево), указывает, будет ли последующий пакет сжат
• Возвращает Socket для цепочки вызовов

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

io.on('connection', (socket) => {  socket.compress(false).emit('uncompressed', "that's rough");});

socket.disconnect(close)

• close (Булево), указывает, следует ли закрыть базовое соединение
• Возвращает Socket

Отключает этого клиента. Если значение close true, закрывает базовое соединение. В противном случае просто отключает пространство имен.

io.on('connection', (socket) => {  setTimeout(() => socket.disconnect(true), 5000);});

Флаг: ‘broadcast’

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

io.on('connection', (socket) => {  socket.broadcast.emit('an event', { some: 'data' }); // everyone gets it but the sender});

Флаг: ‘volatile’

Устанавливает модификатор для последующей отправки события, что данные события могут быть потеряны, если клиент не готов получать сообщения (из-за медленной сети или других проблем, или если подключение через длинный опрос и находится в процессе цикла «запрос-ответ»).

io.on('connection', (socket) => {  socket.volatile.emit('an event', { some: 'data' }); // the client may or may not receive it});

Флаг: ‘binary’

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

const io = require('socket.io')();io.on('connection', (socket) => {  socket.binary(false).emit('an event', { some: 'data' }); // The data to send has no binary data});

Событие: ‘disconnect’

• reason (Строка) причина отключения (клиентская или серверная)

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

io.on('connection', (socket) => {  socket.on('disconnect', (reason) => {    // ...  });});

Возможные причины:

Событие: ‘error’

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

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

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

Событие: ‘disconnecting’

• reason (Строка) причина отключения (клиентская или серверная)

Срабатывает, когда клиент отключается (но еще не покинул rooms).

io.on('connection', (socket) => {  socket.on('disconnecting', (reason) => {    let rooms = Object.keys(socket.rooms);    // ...  });});

Это резервированные события (вместе с connect, newListener и removeListener), которые нельзя использовать в качестве имён событий.

Клиент

Класс Client представляет входящее соединение транспорта (engine.io). Один Client может быть связан со многими мультиплексированными Socket , принадлежащими разным Namespace.

client.conn

• (engine.Socket)

Ссылка на базовое соединение engine.io Socket.

client.request

• (Запрос)

Прокси-метод-получатель, который возвращает ссылку на request , который инициировал соединение engine.io. Полезно для доступа к заголовкам запроса, таким как Cookie или User-Agent.