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