Persistent Websocket

An automatically-reconnecting websocket wrapper that respects server reachability and good backoff practices

Features

• Optionally ping the backend (using a custom function) to make sure you're not on a zombie connection
• Optionally check for basic internet connectivity before trying to reconnect (via a configured url endpoint)
• "Decorrelated jitter" backoff
• umd / universal library
• Configurable timeouts, ping intervals, and backoff delay limits

Usage

import {PersistentWebsocket} from "persistent-websocket";

const pws = new PersistentWebsocket("ws://mysite.com/", {
  pingSendFunction: (pws) => pws.send("ping"),
  reachabilityTestUrl: "/favicon.ico"  
});
pws.onmessage = (e) => console.log(e);
pws.onopen = (e) => console.log(e);
pws.onclose = (e) => console.log(e);
pws.onerror = (e) => console.log(e);

pws.open(); // Must be explicitly opened, unlike regular WebSocket

// Now you can use the PersistentWebsocket instance like a plain WebSocket instance, 
// except this instance will automatically try to reconnect if the connection dies 

Options

The full list of available options is:

• debug boolean (default false):
  Controls logging of verbose/debug output
• initialBackoffDelayMillis numeric (default 500):
  Delay before first reconnection attempt (also acts as a minimum delay)
• maxBackoffDelayMillis numeric (default 120000):
  Maximum delay between reconnection attempts
• pingSendFunction function (no default):
  An optional function that takes the PersistentWebsocket instance as its only parameter.
  When left undefined, pings will not be performed.
• pingIntervalSeconds numeric (default 30):
  If the remote end of the websocket connection hasn't sent anything after this number of seconds, a ping will be sent (via pingSendFunction) to probe the connection.
  Note that pings aren't sent at regular intervals. They're only sent when the line is otherwise quiet.
• pingTimeoutMillis numeric (default 2000):
  How long to wait for a ping response before calling the connection dead
• connectTimeoutMillis numeric (default 3000):
  How long to wait for the websocket connection to reach a WebSocket.OPEN ready state
• reachabilityTestUrl string (no default):
  An optional url to use to test for internet connectivity (may be absolute or relative)
  A HEAD request will be sent to this url before trying to reconnect, and if it fails, the library will reset the backoff timing to its initial value and poll that url until it successfully responds.
  If left undefined, no reachability/internet connectivity check will be performed.
• reachabilityTestTimeoutMillis numeric (default 2000):
  How long to wait for a response from the reachabilityTestUrl
• reachabilityPollingIntervalMillis numeric (default 3000):
  How long to between a failed reachability test and the next request to the reachabilityTestUrl

Events

In addition to the standard websocket events, the library also provides a "beforereconnect" event. This event is fired when a reconnection is scheduled (as opposed to attempted), and has the following properties:

• attemptNumber numeric
  The number of this attempt relative to the last disconnect
• waitMillis numeric
  The timeout until the next connection attempt will be made (in milliseconds)

It also adds a couple fields to existing websocket events:

• wasExpected boolean
  Added to the close event
• wasReconnect boolean
  Added to the open event

License

MIT