Attaches the Socket.IO server to an µWebSockets.js app:

import { App } from "uWebSockets.js";
import { Server } from "socket.io";
const app = new App();
const io = new Server();
io.attachApp(app);
io.on("connection", (socket) => {
  // ...
});
app.listen(3000, (token) => {
  if (!token) {
    console.warn("port already in use");
  }
});

server.listen(httpServer[, options])

Synonym of server.attach(httpServer[, options]).

server.listen(port[, options])

Synonym of server.attach(port[, options]).

server.on(eventName, listener)

Inherited from the EventEmitter class.

• eventName |
• listener
• Returns

Adds the listener function to the end of the listeners array for the event named eventName.

Available events:

• connection
• new_namespace
• any custom event from the serverSideEmit method

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

server.bind(engine)

• engine <engine.Server>
• Returns

Advanced use only. Binds the server to a specific engine.io Server (or compatible API) instance.

import { Server } from "socket.io";
import { Server as Engine } from "engine.io";
const engine = new Engine();
const io = new Server();
io.bind(engine);
engine.listen(3000);

server.onconnection(socket)

• socket <engine.Socket>
• Returns

Advanced use only. Creates a new socket.io client from the incoming engine.io (or compatible API) Socket.

import { Server } from "socket.io";
import { Server as Engine } from "engine.io";
const engine = new Engine();
const io = new Server();
engine.on("connection", (socket) => {
  io.onconnection(socket);
});
engine.listen(3000);

server.of(nsp)

• nsp | |
• Returns

Initializes and retrieves the given Namespace by its pathname identifier nsp. If the namespace was already initialized it returns it immediately.

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

A regex or a function can also be provided, in order to create namespace in a dynamic way:

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) => { /* ... */ });

With a function:

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

Closes the Socket.IO server and disconnect all clients. The callback argument is optional and will be called when all connections are closed.

信息

This also closes the underlying HTTP server.

import { createServer } from "http";
import { Server } from "socket.io";
const PORT = 3030;
const io = new Server(PORT);
io.close();
const httpServer = createServer();
httpServer.listen(PORT); // PORT is free to use
io.attach(httpServer);

备注

Only closing the underlying HTTP server is not sufficient, as it will only prevent the server from accepting new connections but clients connected with WebSocket will not be disconnected right away.

Reference: https://nodejs.org/api/http.html#serverclosecallback

server.engine

A reference to the underlying Engine.IO server. See here.

server.socketsJoin(rooms)

Added in v4.0.0

Alias for io.of(“/“).socketsJoin(rooms).

// make all Socket instances join the "room1" room
io.socketsJoin("room1");
// make all Socket instances in the "room1" room join the "room2" and "room3" rooms
io.in("room1").socketsJoin(["room2", "room3"]);
// this also works with a single socket ID
io.in(theSocketId).socketsJoin("room1");

See here.

server.socketsLeave(rooms)

Added in v4.0.0

Alias for io.of(“/“).socketsLeave(rooms).

// make all Socket instances leave the "room1" room
io.socketsLeave("room1");
// make all Socket instances in the "room1" room leave the "room2" and "room3" rooms
io.in("room1").socketsLeave(["room2", "room3"]);
// this also works with a single socket ID
io.in(theSocketId).socketsLeave("room1");

See here.

server.disconnectSockets([close])

Added in v4.0.0

Alias for io.of(“/“).disconnectSockets(close).

// make all Socket instances disconnect
io.disconnectSockets();
// make all Socket instances in the "room1" room disconnect (and close the low-level connection)
io.in("room1").disconnectSockets(true);

See here.

server.fetchSockets()

Added in v4.0.0

Alias for io.of(“/“).fetchSocket().

// return all Socket instances of the main namespace
const sockets = await io.fetchSockets();
// return all Socket instances in the "room1" room of the main namespace
const sockets = await io.in("room1").fetchSockets();

Sample usage:

io.on("connection", (socket) => {
  const userId = computeUserId(socket);
  socket.join(userId);
  socket.on("disconnect", async () => {
    const sockets = await io.in(userId).fetchSockets();
    if (socket.length === 0) {
      // no more active connections for the given user
    }
  });
});

See here.

server.serverSideEmit(eventName[, …args][, ack])

Added in v4.1.0

Alias for: io.of(“/“).serverSideEmit(/* … */);

Event: connection

• socket (Socket) socket connection with client

Fired upon a connection from client.

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

Event: connect

Synonym of Event: “connection”.

Event: new_namespace

• namespace Namespace

Fired when a new namespace is created:

io.on("new_namespace", (namespace) => {
  // ...
});

This can be useful for example:

• to attach a shared middleware to each namespace

io.on("new_namespace", (namespace) => {
  namespace.use(myMiddleware);
});

