microservice-ws: a Node.js WebSocket library for microservices communications

microservice-ws is a simple to use, blazing fast, and thoroughly tested WebSocket client and server, with optional built in authentication.

Table of Contents

• microservice-ws: a Node.js WebSocket library for microservices communications
  • Table of Contents
  • Installing
  • Usage examples
    • Sending and receiving text data
    • Sending binary data
    • Simple server
    • External HTTP/S server
    • Client authentication
    • Server broadcast
    • Round-trip time
  • FAQ
    • How to detect and close broken connections?
  • License

Installing

npm install microservice-ws

Usage examples

Sending and receiving text data

import { Client } from 'microservice-ws';

Client({
  host: 'ws://www.host.com',
  port: 8080
}, {
  onConnection: (ws) => {
    ws.send('something')
  },
  onMessage: (data) => {
    console.log('received: %s', data);
  },
  onError: console.error
})

Sending binary data

import { Client } from 'microservice-ws';

Client({
  host: 'ws://www.host.com',
  port: 8080
}, {
  onConnection: (ws) => {
    const array = new Float32Array(5);

    for (var i = 0; i < array.length; ++i) {
      array[i] = i / 2;
    }

    ws.send(array);
  }
})

Simple server

import { Server } from 'microservice-ws';

Server({
  port: 8080
}, {
  onMessage: (data) => {
    console.log('received: %s', data);
  },
  onConnection: (ws) => {
    ws.send('something');
  },
  onError: console.error
})

External HTTP/S server

Coming Soon

Client authentication

import { AuthServer, AuthClient } from 'microservice-ws';

AuthServer({
  port: 8080,
  pingInterval: 60000,
  processAuthToken: (token) => Promise.resolve(token == "valid" ? "test_uid" : null)
}, {
  onAuthenticate: (uid) => {
    console.log('Authenticated: %s', uid);
  },
  onMessage: (data, isBinary, ws) => {
    console.log('Message From: %s', ws.userId);
  },
  onError: console.error
});

AuthClient({
  host: 'ws://www.host.com',
  port: 8080,
  pingInterval: 60000,
  lagBeforeClose: 60000,
  onAuthToken: () => Promise.resolve("your_auth_token")
}, {
  onAuthenticated: (ws) => {
    console.log('Client Authenticated');
  }
});

Server broadcast

A client WebSocket broadcasting to all connected WebSocket clients, including itself.

import { AuthServer } from 'microservice-ws';

AuthServer({
  port: 8080,
  pingInterval: 60000,
  processAuthToken: (token) => Promise.resolve(token == "valid" ? "test_uid" : null)
}, {
  onStart: (wss) => {
    wss.clients.forEach((client) => {
      if (client.readyState === WebSocket.OPEN) {
        client.send("Broadcasted message");
      }
    });
  },
  onError: console.error
});

A client WebSocket broadcasting to every other connected WebSocket clients, excluding itself.

import { AuthServer } from 'microservice-ws';

AuthServer({
  port: 8080,
  pingInterval: 60000,
  processAuthToken: (token) => Promise.resolve(token == "valid" ? "test_uid" : null)
}, {
  onMessage: (data, isBinary, ws, wss) => {
    wss.clients.forEach((client) => {
      if (client !== ws && client.readyState === WebSocket.OPEN) {
        client.send(data, { binary: isBinary });
      }
    });
  },
  onError: console.error
});

Round-trip time

import { AuthClient } from 'microservice-ws';

AuthClient({
  host: 'ws://www.host.com',
  port: 8080,
  pingInterval: 60000,
  lagBeforeClose: 60000,
  onAuthToken: () => Promise.resolve("your_auth_token")
}, {
  onConnection: (ws) => {
    console.log('connected');
    ws.send(Date.now());
  },
  onDisconnect: () => {
    console.log('disconnected');
  },
  onMessage: (data, ws) => {
    console.log(`Round-trip time: ${Date.now() - data} ms`);

    setTimeout(() => {
      ws.send(Date.now());
    }, 500);
  },
  onError: console.error
});

FAQ

How to detect and close broken connections?

Your clients might as well lose connection without knowing it. AuthClient and AuthServer handles this for you to detect and close broken connections.

However Client and Server does not have this functionality to stay bare bones, for efficiency.

License

MIT