Migrating from 2.x to 3.0

This release should fix most of the inconsistencies of the Socket.IO library and provide a more intuitive behavior forthe end users. It is the result of the feedback of the community over the years. A big thanks to everyone involved!

TL;DR: due to several breaking changes, a v2 client will not be able to connect to a v3 server (and vice versa)

Update: As of Socket.IO 3.1.0, the v3 server is now able to communicate with v2 clients. More information below. A v3 client is still not be able to connect to a v2 server though.

For the low-level details, please see:

• Engine.IO protocol v4
• Socket.IO protocol v5

Here is the complete list of changes:

• Configuration

  • Saner default values
  • CORS handling
  • No more cookie by default

• API change

  • io.set() is removed
  • No more implicit connection to the default namespace
  • Namespace.connected is renamed to Namespace.sockets and is now a Map
  • Socket.rooms is now a Set
  • Socket.binary() is removed
  • Socket.join() and Socket.leave() are now synchronous
  • Socket.use() is removed
  • A middleware error will now emit an Error object
  • Add a clear distinction between the Manager query option and the Socket query option
  • The Socket instance will no longer forward the events emitted by its Manager
  • Namespace.clients() is renamed to Namespace.allSockets() and now returns a Promise
  • Client bundles
  • No more “pong” event for retrieving latency
  • ES modules syntax
  • emit() chains are not possible anymore
  • Room names are not coerced to string anymore

• New features

  • Catch-all listeners
  • Volatile events (client)
  • Official bundle with the msgpack parser

• Miscellaneous

  • The Socket.IO codebase has been rewritten to TypeScript
  • Support for IE8 and Node.js 8 is officially dropped

• How to upgrade an existing production deployment

• Known migration issues

Configuration

Saner default values

• the default value of maxHttpBufferSize was decreased from 100MB to 1MB.
• the WebSocket permessage-deflate extension is now disabled by default
• you must now explicitly list the domains that are allowed (for CORS, see below)

CORS handling

In v2, the Socket.IO server automatically added the necessary headers to allow Cross-Origin Resource Sharing (CORS).

This behavior, while convenient, was not great in terms of security, because it meant that all domains were allowed to reach your Socket.IO server, unless otherwise specified with the origins option.

That’s why, as of Socket.IO v3:

• CORS is now disabled by default
• the origins option (used to provide a list of authorized domains) and the handlePreflightRequest option (used to edit the Access-Control-Allow-xxx headers) are replaced by the cors option, which will be forwarded to the cors package.

The complete list of options can be found here.

Before:

const io = require("socket.io")(httpServer, {
  origins: ["https://example.com"],

  // optional, useful for custom headers
  handlePreflightRequest: (req, res) => {
    res.writeHead(200, {
      "Access-Control-Allow-Origin": "https://example.com",
      "Access-Control-Allow-Methods": "GET,POST",
      "Access-Control-Allow-Headers": "my-custom-header",
      "Access-Control-Allow-Credentials": true
    });
    res.end();
  }
});

After:

const io = require("socket.io")(httpServer, {
  cors: {
    origin: "https://example.com",
    methods: ["GET", "POST"],
    allowedHeaders: ["my-custom-header"],
    credentials: true
  }
});

No more cookie by default

In previous versions, an io cookie was sent by default. This cookie can be used to enable sticky-session, which is still required when you have several servers and HTTP long-polling enabled (more information here).

However, this cookie is not needed in some cases (i.e. single server deployment, sticky-session based on IP) so it must now be explicitly enabled.

Before:

const io = require("socket.io")(httpServer, {
  cookieName: "io",
  cookieHttpOnly: false,
  cookiePath: "/custom"
});

After:

const io = require("socket.io")(httpServer, {
  cookie: {
    name: "test",
    httpOnly: false,
    path: "/custom"
  }
});

All other options (domain, maxAge, sameSite, …) are now supported. Please see here for the complete list of options.

API change

Below are listed the non backward-compatible changes.

io.set() is removed

