We are happy to announce that we now provide a low-level engine for Bun.

Bun could already be used without any modification:

import { Server } from "socket.io";

const io = new Server({ /* options */ });

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

io.listen(3000);

However, this relied on Bun's polyfill for the Node.js HTTP server.

So, in order to fully benefit from the performance of Bun's native HTTP server, we have created a dedicated engine:

import { Server as Engine } from "@socket.io/bun-engine";
import { Server } from "socket.io";

const io = new Server();

const engine = new Engine({
  path: "/socket.io/",
});

io.bind(engine);

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

export default {
  port: 3000,
  idleTimeout: 30, // must be greater than the "pingInterval" option of the engine, which defaults to 25 seconds

  ...engine.handler(),
};

Which means that you can now take advantage of the speed and scalability of Bun, with the same high-level API offered by Socket.IO (and its existing adapters, when scaling to multiple servers).

The source code of this engine can be found here: https://github.com/socketio/bun-engine

import { Server } from "socket.io";
import { Server as Engine } from "@socket.io/bun-engine";
import { Hono } from "hono";

const io = new Server();
const engine = new Engine();

io.bind(engine);

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

const app = new Hono();

const { websocket } = engine.handler();

export default {
  port: 3000,
  idleTimeout: 30, // must be greater than the "pingInterval" option of the engine, which defaults to 25 seconds

  fetch(req, server) {
    const url = new URL(req.url);

    if (url.pathname === "/socket.io/") {
      return engine.handleRequest(req, server);
    } else {
      return app.fetch(req, server);
    }
  },

  websocket
}

Have a great day!

We are happy to announce that Socket.IO packages will now be published with a provenance statement.

Starting today, new Socket.IO versions will be published directly from GitHub Actions and no longer from a maintainer machine.

The publication workflow can be found here: publish.yml

Notes​

There are a few notable differences from the reference workflow:

Workflow trigger​

The workflow is triggered when pushing a tag to GitHub:

on:
  push:
    tags:
      - '**@*'

The expected format is <package>@<version>, for example:

• socket.io@1.2.3
• @socket.io/redis-adapter@3.4.5 (hence the ** to match the / char)

The <package> part is then used to select the right workspace (since we are using a monorepo):

jobs:
  publish:
    steps:
      # [...]

      - name: Publish package
        run: npm publish --workspace=${GITHUB_REF_NAME%@*} --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Reference: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

Compilation step​

A TypeScript compilation step is necessary, since some packages depend on the types of other packages:

jobs:
  publish:
    steps:
      # [...]

      - name: Compile each package
        run: npm run compile --workspaces --if-present

      - name: Publish package
      # [...]

First verified version​

The latest version of the engine.io-parser package has been released this way.

On the npmjs.com website, you can find:

• the details of the build, at the bottom of the page:

• a checked badge, in the "Versions" tab

You can also verify the attestations of your dependencies:

$ npm i socket.io

added 22 packages, and audited 23 packages in 853ms

found 0 vulnerabilities

$ npm audit signatures

audited 22 packages in 1s

22 packages have verified registry signatures

1 package has a verified attestation # <-- it's a good start!

Conclusion​

This is a big step forward in increasing trust in the JS ecosystem, congratulations to the npm team!

Some big names have already joined the club:

• axios
• next
• vite

That's all folks, thanks for reading!

We are happy to announce that the Socket.IO codebase has been merged into a monorepo.

Modular architecture​

As part of the work towards v1.0 ten years ago (!), the Socket.IO codebase was split into several packages, each with its own responsibility:

At the time, tools like lerna or pnpm workspaces that make it easier to develop and publish multiple JavaScript packages from the same repository did not exist yet, so the codebase was split into multiple GitHub repositories:

• https://github.com/socketio/socket.io
• https://github.com/socketio/socket.io-client
• https://github.com/socketio/socket.io-parser
• ...

However, this structure has several downsides:

• it's harder for newcomers to dig into the codebase and understand what's going on under the hood
• a change that affects multiple repositories is more difficult to test
• mundane tasks like configuring CI or updating development dependencies must be replicated across all repositories

That's why we have made the decision to merge all repositories into a single one. The source codes for the different packages are now located in the packages/ directory:

packages/
├── engine.io
├── engine.io-client
├── engine.io-parser
├── socket.io
├── socket.io-adapter
├── socket.io-client
└── socket.io-parser

Workspaces​

To manage the packages, we use npm workspaces which were introduced in npm v7 (bundled with Node.js v15). The package.json file at the root of the repository lists all packages and their development dependencies:

{
  "private": true,
  "workspaces": [
    "packages/engine.io-parser",
    "packages/engine.io",
    "packages/engine.io-client",
    "packages/socket.io-adapter",
    "packages/socket.io-parser",
    "packages/socket.io-client",
    "packages/socket.io"
  ],
  "devDependencies": {
    // [...]
  }
}

After cloning the repository, running npm install will fetch all necessary dependencies and create the links between the packages:

$ npm ls
socket.io@ /git/socket.io
└─┬ socket.io@4.7.5 -> ./packages/socket.io
  ├── accepts@1.3.8
  ├── base64id@2.0.0
  ├── cors@2.8.5
  ├── debug@4.3.5
  ├── engine.io@6.6.0 -> ./packages/engine.io
  ├─┬ socket.io-adapter@2.5.5 -> ./packages/socket.io-adapter
  │ ├── debug@4.3.5 deduped
  │ └── ws@8.17.1 overridden
  └─┬ socket.io-parser@4.2.4 -> ./packages/socket.io-parser
    ├── @socket.io/component-emitter@3.1.2 -> ./packages/socket.io-component-emitter
    └── debug@4.3.5 deduped

And finally, running npm test --workspaces (or npm test -ws) will run the tests on all workspaces, ensuring that any change is properly tested over the whole codebase.

Git history​

Obviously, losing 10 years of git history from the other repositories was not an option. The repositories have thus been merged with the --allow-unrelated-histories option, in order to include their history in the monorepo:

Reference: https://git-scm.com/docs/git-merge#Documentation/git-merge.txt---allow-unrelated-histories

GitHub issues​

Similarly, it was not conceivable to lose the list of open GitHub issues across all repositories, since it is our most valuable source of user feedback, so they have been moved to the main repository: https://github.com/socketio/socket.io/issues

Hopefully, this change should make it easier for anyone to contribute to the project in the future.

That's all folks, thanks for reading!

I'm happy to announce that we provide 3 new official adapters:

• the Google Cloud Pub/Sub adapter
• the AWS SQS adapter
• the Azure Service Bus adapter

Any feedback is welcome!

A new sample project is available: the Chat platform.

The source code can be found here.

Goal​

The goal of this project is to provide a full-blown project based on Socket.IO with:

• authentication/user registration
• public and private messaging
• proper reconnection management
• presence management

The source code is provided with a permissive MIT license, so that you can use it/extend it to your will.

How to use​

Check out the code here and follow the instructions in the README.

Features​

Channel-based messages​

Private messages​

Tools​

