ssignal v0.1.8

*Important: This package is not maintained anymore.

ssignal

A simple way to keep communicating between Node.js server and browsers.

Roles:

• Node.js server: Publisher, holding the connections and deliverying the messages
• Browsers: Subscribers, sending the signals to Node.js server

Firstly, please install ssignal package in Node.js:

npm install ssignal --save

Then, you need to call its "init" method as below:

var Publisher = require('ssignal').Publisher;

// without Express
var http = require('http');
var server = http.createServer(/* request handler */);

// or with Express
var app = express();
var server = http.createServer(app);

// init
Publisher.init(server [, option]);

ssignal was built on top of Primus. The second parameter will be passed to Primus object behind the scene. Here is documentation:

https://github.com/primus/primus#getting-started

As default, ssignal automatically generates 2 files .js into the "/ssignal" directory:

/ssignal/publisher.min.js
/ssignal/subscriber.min.js

You can choose another place within your project folder, by specifying "pathname" option as below:

var Publisher = require('ssignal').Publisher;

var http = require('http');
var server = http.createServer(/* request handler */);

// init with second parameter
Publisher.init(server, {pathname: 'public/js/somewhere'});

You need to be able to access them from outside. Assume that you can insert them into client side with the script tags like this:

<script type="text/javascript" src="/public/js/lib/ssignal/publisher.min.js"></script>
<script type="text/javascript" src="/public/js/lib/ssignal/subscriber.min.js"></script>
<script type="text/javascript">
    Subscriber.init('//domain.com');
</script>

Of course, you can use AMD or UMD:

// SystemJS
    System.import('/public/js/lib/ssignal/publisher.min').then(function(){
       System.import('/public/js/lib/ssignal/subscriber.min').then(function(subscriber){
            subscriber.init('//domain.com');
        });
    });

// RequireJS
    require(['/public/js/lib/ssignal/publisher.min'], function(){
        require(['/public/js/lib/ssignal/subscriber.min'], function(subscriber){
            subscriber.init('//domain.com');
        });
    });

Subscriber.init requires a parameter with it you specify the URL to Publisher's server. It may be an IP address and port. That makes a communication channel between Publisher and Subscriber.

If everything is OK, you have got a connection between client and server.

The next step depends on your app and the way you handle your users' session.

Usage

Publisher's methods

• Publisher.init(Object server , Object option);
• Publisher.on(String event, Function callback)
• Publisher.off(String event)
• Publisher.delivery(String | Array identifier, Object data)
• Publisher.getOnlineUsers()
• Publisher.getOnlineClients()

Examples:

var express = require('express');
var app = express();
var server = http.createServer(app);


var Publisher = require('ssignal').Publisher;
Publisher.init(server, {pathname: '/public/js/lib/ssignal'});


var Bella = require('bellajs');

// every 1 minute, check...
Bella.scheduler.every('1m', function(){

    // how many users are online
    var onlineUsers = Publisher.getOnlineUsers();
    console.log('Users: %s', onlineUsers.length);

    // and how many clients are connecting to app (including logged users)
    var onlineClients = Publisher.getOnlineClients();
    console.log('Clients: %s', onlineClients.length);

});

Is that simple?

Subscriber's methods

• Subscriber.init(String host);
• Subscriber.identify(String userId);
• Subscriber.on(String event, Function callback)
• Subscriber.off(String event)
• Subscriber.signal(Object data)

In order to have the correct result while checking on the server as above script, we need some helps from Subscriber at client side, for example:

require.config({
    baseUrl: '/public/js/lib/ssignal/',
    paths: {
        primus: 'primus.min',
        subscriber: 'subscriber.min'
    }
});
requirejs(['subscriber', 'primus'], function(subscriber){
    // if we have a logged user, talk to ssignal:
    var userid = User.isLogged()?User.id:'';
    if(userid){
        subscriber.identify(userid);
    }
    // get domain
    var url =  new URL(document.URL);
    var domain = url.hostname;

    // start connect to server
    subscriber.init('//'+domain);
});