This method was deprecated in the 1.0 release and kept for backward-compatibility. It is now removed.

It was replaced by middlewares.

Before:

io.set("authorization", (handshakeData, callback) => {
  // make sure the handshake data looks good
  callback(null, true); // error first, "authorized" boolean second 
});

After:

io.use((socket, next) => {
  var handshakeData = socket.request;
  // make sure the handshake data looks good as before
  // if error do this:
    // next(new Error("not authorized"));
  // else just call next
  next();
});

No more implicit connection to the default namespace

This change impacts the users of the multiplexing feature (what we call Namespace in Socket.IO).

In previous versions, a client would always connect to the default namespace (/), even if it requested access to another namespace. This meant that the middlewares registered for the default namespace were triggered, which may be quite surprising.

// client-side
const socket = io("/admin");

// server-side
io.use((socket, next) => {
  // not triggered anymore
});

io.on("connection", socket => {
  // not triggered anymore
})

io.of("/admin").use((socket, next) => {
  // triggered
});

Besides, we will now refer to the “main” namespace instead of the “default” namespace.

Namespace.connected is renamed to Namespace.sockets and is now a Map

The connected object (used to store all the Socket connected to the given Namespace) could be used to retrieve a Socket object from its id. It is now an ES6 Map.

Before:

// get a socket by ID in the main namespace
const socket = io.of("/").connected[socketId];

// get a socket by ID in the "admin" namespace
const socket = io.of("/admin").connected[socketId];

// loop through all sockets
const sockets = io.of("/").connected;
for (const id in sockets) {
  if (sockets.hasOwnProperty(id)) {
    const socket = sockets[id];
    // ...
  }
}

// get the number of connected sockets
const count = Object.keys(io.of("/").connected).length;

After:

// get a socket by ID in the main namespace
const socket = io.of("/").sockets.get(socketId);

// get a socket by ID in the "admin" namespace
const socket = io.of("/admin").sockets.get(socketId);

// loop through all sockets
for (const [_, socket] of io.of("/").sockets) {
  // ...
}

// get the number of connected sockets
const count = io.of("/").sockets.size;

Socket.rooms is now a Set

The rooms property contains the list of rooms the Socket is currently in. It was an object, it is now an ES6 Set.

Before:

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

  console.log(Object.keys(socket.rooms)); // [ <socket.id> ]

  socket.join("room1");

  console.log(Object.keys(socket.rooms)); // [ <socket.id>, "room1" ]

});

After:

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

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

  socket.join("room1");

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

});

Socket.binary() is removed

The binary method could be used to indicate that a given event did not contain any binary data (in order to skip the lookup done by the library and improve performance in certain conditions).

It was replaced by the ability to provide your own parser, which was added in Socket.IO 2.0.

Before:

socket.binary(false).emit("hello", "no binary");

After:

const io = require("socket.io")(httpServer, {
  parser: myCustomParser
});

Please see socket.io-msgpack-parser for example.

Socket.join() and Socket.leave() are now synchronous

The asynchronicity was needed for the first versions of the Redis adapter, but this is not the case anymore.

For reference, an Adapter is an object that stores the relationships between Sockets and Rooms. There are two official adapters: the in-memory adapter (built-in) and the Redis adapter based on Redis pub-sub mechanism.

Before:

socket.join("room1", () => {
 io.to("room1").emit("hello");
});

socket.leave("room2", () => {
  io.to("room2").emit("bye");
});

After:

socket.join("room1");
io.to("room1").emit("hello");

socket.leave("room2");
io.to("room2").emit("bye");

Note: custom adapters may return a Promise, so the previous example becomes:

await socket.join("room1");
io.to("room1").emit("hello");

Socket.use() is removed

socket.use() could be used as a catch-all listener. But its API was not really intuitive. It is replaced by socket.onAny().

UPDATE: the Socket.use() method was restored in socket.io@3.0.5.

Before:

socket.use((packet, next) => {
  console.log(packet.data);
  next();
});

After:

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

A middleware error will now emit an Error object

