robust-websocket

A robust, reconnecting WebSocket client for the browser

robust-websocket is a wrapper around the standard WebSocket class that implements the same interface, but can reconnect when disconnected or the user's computer comes back online.

It is error-code aware and will not reconnect on 1008 (HTTP 400 equivalent) and 1011 (HTTP 500 equivalent) by default. This behavior is fully configurable via the shouldConnect (see Usage).

Compared to reconnecting-websocket

• Tests! You know it works like stated and regressions will be caught.
• Is aware of online and offline, and won't burn up the users battery and CPU reconnected when offline, and will reconnect when it is online again.
• Natively aware of error codes
• Any kind of reconnect strategy is possible via functional composition

Usage

Use it as you would a normal websocket:

var ws = new RobustWebSocket('ws://echo.websocket.org/')
ws.addEventListener('message', function(event) {
  console.log('we got: ' + event.data)
})

ws.send('Hello!')

But with an optional set of options you can specify as a 3rd parameter

timeout

The number of milliseconds to wait before a connection is considered to have timed out. Defaults to 4 seconds.

shouldReconnect

A function that given a CloseEvent or online event and the RobustWebSocket will return the number of milliseconds to wait to reconnect, or a non-Number to not reconnect.

Examples:

Reconnect with an exponetial backoff on all errors

function shouldReconnect(event, ws) {
  return Math.pow(1.5, ws.attempts) * 500
}

Reconnect immediately but only 20 times per RobustWebSocket instance

function shouldReconnect(event, ws) {
  return ws.reconnects <= 20 && 0
}

Reconnect only on some whitelisted codes, and only 3 attempts, except on online events, then connect immediately

function shouldReconnect(event, ws) {
  if (event.type === 'online') return 0
  return [1006,1011,1012].indexOf(event.code) && [1000,5000,10000][ws.attempt]
}

automaticOpen

A boolean indicating whether or not to open the connection automatically. Defaults to true, matching native WebSocket behavior.

You can open the websocket by calling open() when you are ready. You can close and re-open the RobustWebSocket as much as you wish.

Polyfills needed

You may need these polyfills to support older browsers

• Object.assign - npm package or 24-line MDN snippet
• CustomEvent - npm package or 15-line MDN snippet