ws-server-wrapper

Lightweight WebSocketServer wrapper lib using ws-wrapper
and ws to wrap connected WebSockets. The
only dependency is ws-wrapper itself.

Install

``
npm install ws-server-wrapper
`

Usage

See ws-wrapper README or the API
documentation below for more details.

Quick Server-side Example:

Use ws-server-wrapper to wrap
the WebSocket.Server:

`javascript
const WebSocketServer = require("ws").Server
, WebSocketServerWrapper = require("ws-server-wrapper");
var wss = new WebSocketServer({port: 3000});
var serverWrapper = new WebSocketServerWrapper(wss);
// Send "msg" event to all connected clients
serverWrapper.emit("msg", "Hello!");
// For all connected clients, listen for the "ping" request on the channel "pointless"
serverWrapper.of("pointless").on("ping", function() {
// this refers to the "pointless" channel for the socket who sent the "ping" request
// Let's just respond to the request with the value "pong"
return "pong";
});
`

API

Class: WebSocketServerWrapper

A WebSocketServerWrapper simply wraps around a
WebSocket.Server
to give you well-deserved functionality. :)

server = new WebSocketServerWrapper(webSocketServerInstance[, options]);

Constructs a new WebSocketServerWrapper, and binds it to the native
WebSocketServer instance from ws.

- webSocketServerInstance - the native WebSocketServer instance
- options - options passed to each WebSocketWrapper constructor when a
WebSocket connects. See the ws-wrapper API
for details.
- requestTimeout - See the ws-wrapper API
API for more info. Defaults to 2 minutes if not specified.
- heartbeatInterval - If set, a "ping" will be sent to all connected
sockets every heartbeatInterval milliseconds. If a "pong" response
is not received by the start of the next ping, the connection will be
terminated. Defaults to 1 minute if not specified. Set to a falsy value
to disable heartbeats.

Events

- Event: "connection" - Emitted when a WebSocket connects to the WebSocketServer
- socket - A WebSocketWrapper instance, wrapping a native WebSocket
- request - A http.IncomingMessage
instance.
- Event: "disconnect" - Emitted when a WebSocket disconnects from the WebSocketServer
- socket - A WebSocketWrapper instance, wrapping a native WebSocket
- Event: "error" - Emitted when an error occurs on the WebSocketServer
- err

The EventEmitter-like API looks like this:

See the ws-wrapper API documentation
for more details.

- server.on(eventName, listener)
Adds the listener function to the end of the listeners array for the
event named eventName for all connected sockets, now and in the future.
When an event or request matching the eventName is received by any
connected WebSocket, the listener is called.

Values returned by the listener callback are used to respond to
requests. If the return value of the listener is a Promise, the
response to the request will be sent once the Promise is resolved or
rejected; otherwise, the return value of the listener is sent back to
the remote end immediately.

If the inbound message is a simple event (not a request), the return
value of the listener is ignored.
- server.removeListener(eventName, listener)
Removes the specified listener from the listener array for the event
named eventName.
- server.removeAllListeners([eventName])
Removes all listeners, or those of the specified eventName.
- server.eventNames()
Returns an array listing the events for which the emitter has registered
listeners.
- server.listeners(eventName)
Returns a copy of the array of listeners for the event named eventName.
- server.emit(eventName[, ...args])
Sends an event to all connected WebSockets with the specified eventName
calling all listeners for eventName on the remote end, in the order they were
registered, passing the supplied arguments to each.

Note: server.once() and server.request() are not supported at this time.

Channel API:
- server.of(channelName)
Returns the channel with the specified channelName. Every channel has the
same EventEmitter-like API as described above for sending and handling
channel-specific events for all connected sockets.

Other methods and properties:

- server.sockets - A Set
of connected WebSocketWrappers.
- server.close()
Closes the native WebSocketServer

Detecting Broken Connections

The WebSocketServerWrapper will automatically (by default) ping all open sockets
on a regular basis. If there is no "pong" response by the start of the next ping,
the connection will be assumed to be "broken" and will be terminated automatically.
See options.heartbeatInterval` for more information. Also see the approached
outlined here.