The error event is renamed to connect_error and the object emitted is now an actual Error:

Before:

// server-side
io.use((socket, next) => {
  next(new Error("not authorized"));
});

// client-side
socket.on("error", err => {
  console.log(err); // not authorized
});

// or with an object
// 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("error", err => {
  console.log(err); // { content: "Please retry later" }
});

After:

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

Add a clear distinction between the Manager query option and the Socket query option

In previous versions, the query option was used in two distinct places:

• in the query parameters of the HTTP requests (GET /socket.io/?EIO=3&abc=def)
• in the CONNECT packet

Let’s take the following example:

const socket = io({
  query: {
    token: "abc"
  }
});

Under the hood, here’s what happened in the io() method:

const { Manager } = require("socket.io-client");

// a new Manager is created (which will manage the low-level connection)
const manager = new Manager({
  query: { // sent in the query parameters
    token: "abc"
  }
});

// and then a Socket instance is created for the namespace (here, the main namespace, "/")
const socket = manager.socket("/", {
  query: { // sent in the CONNECT packet
    token: "abc"
  }
});

This behavior could lead to weird behaviors, for example when the Manager was reused for another namespace (multiplexing):

// client-side
const socket1 = io({
  query: {
    token: "abc"
  }
});

const socket2 = io("/my-namespace", {
  query: {
    token: "def"
  }
});

// server-side
io.on("connection", (socket) => {
  console.log(socket.handshake.query.token); // abc (ok!)
});

io.of("/my-namespace").on("connection", (socket) => {
  console.log(socket.handshake.query.token); // abc (what?)
});

That’s why the query option of the Socket instance is renamed to ̀auth in Socket.IO v3:

// plain object
const socket = io({
  auth: {
    token: "abc"
  }
});

// or with a function
const socket = io({
  auth: (cb) => {
    cb({
      token: "abc"
    });
  }
});

// server-side
io.on("connection", (socket) => {
  console.log(socket.handshake.auth.token); // abc
});

Note: the query option of the Manager can still be used in order to add a specific query parameter to the HTTP requests.

The Socket instance will no longer forward the events emitted by its Manager

In previous versions, the Socket instance emitted the events related to the state of the underlying connection. This will not be the case anymore.

You can still have access to those events on the Manager instance (the io property of the socket) :

Before:

socket.on("reconnect_attempt", () => {});

After:

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

Here is the updated list of events emitted by the Manager:

Here is the updated list of events emitted by the Socket:

And finally, here’s the updated list of reserved events that you cannot use in your application:

• connect (used on the client-side)
• connect_error (used on the client-side)
• disconnect (used on both sides)
• disconnecting (used on the server-side)
• newListener and removeListener (EventEmitter reserved events)

socket.emit("connect_error"); // will now throw an Error

Namespace.clients() is renamed to Namespace.allSockets() and now returns a Promise

This function returns the list of socket IDs that are connected to this namespace.

Before:

// all sockets in default namespace
io.clients((error, clients) => {
  console.log(clients); // => [6em3d4TJP8Et9EMNAAAA, G5p55dHhGgUnLUctAAAB]
});

// all sockets in the "chat" namespace
io.of("/chat").clients((error, clients) => {
  console.log(clients); // => [PZDoMHjiu8PYfRiKAAAF, Anw2LatarvGVVXEIAAAD]
});

// all sockets in the "chat" namespace and in the "general" room
io.of("/chat").in("general").clients((error, clients) => {
  console.log(clients); // => [Anw2LatarvGVVXEIAAAD]
});

After:

// all sockets in default namespace
const ids = await io.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();

Note: this function was (and still is) supported by the Redis adapter, which means that it will return the list of socket IDs across all the Socket.IO servers.

Client bundles

There are now 3 distinct bundles:

By default, all of them are served by the server, at /socket.io/<name>.

Before:

<!-- note: this bundle was actually minified but included the debug package -->
<script src="/socket.io/socket.io.js"></script>

After:

<!-- during development -->
<script src="/socket.io/socket.io.js"></script>
<!-- for production -->
<script src="/socket.io/socket.io.min.js"></script>

