Lively WebSocket
A nodejs module used to keep a websocket connection alive through routine pings
and reconnects.
Usage
Use npm install --save livelyws to install the module as a dependency in your
application. Import the module in your code and create an instance of LivelyWS
connected to your websocket server. Add event handlers as needed.
Example:
import LivelyWS from 'livelyws';
let ws = new LivelyWS('ws://myserver.local', [], { timeout: 5000, handshakeTimeout: 5000 }, { debug: true });
ws
.on('debug', message => {
console.log(`DEBUG: ${message}`);
})
.on('open', () => {
console.log('WebSocket open.');
ws.send(JSON.stringify('{"action":"start"}'));
})
.on('close', cev => {
console.log('WebSocket closed.');
})
.on('error', error => {
console.log(`ERROR: ${error.toString()}`);
})
.on('message', message => {
console.log(message.toString());
});
ws.init();
Constructor (url [, protocols [, options [, settings ] ] ])
The LivelyWS constructor requires an url to the websocket server to establish a
connection and has optional arguments for the websocket protocols, connection
options, and settings for the keep alive features.
url
Connection URL to the websocket server.
protocols
Optional array of sub-protocol strings.
options
Optional object with option settings for websocket connection. See the
ws WebSocket documentation,
the NodeJS http request options,
and NodeJS https request options.
settings
Optional settings for the keep alive features. This is an object that may contain
one or more settings to adjust the operation of the keep alive features.
Example:
let keepAliveSettings = {
debug: true,
pingMessage: 'custom ping payload'
};
let ws = new LivelyWS('ws://myserver.local', null, null, keepAliveSettings);
}
settings.debug
Default: false
When enabled the LivelyWS instance will emit debug events to assist with diagnosing
websocket issues.
settings.reconnect
Default: true
When set to false the LivelyWS will not attempt reconnects if the websocket fails.
settings.reconnectInterval
Default: 1000
The number of milli-seconds to wait between websocket reconnect attempts.
settings.heartbeatInterval
Default: 5000
The milli-seconds between keep alive heartbeats (pings).
settings.heartbeatTimeout
Default: 5000
The number of milli-seconds to wait for a heartbeat response from the server
before closing the websocket due to heartbeat failure.
settings.pingMessage
Default: 'ClientWebSocket'
A message string that will be sent as a payload in the heartbeat ping.
settings.messagePing
Default: false
When set to true the heartbeat will send the settings.pingMessage as a normal
websocket message as an application level ping. This will require that the
websocket server application listens for the message and the client application
listens for the response message and calls the LivelyWS stopHeartbeatTimeout()
method to prevent heartbeat timeouts.
The default setting use the standard websocket ping and pong frames to keep the
websocket connection alive. This assumes that the websocket server supports the
websocket ping and pong frames. This will free the application from handling
the heartbeat pings and pongs.
Events
The LivelyWS instance will emit various event during operation.
debug
When the debug setting is enabled the LivelyWS instance will emit debug events
that include a test message payload to indicate various debug conditions during
operation.
error
The error event type is emitted when an error is encountered during operation.
The event will include an Error object.
open
When the websocket connection is completed and in the ready state the open event
type is emitted and the application can begin using the LivelyWS.
close
If the websocket closes for any reason the close event is emitted and will be
accompanied with a code number and reason string.
heartbeat
A heartbeat event type is emitted when a heartbeat ping is sent to the websocket
server.
ping
When a ping frame is received from the websocket server the ping event type is
emitted and will include the ping payload message. In most cases this is for
information only and will be handled automatically by the LivelyWS instance.
pong
When a pong frame is received from the websocket server the pong event type is
emitted and will include the pong payload message. This event is normally for
information only and will be handled by the LivelyWS instance.
message
The message event is emitted when a message is received from the websocket
server. These messages should be handled by the application.
NOTE: When the messagePing setting is enabled the heartbeat pong response
will be recieved as a message and must be handled by the application by calling
the LivelyWS stopHeartbeatTimeout() method.
Methods
Methods provided by the LivelyWS.
send (data)
Use the send method to send a message to the websocket server.
Example:
ws.send(JSON.stringify({ action: "restart" }));
stopHeartbeatTimeout ()
Stop the heartbeat timeout timer. Used when the messagePing setting is enabled
and the application must handle server pong responses as a message. If the
application does not call the stopHeartbeatTimeout() method before the heartbeat
timeout expires then the websocket will be closed due to a heartbeat failure.
close (code, reason [, stopReconnect ])
Use the close method to close the LivelyWS connection. A code number and reason
string should be provided. Optionally the stopReconnect flag can be set to true
to prevent a websocket reconnect after the close completes.