Server​

The server is written in plain JavaScript, with the express, express-session and passport packages. The database is PostgreSQL.

Client​

The client is a Vue.js single-page application, with the vue-router and pinia packages. It uses Bootstrap v5 for the styles.

Roadmap​

• React client (link)
• MongoDB server (link)

Any additional suggestion is welcome!

Hello developers,

Since we put up an invitation to participate in a user study, we collected hundreds of responses and had the chance to speak in depth with several Socket.IO users. Thank you for your interest in the user study and helping us understand your experience.

In this post, I am going to share with you some notable learnings from the study. It’s our hope that such sharing can shed light on how we can build a stronger community as Socket.IO users, contributors, and cloud providers.

Socket.IO is used in a wide range of app scenarios​

We were pleasantly surprised by the variety of applications built using Socket.IO. Although a fair number of users reported building chat apps using Socket.IO, many shared that they use Socket.IO for identity management to limit the number of active browser tabs, for robotics to control the movement of mobile robots, for multi-player mobile games and for collaborative apps where users can track work items in real-time.

Overwhelmingly, users enjoy the “intuitive APIs”​

Users seem to have exhausted the synonyms for “intuitive” in their responses. Once users have gone over the initial learning curve, it doesn’t take long before they can get productive with Socket.IO’s APIs, which are described as “simple”, “easy” and “plain”. Plains APIs are definitely a praise in this case.

Some users seem to have doubts about Socket.IO’s viability for large projects​

Users new to Socket.IO seem to have the impression that Socket.IO is for small-scale and toy projects and it would be necessary to find alternatives when an app needs to scale. I am happy to report that impression doesn’t reflect the reality; a few Socket.IO users shared that their apps handled 10s of thousand concurrent connections well, powered by running multiple Socket.IO instances behind a load balancer.

Scaling out a Socket.IO is where developers report the most pain​

Scaling out a Socket.IO app requires a multi-server setup. Essentially, client connections are spread across several Socket.IO server instances. To emit an event to clients connected with different server instances, there needs to be a component to coordinate the message passing. While simple in broad-stroke description, implementation is not particularly straight-forward or familiar to most users. Deploying and maintaining a separate adapter component add additional complexity to the task.

This is an area where we studied the most and thought we could bring the most value to developers. I am happy to share with you that with the input from the open-source community, we brought support for Socket.IO on Azure. With this support, Azure hosts and manages client connections; in other words, developers don’t need an “adapter” component.

What’s more important is that server and client apps continue using the same and familiar Socket.IO APIs. With only a few lines of code, you can get any socket.io apps running locally to Azure. You can learn more about the support and try it out for free by following the links below.

• Overview of Socket.IO support on Azure
• Quickstarts of hosting a Socket.IO app on Azure

There is a new official adapter for Socket.IO: the Redis Streams adapter.

The adapter will use a Redis stream to forward packets between the Socket.IO servers.

The main difference with the existing Redis adapter (which use the Redis Pub/Sub mechanism) is that this adapter will properly handle any temporary disconnection to the Redis server and resume the stream without losing any packets.

See also:

• Installation steps
• Source code

If you have any feedback, feel free to open an issue in the repository.

I'm happy to announce that Socket.IO is now compatible with Deno, which is a runtime for JavaScript and TypeScript written in Rust.

Usage:

import { serve } from "https://deno.land/std@0.150.0/http/server.ts";
import { Server } from "https://deno.land/x/socket_io@0.1.1/mod.ts";

const io = new Server();

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

  socket.emit("hello", "world");

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

await serve(io.handler(), {
  port: 3000,
});

And then run with:

$ deno run --allow-net index.ts

The API is very similar to the one exposed by the Node.js implementation.

Next steps:

• client implementation
• compatibility with the Node.js ecosystem (msgpack parser, adapters, admin UI, ...)

Feedback is welcome!

• Source code: https://github.com/socketio/socket.io-deno
• Module: https://deno.land/x/socket_io

We have just published a new minor version of Socket.IO: 4.5.0

Here are the new features in this release:

Catch-all listeners for outgoing packets​

This is similar to onAny(), but for outgoing packets.

Syntax:

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

This feature can be used on both sides, and will also work when broadcasting events:

io.on("connection", (socket) => {
  socket.onAnyOutgoing((event, ...args) => {
    console.log(event); // prints "some event"
  });

  io.emit("some event");
});

Multiple acknowledgements when broadcasting​

You can now broadcast an event to multiple clients and expect an acknowledgement:

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

Limit the number of packets sent in HTTP long-polling mode​

The server will now include the value of the maxHttpBufferSize in the handshake, so the clients will now be able to decide how many packets they have to send to stay under this value.

Here is what the handshake will now look like:

0{"sid":"lv_VI97HAXpY6yYWAAAC","upgrades":["websocket"],"pingInterval":25000,"pingTimeout":5000,"maxPayload":1000000}

More information here.

Disconnection details​

The "disconnect" event on the client side will now include additional details to help debugging if anything has gone wrong.

Example when sticky session is not enabled:

socket.on("disconnect", (reason, details) => {
  console.log(details.context.status); // 400
  console.log(details.context.responseText); // '{"code":1,"message":"Session ID unknown"}'
});

This release also includes some bug fixes, please see the complete diff below.

Links​

• Server: GitHub release / Diff / npm
• Client: GitHub release / Diff / npm

Size of the bundles:

That's all for this release, thanks for reading!

We have just published a new minor version of Socket.IO: 4.4.0

After a big focus on the client in the latest release, this release is more oriented towards the server.

Support for µWebSockets.js​

Why should one choose between performance and reliability? Starting with socket.io@4.4.0, you can now use the HTTP/WebSocket server provided by the µWebSockets.js package:

const { App } = require("uWebSockets.js");
const { Server } = require("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");
  }
});

It acts as a replacement for both the default Node.js HTTP server and the WebSocket server provided by the ws package, and should improve the memory footprint and the latency of your application. Benchmarks coming soon!

Emit with timeout​

There is a new socket.timeout() method available on both sides:

socket.timeout(5000).emit("my-event", (err) => {
  if (err) {
    // the other side did not acknowledge the event in the given delay
  }
});

socket.data can now be typed​

For TypeScript users, the socket.data can now be typed:

interface SocketData {
  name: string;
  age: number;
}

const io = new Server<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>();

io.on("connection", (socket) => {
  socket.data.name = "john";
  socket.data.age = 42;
});

This release also includes some bug fixes, please see the complete diff below.

Links​

• Server: GitHub release / Diff / npm
• Client: GitHub release / Diff / npm

Size of the bundles:

That's all for this release, thanks for reading!

We have just published a new minor version of Socket.IO: 4.3.0

An ESM bundle is now provided:

<script type="module">
  import { io } from "https://cdn.socket.io/4.3.0/socket.io.esm.min.js";

  const socket = io();

  socket.emit("hello", "world");
</script>

The bundle size has been greatly reduced, thanks to:

• the migration to rollup
• the cleanup of some unused code
• the removal of debug calls from the bundle (explanation here)

