ClusterWS/uWS Implementation

Modified version of uWebSockets

This module is modified version of the uWebSockets with some minor tweaks in C++ code and complete rewrite of JS code to TS. Original software is available in uWebSockets repository.

This repository is based on the uWebSockets therefore has two licence ClusterWS MIT and Alex Hultman ZLIB.

Big thanks to SirAnthony for ssl workaround (has been taken from SirAnthony's uWebSockets fork).

Please consider to support ClusterWS development:

• Become a Backer on Patreon
• One time Donation via PayPal

Installation

npm i @clusterws/uws

Server example

uWebSockets node was designed to mimic node js ws module there are some things which are not available in uWebSockets.

// use WebSocketServer to create server
const { WebSocketServer } = require('@clusterws/uws');

// Create websocket server 
const server = new WebSocketServer({ port: 3000 }, () => {
    console.log('Server is running on port: ', 3000)
});

// Accept ws connections
server.on('connection', (socket, upgReq) => {
    // gives you remoteAddress info
    let address = socket._socket 
    // emitted when receive new message
    socket.on('message', (message) => { });

    // emitted when connection closes 
    socket.on('close', (code, reason) => { });

    // emitted on error
    socket.on('error', (err) => { });

    // emitted when pong comes back from the client connection
    socket.on('pong', () => { 
      // make sure to add below line (important to do not drop connections)
      socket.isAlive = true;
    });

    // emitted when get ping from the server (if you send)
    socket.on('ping', () => {})

    // this function accepts string or binary (node buffer)
    socket.send(message)

    // destroy connection
    socket.terminate()

    // close connection
    socket.close(code, reason)

    // to manually send ping to the client
    socket.ping()
});

server.on('error', (err, socket) => {
  // in some cases there is not socket param
  // handle http errors, TLS errors, ... 
})

// Start auto ping (second parameter is type of ping `false` is low level)
// use `false` most of the time except if you want to track ping pong on the client side 
// which does not have onping & onpong methods (like browser websocket)
// check Handle AutoLevelPing In Browser Example part below
// event if you use app level ping server onPong will be called
server.startAutoPing(20000, false)

// broadcast to all connected clients
// message: string | binary (node buffer)
// options?: { binary: true | false }
server.broadcast(message, options)

// destroy or close server
server.close(callback)

Client example

// Client part is pretty much the same as in server
// use WebSocket to create client
const { WebSocket } = require('@clusterws/uws');

const socket = new WebSocket('ws://url:port');

// emitted when websocket is connected
socket.on('open', () => {})

// emitted when receive new message
socket.on('message', (message) => { });

// emitted when error happens
socket.on('error', (err) => {})

// emitted on close websocket
socket.on('close', (code, reason) => {})

// emitted when get ping from the server (if you send)
socket.on('ping', () => {})

// emitted when get pong from the server (if you send)
socket.on('pong', () => {})

socket.ping() // manually send ping to the server

socket.send(msg) // send message to the server binary | string

socket.terminate() // destroy connection

socket.close(code, reason) // close connection

Handle AppLevelPing In Browser Example

This is just an example of handling app level ping pong from the client side which does not have onping and onpong methods available

Note if your clients have onping and onpong methods (or similar) do not send appLevel ping from the server as it requires more work.

socket.binaryType = 'arraybuffer' // Do not forget to set to `arraybuffer`
socket.onmessage = function (message) {
    if (typeof message.data !== 'string') {
        let buffer = new Uint8Array(message.data);
        if (buffer[0] === 57) {
            // output should be an array with one bit and [0] is === 65
            return socket.send(new Uint8Array(['A'.charCodeAt()]));
        }

        // process with your binary data
    }
    // process with your string data
}