README

Snub-WS

Middleware WS server that allows you to run web-sockets over snub.

Usage

npm install snub

npm install snub-ws

Basic Example

With redis installed and running with default port and no auth.

const Snub = require('snub');
const snub = new Snub();
const SnubWS = require('snub-ws');

const snubws = new SnubWS(
  debug: true
);

snub.use(snubws);

Config options

{
  port: 8585, // Web-socket server port
  debug: true, // Bool, turns on verbose messaging.
  mutliLogin: true, // Bool, can the same username connection more than once?
  auth: 'auth-event', // String OR Function OR bool for no auth required
  authTimeout: 3000, // how long to wait for the client to auth before disconnecting
  throttle: [50, 5000], // X number of messages per Y milliseconds before disconnecting
  idleTimeout: 1000 * 60 * 60, // how long can an idle client be connected
}

Auth Config extra

auth can be passed of 3 things

Function

A function passed to auth

{
  auth: function (auth, accept) {
    if (auth.username == 'username')
      return accept(true); // run accept to authenticate the web-socket client connection.
    accept(false); // run with false to decline the web-socket connection and disconnect the client.
  }
}

Authenticating a client

The first thing a client should do after connecting is send an authenitication message. username is required, the entire object will be passed to your authentication method.

['_auth', { username, password}];

Sending messages from the client

Web socket message objects should be JSON stringified arrays. The first item is always the event name followed by payload, followed by the replyId. Only event name is required.

['event-name', { payload }, replyId];

String

A string passed to auth will run the method as a snub event. Reply true or false.

{
  auth: 'authenticate-client'
}

snub.on('ws:authenticate-client', function (auth, reply) {
  console.log(auth);
  if (auth.username == 'username')
    return reply(true);
  reply(false);
});

Boolean

A bool with false will authenticate any web-socket client connection.

{
  auth: false
}

Events

Client > Server

When a client sends data to the server the event will be prefixed with ws:

{
  from: { // client socket info
    id: '89668-mnm4i6', // unique uuid generated by snub-ws
    username: 'username', // defined in auth
    channels: [], // clients channel list
    connected: true, // connection status
    authenticated: true, // auth status
    connectTime: 1583803891546, // timestamp
    remoteAddress: '::1', // clients ip address
    meta: {} // client meta obj
  },
  payload: {}, // payload from client
  _ts: 1583803922264 // timestamp
}

Simple snub listener. inbound messages from client will be prefixed with ws:

snub.on('ws:do-math', function (event, reply) {
  console.log('domath');
  reply(event.payload * 10);
});

Server > Client

Send event to all clients

snub.poly('ws:send-all', ['event-name', {payload}]).send();

Send event to channel

snub.poly('ws:send-channel:' + 'channel6', ['event-name', {payload}]).send();

Send event to multiple channels

snub.poly('ws:send-channel:' + ['channel6', 'channel2', 'channel3'].join(','), ['event-name', {payload}]).send();

Send event to client

snub.poly('ws:send:' + 'username', ['event-name', {payload}]).send();
// or
snub.poly('ws:send:' + event.from.id, ['event-name', {payload}]).send();

Send event to multiple users

snub.poly('ws:send:' + ['user1', 'user2', 'user3'].join(','), ['event-name', {payload}]).send();

Channels

// TODO

snub-ws

Usage no npm install needed!