No more “pong” event for retrieving latency

In Socket.IO v2, you could listen to the pong event on the client-side, which included the duration of the last health check round-trip.

Due to the reversal of the heartbeat mechanism (more information here), this event has been removed.

Before:

socket.on("pong", (latency) => {
  console.log(latency);
});

After:

// server-side
io.on("connection", (socket) => {
  socket.on("ping", (cb) => {
    if (typeof cb === "function")
      cb();
  });
});

// client-side
setInterval(() => {
  const start = Date.now();

  // volatile, so the packet will be discarded if the socket is not connected
  socket.volatile.emit("ping", () => {
    const latency = Date.now() - start;
    // ...
  });
}, 5000);

ES modules syntax

The ECMAScript modules syntax is now similar to the Typescript one (see below).

Before (using default import):

// server-side
import Server from "socket.io";

const io = new Server(8080);

// client-side
import io from 'socket.io-client';

const socket = io();

After (with named import):

// server-side
import { Server } from "socket.io";

const io = new Server(8080);

// client-side
import { io } from 'socket.io-client';

const socket = io();

emit() chains are not possible anymore

The emit() method now matches the EventEmitter.emit() method signature, and returns true instead of the current object.

Before:

socket.emit("event1").emit("event2");

After:

socket.emit("event1");
socket.emit("event2");

Room names are not coerced to string anymore

We are now using Maps and Sets internally instead of plain objects, so the room names are not implicitly coerced to string anymore.

Before:

// mixed types were possible
socket.join(42);
io.to("42").emit("hello");
// also worked
socket.join("42");
io.to(42).emit("hello");

After:

// one way
socket.join("42");
io.to("42").emit("hello");
// or another
socket.join(42);
io.to(42).emit("hello");

New features

Some of those new features may be backported to the 2.4.x branch, depending on the feedback of the users.

Catch-all listeners

This feature is inspired from the EventEmitter2 library (which is not used directly in order not to increase the browser bundle size).

It is available for both the server and the client sides:

// server
io.on("connection", (socket) => {
  socket.onAny((event, ...args) => {});
  socket.prependAny((event, ...args) => {});
  socket.offAny(); // remove all listeners
  socket.offAny(listener);
  const listeners = socket.listenersAny();
});

// client
const socket = io();
socket.onAny((event, ...args) => {});
socket.prependAny((event, ...args) => {});
socket.offAny(); // remove all listeners
socket.offAny(listener);
const listeners = socket.listenersAny();

Volatile events (client)

A volatile event is an event that is allowed to be dropped if the low-level transport is not ready yet (for example when an HTTP POST request is already pending).

This feature was already available on the server-side. It might be useful on the client-side as well, for example when the socket is not connected (by default, packets are buffered until reconnection).

socket.volatile.emit("volatile event", "might or might not be sent");

Official bundle with the msgpack parser

A bundle with the socket.io-msgpack-parser will now be provided (either on the CDN or served by the server at /socket.io/socket.io.msgpack.min.js).

Pros:

• events with binary content are sent as 1 WebSocket frame (instead of 2+ with the default parser)
• payloads with lots of numbers should be smaller

Cons:

