JarCastingReconnectingWebSocket
A small JavaScript library that decorates the WebSocket API to provide a WebSocket connection that will automatically reconnect if the connection is dropped.
It is API compatible, so when you have:
var ws = new WebSocket('ws://....');
you can replace with:
var ws = new ReconnectingWebSocket('ws://....');
Minified library with gzip compression is less than 600 bytes.
How reconnections occur
With the standard WebSocket API, the events you receive from the WebSocket instance are typically:
onopen
onmessage
onmessage
onmessage
onclose // At this point the WebSocket instance is dead.
With a ReconnectingWebSocket, after an onclose event is called it will automatically attempt to reconnect. In addition, a connection is attempted repeatedly (with a small pause) until it succeeds. So the events you receive may look something more like:
onopen
onmessage
onmessage
onmessage
onclose
// ReconnectingWebSocket attempts to reconnect
onopen
onmessage
onmessage
onmessage
onclose
// ReconnectingWebSocket attempts to reconnect
onopen
onmessage
onmessage
onmessage
onclose
This is all handled automatically for you by the library.
Parameters
var socket = new ReconnectingWebSocket(url, protocols, options);
url
- The URL you are connecting to.
- https://html.spec.whatwg.org/multipage/comms.html#network
protocols
- Optional string or array of protocols per the WebSocket spec.
- https://tools.ietf.org/html/rfc6455
options
- Options (see below)
Options
Options can either be passed as the 3rd parameter upon instantiation or set directly on the object after instantiation:
var socket = new ReconnectingWebSocket(url, null, {debug: true, reconnectInterval: 3000});
or
var socket = new ReconnectingWebSocket(url);
socket.debug = true;
socket.timeoutInterval = 5400;
debug
- Whether this instance should log debug messages or not. Debug messages are printed to
console.debug(). - Accepts
trueorfalse - Default value:
false
automaticOpen
- Whether or not the websocket should attempt to connect immediately upon instantiation. The socket can be manually opened or closed at any time using ws.open() and ws.close().
- Accepts
trueorfalse - Default value:
true
reconnectInterval
- The number of milliseconds to delay before attempting to reconnect.
- Accepts
integer - Default:
1000
maxReconnectInterval
- The maximum number of milliseconds to delay a reconnection attempt.
- Accepts
integer - Default:
30000
####reconnectDecay
- The rate of increase of the reconnect delay. Allows reconnect attempts to back off when problems persist.
- Accepts
integerorfloat - Default:
1.5
timeoutInterval
- The maximum time in milliseconds to wait for a connection to succeed before closing and retrying.
- Accepts
integer - Default:
2000
maxReconnectAttempts
- The maximum number of reconnection attempts that will be made before giving up. If null, reconnection attempts will be continue to be made forever.
- Accepts
integerornull. - Default:
null
binaryType
- The binary type is required by some applications.
- Accepts strings
'blob'or'arraybuffer'. - Default:
'blob'
Methods
ws.open()
- Open the Reconnecting Websocket
ws.close(code, reason)
- Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.
codeis optional the closing code (default value 1000). https://tools.ietf.org/html/rfc6455#section-7.4.1reasonis the optional reason that the socket is being closed. https://tools.ietf.org/html/rfc6455#section-7.1.6
ws.refresh()
- Refresh the connection if still open (close and then re-open it).
ws.send(data)
- Transmits data to the server over the WebSocket connection.
- Accepts @param data a text string, ArrayBuffer or Blob
Like this? Check out websocketd for the simplest way to create WebSocket backends from any programming language.