And finally, the Socket.IO client is now compatible with Vite (#1492).

Links​

• Server: Release notes / Diff
• Client: Release notes / Diff
• ws version: ~8.2.3 (diff)

Size of the bundles:

That's all for this release, thanks for reading!

Here's the #5 edition of our Monthly update.

So, what's new in the Socket.IO ecosystem?

• A new API for inter-server communication
• New official adapters
• Additional documentation
• Version updates
• What's next

A new API for inter-server communication​

This feature had been requested for quite some time, it is now implemented in release 4.1.0. It allows to broadcast events between your Socket.IO servers.

The syntax is very similar to the existing one, except it's for server-to-server communication:

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

You can find the complete release notes here.

New official adapters​

Historically, the Redis adapter was the only official adapter when scaling to multiple nodes.

There are now three additional official adapters:

• the MongoDB adapter
• the Postgres adapter
• the cluster adapter

Note: the first two were inspired from existing adapters maintained by the community and were updated to support Socket.IO v3.

All of them supports the utility methods that were added in v4, including the serverSideEmit() method described above.

Additional documentation​

• usage with bundlers like webpack for the client and the server
• usage with PM2

Version updates​

• socket.io@4.1.2
• socket.io-client@4.1.2

What's next​

• a continuous focus on the documentation (additional code examples, extended guide, ...)
• additional tooling around Socket.IO

Happy coding!

We have just published a new minor version of Socket.IO: 4.1.0

New features​

• Add support for inter-server communication
• Emit an event when a namespace is created
• Add a way to customize the response headers
• Add a way to get access to the reason of a connection error
• Add a way to ignore the beforeunload event

Add support for inter-server communication​

This feature might be useful in a multi-server setup: you can now broadcast events between your Socket.IO servers.

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

A few notes:

• the events are specific to each namespace

// server A
io.of("/custom").serverSideEmit("sync");

// server B
io.of("/custom").on("sync", () => {
  // ...
});

• the connection, connect and new_namespace (see below) 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 Redis adapter and its associated emitter have been updated to support this new functionality.

Emit an event when a namespace is created​

The new_namespace event will be emitted by the Server instance 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);
});

Add a way to customize the response headers​

The underlying Engine.IO server, which manages the low-level connection (HTTP long-polling and/or WebSocket), will now emit two additional events:

• initial_headers
• headers

Like the name suggests, the initial_headers event will be emitted only for the first HTTP request of the session, while the headers event will be emitted for each HTTP request (including the WebSocket upgrade).

Example:

io.engine.on("initial_headers", (headers, req) => {
  headers["test"] = "123";
  headers["set-cookie"] = "mycookie=456";
});

io.engine.on("headers", (headers, req) => {
  headers["test"] = "789";
});

Note: it was previously possible to achieve this by listening to the "request" event, but this should be easier with those new events:

const httpServer = require("http").createServer();
const { Server } = require("socket.io");
const io = new Server(httpServer);

httpServer.prependListener("request", (req, res) => {
  res.setHeader("test", "789");
});

Add a way to get access to the reason of a connection error​

The underlying Engine.IO server will also emit a new event: connection_error.

Syntax:

io.engine.on("connection_error", (err) => {
  console.log(err.req);      // the request object
  console.log(err.code);     // the error code, for example 1
  console.log(err.message);  // the error message, for example "Session ID unknown"
  console.log(err.context);  // some additional error context
});

Here is the list of possible error codes:

Add a way to ignore the beforeunload event​

A few months ago, a user reported a weird behavior when reloading a page: on Firefox, the Socket instance would emit a disconnect event, but not on Chrome or Safari.

We have published a fix for this issue in socket.io-client@3.1.1, by silently closing the connection when receiving a beforeunload event from the browser.

Unfortunately, this fix had unintended consequences: if you relied on the beforeunload event to prompt the user for confirmation ("your last modifications are not saved yet, do you really want to leave?"), the Socket.IO connection would now be closed, even if the user decided to stay on the page.

That's why we have added the closeOnBeforeunload option, to give you total control over this behavior:

const socket = io("/", {
  closeOnBeforeunload: false // defaults to true
})

• closeOnBeforeunload: true (the default value) will make all browsers behave the same (no disconnect event when reloading the page)
• closeOnBeforeunload: false will ignore the beforeunload event, but you will get a disconnect event on Firefox

That's all for this release, thanks for reading!

Here's the #4 edition of our Monthly update.

So, what's new in the Socket.IO ecosystem?

• A new Admin UI
• A new guide
• Version updates
• What's next

A new Admin UI​

Following our focus on tooling, we have published a first release of the Socket.IO Admin UI:

This Admin UI is meant to give you an overview of your Socket.IO deployment.

Here is the list of the current features:

• overview of the servers and the clients that are currently connected
• details of each socket instance (active transport, handshake, rooms, ...)
• details of each room
• administrative operations (join, leave, disconnect)

And the features which will be added in the near future:

• overview of the number of packets/bytes sent and received per second
• emitting an event to all clients, a room or a particular Socket instance

The installation steps can be found here.

The source code can be found here: https://github.com/socketio/socket.io-admin-ui/

If you have any feedback / suggestions, do not hesitate!

Please note that the Admin UI does support a cluster of several Socket.IO servers too.

A new guide​

We have added a new guide (here), using Socket.IO to create a basic CRUD application.

Version updates​

• socket.io@4.0.2
• socket.io-client@4.0.2

What's next​

• a continuous focus on the documentation (additional code examples, extended guide, ...)
• additional tooling around Socket.IO

Happy coding!

We have published a first release of the Socket.IO Admin UI:

Current features:

• overview of the servers and the clients that are currently connected
• details of each socket instance (active transport, handshake, rooms, ...)
• details of each room
• administrative operations (join, leave, disconnect)

The installation steps can be found here.

The source code can be found here: https://github.com/socketio/socket.io-admin-ui/

If you have any feedback / suggestions, do not hesitate!

Here's the #3 edition of our Monthly update.

So, what's new in the Socket.IO ecosystem?

• Socket.IO v4
• Redis Adapter v6.1.0 and Redis Emitter v4.0.0
• Documentation
• New versions
• What's next

Socket.IO v4​

Wait, already v4?

Yes, but the upgrade should be a lot easier than from v2 to v3, since the two breaking changes only impact the API on the server side.

The most important breaking change is related to broadcasting: calling to() or any other broadcast modifier will now return an immutable object.

Previously, the modifiers were saved on the io instance directly, which could lead to surprising behaviors:

io.to("room1");
// and then later
io.to("room2").emit(/* ... */); // also sent to room1

You were also not able to reuse the operator:

const operator = io.to("room1");

operator.emit(/* ... */); // to room1 (assuming synchronous call)
operator.emit(/* ... */); // to all clients

Even more surprising, with asynchronous code:

io.to("room3").emit("details", await fetchDetails()); // unspecified behavior: maybe in room3, maybe to all clients

Starting with v4.0.0, you can now use io.to() safely:

