From beefbc96da633c9eb65b26d05b26825ea09cde61 Mon Sep 17 00:00:00 2001 From: Damien Arrachequesne Date: Fri, 13 Jan 2017 12:30:32 +0100 Subject: [PATCH 1/3] Add 'Features' section in the README --- Readme.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/Readme.md b/Readme.md index 3e351470c9..36a2df260b 100644 --- a/Readme.md +++ b/Readme.md @@ -8,6 +8,71 @@ ![Downloads](https://img.shields.io/npm/dm/socket.io.svg?style=flat) [![](http://slack.socket.io/badge.svg?)](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) for 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 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. + +#### 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](https://github.com/socketio/socket.io-client/blob/master/docs/API.md#new-managerurl-options). + +#### Binary support + +Any serializable data structures can be emitted, including: + +- [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 +- [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 + +#### 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: + +[![Sauce Test Status](https://saucelabs.com/browser-matrix/socket.svg)](https://saucelabs.com/u/socket) + +#### 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, it uses WebSocket as a transport when possible but has its own [protocol](https://github.com/socketio/socket.io-protocol). That's why a Socket.IO client will not be able to connect to `ws://echo.websocket.org`. + ## Installation ```bash @@ -65,9 +130,9 @@ io.on('connection', function(){ /* … */ }); server.listen(3000); ``` -## API +## Documentation -See [API](/docs/API.md). +Please see the documentation [here](/docs/README.md). Contributions are welcome! ## Debug / logging From fc2363f08f8cfae13d862ffacb81e367a7bdcb29 Mon Sep 17 00:00:00 2001 From: Damien Arrachequesne Date: Mon, 16 Jan 2017 09:36:02 +0100 Subject: [PATCH 2/3] document the heartbeat mechanism --- Readme.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Readme.md b/Readme.md index 36a2df260b..4512e70e95 100644 --- a/Readme.md +++ b/Readme.md @@ -35,6 +35,12 @@ For this purpose, it relies on [Engine.IO](https://github.com/socketio/engine.io 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). +#### 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 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: From 72220edc3e12e620b92fca5b9bb1a8d93cb50a02 Mon Sep 17 00:00:00 2001 From: Damien Arrachequesne Date: Mon, 16 Jan 2017 09:37:19 +0100 Subject: [PATCH 3/3] Make the 'not a Websocket-implementation' section clearer --- Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Readme.md b/Readme.md index 4512e70e95..66cda4722c 100644 --- a/Readme.md +++ b/Readme.md @@ -77,7 +77,7 @@ Within each `Namespace`, you can define arbitrary channels, called `Rooms`, that 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, it uses WebSocket as a transport when possible but has its own [protocol](https://github.com/socketio/socket.io-protocol). That's why a Socket.IO client will not be able to connect to `ws://echo.websocket.org`. +**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). ## Installation