wicker

A WebSocket Server module for Node.js

Use

Install

To use this module, install via npm npm install wicker
or by manually including the file var wicker = require('./wicker.js');

Creating a Server

var wicker = require('wicker');

var server = wicker.createSocketServer({ port: 80 });

Specifying the Protocol

You can specify another protocol other than the default 'echo-protocol'

Specify it in the "protocol" option.

var server = wicker.createSocketServer({ port: 80, protocol: 'test-protocol' });

SSL

NOTE: You may pass in a file path to the certs or the 'utf-8' contents of the cert/key files.

var wicker = require('wicker');
var sslOptions = { key: keyFile, cert: certFile };
var server = wicker.createSocketServer({ port: 80, ssl: sslOptions });

Valid Topics

Valid topics must be an array.

var wicker = require('wicker');

var topics = ['posts', 'comments'];

var server = wicker.createSocketServer({ port: 80, validTopics: topics });

Commands

Use custom commands to perform actions.

Commands are executed similarly to express routing

Reserved routes are subscribe and unsubscribe

Routes are not case sensative

Arguments passed to the route callback are message and connection

Message contains all data recieved from the client.
Most data needed will be in message.data

Connection is the sending connection.

var wicker = require('wicker');

wicker.route('send', (message, connection) => {
  // do stuff
});

Sending To All Topics

wicker.sendToAll('hello');

Sending To a Specfic Topic

Topic is the topic name

ids is the topic ids that will be recieving the data and is optional, only use the parameter when you wish to target only a subsset of the topic.

var ids = message.data.id;
var topic = message.data.topic;

// message to send to subscribers
var message = 'hello';

wicker.sendToTopic(topic, message, ids);

Client Commands

All data needs to be sent as json or else it will not be parsed by the server.

Data Payload

All payloads must contain a "command" key to be executed.

All topic data such as topic name and associated IDs must be in the "data" key of the payload.

Any other data you wish to send can be placed in the payload however you like.

Subscribe To a Topic

{
     "command": "subscribe",
     "data":
         {
             "topic": "topicname"
         }
}

Unsubscribe To a Topic

{
     "command": "unsubscribe",
     "data":
         {
             "topic": "topicname"
         }
}

Subscrbing To Topics By ID

You can pass an array of item IDs that belong to a topic.

IDs can be used for subscribing, unsubscribing,or for routes.

{
     "command": "route",
     "data":
         {
             "topic": "topicname",
             "id": [12, 789]
         }
}

Routes

Replace "key" with the preferred key for your data.

Customize data payload as you like.

{
     "command": "route",
     "data":
         {
             "topic": "topicname",
             "<key>": "<data>"
         }
}