wireapp/reconnecting-websocket

Name: reconnecting-websocket

Owner: Wire Swiss GmbH

Description: Reconnecting WebSocket. For Web, React Native, cli (Node.js)

Forked from: pladaria/reconnecting-websocket

Created: 2017-09-20 10:25:59.0

Updated: 2017-10-19 12:27:57.0

Pushed: 2017-09-20 16:11:53.0

Homepage: null

Size: 129

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Reconnecting WebSocket

WebSocket that will automatically reconnect if the connection is closed.

Features

• Small (~150 LOC)
• WebSocket API compatible (same interface, Level0 and Level2 event model)
• Fully configurable
• Multiplatform (Web, ServiceWorkers, Node.js, React Native)
• Dependency free (does not depends on Window, DOM or any EventEmitter library)
• Reassign event listeners when a new WebSocket instance is created
• Automatic reconnection using rfc6455 guidelines
• Handle connection timeouts
• Full test coverage
• Debug mode
• Fast close
• AMD build available (see dist folder)
• Allows changing server URL

Install

install --save reconnecting-websocket

Run tests

one
clone https://github.com/pladaria/reconnecting-websocket
ter
econnecting-websocket
stall deps
install
n tests
test

view the test coverage report
run report

Usage

Compatible with WebSocket Browser API

So this documentation should be valid: MDN WebSocket API.

Ping me if you find any problems. Or, even better, write a test for your case and make a pull request :)

Simple usage

t ReconnectingWebSocket = require('reconnecting-websocket');
t rws = new ReconnectingWebSocket('ws://my.site.com');

addEventListener('open', () => {
rws.send('hello!');

Update URL

The url parameter also accepts a function so you have a chance to update the URL before connecting:

t ReconnectingWebSocket = require('reconnecting-websocket');

t urls = ['ws://my.site.com', 'ws://your.site.com', 'ws://their.site.com'];
urlIndex = 0;

ound robin url provider
t getUrl = () => urls[urlIndex++ % urls.length];

t rws = new ReconnectingWebSocket(getUrl);

Configure

Default options

Options should be self explanatory

t defaultOptions = {
constructor: isGlobalWebSocket() ? WebSocket : null,
maxReconnectionDelay: 10000,
minReconnectionDelay: 1500,
reconnectionDelayGrowFactor: 1.3,
connectionTimeout: 4000,
maxRetries: Infinity,
debug: false,

Sample with custom options

t ReconnectingWebSocket = require('reconnecting-websocket');

t options = {connectionTimeout: 1000};
t rws = new ReconnectingWebSocket('ws://my.site.com', [], options);

Manually closing

The close function has an additional options parameter

e(code = 1000, reason = '', {keepClosed: boolean, fastClose: boolean, delay: number})

• Use the keepClosed option to keep the WebSocket closed or automatically reconnect (default false).
• If fastClose option is true, all close listeners are executed as soon as the close() method is called, otherwise it waits until the websocket closing protocol finishes, this can be a long time if there's no connection (default true). Keep in mind that with this option, it may happen that the close event is fired with a ready state of CLOSING.
• Use the delay option to set the initial delay for the next connection retry (ignored if 0).

Setting WebSocket options

If you set any attributes of WebSocket itself, such as binaryType, make sure to set them again after each reconnection, i.e. on the open event:

addEventListener('open', () => {
ws.binaryType = 'arraybuffer';
ws.send('i am ready to receive some data!');

Using alternative constructor

This way you can use this module in cli/testing/node.js or use a decorated/alternative WebSocket. The only requisite is that the given constructor must be compatible with the WebSocket API.

The example uses the html5-websocket module.

t Html5WebSocket = require('html5-websocket');
t ReconnectingWebSocket = require('reconnecting-websocket');

t options = {constructor: Html5WebSocket};
t rws = new ReconnectingWebSocket('ws://my.site.com', undefined, options);

Max retries

When the max retries limit is reached, an error event with code EHOSTDOWN is emitted.

By default, maxRetries is set to Infinity.

t ReconnectingWebSocket = require('reconnecting-websocket');

t rws = new ReconnectingWebSocket('ws://my.site.com', undefined, {maxRetries: 3});
nerror = (err) => {
if (err.code === 'EHOSTDOWN') {
    console.log('server down');
}

License

MIT