• no IE9 support (https://caniuse.com/mdn-javascript_builtins_arraybuffer)
• a slightly bigger bundle size

// server-side
const io = require("socket.io")(httpServer, {
  parser: require("socket.io-msgpack-parser")
});

No additional configuration is needed on the client-side.

Miscellaneous

The Socket.IO codebase has been rewritten to TypeScript

Which means npm i -D @types/socket.io should not be needed anymore.

Server:

import { Server, Socket } from "socket.io";

const io = new Server(8080);

io.on("connection", (socket: Socket) => {
    console.log(`connect ${socket.id}`);

    socket.on("disconnect", () => {
        console.log(`disconnect ${socket.id}`);
    });
});

Client:

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

const socket = io("/");

socket.on("connect", () => {
    console.log(`connect ${socket.id}`);
});

Plain javascript is obviously still fully supported.

Support for IE8 and Node.js 8 is officially dropped

IE8 is no longer testable on the Sauce Labs platform, and requires a lot of efforts for very few users (if any?), so we are dropping support for it.

Besides, Node.js 8 is now EOL. Please upgrade as soon as possible!

How to upgrade an existing production deployment

• first, update the servers with allowEIO3 set to true (added in socket.io@3.1.0)

const io = require("socket.io")({
  allowEIO3: true // false by default
});

Note: If you are using the Redis adapter to broadcast packets between nodes, you must use socket.io-redis@5 with socket.io@2 and socket.io-redis@6 with socket.io@3. Please note that both versions are compatible, so you can update each server one by one (no big bang is needed).

• then, update the clients

This step may actually take some time, as some clients may still have a v2 client in cache.

You can check the version of the connection with:

io.on("connection", (socket) => {
  const version = socket.conn.protocol; // either 3 or 4
});

This matches the value of the EIO query parameter in the HTTP requests.

• and finally, once every client was updated, set allowEIO3 to false (which is the default value)

const io = require("socket.io")({
  allowEIO3: false
});

With allowEIO3 set to false, v2 clients will now receive an HTTP 400 error (Unsupported protocol version) when connecting.

Known migration issues

• stream_1.pipeline is not a function

TypeError: stream_1.pipeline is not a function
    at Function.sendFile (.../node_modules/socket.io/dist/index.js:249:26)
    at Server.serve (.../node_modules/socket.io/dist/index.js:225:16)
    at Server.srv.on (.../node_modules/socket.io/dist/index.js:186:22)
    at emitTwo (events.js:126:13)
    at Server.emit (events.js:214:7)
    at parserOnIncoming (_http_server.js:602:12)
    at HTTPParser.parserOnHeadersComplete (_http_common.js:116:23)

This error is probably due to your version of Node.js. The pipeline method was introduced in Node.js 10.0.0.

• error TS2416: Property 'emit' in type 'Namespace' is not assignable to the same property in base type 'EventEmitter'.

node_modules/socket.io/dist/namespace.d.ts(89,5): error TS2416: Property 'emit' in type 'Namespace' is not assignable to the same property in base type 'EventEmitter'.
  Type '(ev: string, ...args: any[]) => Namespace' is not assignable to type '(event: string | symbol, ...args: any[]) => boolean'.
    Type 'Namespace' is not assignable to type 'boolean'.
node_modules/socket.io/dist/socket.d.ts(84,5): error TS2416: Property 'emit' in type 'Socket' is not assignable to the same property in base type 'EventEmitter'.
  Type '(ev: string, ...args: any[]) => this' is not assignable to type '(event: string | symbol, ...args: any[]) => boolean'.
    Type 'this' is not assignable to type 'boolean'.
      Type 'Socket' is not assignable to type 'boolean'.

The signature of the emit() method was fixed in version 3.0.1 (commit).

• the client is disconnected when sending a big payload (> 1MB)

This is probably due to the fact that the default value of maxHttpBufferSize is now 1MB. When receiving a packet that is larger than this, the server disconnects the client, in order to prevent malicious clients from overloading the server.

You can adjust the value when creating the server:

const io = require("socket.io")(httpServer, {
  maxHttpBufferSize: 1e8
});

• Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at xxx/socket.io/?EIO=4&transport=polling&t=NMnp2WI. (Reason: CORS header ‘Access-Control-Allow-Origin’ missing).

Since Socket.IO v3, you need to explicitly enable Cross-Origin Resource Sharing (CORS). The documentation can be found here.

• Uncaught TypeError: packet.data is undefined

It seems that you are using a v3 client to connect to a v2 server, which is not possible. Please see the following section.

• Object literal may only specify known properties, and 'extraHeaders' does not exist in type 'ConnectOpts'

Since the codebase has been rewritten to TypeScript (more information here), @types/socket.io-client is no longer needed and will actually conflict with the typings coming from the socket.io-client package.