Серверный API

Сервер

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

Связанные страницы документации:

• установка
• инициализация
• подробности экземпляра сервера

new Server(httpServer[, options])

• httpServer (http.Server) сервер, к которому нужно привязаться.
• options (Объект)

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

const io = require("socket.io")();
// or
const { Server } = require("socket.io");
const io = new Server();

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

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

Дополнительная информация здесь.

new 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
});

new Server(options)

• options (Объект)

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

const io = require("socket.io")({
  path: "/test",
  serveClient: false,
});

// either
const server = require("http").createServer();

io.attach(server, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.listen(3000);

// or
io.attach(3000, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.sockets

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

Псевдоним для пространства имен по умолчанию (/).

io.sockets.emit("hi", "everyone");
// is equivalent to
io.of("/").emit("hi", "everyone");

server.serveClient([value])

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

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

// pass a server and the `serveClient` option
const io = require("socket.io")(http, { serveClient: false });

// or pass no server and then you can call the method
const 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-side
const 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.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-side
const socket = io("/dynamic-101");

// broadcast to all clients in each sub-namespace
dynamicNsp.emit("hello");

// use a middleware for each sub-namespace
dynamicNsp.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 необязателен и будет вызван, когда все подключения будут закрыты.

Примечание: это также закрывает лежащий в основе HTTP-сервер.

const Server = require("socket.io");
const PORT   = 3030;
const server = require("http").Server();

const io = Server(PORT);

io.close(); // Close current server

server.listen(PORT); // PORT is free to use

io = Server(server);

server.engine.generateId

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

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

const uuid = require("uuid");

io.engine.generateId = (req) => {
  return uuid.v4(); // must be unique across all Socket.IO servers
}

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

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

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

namespace.name

• (Строка)

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

namespace.sockets

• (Карта<SocketId, Socket>)

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

// number of sockets in this namespace (on this node)
const socketCount = io.of("/admin").sockets.size;

пространство имен.адаптер

• (Адаптер)

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

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

См. объяснение здесь.

пространство имен.к(комната)

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

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

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

const io = require("socket.io")();
const adminNamespace = io.of("/admin");

adminNamespace.to("level1").emit("an event", { some: "data" });

пространство имен.в(комната)

Синоним пространство имен.к(комната).

пространство имен.emit(имяСобытия[, …аргументы])

• eventName (Строка)
• args
• Возвращает true

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

const io = require("socket.io")();
io.emit("an event sent to all connected clients"); // main namespace

const chat = io.of("/chat");
chat.emit("an event sent to all connected clients in chat namespace");

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

пространство имен.allSockets()

• Возвращает Promise<Set<SocketId>>

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

// all sockets in the main namespace
const ids = await io.allSockets();

// all sockets in the main namespace and in the "user:1234" room
const ids = await io.in("user:1234").allSockets();

// all sockets in the "chat" namespace
const ids = await io.of("/chat").allSockets();

// all sockets in the "chat" namespace and in the "general" room
const ids = await io.of("/chat").in("general").allSockets();

пространство имен.use(функция)

• fn (Функция)

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

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

// server-side
io.use((socket, next) => {
  const err = new Error("not authorized");
  err.data = { content: "Please retry later" }; // additional details
  next(err);
});

// client-side
socket.on("connect_error", err => {
  console.log(err instanceof Error); // true
  console.log(err.message); // not authorized
  console.log(err.data); // { content: "Please retry later" }
});

Событие: ‘connection’

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

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

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

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

Событие: ‘connect’

Синоним Событие: “connection”.

Флаг: ‘volatile’

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

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

Флаг: ‘local’

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

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

Сокет

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

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

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

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

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

socket.id

• (Строка)

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

socket.rooms

• (Множество)

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

io.on("connection", (socket) => {

  console.log(socket.rooms); // Set { <socket.id> }

  socket.join("room1");

  console.log(socket.rooms); // Set { <socket.id>, "room1" }

});

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 params of the first request */,
  auth: /* the authentication payload */
}

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

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

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

socket.send([…аргументы][, подтверждение])

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

Отправляет событие message. См. socket.emit(имяСобытия[, …аргументы][, подтверждение]).

socket.emit(имяСобытия[, …аргументы][, подтверждение])

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

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

Отправляет событие с заданным именем сокету. Можно включить любые другие параметры. Поддерживаются все сериализуемые структуры данных, включая 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(имяСобытия, колбэк)

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

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

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

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

socket.once(имяСобытия, обработчик)

socket.removeListener(имяСобытия, обработчик)

socket.removeAllListeners([имяСобытия])

socket.eventNames()

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

socket.onAny(колбэк)

• callback (Функция)

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

socket.onAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.prependAny(колбэк)

• callback (Функция)

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

socket.prependAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.offAny([обработчик])

• listener (Функция)

Удаляет ранее зарегистрированный обработчик. Если обработчик не указан, удаляются все универсальные обработчики.

const myListener = () => { /* ... */ };

socket.onAny(myListener);

// then, later
socket.offAny(myListener);

socket.offAny();

socket.listenersAny()

• Возвращает Function[]

Возвращает список зарегистрированных универсальных обработчиков.

const listeners = socket.listenersAny();

socket.join(комната)

• room (строка) | (массив строк)
• Возвращает void | Promise

Добавляет сокет в заданную room или в список комнат.

io.on("connection", (socket) => {
  socket.join("room 237");
  
  console.log(socket.rooms); // Set { <socket.id>, "room 237" }

  socket.join(["room 237", "room 238"]);

  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.leave(комната)

• room (Строка)
• Возвращает void | Promise

Удаляет сокет из заданной room.

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
});

Событие: ‘disconnect’

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

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

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

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

Событие: ‘disconnecting’

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

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

io.on("connection", (socket) => {
  socket.on("disconnecting", (reason) => {
    console.log(socket.rooms); // Set { ... }
  });
});

Примечание: эти события, наряду с connect, connect_error, newListener и removeListener, являются специальными событиями, которые не следует использовать в вашем приложении:

// BAD, will throw an error
socket.emit("disconnect");

Клиент

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

client.conn

• (engine.Socket)

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

client.request

• (Request)

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