const operator = io.to("room1").except("room2");

operator.emit(/* ... */);
operator.emit(/* ... */);

This release also brings some interesting new features, like the fetchSockets() method.

Please check the migration guide here.

Redis Adapter v6.1.0 and Redis Emitter v4.0.0​

The Redis adapter (for broadcasting packets with multiple Socket.IO servers) and the Redis emitter (for broadcasting packets from another Node.js process) have been updated in order to support the new features of the v4 release.

For example, the socketsJoin method will work across Socket.IO servers:

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

More information can be found here.

Documentation​

The documentation continues to be improved.

A new example project has been added in the "Get started" section, with middlewares and rooms: Private messaging

As usual, if you find a typo or think that some details are missing, please open an issue here: https://github.com/socketio/socket.io-website

New versions​

• socket.io@4.0.1 (release notes)

  • engine.io-parser@4.0.2 (included in socket.io{% raw %}@{% endraw %}4.0.1)
  • engine.io@5.0.0 (included in socket.io{% raw %}@{% endraw %}4.0.1)
  • socket.io-parser@4.0.4 (included in socket.io{% raw %}@{% endraw %}4.0.1)

• socket.io-client@4.0.1

  • engine.io-parser@4.0.2 (included in socket.io-client{% raw %}@{% endraw %}4.0.1)
  • engine.io-client@5.0.1 (included in socket.io-client{% raw %}@{% endraw %}4.0.1)
  • socket.io-parser@4.0.4 (included in socket.io-client{% raw %}@{% endraw %}4.0.1)

• socket.io-redis@6.1.0

• @socket.io/redis-emitter@4.0.0

What's next​

• a continuous focus on the documentation (additional code examples, extended guide, ...)
• additional tooling around Socket.IO

Stay safe!

We just published a new major version of Socket.IO: 4.0.0

Please see the associated migration guide.

TL;DR: this major bump is due to a few breaking changes at the API level.

Apart from this, the Socket.IO protocol was not updated, so a v3 client will be able to reach a v4 server and vice-versa. Besides, the compatibility mode (allowEIO3: true) is still available between a Socket.IO v2 client and a Socket.IO v4 server.

Bug Fixes (server)​