• to track the dynamically created namespaces

io.of(/\/nsp-\w+/);
io.on("new_namespace", (namespace) => {
  console.log(namespace.name);
});

Namespace

Represents a pool of sockets connected under a given scope identified by a pathname (eg: /chat).

More information can be found here.

namespace.name

The namespace identifier property.

namespace.sockets

• Map

A map of Socket instances that are connected to this namespace.

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

namespace.adapter

The “Adapter” used for the namespace.

Note: the adapter of the main namespace can be accessed with io.of("/").adapter.

More information about it here.

const adapter = io.of("/my-namespace").adapter;

namespace.to(room)

History

• room |
• Returns BroadcastOperator for chaining

Sets a modifier for a subsequent event emission that the event will only be broadcast to clients that have joined the given room.

To emit to multiple rooms, you can call to several times.

const io = require("socket.io")();
const adminNamespace = io.of("/admin");
adminNamespace.to("level1").emit("an event", { some: "data" });
// multiple rooms
io.to("room1").to("room2").emit(/* ... */);
// or with an array
io.to(["room1", "room2"]).emit(/* ... */);

namespace.in(room)

Added in v1.0.0

Synonym of namespace.to(room).

namespace.except(rooms)

Added in v4.0.0

• rooms |
• Returns BroadcastOperator

Sets a modifier for a subsequent event emission that the event will only be broadcast to clients that have not joined the given rooms.

// to all clients except the ones in "room1"
io.except("room1").emit(/* ... */);
// to all clients in "room2" except the ones in "room3"
io.to("room2").except("room3").emit(/* ... */);

namespace.emit(eventName[, …args])

• eventName |
• args any[]
• Returns true

Emits an event to all connected clients in the given namespace.

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

信息

Starting with version 4.5.0, it is now possible to use acknowledgements when broadcasting:

io.of("/chat").timeout(10000).emit("some-event", (err, responses) => {
  if (err) {
    // some clients did not acknowledge the event in the given delay
  } else {
    console.log(responses); // one response per client
  }
});

namespace.timeout(value)

Added in v4.5.0

• value
• Returns BroadcastOperator

Sets a modifier for a subsequent event emission that the callback will be called with an error when the given number of milliseconds have elapsed without an acknowledgement from the client:

io.of("/chat").timeout(10000).emit("some-event", (err, responses) => {
  if (err) {
    // some clients did not acknowledge the event in the given delay
  } else {
    console.log(responses); // one response per client
  }
});

namespace.allSockets()

• Returns Promise<Set<SocketId>>

Gets a list of socket IDs connected to this namespace (across all nodes if applicable).

// 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();

namespace.use(fn)

• fn

Registers a middleware, which is a function that gets executed for every incoming Socket, and receives as parameters the socket and a function to optionally defer execution to the next registered middleware.

Errors passed to middleware callbacks are sent as special connect_error packets to clients.

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

More information can be found here.

namespace.socketsJoin(rooms)

Added in v4.0.0

• rooms |
• Returns void

Makes the matching Socket instances join the specified rooms:

// make all Socket instances join the "room1" room
io.socketsJoin("room1");
// make all Socket instances in the "room1" room join the "room2" and "room3" rooms
io.in("room1").socketsJoin(["room2", "room3"]);
// make all Socket instances in the "room1" room of the "admin" namespace join the "room2" room
io.of("/admin").in("room1").socketsJoin("room2");
// this also works with a single socket ID
io.in(theSocketId).socketsJoin("room1");

More information can be found here.

namespace.socketsLeave(rooms)

Added in v4.0.0

• rooms |
• Returns void

Makes the matching Socket instances leave the specified rooms:

// make all Socket instances leave the "room1" room
io.socketsLeave("room1");
// make all Socket instances in the "room1" room leave the "room2" and "room3" rooms
io.in("room1").socketsLeave(["room2", "room3"]);
// make all Socket instances in the "room1" room of the "admin" namespace leave the "room2" room
io.of("/admin").in("room1").socketsLeave("room2");
// this also works with a single socket ID
io.in(theSocketId).socketsLeave("room1");

namespace.disconnectSockets([close])

Added in v4.0.0

• close whether to close the underlying connection
• Returns void

Makes the matching Socket instances disconnect.

// make all Socket instances disconnect
io.disconnectSockets();
// make all Socket instances in the "room1" room disconnect (and discard the low-level connection)
io.in("room1").disconnectSockets(true);
// make all Socket instances in the "room1" room of the "admin" namespace disconnect
io.of("/admin").in("room1").disconnectSockets();
// this also works with a single socket ID
io.of("/admin").in(theSocketId).disconnectSockets();

namespace.fetchSockets()

Added in v4.0.0

• Returns Socket[] | RemoteSocket[]

Returns the matching Socket instances:

