neboola v0.9.2

neboola

a bunch of new gadgets to build distributed websocket server in node.js

neboola is a library to build distributed websocket-based (ws) client/server applications in node.js for realtime web applications, games, etc. It's designed to run multiple applications on a single server instance (cluster).

installation

$ npm install neboola

design

Network application development is about protocol mostly. If you can keep your protocol clean and under control, you can build applications more easily even if they look complex from outside. neboola provides a clean interface to create your own events to build protocol for your websocket-based network application. That interface is called Application. When you create an application with a unique name, you have one important method called register. This method is for creating your own events (commands).

Because of multiple application design, clients must provide unique application name for routing. That information stays on socket's private storage by app parameter. Before applying your protocol, neboola needs a method to accept connections. There is a method called accept in Server class to manage new sockets. When a new connection shows up first time, neboola fires an accept event with no data. If client sends any message before selecting application, neboola fires another accept event with data provided by client. To create a clean protocol, you might use that to make clients to be able to pick application by data parameter. If you check example, you can see server selects default application in accept method. Otherwise there would be second fire of accept event on next message.

After client selects application, it's up to your protocol which you created by calling register method in Application by unique event names and handler methods.

how it works

neboola use node.js' cluster module when it's convenient such as server part. That means there will be forks as much as number of cpu cores unless you specify something else. In that case, while one of your clients connected on Fork A, the other might be on Fork B. If you want to trigger a broadcast to all those clients, you should inform both forked instances.

That schema represents single server with multiple cores. If you have also multiple servers, I would recommend you to implement a pub/sub method via Redis for now.

usage

Server

var $server = require('neboola').$server;
var Application = require('neboola').Application;

$server.setup({port: 8688});
$server.forever();

var $app = new Application();
$app.setup({name: 'neboola'});

$server.accept(function (socket, data) {
    if (!socket.hasData('app')) {
        console.log(socket.getRemoteIP(), '\t\t->\t\t', socket.getIdentifier());
        socket.setData('app', 'neboola');
    }
});

$app.register('client.close', function (socket, code, message) {
    console.log('client disconnected', code, message);
});

$app.register('echo', function (socket, data) {
    process.send('broadcast this message to all instances');
    socket.send({c: 'echo', d: data});
});

process.on('message', function (message) {
    console.log(message);
});

$server.addApplication($app);
$server.run();

Client

var Client = require('neboola').Client;
var $client = new Client({
    server: '127.0.0.1:8688'
});

$client.on('open', function () {
    $client.send({c: 'echo', d: 'TEST'});
});

$client.on('close', function () {
    console.log('disconnected');
});

$client.on('error', function (e) {
    console.log(e);
});

$client.on('echo', function (data) {
    console.log('server says %s', data);
});

$client.connect();