brokowski

Known issues

RESTful publish/subscribe toolkit including broker, publisher and subscriber.

Brokowski has a RESTful pub/sub broker, which runs as a HTTP server. It receives subscriptions and events via a RESTful API. The events will be forwarded to the connected subscriber services. Brokowski also includes publisher and subcriber modules, which offer simple APIs for RESTful event handling. They take care of setting up HTTP servers, connecting to the broker and sending/receiving events via the broker's RESTful API, making it easy to include pub/sub event handling into your apps. And since the broker runs on HTTP you can connect your own services via HTTP, too.

Installation and usage

Node.js ~0.10 is required

$ npm install -g brokowski
$ brokowski server 6000
$ brokowski cluster 6000

API

broker server:

// start a broker server at http://192.168.0.1:6000

var Brokowski = require('brokowski').BrokowskiServer
  , brokowski = new Brokowski({
      port: 6000    // default: 3000
    }).start();

// start a cluster of brokers at http://192.168.0.1:6000 (one server on each CPU core)

var Brokowski = require('brokowski').BrokowskiCluster
  , brokowski = new Brokowski({port: 6000}).start();

// start the broker with default subscribers

new Brokowski({
  port: 6000,
  subscribers: [{
    event: 'my-event',
    method: 'GET',
    hostname: '192.168.0.100',
    port: 6002,
    path: 'my-service'
  }]
}).start();

subscriber server:

// start a subscriber at http://localhost:6002/mysubscriber

var Sub = require('brokowski').Sub
  , sub = new Sub({
      port: 6002                        // optional, default: 3000
      name: 'mysubscriber',             // mandatory
      broker: 'http://192.168.0.1:6000' // mandatory
    }).start();

sub
  .get('my-event', function(data) { // resubscribing
    if(data.coolstuff) console.log('GET my-event');
  })
  .post('my-event', function(data) { // resubscribing
    if(data.coolstuff) console.log('POST my-event');
  })
  .put('my-event', function(data) { // resubscribing
    if(data.coolstuff) console.log('PUT my-event');
  })
  .delete('my-event', function(data) { // resubscribing
    if(data.coolstuff) console.log('DELETE my-event');
  })
  .subscribe({
    event: 'my-other-event',
    method: 'GET',             /* or 'POST' or 'PUT' or 'DELETE' */
    hostname: '192.168.0.100', /* default: 'localhost' */
    port: 6002,                /* default: port provided to sub(options) */
    path: 'my-service',        /* default: '/service-name/method/event' */
    handler: function(data) {
      console.log('GET my-other-event');
    }
  });
  .resubscribe({
    event: 'my-other-event',
    method: 'GET',
    handler: function(data) {
      console.log('GET my-other-event');
    }
  });
  .unsubscribe({
    event: 'my-other-event',
    method: 'GET',
    handler: function(data) {
      console.log('GET my-other-event');
    }
  });

publisher:

var Pub = require('brokowski').Pub
  , pub = new Pub({broker: 'http://192.168.0.1:6000'});

pub.send('my-event', {coolstuff: true});

RESTful API of the broker

Subscription parameters:

{
  method: 'GET', /* or 'POST' or 'PUT' or 'DELETE' */
  hostname: '192.168.0.100' ,
  port: 6000,
  path: 'subscriber-path'
}

subscribe

• method: POST
• url: http://localhost:6000/subscribe/myevent
• json: see the parameters
• returns 200 if everything is ok
• returns 400 if json is incomplete
• returns 500 if subscriber was subscribed to event

resubscribe

All subscribers matching the given json will be removed before the new subscription.

• method: POST
• url: http://localhost:6000/resubscribe/myevent
• json: see the parameters
• returns 200 if everything is ok
• returns 400 if json is incomplete

unsubscribe

All subscribers matching the given json will be removed.

• method: POST
• url: http://localhost:6000/unsubscribe/myevent
• json: see the parameters
• returns 200 if everything is ok
• returns 500 if subscriber wasn't already subscribed to event

publish

• method: POST
• url: http://localhost:6000/publish/myevent
• json: any
• returns 200 if everything is ok

clear

Removes all subscriptions.

• method: GET
• url: http://localhost:6000/clear
• should return 200

monitoring

• method: GET
• url: http://localhost:6000/monitoring/alive
• should return 200

Performance (0.1.2)

For the performance tests I used most of the test code from node-zmq.

My machine:

• Windows 7 64bit
• AMD Phenom(tm) II X4 955 @ 3.2 GHz
• 6 GB memory
• 100 Mbit LAN

Tests with single subscriber:

| | 10.000 messages | 100.000 messages | | --------------: |:-----------------------------------:| :-------------------:| | 2 Byte | 3951 [msg/s] | 4027 [msg/s] | | 64 Byte | 3841 [msg/s] | 3931 [msg/s] | | 3072 Byte | 3326 [msg/s] | 3043 [msg/s] |

Tests with two subscribers listening to the same event:

The results were almost the same for both the subscribers, so I just documented the worst.

| | 10.000 messages | 100.000 messages | | --------------: |:-----------------------------------:| :-------------------:| | 2 Byte | 2774 [msg/s] | 2858 [msg/s] | | 64 Byte | 2707 [msg/s] | 2759 [msg/s] | | 3072 Byte | 2304 [msg/s] | 2327 [msg/s] |

You can test the performance yourself:

$ brokowski server 6000

$ cd perf

# connect as many subscribers as you like
$ node startSubscriber.js 6000 my-event http://localhost:3000 4096 10000

# start publishing 10000 events with a msg size of 4096 byte
$ node startPublisher.js http://localhost:3000 my-event 4096 10000