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 $webSocket('ws://....');
Minified library with gzip compression is less than 600 bytes.
You can install this package locally with bower
.
Please note that Angular WebSocket requires Angular 1.3.x or higher.
# To get the latest stable version, use bower from the command line.
bower install angular-rws
# To get the most recent, last committed-to-master version use:
bower install 'angular-rws#master'
# To save the bower settings for future use:
bower install angular-rws --save
# Later, you can use easily update with:
bower update
Now that you have installed the Angular libraries, simply include the scripts and stylesheet in your main HTML file, in the order shown in the example below. Note that npm will install the files under /bower_components/angular-rws/
.
<!DOCTYPE html>
<html>
<head>
</head>
<body ng-app="YourApp">
<div ng-controller="YourController">
</div>
<script src="/bower_components/angular/angular.js"></script>
<script src="/bower_components/angular-rws/angular-rws.js"></script>
<script>
// Include app dependency on ngWebSocket
angular.module( 'YourApp', [ 'ngWebSocket' ] )
.controller("YourController", YourController );
</script>
</body>
</html>
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 $webSocket
, 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
// Attempts to reconnect
onopen
onmessage
onmessage
onmessage
onclose
// Attempts to reconnect
onopen
onmessage
onmessage
onmessage
onclose
This is all handled automatically for you by the library.
var socket = new $webSocket(url, protocols, options);
- The URL you are connecting to.
- https://html.spec.whatwg.org/multipage/comms.html#network
- Optional string or array of protocols per the WebSocket spec.
- https://tools.ietf.org/html/rfc6455
- Options (see below)
Options can either be passed as the 3rd parameter upon instantiation or set directly on the object after instantiation:
var socket = new $webSocket(url, null, {debug: true, reconnectInterval: 3000});
or
var socket = new $webSocket(url);
socket.debug = true;
socket.timeout_interval = 5400;
- Whether this instance should log debug messages or not. Debug messages are printed to
console.debug()
. - Accepts
true
orfalse
- Default value:
false
- 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
true
orfalse
- Default value:
true
- The number of milliseconds to delay before attempting to reconnect.
- Accepts
integer
- Default:
1000
- The maximum number of milliseconds to delay a reconnection attempt.
- Accepts
integer
- Default:
30000
- The rate of increase of the reconnect delay. Allows reconnect attempts to back off when problems persist.
- Accepts
integer
orfloat
- Default:
1.5
- The maximum time in milliseconds to wait for a connection to succeed before closing and retrying.
- Accepts
integer
- Default:
2000
- 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
integer
ornull
. - Default:
null
- The binary type is required by some applications.
- Accepts strings
'blob'
or'arraybuffer'
. - Default:
'blob'
- Open the Reconnecting Websocket
- Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.
code
is optional the closing code (default value 1000). https://tools.ietf.org/html/rfc6455#section-7.4.1reason
is the optional reason that the socket is being closed. https://tools.ietf.org/html/rfc6455#section-7.1.6
- Refresh the connection if still open (close and then re-open it).
- Transmits data to the server over the WebSocket connection.
- Accepts @param data a text string, ArrayBuffer or Blob
Like this? Check out angular-rws for the simplest way to create WebSocket backends from any programming language.