ikue

AMQP-based work dispatching

ikue is a job dispatching library built on top of RabbitMQ and nodejs.

ikue allows you to easily dispatch works to differents parts of your infrastructure.

---

Features

• Simple api to create and submit jobs
• Retry failed jobs
• Support two backoff strategies for failed job
  • 'fixed': will retry the job at a fixed interval
  • 'exponential': will retry failed job doubling the wait time after each failure.
• Pluggable logger: By default ikue log to stdout but you can easily plug in your own logger.
• Selective job reception: If you only want to receive jobs with a specific name in your workQueue, you can selectively specify a whitelist.

Requirements

• RabbitMQ >= 3.5.0 (This is what we use in production, it might work well on older version of RabbitMQ, so if you are able to run it on a previous version let me know).
• nodejs > 0.10.0 any node version greater than 0.10.0 should work without any problem.

Getting started

Installation

To install the latest release:

$ npm install ikue

To install the Edge version of ikue from github

$ npm install ecstasy2/ikue

Initialize ikue

initializing ikue consist of creating a WorkQueueManager and creating at least a WorkQueue from it.

var WorkQueueMgr = require('ikue').WorkQueueMgr;

var queueMgr = new WorkQueueMgr({
  component: 'consumer', 
  amqp: {
    url: "amqp://guest:guest@localhost:5672/bench"
  },
  name: 'Benchmark'
});

// Create a workQueue, this is the object we will be 
// actually using to send/receive jobs
var workQueue = queueMgr.createQueue('Queue1');
queueMgr.on('ready', function(){
	workQueue.triggers = ['jobName'];

	// Start the work queue, will emit 'ready' when it succeed.
    workQueue.start();

    workQueue.on('ready', function(){
		// The work queue is ready and we can start using it
	});
  
});

// Connect the queue manager, this will emit the 'ready' event when it can be used.
queueMgr.connect();

• WorkQueueManager: The queueMgr is responsible for handling the connection with the AMQP server and for coordinating the job dispatching mechanism.

  ikue was built to fit in a distributed environment; with eventually many different apps using ikue for job/event dispatching. You can run any number of workers/apps completely in isolation on the same AMQP virtual host.

  • Options:

    • name: This should be a unique name across all your projects. Note that project here doesn't necessarily mean a unit of deployment. So if you have an "project" that consist of a producer component and a consumer component, those two app should use EXACTLY the same name.

    • amqp: This object will be passed as is to node-amqp when creating the connection to RabbitMQ.

      The url is the connection string containing all the credential to access the RabbitMQ server.

    • component: Use this field to compartmentalize different deployment units (namely apps) for the same project.

• WorkQueue: To create a WorkQueue you just need to provide a queueName. A work queue is actually the object you will be interacting with. Upon initialization you can configure a workQueue object to receive all jobs with specific names. This feature allows you to specify the list of job name it will be receiving. Right now you need to explicitly set this list. One of the upcoming feature is the ability to receive all jobs by default.

Create and submit a Job

// We create the job we want to send for processing.
// We need to provide the job a unique *name* and a hash of parameters.
var job = workQueue.createJob('say_hello', {name: "John Smith"})
  .maxRetry(30)
  .backoff('fixed')
  .delay(20000);

job.send();

• maxRetry(count): The maximum number of times this job will be retried in case of failure.
• backoff(strategy): Which backoff strategy to use for failed jobs.

Receive and handle a Job

    workQueue.on('ready', function(){
	  // The work queue is ready and we can start using it
	});
	
	// Will be called whenever there is a job named 'job_name' to be handled.
	// @param contains the hash object that was sent with the job
	// @param done is a callback function that should be called when the job is complete.
	//    passing it an error as the first parameter will mark this job as failed.  
	workQueue.on('job_name', function(params, done){
	  // 
	});