// return all Socket instances in the main namespace
const sockets = await io.fetchSockets();
// return all Socket instances in the "room1" room of the main namespace
const sockets = await io.in("room1").fetchSockets();
// return all Socket instances in the "room1" room of the "admin" namespace
const sockets = await io.of("/admin").in("room1").fetchSockets();
// this also works with a single socket ID
const sockets = await io.in(theSocketId).fetchSockets();

The sockets variable in the example above is an array of objects exposing a subset of the usual Socket class:

for (const socket of sockets) {
  console.log(socket.id);
  console.log(socket.handshake);
  console.log(socket.rooms);
  console.log(socket.data);
  socket.emit(/* ... */);
  socket.join(/* ... */);
  socket.leave(/* ... */);
  socket.disconnect(/* ... */);
}

The data attribute is an arbitrary object that can be used to share information between Socket.IO servers:

// server A
io.on("connection", (socket) => {
  socket.data.username = "alice";
});
// server B
const sockets = await io.fetchSockets();
console.log(sockets[0].data.username); // "alice"

Important note: this method (and socketsJoin, socketsLeave and disconnectSockets too) is compatible with the Redis adapter (starting with socket.io-redis@6.1.0), which means that they will work across Socket.IO servers.

namespace.serverSideEmit(eventName[, …args][, ack])

Added in v4.1.0

• eventName
• args <any[]>
• ack
• Returns true

Sends a message to the other Socket.IO servers of the cluster.

Syntax:

io.serverSideEmit("hello", "world");

And on the receiving side:

io.on("hello", (arg1) => {
  console.log(arg1); // prints "world"
});

Acknowledgements are supported too:

// server A
io.serverSideEmit("ping", (err, responses) => {
  console.log(responses[0]); // prints "pong"
});
// server B
io.on("ping", (cb) => {
  cb("pong");
});

Notes:

• the connection, connect and new_namespace strings are reserved and cannot be used in your application.

• you can send any number of arguments, but binary structures are currently not supported (the array of arguments will be JSON.stringify-ed)

Example:

io.serverSideEmit("hello", "world", 1, "2", { 3: "4" });

• the acknowledgement callback might be called with an error, if the other Socket.IO servers do not respond after a given delay

io.serverSideEmit("ping", (err, responses) => {
  if (err) {
    // at least one Socket.IO server has not responded
    // the 'responses' array contains all the responses already received though
  } else {
    // success! the 'responses' array contains one object per other Socket.IO server in the cluster
  }
});

Event: ‘connection’

• socket

Fired upon a connection from client.

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

Event: ‘connect’

Synonym of Event: “connection”.

Flag: ‘volatile’

Sets a modifier for a subsequent event emission that the event data may be lost if the clients are not ready to receive messages (because of network slowness or other issues, or because they’re connected through long polling and is in the middle of a request-response cycle).

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

Flag: ‘local’

Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node (when scaling to multiple nodes).

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

Socket

A Socket is the fundamental class for interacting with browser clients. A Socket belongs to a certain Namespace (by default /) and uses an underlying Client to communicate.

It should be noted the Socket doesn’t relate directly to the actual underlying TCP/IP socket and it is only the name of the class.

Within each Namespace, you can also define arbitrary channels (called room) that the Socket can join and leave. That provides a convenient way to broadcast to a group of Sockets (see Socket#to below).

The Socket class inherits from EventEmitter. The Socket class overrides the emit method, and does not modify any other EventEmitter method. All methods documented here which also appear as EventEmitter methods (apart from emit) are implemented by EventEmitter, and documentation for EventEmitter applies.

More information can be found here.

socket.id

A unique identifier for the session, that comes from the underlying Client.

socket.rooms

• Set

A Set of strings identifying the rooms this client is in.

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

socket.client

A reference to the underlying Client object.

socket.conn

• <engine.Socket>

A reference to the underlying Client transport connection (engine.io Socket object). This allows access to the IO transport layer, which still (mostly) abstracts the actual TCP/IP socket.

io.on("connection", (socket) => {
  console.log("initial transport", socket.conn.transport.name); // prints "polling"
  socket.conn.once("upgrade", () => {
    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
    console.log("upgraded transport", socket.conn.transport.name); // prints "websocket"
  });
  socket.conn.on("packet", ({ type, data }) => {
    // called for each packet received
  });
  socket.conn.on("packetCreate", ({ type, data }) => {
    // called for each packet sent
  });
  socket.conn.on("drain", () => {
    // called when the write buffer is drained
  });
  socket.conn.on("close", (reason) => {
    // called when the underlying connection is closed
  });
});

socket.request

A getter proxy that returns the reference to the request that originated the underlying engine.io Client. Useful for accessing request headers such as Cookie or User-Agent.

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

socket.handshake