Github url

socket.io

by socketio

socketio /socket.io

Realtime application framework (Node.JS server)

50.2K Stars 9.1K Forks Last release: over 1 year ago (2.2.0) MIT License 1.7K Commits 128 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

socket.io

Backers on Open Collective Sponsors on Open CollectiveBuild StatusDependency StatusdevDependency StatusNPM version Downloads

Features

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

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

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.

Binary support

Any serializable data structures can be emitted, including:

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 Saucelabs:

Sauce Test Status

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, called

Rooms

, 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

npm install 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);

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

, and 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);

Documentation

Please see the documentation 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.

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

MIT

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.