Hare

Hare is a wrapper around amqp providing a cleaner chainable API for some of the common patterns.

Installation

npm install hare

Connecting

To connect to your amqp server you can pass in your options to hare

var myHare = hare({url : "amqp://guest:guest@localhost:5672"});

Or you can specify through the connectionOptions method

hare.connectionOptions({url : "amqp://guest:guest@localhost:5672"});

var myHare = hare();

Heartbeat

You may also specify a heartbeat (See here)

hare({url : "amqp://guest:guest@localhost:5672", heartbeat: 2});

//or

hare({url : "amqp://guest:guest@localhost:5672"}).heartbeat(2);

WorkerQueues

Worker queues allow you to ditribute messages to workers, where only one worker will recieve the message. Allowing for the distribution of resource intensive tasks across a worker pool.

To publish to a worker queue.

var queue = myHare.workerQueue("my.queue");

queue.publish({hello : "world"});

To create a worker subscribe to the worker queue.

myHare.workerQueue("my.queue").subscribe(function(message, headers, deliveryInfo, done){
	console.log(message);
	//call done to ack the message	
	done();
});

To read more about worker queues click here

Publish/Subscribe

Publish and Subscribe allows you to broadcast messages to multiple consumers at a time.

To create a pub sub system you can use the pubSub method.

var queue = myHare.pubSub("my-exchange");

setInterval(function () {
   queue.publish({hello: i++});
}, 500);

To subscribe to the topic

myHare.pubSub("my-exchange").subscribe(function (event) {
   console.log("%d, got message %j", process.pid, event);
});

To read more about publishing and subscribing click here

Routing

Routing is similar to pubSub except that subscribers can listen to a subset of messages.

To create a routing system you can use the route method.

var queue = myHare.route("direct_logs");

var LEVELS = ["debug", "info", "warn", "error", "fatal"];

setInterval(function () {
	var level = LEVELS[i++ % LEVELS.length];
	queue.publish(level, {hello:level});
}, 500);

To subscribe to the topics…

hare().route("direct_logs", "debug").subscribe(function (event) {
   console.log("%d, got message %j for level %s", process.pid, event, level);
});

To read more about routing click here

Topics

Topics is similar to routing except that it allows you to subscribe to messages on multiple criteria.

To create a topic queue use the topic method.

var queue = myHre.topic("topic_logs")
var LEVELS = ["log.debug", "log.info", "log.warn", "log.error", "log.fatal"];

setInterval(function () {
   var level = LEVELS[i++ % LEVELS.length];
   queue.publish(level, {hello:level});
}, 500);

To bind to topic yous can use the wildcards:

• * (star) can substitute for exactly one word.
• # (hash) can substitute for zero or more words.

myHare.topic("topic_logs", "log.*").subscribe(function(message){

})

Or bind directly.

myHare.topic("topic_logs", "log.info").subscribe(function(message){

})

To read more about topics click here

Rpc

Using the rpc() provides a basic rpc mechanism that can be used for request response style messaging.

To create an rpc queue use the rpc method.

var rpcQueue = hare().rpc("my_queue");

In the server you can provide a handle function which responds to messages.

rpcQueue.handle(function(msg){
    return "hello " + msg.name;
});

If your handler is async you can either return a promise.

rpcQueue.handle(function(msg){
    return new Promise().callback("hello " + msg.name).promise();
});

or invoke the done callback

rpcQueue.handle(function(msg, done){
    return done(null, "hello " + msg.name);
});

In the client you just invoke the call method which sends a message.

The call method returns a promise.

rpcQueue.call({name: "Bob"}).chain(function(res){
    console.log(res); //"hello Bob"
});

Or you can provide a callback

rpcQueue.call({name: "Bob"}, function(err, res){
    console.log(res); //"hello Bob"
});

Creating your own Queue

You may also use the queue method to create your own queue if the above patterns do not match your needs.

For example to create a worker queue manually that is durable, and will not auto delete

var queue = myHare.queue("name").ack(true).durable(true).autoDelete(false);

queue.publish({hello : "world"});

To customize the queue even further you may specify the following options using the chainable api.

• passive()
• durable()
• exclusive()
• autoDelete()
• noDeclare()
• args()
• closeChannelOnUnsubscribe()
• exchange()
• routingKey()
• ack()
• prefetchCount()

To read more about the queue options click here

Creating Exchanges

You may also use the exchange method to work with your own exchange.

For example to create a pubsub queue manually you could to the following.

var queue = myHare.exchange("name").type("fanout").queue().exclusive(true);

queue.publish({hello : "world"});

To customize the exchange even further you may specify the following options using the chainable api.

• passive()
• type()
• durable()
• confirm()
• comfirm()
• autoDelete()
• noDeclare()

To read more about the queue options click here

Logging

Hare comes with a logger which is useful for debugging. By default logging is turned off.

To turn on logging.

hare.log();

To turn off logging.

hare.noLog();

Or to set the level

//only log error messages
hare.logLevel("error");

Configuring Defaults

You can configure defaults for all queues using the queueOptions options.

hare.queueOptions({durable : true, passive : false, autoDelete : false});

License

MIT https://github.com/c2fo/hare/raw/master/LICENSE

Meta

• Code: git clone git://github.com/c2fo/hare.git
• Website: http://c2fo.com - Twitter: http://twitter.com/c2fo - 877.465.4045