ws-server-wrapper

Lightweight WebSocketServer wrapper lib using ws-wrapper to wrap connected WebSockets

Usage no npm install needed!

<script type="module">
  import wsServerWrapper from 'https://cdn.skypack.dev/ws-server-wrapper';
</script>

README

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:

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.