hare

Wrapper around amqp to make common patterns easier

Hare

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

npm install hare

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();
 

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);

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(messageheadersdeliveryInfodone){
    console.log(message);
    //call done to ack the message   
    done();
});

To read more about worker queues click here

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 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 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

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(msgdone){
    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(errres){
    console.log(res); //"hello Bob" 
});

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

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

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");

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

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

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