hare

v1.1.0

Published

a year ago

Wrapper around amqp to make common patterns easier

Downloads

411

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