Ir para o conteúdo principal
Version: 4.x

Version 4.6.0

February 7, 2023

Server​

Bug Fixes​

  • add timeout method to remote socket (#4558) (0c0eb00)
  • typings: properly type emits with timeout (f3ada7d)

Features​

Promise-based acknowledgements​

This commit adds some syntactic sugar around acknowledgements:

  • emitWithAck()
try {
  const responses = await io.timeout(1000).emitWithAck("some-event");
  console.log(responses); // one response per client
} catch (e) {
  // some clients did not acknowledge the event in the given delay
}

io.on("connection", async (socket) => {
    // without timeout
  const response = await socket.emitWithAck("hello", "world");

  // with a specific timeout
  try {
    const response = await socket.timeout(1000).emitWithAck("hello", "world");
  } catch (err) {
    // the client did not acknowledge the event in the given delay
  }
});
  • serverSideEmitWithAck()
try {
  const responses = await io.timeout(1000).serverSideEmitWithAck("some-event");
  console.log(responses); // one response per server (except itself)
} catch (e) {
  // some servers did not acknowledge the event in the given delay
}

Added in 184f3cf.

Connection state recovery​

This feature allows a client to reconnect after a temporary disconnection and restore its state:

  • id
  • rooms
  • data
  • missed packets

Usage:

import { Server } from "socket.io";

const io = new Server({
  connectionStateRecovery: {
    // default values
    maxDisconnectionDuration: 2 * 60 * 1000,
    skipMiddlewares: true,
  },
});

io.on("connection", (socket) => {
  console.log(socket.recovered); // whether the state was recovered or not
});

Here's how it works:

  • the server sends a session ID during the handshake (which is different from the current id attribute, which is public and can be freely shared)
  • the server also includes an offset in each packet (added at the end of the data array, for backward compatibility)
  • upon temporary disconnection, the server stores the client state for a given delay (implemented at the adapter level)
  • upon reconnection, the client sends both the session ID and the last offset it has processed, and the server tries to restore the state

The in-memory adapter already supports this feature, and we will soon update the Postgres and MongoDB adapters. We will also create a new adapter based on Redis Streams, which will support this feature.

Added in 54d5ee0.

Compatibility (for real) with Express middlewares​

This feature implements middlewares at the Engine.IO level, because Socket.IO middlewares are meant for namespace authorization and are not executed during a classic HTTP request/response cycle.

Syntax:

io.engine.use((req, res, next) => {
  // do something

  next();
});

// with express-session
import session from "express-session";

io.engine.use(session({
  secret: "keyboard cat",
  resave: false,
  saveUninitialized: true,
  cookie: { secure: true }
}));

// with helmet
import helmet from "helmet";

io.engine.use(helmet());

A workaround was possible by using the allowRequest option and the "headers" event, but this feels way cleaner and works with upgrade requests too.

Added in 24786e7.

Error details in the disconnecting and disconnect events​

The disconnect event will now contain additional details about the disconnection reason.

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

Added in 8aa9499.

Automatic removal of empty child namespaces​

This commit adds a new option, "cleanupEmptyChildNamespaces". With this option enabled (disabled by default), when a socket disconnects from a dynamic namespace and if there are no other sockets connected to it then the namespace will be cleaned up and its adapter will be closed.

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

const httpServer = createServer();
const io = new Server(httpServer, {
  cleanupEmptyChildNamespaces: true
});

Added in 5d9220b.

A new "addTrailingSlash" option​

The trailing slash which was added by default can now be disabled:

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

const httpServer = createServer();
const io = new Server(httpServer, {
  addTrailingSlash: false
});

In the example above, the clients can omit the trailing slash and use /socket.io instead of /socket.io/.

Added in d0fd474.

Performance Improvements​

  • precompute the WebSocket frames when broadcasting (da2b542)

Dependencies​

Client​

Bug Fixes​

  • typings: do not expose browser-specific types (4d6d95e)
  • ensure manager.socket() returns an active socket (b7dd891)
  • typings: properly type emits with timeout (#1570) (33e4172)

Features​

A new "addTrailingSlash" option​

The trailing slash which was added by default can now be disabled:

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

const socket = io("https://example.com", {
  addTrailingSlash: false
});

In the example above, the request URL will be https://example.com/socket.io instead of https://example.com/socket.io/.

Added in 21a6e12.

Promise-based acknowledgements​

This commit adds some syntactic sugar around acknowledgements:

// without timeout
const response = await socket.emitWithAck("hello", "world");

// with a specific timeout
try {
  const response = await socket.timeout(1000).emitWithAck("hello", "world");
} catch (err) {
  // the server did not acknowledge the event in the given delay
}

Note: environments that do not support Promises will need to add a polyfill in order to use this feature.

Added in 47b979d.

Connection state recovery​

This feature allows a client to reconnect after a temporary disconnection and restore its ID and receive any packets that was missed during the disconnection gap. It must be enabled on the server side.

A new boolean attribute named recovered is added on the socket object:

socket.on("connect", () => {
  console.log(socket.recovered); // whether the recovery was successful
});

Added in 54d5ee0 (server) and b4e20c5 (client).

Retry mechanism​

Two new options are available:

  • retries: the maximum number of retries. Above the limit, the packet will be discarded.
  • ackTimeout: the default timeout in milliseconds used when waiting for an acknowledgement (not to be mixed up with the already existing timeout option, which is used by the Manager during the connection)
const socket = io({
  retries: 3,
  ackTimeout: 10000
});

// implicit ack
socket.emit("my-event");

// explicit ack
socket.emit("my-event", (err, val) => { /* ... */ });

// custom timeout (in that case the ackTimeout is optional)
socket.timeout(5000).emit("my-event", (err, val) => { /* ... */ });

In all examples above, "my-event" will be sent up to 4 times (1 + 3), until the server sends an acknowledgement.

Assigning a unique ID to each packet is the duty of the user, in order to allow deduplication on the server side.

Added in 655dce9.

Dependencies​