(The MIT License)

Copyright (c) 2014-2017 Automattic <dev@cloudup.com>

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# socket.io
[![Build Status](https://secure.travis-ci.org/socketio/socket.io.svg?branch=mast
er)](https://travis-ci.org/socketio/socket.io)
[](https://davi
d-dm.org/socketio/socket.io)
[
](https://david-dm.org/socketio/socket.io#info=devDependencies)
[](https://www.npmjs.com/p
ackage/socket.io)
[](http://slack.socket.io)
## Features
Socket.IO enables real-time bidirectional event-based communication. It consists
in:
- a Node.js server (this repository)
- a [Javascript client library](https://github.com/socketio/socket.io-client) fo
r the browser (or a Node.js client)
Some implementations in other languages are also available:
- [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)
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](https://github.com/socketio/engine.io
), which first establishes a long-polling connection, then tries to upgrade to b
etter transports that are "tested" on the side, like WebSocket. Please see the [
Goals](https://github.com/socketio/engine.io#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 opti
ons [here](https://github.com/socketio/socket.io-client/blob/master/docs/API.md#
new-managerurl-options).
#### Disconnection detection
An 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 d
uring 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:
- [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referenc
e/Global_Objects/ArrayBuffer) and [Blob](https://developer.mozilla.org/en-US/doc
s/Web/API/Blob) in the browser
- [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referenc
e/Global_Objects/ArrayBuffer) and [Buffer](https://nodejs.org/api/buffer.html) i
n Node.js
#### Simple and convenient API
Sample code:
```js
io.on('connection', function(socket){
socket.emit('request', /* */); // emit an event to the socket
io.emit('broadcast', /* */); // emit an event to all connected sockets
socket.on('reply', function(){ /* */ }); // listen to the event
});
```
#### Cross-browser
Browser support is tested in Saucelabs:
[](https://
saucelabs.com/u/socket)
#### Multiplexing support
In order to create separation of concerns within your application (for example p
er module, or based on permissions), Socket.IO allows you to create several `Nam
espaces`, which will act as separate communication channels but will share the s
ame 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 give
n 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 pack
et: 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 conn
ect 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 prot
ocol specification [here](https://github.com/socketio/socket.io-protocol).
## Installation
```bash
npm install socket.io --save
```
## How to use
The following example attaches socket.io to a plain Node.JS
HTTP server listening on port `3000`.
```js
var server = require('http').createServer();
var io = require('socket.io')(server);
io.on('connection', function(client){
client.on('event', function(data){});
client.on('disconnect', function(){});
});
server.listen(3000);
```
### Standalone
```js
var io = require('socket.io')();
io.on('connection', function(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`.
```js
var app = require('express')();
var server = require('http').createServer(app);
var io = require('socket.io')(server);
io.on('connection', function(){ /* */ });
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.
```js
var app = require('koa')();
var server = require('http').createServer(app.callback());
var io = require('socket.io')(server);
io.on('connection', function(){ /* */ });
server.listen(3000);
```
## Documentation
Please see the documentation [here](/docs/README.md). Contributions are welcome!
## Debug / logging
Socket.IO is powered by [debug](https://github.com/visionmedia/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 sourc
e 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.
## License
[MIT](LICENSE)