socket.io

Downloads

Features

Socket.IO enables real-time bidirectional event-based communication. It consists of:

a Node.js server (this repository)
a Javascript client library for the browser (or a Node.js client)

Some implementations in other languages are also available:

Its main features are:

Reliability

Connections are established even in the presence of:

proxies and load balancers.
personal firewall and antivirus software.

For this purpose, it relies on Engine.IO, which first establishes a long-polling connection, then tries to upgrade to better transports that are “tested” on the side, like WebSocket. Please see the Goals section for more information.

Disconnection detection

A heartbeat mechanism is implemented at the Engine.IO level, allowing both the server and the client to know when the other one is not responding anymore.

That functionality is achieved with timers set on both the server and the client, with timeout values (the pingInterval and pingTimeout parameters) shared during the connection handshake. Those timers require any subsequent client calls to be directed to the same server, hence the sticky-session requirement when using multiples nodes.

Simple and convenient API

Sample code:

io.on('connection', socket => {
  socket.emit('request', /* … */); // emit an event to the socket
  io.emit('broadcast', /* … */); // emit an event to all connected sockets
  socket.on('reply', () => { /* … */ }); // listen to the event
});

How to use

The following example attaches socket.io to a plain Node.JS HTTP server listening on port 3000.

const server = require('http').createServer();
const io = require('socket.io')(server);
io.on('connection', client => {
  client.on('event', data => { /* … */ });
  client.on('disconnect', () => { /* … */ });
});
server.listen(3000);

Standalone

const io = require('socket.io')();
io.on('connection', client => { ... });
io.listen(3000);

Module syntax

import { Server } from "socket.io";
const io = new Server(server);
io.listen(3000);

In conjunction with Express

Starting with 3.0, express applications have become request handler functions that you pass to http or http Server instances. You need to pass the Server to socket.io, not the express application function. Also make sure to call .listen on the server, not the app.

const app = require('express')();
const server = require('http').createServer(app);
const io = require('socket.io')(server);
io.on('connection', () => { /* … */ });
server.listen(3000);

In conjunction with Koa

Like Express.JS, Koa works by exposing an application as a request handler function, but only by calling the callback method.

const app = require('koa')();
const server = require('http').createServer(app.callback());
const io = require('socket.io')(server);
io.on('connection', () => { /* … */ });
server.listen(3000);

In conjunction with Fastify

To integrate Socket.io in your Fastify application you just need to register fastify-socket.io plugin. It will create a decorator called io.

const app = require('fastify')();
app.register(require('fastify-socket.io'));
app.io.on('connection', () => { /* … */ });
app.listen(3000);

Documentation

Please see the documentation here.

The source code of the website can be found here. Contributions are welcome!

Debug / logging

Socket.IO is powered by debug. In order to see all the debug output, run your app with the environment variable DEBUG including the desired scope.

To see the output from all of Socket.IO’s debugging scopes you can use:

DEBUG=socket.io* node myapp

Testing

npm test

This runs the gulp task test. By default the test will be run with the source code in lib directory.

Set the environmental variable TEST_VERSION to compat to test the transpiled es5-compat version of the code.

The gulp task test will always transpile the source code into es5 and export to dist first before running the test.

Socket.io