• make io.to(...) immutable (ac9e8ca)
• set default protocol version to 3 (#616) (868d891) (Engine.IO)

Bug Fixes (client)​

• bundle: restore support for JS modules (43613d1)

Features (server)​

• add some utility methods (b25495c)
• add support for typed events (#3822) (0107510)
• allow to exclude specific rooms when broadcasting (#3789) (7de2e87)
• allow to pass an array to io.to(...) (085d1de)
• increase the default value of pingTimeout (5a7fa13) (Engine.IO)
• remove dynamic require() with wsEngine (edb7343) (Engine.IO)

Features (client)​

• add autoUnref option (6abfa1f)
• add support for typed events (5902365)
• listen to the "offline" event (c361bc6) (Engine.IO client)

We just published a new version of Socket.IO: 3.1.0

In order to ease the migration to Socket.IO v3, the v3 server is now able to communicate with v2 clients:

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

This should make the migration easier for existing deployments:

• first, update the servers with allowEIO3 set to true

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.

The migration guide was updated accordingly.

Features​

• confirm a weak but matching ETag (#3485) (161091d)
• esm: export the Namespace and Socket class (#3699) (233650c)
• add support for Socket.IO v2 clients (9925746)
• add room events (155fa63)

Bug Fixes​

• typings: make Manager#opts public (#1437) (fe97243)
• allow integers as event names (1c220dd)

We just published a new minor version in the 2.x branch!

Please note that this release contains a breaking change regarding Cross-Origin Resource Sharing (CORS).

UPDATE: this change was reverted in 2.4.1, because it did not follow semantic versioning and broke some deployments (discussed here). Please make sure you are properly securing your application, and upgrade to Socket.IO v3 as soon as possible.

Previously, CORS was enabled by default, which meant that a Socket.IO server sent the necessary CORS headers (Access-Control-Allow-xxx) to any domain. This will not be the case anymore, and you now have to explicitly enable it.

Please note that you are not impacted if:

• you are using Socket.IO v2 and the origins option to restrict the list of allowed domains
• you are using Socket.IO v3 (disabled by default)

This change also removes the support for '*' matchers and protocol-less URL:

io.origins('https://example.com:443'); => io.origins(['https://example.com']);
io.origins('localhost:3000');          => io.origins(['http://localhost:3000']);
io.origins('http://localhost:*');      => io.origins(['http://localhost:3000']);
io.origins('*:3000');                  => io.origins(['http://localhost:3000']);

To restore the previous behavior (please use with caution):

io.origins((_, callback) => {
  callback(null, true);
});

A big thanks to @ni8walk3r for the detailed security report.

See also:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
• https://socket.io/docs/v2/handling-cors/

Features​

• add support for all cookie options (19cc582)
• disable perMessageDeflate by default (5ad2736)

Bug Fixes​

• security: do not allow all origins by default (f78a575)
• properly overwrite the query sent in the handshake (d33a619)

Stay safe!

Here's the #2 edition of our Monthly update. This is a new experiment, we will try to stick to this frequency in order to keep you updated of the work in progress and the directions the project is taking.

So, what's new in the Socket.IO ecosystem?

Socket.IO v3​

As announced in the previous monthly update, Socket.IO v3 has been released a few days ago.

This major version bump is mandated by several necessary changes in the Engine.IO protocol. You can find more information about these changes in the Engine.IO v4 release notes.

You can find the release notes here and the migration guide here.

Let's discuss about this release here: https://github.com/socketio/socket.io/discussions/3674

Redis Adapter v6​

Following the release of Socket.IO v3.0.0, the Redis Adapter was updated and a new release is out: 6.0.0

You can find the release notes here.

Documentation​

The documentation has always been a weak point of the project, leading to a lot of issues opened on GitHub and questions on StackOverflow.

Now that v3 is out, we will focus on this. The following pages have already been created:

• Emitting events
• Broadcasting events
• The Socket instance / server-side
• Middlewares
• Handling CORS

If you find a typo, please open an issue here: https://github.com/socketio/socket.io-website

Minor bumps​

• socket.io@3.0.3 (release notes)

  • engine.io-parser@4.0.1 (included in socket.io{% raw %}@{% endraw %}3.0.3)
  • engine.io@4.0.4 (included in socket.io{% raw %}@{% endraw %}3.0.3)
  • socket.io-parser@4.0.1 (included in socket.io{% raw %}@{% endraw %}3.0.3)

• socket.io-client@3.0.3

  • engine.io-parser@4.0.1 (included in socket.io-client{% raw %}@{% endraw %}3.0.3)
  • engine.io-client@4.0.4 (included in socket.io-client{% raw %}@{% endraw %}3.0.3)
  • socket.io-parser@4.0.1 (included in socket.io-client{% raw %}@{% endraw %}3.0.3)

• socket.io-redis@6.0.1

• socket.io-msgpack-parser@3.0.1

More information about how to use those custom parsers can be found here.

What's next​

• the client implementations in other languages will be updated as well

• a big focus on the documentation (additional code examples, extended guide, ...)

• additional tooling around Socket.IO

Stay safe!

For reference, the Redis Adapter is used when broadcasting packets across a set of Socket.IO servers. It relies on Redis Pub/Sub mechanism.

More information about how it works: https://github.com/socketio/socket.io-redis/#how-does-it-work-under-the-hood

The release notes can be found here: https://github.com/socketio/socket.io-redis/releases/tag/6.0.0

Please note that the new release is not compatible with Socket.IO v2, and previous versions are not compatible with Socket.IO v3 (compatibility table).

Notable changes​

All the requests (for inter-node communication) now return a Promise instead of accepting a callback​

The Redis Adapter exposes additional methods for managing sockets and rooms in a multi-node setup:

• RedisAdapter.sockets(): returns the list of Socket IDs
• RedisAdapter.allRooms(): returns the list of all rooms.
• RedisAdapter.remoteJoin(id, room): make the socket join the room
• RedisAdapter.remoteLeave(id, room): make the socket leave the room
• RedisAdapter.remoteDisconnect(id, close): disconnect the socket with the given id

Those methods used to accept a callback argument, they will now return a Promise.

Before:

io.of('/').adapter.allRooms((err, rooms) => {
  console.log(rooms); // an array containing all rooms (across all nodes)
});

After:

const rooms = await io.of('/').adapter.allRooms();
console.log(rooms); // a Set containing all rooms (across all nodes)

customHook and customRequest methods were removed​

Those methods will be replaced by a more intuitive API in a future iteration.

Migration guide​

This release contains a few non backward compatible changes.

We have published a dedicated migration guide with all necessary details.

Why Socket.IO in 2020?​

That's an excellent question actually. Depending on your use case, it might make sense to use plain WebSocket directly:

• client: MDN, Can I use?
• server: ws or eiows in the Node.JS ecosystem

What Socket.IO brings:

• a fallback to HTTP long-polling, in case the WebSocket connection cannot be established

To be honest, this feature was awesome 10 years ago, when most browsers didn't support WebSocket, but this is not the case anymore. That's still a great safety net though.

• auto-reconnection

Using plain WebSocket, you can take a look at robust-websocket.

• a classic request-response API: acknowledgements

// on one side
socket.emit("updateitem", "1", { name: "updated" }, (response) => {
  console.log(response.status); // ok
});
// on the other
socket.on("updateitem", (arg1, arg2, callback) => {
  console.log(arg1); // 1
  console.log(arg2); // { name: "updated" }
  callback({
    status: "ok"
  });
});

• a way to broadcast data to a given set of clients: Rooms

// server-side
io.on("connection", (socket) => {
  socket.join("room1");

  io.to("room1").emit("hello!");
});

Which also works when scaling to several Socket.IO servers (more information here).

• a way to split your application logic into distinct modules (for more complex applications): Namespaces

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

adminNamespace.use((socket, next) => {
  // ensure the socket is authorized
});

adminNamespace.on((socket) => {
  socket.on("delete project", (id) => {
    // in all handlers, we are sure that the socket is authorized
  });
});

adminNamespace.emit("hello!"); // broadcast to admin only

• an ecosystem of compatible clients in other languages

  • Java: https://github.com/socketio/socket.io-client-java
  • C++: https://github.com/socketio/socket.io-client-cpp
  • Swift: https://github.com/socketio/socket.io-client-swift
  • Dart: https://github.com/rikulo/socket.io-client-dart
  • Python: https://github.com/miguelgrinberg/python-socketio
  • .Net: https://github.com/Quobject/SocketIoClientDotNet

What's next​

• the Redis adapter (used when broadcasting across Socket.IO servers) will be updated in order to be compatible with Socket.IO v3 (update: done!)

• the client implementations in other languages will be updated as well

  • Java client: done!
  • C++ client: done!
  • Swift: done!

• a big focus on the documentation (additional code examples, extended guide, ...)

• additional tooling around Socket.IO

Let's discuss!​

The project is now part of the beta of Github Discussions. Depending on the feedback of the community, it might replace the Slack channel in the future.

If you have any question about the release, let's discuss here.

Stay safe!

Here's the #1 edition of our Monthly update. This is a new experiment, we will try to stick to this frequency in order to keep you updated of the work that is in progress and the directions the project is taking.

So, what's new in the Socket.IO ecosystem?

Socket.IO v3 (WIP)​

The work on Socket.IO v3 has started (let's be honest and not say resumed).

This major version bump is mandated by several necessary changes in the Engine.IO protocol. You can find more information about these changes in the Engine.IO v4 release notes.

It mostly impacts the way packets are encoded when sent over the wire (in the request/response body in case of HTTP long-polling, or in the WebSocket frames), so the public API of Socket.IO should not be impacted that much.

We will also take advantage of this new version to migrate the codebase to Typescript, so the typings which are currently hosted in the DefinitelyTyped will now always be in sync with the actual code.

You can follow the progress here.

If you have any feedback/feature that you would like to see included, please comment here.

Engine.IO v4​

As part of the work towards Socket v3, Engine.IO v4 has been released.

The list of breaking changes can be found in the release notes.

Protocol documentation​

The documentation of the Engine.IO and the Socket.IO protocols has been edited with additional details/examples.

This should help greatly when implementing a client in another programming language.

If you find that something is not clear/is missing, please open an issue in the repository.

For reference, here's the current list of clients in other languages:

• Java: https://github.com/socketio/socket.io-client-java
• C++: https://github.com/socketio/socket.io-client-cpp
• Swift: https://github.com/socketio/socket.io-client-swift
• Dart: https://github.com/rikulo/socket.io-client-dart
• Python: https://github.com/miguelgrinberg/python-socketio
• .Net: https://github.com/Quobject/SocketIoClientDotNet

GitHub discussions​

The project is now part of the beta of Github Discussions. Depending on the feedback of the community, it might replace the Slack channel in the future.

So, let's discuss!

Minor bumps​

• socket.io-client@2.3.1 (release notes)

  • engine.io-parser@2.2.1 (included in socket.io-client{% raw %}@{% endraw %}2.3.1)
  • engine.io-client@3.4.4 (included in socket.io-client{% raw %}@{% endraw %}2.3.1)
  • socket.io-parser@3.3.1 (included in socket.io-client{% raw %}@{% endraw %}2.3.1)

• socket.io-json-parser@2.1.1

• socket.io-msgpack-parser@2.2.1

More information about how to use those custom parsers can be found here.

Going forward​

As announced at the bottom of the Engine.IO v4 release notes, I (@darrachequesne) am now dedicated full time to the project since the beginning of September. This wouldn't be possible without our sponsors, so again, a big thanks to them!

Stay safe!

We have published a minor version of the client: 2.3.1

The debug dependency has been reverted to ~3.1.0, as the newer versions contains ES6 syntax which breaks in IE browsers.

Please note that this only applied to users that bundle the Socket.IO client in their application, with webpack for example, as the "official" bundles (in the dist/ folder) were already transpiled with babel.

For webpack users, you can also take a look at the webpack-remove-debug plugin.

Bug Fixes​

• fix reconnection after opening socket asynchronously (#1253) (050108b)

Get the latest client from the CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.3.1/socket.io.slim.js"></script>

For an explanation between the different bundles, please see here.

Stay safe!

Major breaking changes​

Heartbeat mechanism reversal​

We have received a lot of reports from users that experience random disconnects due to ping timeout, even though their Internet connection is up and the remote server is reachable. It should be noted that in that case the client reconnects right away, but still it was an annoying issue.

After analysis, it seems to be caused by delayed timers on the client-side. Those timers are used in the ping-pong mechanism which helps to ensure the connection between the server and the client is still healthy. A delay on the client-side meant the client sent the ping packet too late, and the server considered that the connection was closed.

That's why the ping packets will now be sent by the server, and the client will respond with a pong packet.

Packet encoding​

We have also changed the way the data is encoded. It previously relied on the string length in Javascript, which meant it was harder to implement clients in other programming languages that do not share the same encoding (more details here).

Technically speaking, it impacts the way an array of packets is encoded when using XHR polling (WebSocket is not affected, as each packet is sent in its own WebSocket frame).

socket.send("€€");
socket.send("й");

// v3 encoding output
"3:4€€2:4й"

// 3        "4€€".length (the JS specific part, 6 bytes)
// :        separator
// 4        the "message" packet type
// €€       the content of the first packet
// 2        "4й".length (again, the JS specific part)
// :        separator
// 4        the "message" packet type
// й        the content of the second packet

// v4 encoding output
"4€€\x1e4й"

// 4        the "message" packet type
// €€       the content of the first packet
// \x1e     separator
// 4        the "message" packet type
// й        the content of the second packet

You can find more details about the updates to the protocol here.

Other changes​

CORS handling​

We now use the cors package to handle the CORS configuration. The handlePreflightRequest option was removed:

const { Server } = require('engine.io');

// before
new Server({
  handlePreflightRequest: (req, res) => {
    res.writeHead(200, {
      "Access-Control-Allow-Origin": 'https://example.com',
      "Access-Control-Allow-Methods": 'GET',
      "Access-Control-Allow-Headers": 'Authorization',
      "Access-Control-Allow-Credentials": true
    });
    res.end();
  }
});

// after
new Server({
  cors: {
    origin: "https://example.com",
    methods: ["GET"],
    allowedHeaders: ["Authorization"],
    credentials: true
  }
});

Please see here for all available options.

No cookie by default​

In Engine.IO v3, the io cookie was sent by default. This cookie can be used to enable sticky-session, which is required when you have several servers (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:

const { Server } = require('engine.io');

// before
new Server({
  cookieName: "io",
  cookieHttpOnly: false,
  cookiePath: "/custom"
});

// after
new Server({
  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.

The default value of maxHttpBufferSize was decreased​

This option defines how many bytes or characters a message can be, before closing the connection. It was reduced from 100MB to 1MB.

const { Server } = require('engine.io');

new Server({
  maxHttpBufferSize: 1e8 // defaults to 1e6
});

perMessageDeflate is now disabled by default​

This option defines whether the WebSocket permessage-deflate extension is enabled or not. This feature, while useful in some cases, adds some extra memory overhead for each WebSocket connection, and could result in huge memory usage in production deployments. It is now disabled by default.

const { Server } = require('engine.io');

new Server({
  perMessageDeflate: true // defaults to false
});

Support for Node.js 8 was dropped​

We are dropping support for Node.js 8, which is now End-of-Life. It will not be tested in the CI anymore, so please upgrade as soon as possible!

How to upgrade​

As detailed in the Major breaking changes section, this release contains several backward incompatible changes, and as such v3 clients will not be able to connect to a v4 server (and vice versa).

In order to upgrade a live production environment, you will need to have both a group of v3 servers and v4 servers in parallel, and route the traffic based on either:

• the EIO query parameter
• the path (by using a different path for the v4 servers)
• or the domain if you use a different domain for the v4 servers

So that it shall be a seamless migration for your end users.

What's next​

This release will be included in Socket.IO v3 in the near future. We will publish a more detailed roadmap in the next blog post.

Besides, I (@darrachequesne) am glad to announce that I will be dedicated full time to the project for the next months. This is possible thanks to our awesome sponsors.

Again, a big shout out to Pia Mancini and all the team behind the Open Collective platform, which helps making Open Source Software sustainable in the long term.

Let's discuss!​

The project is now part of the beta of Github Discussions. Depending on the feedback of the community, it might replace the Slack channel in the future.

If you have any question about the release, let's discuss about it here.

Stay safe!

Including:

• A fix for a race condition within middleware: Issue #2935

• A fix for a potential race condition when emitting to a room: Issue #2962

• A fix for the query option in the client: Issue #1086

Get the latest client from the CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.0.3/socket.io.js"></script>

Open Collective provides a transparent, sustainable, and secure way for people to support and sponsor open source projects. We are joining other great projects (you may have heard about MochaJS, GulpJS or webpack, among lots of other awesome projects) in the quest to ensure the project's sustainability.

What is an Open Collective?​

From their website:

An Open Collective is a group of people with a shared mission that operates in full transparency.

That allows both individuals and companies to sponsor our mission at Socket.IO (with potential tax benefits).

What would Socket.IO do with my sponsorship?​

That will enable the core contributors to spend more time assuring the maintenance of the project. That includes:

• triaging issues and pull requests

• answering questions on Slack and Stackoverflow (which have been somewhat neglected recently)

• updating the documentation (I think a lot has been done recently, but there is still room for improvement!)

Personally I would like to be able to devote a few days a month to the project (I mean a whole day of work, not a few hours taken here and there, usually late in the evening).

The goals in the near future:

• keep the 2.0 version as stable as possible
• provide a complete documentation
• add more examples, besides the classic chat

How can I help?​

To become a sponsor or backer, visit our open collective page and follow the instructions for becoming a part of our collective. Please also take the time to explore the other awesome collectives that people are supporting.

And finally, a big thanks to Pia Mancini and her partners for making this possible.

This major release brings several performance improvements:

• uws is now the default Websocket engine. It should bring significant improvement in performance (particularly in terms of memory consumption) (release note of Engine.IO)

• the Engine.IO and Socket.IO handshake packets were merged, reducing the number of roundtrips necessary to establish a connection. (#2833)

• it is now possible to provide a custom parser according to the needs of your application (#2829). Please take a look at the example for more information.

Please note that this release is not backward-compatible, due to:

• a breaking change related to utf-8 encoding in engine.io-parser

• an update to make the socket id on the client match the id on the server-side (#1058)

Related packages were updated accordingly:

• socket.io-redis version 5.x

• socket.io-emitter version 3.x

Get the latest client from the CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.0.1/socket.io.js"></script>

• Fixed socket.io-client usage with NativeScript.
• Fixed graceful close of the attached http Server of socket.io and engine.io.

Get the latest client from the CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.4.5/socket.io.min.js"></script>

• Building with browserify or webpack is now completely straightforward. No need to exclude/ignore or noParse/externals the ws module.

• Improved the JSONP transport when socket.io-client or engine.io-client are lazily evaluated or the <script> tag that included them gets removed.

Get the latest client from the CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.4.4/socket.io.min.js"></script>

• Socket.IO-client now includes the latest version of engine.io-client

• Fixed an issue that was preventing bundling with webpack.

• Socket.IO now adds support for NativeScript!

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.4.3/socket.io.min.js"></script>

Compression is enabled by default, as it’s highly beneficial for most application payloads. The following example shows the savings for a realtime stream of tweets.

The compression gains will vary by transport. For example, WebSocket defaults to a window size of 32kb when DEFLATE compression is enabled. Repeated occurrences of strings within that window will be compressed. The following demo (inspired by Julia Evans work) will highlight what the LZ77 algorithm de-duplicates from the traffic sent by the Twitter stream that matches javascript.

How this demo works: we re-implemented a part of LZ77 in JavaScript. A React component then renders the compressed strings.

The longer the string, the darker the shade of yellow displayed.

In addition to this default behavior, we’ve introduced the capability to perform selective per-message compression, by introducing the compress flag when emitting an event.

socket.compress(true).emit(‘hi’, { some: ‘data’ });

To configure the defaults, we’ve introduced the following two options that you can pass to socket.io (and engine.io) when starting the server:

• perMessageDeflate – options to customize WebSocket compression (see here) or true for defaults (true).

• httpCompression – options to customize compression for HTTP polling transports or true for defaults (true)

The memory overhead when compression is enabled is not inexistent, however. Make sure to account for a 300kb~ overhead per connection in terms of memory allocation. Read here about the parameters you can customize to change how much memory is allocated and how aggressively data is compressed.

The following improvements have been made to the server:

• Assume 443 port when passing https:// to the origins parameter – Evan Lucas
• Improve detection of binary data inside events (in the has-binary module) – Gunther Brunner
• Warn about missing error event handlers on sockets to prevent silent hard-to-debug situations
• Allow a custom function for the allowRequest function for origins verification
• Fixes for “use strict” environments – Naoyuki Kanezawa
• Prevent users calling the ack function multiple times – Kevin Jose Martin
• Fixed potential memory leaks with open sockets when upgrade fails – Naoyuki Kanezawa
• Fix lingering requests when a polling error occurs – Naoyuki Kanezawa
• Drastically more memory efficient when keeping track of clients – Damien Arrachequesne
• Drastically more memory efficient when keeping track of rooms – Jérémy Lal
• Trigger callback if the client is already in the given room when join is called – Damien Arrachequesne
• Minor parser fixes and performance improvements.

The following improvements have been made to the client:

• Fix for specifying custom ports when connecting
• 2 or more connections to the same namespace now create new sockets, instead of reusing a single one.
• Added new reserved ping and pong events when a heartbeat is emitted and received.
• Add support for environments that extend Object.prototype – Damien Arrachequesne
• Fixes for “use strict” environments – Naoyuki Kanezawa
• Added an extraHeaders feature for custom headers in HTTP transports (non-WebSocket)
• Fix handling of disconnection while in the opening state.
• Improved error handling for unmatched acknowledgements.
• Parser fixes and improvements.

We've also released socket.io-redis 0.2.0 with significant performance improvements.

Special thanks to Damien Arrachequesne, Naoyuki Kanezawa and Jérémy Lal for their amazing and continued contributions that made this release possible.

Lets look at the API and build a little chat application. Or check out the repository directly!

Socket.IO P2P provides an easy and reliable way to setup a WebRTC connection between peers and communicate using the socket.io-protocol.

Socket.IO is used to transport signaling data and as a fallback for clients where the WebRTC PeerConnection is not supported. Adding a simple piece of middleware to your socket.io setup enables this – no need to hand roll your own signaling exchange or set up, deploy and scale new servers.

Usage​

It only takes a few lines of code to set up the server and client.

Server:

var io = require('socket.io')(server);
var p2p = require('socket.io-p2p-server').Server;
io.use(p2p);

Client:

var P2P = require('socket.io-p2p');
var io = require('socket.io-client');
var socket = io();
var p2p = new P2P(socket);
p2p.on('peer-msg', function (data) {
  console.log('From a peer %s', data);
});

There are various options for the advanced user. Once signaling data has been exchanged an upgrade event is triggered and an optional callback is called.

var opts = { numClients: 10 }; // connect up to 10 clients at a time
var p2p = new P2P(socket, opts, function(){
  console.log('We all speak WebRTC now');
});

The Chat example​

We will build a simple chat application, as our tradition dictates, but with P2P capabilities! In this application:

• Clients can send text messages to each other. Messages display in a timeline
• Clients connect to each other over socket.io and initially send messages via the server
• Clients can choose to go private – switching the transport to WebRTC
• All clients connected to the server can connect via WebRTC up to a maximum of 10 clients

All code from this example is included in the main repository.

We first setup the client with autoUpgrade set to false so that clients can upgrade the connection themselves. Set numClients to 10 to allow up to 10 clients to connect with each other.

var opts = {autoUpgrade: false, numClients: 10};
var p2psocket = new P2P(socket, opts)

Setup the event listeners:

p2psocket.on('peer-msg', function(data) {
  // append message to list
});

p2psocket.on('go-private', function () {
  p2psocket.upgrade(); // upgrade to peerConnection
});

In this example, we want any clients connecting to the server to exchange signaling data with each other. We can use the server component as a simple middleware. Clients will connect on the root namespace.

If we wanted clients to exchange signalling data in rooms, rather than on a whole namespace, we could use the server module upon connection like this.

var server = require('http').createServer();
var p2pserver = require('socket.io-p2p-server').Server
var io = require('socket.io')(server);
server.listen(3030)
io.use(p2pserver);

We then setup listeners to pass messages between clients and to broadcast the go-private event.

io.on('connection', function(socket) {
  socket.on('peer-msg', function(data) {
    console.log('Message from peer: %s', data);
    socket.broadcast.emit('peer-msg', data);
  })

  socket.on('go-private', function(data) {
    socket.broadcast.emit('go-private', data);
  });
});

Thats all you need: add a little markup we are off! Heres the demo application in action:

Thanks to Guillermo Rauch (@rauchg) for the advice, testing and patience, Harrison Harnisch (@hharnisc) for bug fixes and to Feross Aboukhadijeh (@feross) for providing the underlying WebRTC abstraction simple-peer.

Pull requests, issues, comments and general rantings are all welcome over at the GitHub repo.

Based on Boost and WebSocket++, this full-featured Socket.IO 1.0 client has the fundamental advantage of working on multiple platforms. Check out the directory of examples. It contains examples of iOS, QT, and CLI chat clients!

To learn how to use this client, I put together a QT chat example that communicates using a Socket.IO Node.JS chat server. Keep reading for step-by-step instructions.

Introduction​

If you’d like to follow along, begin by cloning the socket.io-client-cpp repository using the following:

git clone --recurse-submodules https://github.com/socketio/socket.io-client-cpp.git

The app includes the following features:

• Send messages to all users joining the room.
• Receive a notification when users join or leave the room.
• Receive notifications when a user starts typing a message.

Before you get started, visit the QT community to download and install QT.

Creating a QT GUI Application​

Launch the QT Creator.

On the welcome page, select New Project, then create a QT Widget Application. Name it SioChatDemo.

The project structure should look like this:

SioChatDemo
    |__ SioChatDemo.pro
    |__Headers
    |   |__mainwindow.h
    |__Sources
    |   |__main.cpp
    |   |__mainwindow.cpp
    |__Forms
        |__mainwindow.ui

Importing an SioClient​

Lets copy the SioClient into the QT project under the subfolder sioclient.

Edit SioChatDemo.pro to configure paths and compile options by simply adding:

SOURCES += ./sioclient/src/sio_client.cpp
           ./sioclient/src/sio_packet.cpp

HEADERS  += ./sioclient/src/sio_client.h
            ./sioclient/src/sio_message.h

INCLUDEPATH += $$PWD/sioclient/lib/rapidjson/include
INCLUDEPATH += $$PWD/sioclient/lib/websocketpp

Add two additional compile options:

CONFIG+=no_keywords
CONFIG+=c++11

The no_keywords flag prevents qmake from treating some function names as emit as the keyword for the signal-slot mechanism.

Use c++11 to ask for C++11 support.

Importing Boost​

We now have our boost headers and a fat boost static lib named libboost.a(non-win32) or boost.lib(win32).

To import them, we need to edit SioChatDemo.pro again by adding a header including the following:

INCLUDEPATH += `our boost headers folder`

Linker options:

win32:CONFIG(release, debug|release): LIBS += -L`our Win32 boost static lib folder` -lboost
else:win32:CONFIG(debug, debug|release): LIBS += -L`our Win32 boost static lib folder` -lboost
else:unix: LIBS += -L`our osx boost static lib folder` -lboost

Create the Main Window UI​

Create a simple UI by dragging and dropping a widget from the widget box on the left-hand side.

It contains the following:

• A QLineEdit at the top to input a nickname: nickNameEdit
• A QPushButton at the top right for login: loginBtn
• A QListWidget in the center for showing messages: listView
• A QLineEdit at the bottom for typing messages: messageEdit
• A QPushButton at the bottom right for sending messages: sendBtn

Add Slots in the Main Window​

The following slots need to be added in the mainwindow class to handle UI events:

• Click ‘Login’ button
• Click ‘Send Message’ button
• Text change in message editing (to show typing status)
• Return message editing (for sending responses)

Insert the following code into the MainWindow class in mainwindow.h:

public Q_SLOTS:
    void SendBtnClicked();
    void TypingChanged();
    void LoginClicked();
    void OnMessageReturn();

Connect the UI Event Signal and Slots​

Open mainwindow.ui in the design mode. Switch to the signals/slots mode using Menu->Edit->Edit Signals/Slots.

Click and hold the widget and drag it to the window (the cursor will become an electrical ground symbol) to open the connection editor.

In the connection editor, edit the main window slots on the right side. Add the slot function names added in mainwindow.h before.

Then we can connect the event signal to the widget with our own slots. The result should look like this:

Adding UI Refresh Signals/Slots​

The sio::client callbacks are not in the UI thread. However, the UI must be updated with those callbacks, so we need a signal for the non-UI thread to request the slots functions in the UI thread. To signal that QListWidgetItem has been added, insert the following:

// in mainwindow.h
Q_SIGNALS:
    void RequestAddListItem(QListWidgetItem *item);
private Q_SLOTS:
    void AddListItem(QListWidgetItem *item);

//In mainwindow.cpp
void MainWindow::AddListItem(QListWidgetItem* item)
{
    this->findChild<QListWidget*>("listView")->addItem(item);
}

Then connect them in the MainWindow constructor.

connect(this,SIGNAL(RequestAddListItem(QListWidgetItem*)),this,SLOT(AddListItem(QListWidgetItem*)));

Setting up the Socket​

For single-window applications, simply let MainWindow class hold the sio::client object by declaring a unique_ptr member of the sio::client and several event handling functions in mainwindow.h.

private:
    void OnNewMessage(std::string const& name,message::ptr const& data,bool hasAck,message::ptr &ack_resp);
    void OnUserJoined(std::string const& name,message::ptr const& data,bool hasAck,message::ptr &ack_resp);
    void OnUserLeft(std::string const& name,message::ptr const& data,bool hasAck,message::ptr &ack_resp);
    void OnTyping(std::string const& name,message::ptr const& data,bool hasAck,message::ptr &ack_resp);
    void OnStopTyping(std::string const& name,message::ptr const& data,bool hasAck,message::ptr &ack_resp);
    void OnLogin(std::string const& name,message::ptr const& data,bool hasAck,message::ptr &ack_resp);
    void OnConnected();
    void OnClosed(client::close_reason const& reason);
    void OnFailed();

    std::unique_ptr<client> _io;

Initialize sio::client and setup event bindings for the default socket in the MainWindow constructor.

We also need to handle connectivity and disconnect events.

Add the following to the MainWindow constructor:

MainWindow::MainWindow(QWidget *parent) :
    QMainWindow(parent),
    ui(new Ui::MainWindow),
    _io(new client())
{
    ui->setupUi(this);
    using std::placeholders::_1;
    using std::placeholders::_2;
    using std::placeholders::_3;
    using std::placeholders::_4;
    socket::ptr sock = _io->socket();
    sock->on("new message",std::bind(&MainWindow::OnNewMessage,this,_1,_2,_3,_4));
    sock->on("user joined",std::bind(&MainWindow::OnUserJoined,this,_1,_2,_3,_4));
    sock->on("user left",std::bind(&MainWindow::OnUserLeft,this,_1,_2,_3,_4));
    sock->on("typing",std::bind(&MainWindow::OnTyping,this,_1,_2,_3,_4));
    sock->on("stop typing",std::bind(&MainWindow::OnStopTyping,this,_1,_2,_3,_4));
    sock->on("login",std::bind(&MainWindow::OnLogin,this,_1,_2,_3,_4));
    //default socket opened, also we have "set_open_listener" for monitoring physical connection opened.
    _io->set_socket_open_listener(std::bind(&MainWindow::OnConnected,this,std::placeholders::_1));
    //physical connection closed or drop.
    _io->set_close_listener(std::bind(&MainWindow::OnClosed,this,_1));
    //physical connection fail to establish.
    _io->set_fail_listener(std::bind(&MainWindow::OnFailed,this));
    connect(this,SIGNAL(RequestAddListItem(QListWidgetItem*)),this,SLOT(AddListItem(QListWidgetItem*)));
}