Readme.md (16588B)
1 2 # socket.io 3 4 [](#backers) [](#sponsors) 5 [](https://travis-ci.org/socketio/socket.io) 6 [](https://david-dm.org/socketio/socket.io) 7 [](https://david-dm.org/socketio/socket.io#info=devDependencies) 8 [](https://www.npmjs.com/package/socket.io) 9  10 [](https://slackin-socketio.now.sh) 11 12 ## Features 13 14 Socket.IO enables real-time bidirectional event-based communication. It consists of: 15 16 - a Node.js server (this repository) 17 - a [Javascript client library](https://github.com/socketio/socket.io-client) for the browser (or a Node.js client) 18 19 Some implementations in other languages are also available: 20 21 - [Java](https://github.com/socketio/socket.io-client-java) 22 - [C++](https://github.com/socketio/socket.io-client-cpp) 23 - [Swift](https://github.com/socketio/socket.io-client-swift) 24 - [Dart](https://github.com/rikulo/socket.io-client-dart) 25 26 Its main features are: 27 28 #### Reliability 29 30 Connections are established even in the presence of: 31 - proxies and load balancers. 32 - personal firewall and antivirus software. 33 34 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 better transports that are "tested" on the side, like WebSocket. Please see the [Goals](https://github.com/socketio/engine.io#goals) section for more information. 35 36 #### Auto-reconnection support 37 38 Unless instructed otherwise a disconnected client will try to reconnect forever, until the server is available again. Please see the available reconnection options [here](https://github.com/socketio/socket.io-client/blob/master/docs/API.md#new-managerurl-options). 39 40 #### Disconnection detection 41 42 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. 43 44 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. 45 46 #### Binary support 47 48 Any serializable data structures can be emitted, including: 49 50 - [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) and [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) in the browser 51 - [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) and [Buffer](https://nodejs.org/api/buffer.html) in Node.js 52 53 #### Simple and convenient API 54 55 Sample code: 56 57 ```js 58 io.on('connection', socket => { 59 socket.emit('request', /* … */); // emit an event to the socket 60 io.emit('broadcast', /* … */); // emit an event to all connected sockets 61 socket.on('reply', () => { /* … */ }); // listen to the event 62 }); 63 ``` 64 65 #### Cross-browser 66 67 Browser support is tested in Saucelabs: 68 69 [](https://saucelabs.com/u/socket) 70 71 #### Multiplexing support 72 73 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. 74 75 #### Room support 76 77 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. 78 79 This is a useful feature to send notifications to a group of users, or to a given user connected on several devices for example. 80 81 82 **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](https://github.com/socketio/socket.io-protocol). 83 84 ## Installation 85 86 ```bash 87 npm install socket.io 88 ``` 89 90 ## How to use 91 92 The following example attaches socket.io to a plain Node.JS 93 HTTP server listening on port `3000`. 94 95 ```js 96 const server = require('http').createServer(); 97 const io = require('socket.io')(server); 98 io.on('connection', client => { 99 client.on('event', data => { /* … */ }); 100 client.on('disconnect', () => { /* … */ }); 101 }); 102 server.listen(3000); 103 ``` 104 105 ### Standalone 106 107 ```js 108 const io = require('socket.io')(); 109 io.on('connection', client => { ... }); 110 io.listen(3000); 111 ``` 112 113 ### In conjunction with Express 114 115 Starting with **3.0**, express applications have become request handler 116 functions that you pass to `http` or `http` `Server` instances. You need 117 to pass the `Server` to `socket.io`, and not the express application 118 function. Also make sure to call `.listen` on the `server`, not the `app`. 119 120 ```js 121 const app = require('express')(); 122 const server = require('http').createServer(app); 123 const io = require('socket.io')(server); 124 io.on('connection', () => { /* … */ }); 125 server.listen(3000); 126 ``` 127 128 ### In conjunction with Koa 129 130 Like Express.JS, Koa works by exposing an application as a request 131 handler function, but only by calling the `callback` method. 132 133 ```js 134 const app = require('koa')(); 135 const server = require('http').createServer(app.callback()); 136 const io = require('socket.io')(server); 137 io.on('connection', () => { /* … */ }); 138 server.listen(3000); 139 ``` 140 141 ## Documentation 142 143 Please see the documentation [here](/docs/README.md). Contributions are welcome! 144 145 ## Debug / logging 146 147 Socket.IO is powered by [debug](https://github.com/visionmedia/debug). 148 In order to see all the debug output, run your app with the environment variable 149 `DEBUG` including the desired scope. 150 151 To see the output from all of Socket.IO's debugging scopes you can use: 152 153 ``` 154 DEBUG=socket.io* node myapp 155 ``` 156 157 ## Testing 158 159 ``` 160 npm test 161 ``` 162 This runs the `gulp` task `test`. By default the test will be run with the source code in `lib` directory. 163 164 Set the environmental variable `TEST_VERSION` to `compat` to test the transpiled es5-compat version of the code. 165 166 The `gulp` task `test` will always transpile the source code into es5 and export to `dist` first before running the test. 167 168 169 ## Backers 170 171 Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/socketio#backer)] 172 173 <a href="https://opencollective.com/socketio/backer/0/website" target="_blank"><img src="https://opencollective.com/socketio/backer/0/avatar.svg"></a> 174 <a href="https://opencollective.com/socketio/backer/1/website" target="_blank"><img src="https://opencollective.com/socketio/backer/1/avatar.svg"></a> 175 <a href="https://opencollective.com/socketio/backer/2/website" target="_blank"><img src="https://opencollective.com/socketio/backer/2/avatar.svg"></a> 176 <a href="https://opencollective.com/socketio/backer/3/website" target="_blank"><img src="https://opencollective.com/socketio/backer/3/avatar.svg"></a> 177 <a href="https://opencollective.com/socketio/backer/4/website" target="_blank"><img src="https://opencollective.com/socketio/backer/4/avatar.svg"></a> 178 <a href="https://opencollective.com/socketio/backer/5/website" target="_blank"><img src="https://opencollective.com/socketio/backer/5/avatar.svg"></a> 179 <a href="https://opencollective.com/socketio/backer/6/website" target="_blank"><img src="https://opencollective.com/socketio/backer/6/avatar.svg"></a> 180 <a href="https://opencollective.com/socketio/backer/7/website" target="_blank"><img src="https://opencollective.com/socketio/backer/7/avatar.svg"></a> 181 <a href="https://opencollective.com/socketio/backer/8/website" target="_blank"><img src="https://opencollective.com/socketio/backer/8/avatar.svg"></a> 182 <a href="https://opencollective.com/socketio/backer/9/website" target="_blank"><img src="https://opencollective.com/socketio/backer/9/avatar.svg"></a> 183 <a href="https://opencollective.com/socketio/backer/10/website" target="_blank"><img src="https://opencollective.com/socketio/backer/10/avatar.svg"></a> 184 <a href="https://opencollective.com/socketio/backer/11/website" target="_blank"><img src="https://opencollective.com/socketio/backer/11/avatar.svg"></a> 185 <a href="https://opencollective.com/socketio/backer/12/website" target="_blank"><img src="https://opencollective.com/socketio/backer/12/avatar.svg"></a> 186 <a href="https://opencollective.com/socketio/backer/13/website" target="_blank"><img src="https://opencollective.com/socketio/backer/13/avatar.svg"></a> 187 <a href="https://opencollective.com/socketio/backer/14/website" target="_blank"><img src="https://opencollective.com/socketio/backer/14/avatar.svg"></a> 188 <a href="https://opencollective.com/socketio/backer/15/website" target="_blank"><img src="https://opencollective.com/socketio/backer/15/avatar.svg"></a> 189 <a href="https://opencollective.com/socketio/backer/16/website" target="_blank"><img src="https://opencollective.com/socketio/backer/16/avatar.svg"></a> 190 <a href="https://opencollective.com/socketio/backer/17/website" target="_blank"><img src="https://opencollective.com/socketio/backer/17/avatar.svg"></a> 191 <a href="https://opencollective.com/socketio/backer/18/website" target="_blank"><img src="https://opencollective.com/socketio/backer/18/avatar.svg"></a> 192 <a href="https://opencollective.com/socketio/backer/19/website" target="_blank"><img src="https://opencollective.com/socketio/backer/19/avatar.svg"></a> 193 <a href="https://opencollective.com/socketio/backer/20/website" target="_blank"><img src="https://opencollective.com/socketio/backer/20/avatar.svg"></a> 194 <a href="https://opencollective.com/socketio/backer/21/website" target="_blank"><img src="https://opencollective.com/socketio/backer/21/avatar.svg"></a> 195 <a href="https://opencollective.com/socketio/backer/22/website" target="_blank"><img src="https://opencollective.com/socketio/backer/22/avatar.svg"></a> 196 <a href="https://opencollective.com/socketio/backer/23/website" target="_blank"><img src="https://opencollective.com/socketio/backer/23/avatar.svg"></a> 197 <a href="https://opencollective.com/socketio/backer/24/website" target="_blank"><img src="https://opencollective.com/socketio/backer/24/avatar.svg"></a> 198 <a href="https://opencollective.com/socketio/backer/25/website" target="_blank"><img src="https://opencollective.com/socketio/backer/25/avatar.svg"></a> 199 <a href="https://opencollective.com/socketio/backer/26/website" target="_blank"><img src="https://opencollective.com/socketio/backer/26/avatar.svg"></a> 200 <a href="https://opencollective.com/socketio/backer/27/website" target="_blank"><img src="https://opencollective.com/socketio/backer/27/avatar.svg"></a> 201 <a href="https://opencollective.com/socketio/backer/28/website" target="_blank"><img src="https://opencollective.com/socketio/backer/28/avatar.svg"></a> 202 <a href="https://opencollective.com/socketio/backer/29/website" target="_blank"><img src="https://opencollective.com/socketio/backer/29/avatar.svg"></a> 203 204 205 ## Sponsors 206 207 Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/socketio#sponsor)] 208 209 <a href="https://opencollective.com/socketio/sponsor/0/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/0/avatar.svg"></a> 210 <a href="https://opencollective.com/socketio/sponsor/1/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/1/avatar.svg"></a> 211 <a href="https://opencollective.com/socketio/sponsor/2/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/2/avatar.svg"></a> 212 <a href="https://opencollective.com/socketio/sponsor/3/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/3/avatar.svg"></a> 213 <a href="https://opencollective.com/socketio/sponsor/4/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/4/avatar.svg"></a> 214 <a href="https://opencollective.com/socketio/sponsor/5/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/5/avatar.svg"></a> 215 <a href="https://opencollective.com/socketio/sponsor/6/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/6/avatar.svg"></a> 216 <a href="https://opencollective.com/socketio/sponsor/7/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/7/avatar.svg"></a> 217 <a href="https://opencollective.com/socketio/sponsor/8/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/8/avatar.svg"></a> 218 <a href="https://opencollective.com/socketio/sponsor/9/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/9/avatar.svg"></a> 219 <a href="https://opencollective.com/socketio/sponsor/10/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/10/avatar.svg"></a> 220 <a href="https://opencollective.com/socketio/sponsor/11/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/11/avatar.svg"></a> 221 <a href="https://opencollective.com/socketio/sponsor/12/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/12/avatar.svg"></a> 222 <a href="https://opencollective.com/socketio/sponsor/13/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/13/avatar.svg"></a> 223 <a href="https://opencollective.com/socketio/sponsor/14/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/14/avatar.svg"></a> 224 <a href="https://opencollective.com/socketio/sponsor/15/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/15/avatar.svg"></a> 225 <a href="https://opencollective.com/socketio/sponsor/16/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/16/avatar.svg"></a> 226 <a href="https://opencollective.com/socketio/sponsor/17/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/17/avatar.svg"></a> 227 <a href="https://opencollective.com/socketio/sponsor/18/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/18/avatar.svg"></a> 228 <a href="https://opencollective.com/socketio/sponsor/19/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/19/avatar.svg"></a> 229 <a href="https://opencollective.com/socketio/sponsor/20/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/20/avatar.svg"></a> 230 <a href="https://opencollective.com/socketio/sponsor/21/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/21/avatar.svg"></a> 231 <a href="https://opencollective.com/socketio/sponsor/22/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/22/avatar.svg"></a> 232 <a href="https://opencollective.com/socketio/sponsor/23/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/23/avatar.svg"></a> 233 <a href="https://opencollective.com/socketio/sponsor/24/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/24/avatar.svg"></a> 234 <a href="https://opencollective.com/socketio/sponsor/25/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/25/avatar.svg"></a> 235 <a href="https://opencollective.com/socketio/sponsor/26/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/26/avatar.svg"></a> 236 <a href="https://opencollective.com/socketio/sponsor/27/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/27/avatar.svg"></a> 237 <a href="https://opencollective.com/socketio/sponsor/28/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/28/avatar.svg"></a> 238 <a href="https://opencollective.com/socketio/sponsor/29/website" target="_blank"><img src="https://opencollective.com/socketio/sponsor/29/avatar.svg"></a> 239 240 241 ## License 242 243 [MIT](LICENSE)