- ×
Realtime application framework for Node.JS, with HTML5 WebSockets and cross-browser fallbacks support.
Filed under dataShow Allsocket.io
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.
Auto-reconnection support
Unless instructed otherwise a disconnected client will try to reconnect forever, until the server is available again. Please see the available reconnection options here.
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
andpingTimeout
parameters) shared during the connection handshake. Those timers require any subsequent client calls to be directed to the same server, hence thesticky-session
requirement when using multiples nodes.Binary support
Any serializable data structures can be emitted, including:
- ArrayBuffer and Blob in the browser
- ArrayBuffer and Buffer in Node.js
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 });
Cross-browser
Browser support is tested in Sauce Labs:
Multiplexing support
In order to create separation of concerns within your application (for example per module, or based on permissions), Socket.IO allows you to create several
Namespaces
, which will act as separate communication channels but will share the same underlying connection.Room support
Within each
Namespace
, you can define arbitrary channels, calledRooms
, that sockets can join and leave. You can then broadcast to any given room, reaching every socket that has joined it.This is a useful feature to send notifications to a group of users, or to a given user connected on several devices for example.
Note: Socket.IO is not a WebSocket implementation. Although Socket.IO indeed uses WebSocket as a transport when possible, it adds some metadata to each packet: the packet type, the namespace and the ack id when a message acknowledgement is needed. That is why a WebSocket client will not be able to successfully connect to a Socket.IO server, and a Socket.IO client will not be able to connect to a WebSocket server (like
ws://echo.websocket.org
) either. Please see the protocol specification here.Installation
// with npm npm install socket.io // with yarn yarn add socket.io
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
orhttp
Server
instances. You need to pass theServer
tosocket.io
, not the express application function. Also make sure to call.listen
on theserver
, not theapp
.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 adecorator
calledio
.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
tasktest
. By default the test will be run with the source code inlib
directory.Set the environmental variable
TEST_VERSION
tocompat
to test the transpiled es5-compat version of the code.The
gulp
tasktest
will always transpile the source code into es5 and export todist
first before running the test.Backers
Support us with a monthly donation and help us continue our activities. [Become a backer]
Sponsors
Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]
License