An AWS SQS package

Setting Up SQS

First configure your SQS queue on AWs. Cutie is a minimalist package, so configure your queue's default values to what you want in the AWS interface (cutie does not provide an interface for this).

Please note:

• Cutie only processes one message at a time, so your queue should be set up for one message at a time.
• Cutie does not have an interface for configuring credentials. You must set this up through AWS roles.
• Cutie expects your queue to be configured with a Default Visibility Timeout of 2 minutes.

Setting up cutie

var Cutie = require("cutie");
var options = {
	verbose: true, // defaults to false
};
var cutie = new Cutie("http://queue.url.whatever"); // URL from AWS

Adding tasks

Messages sent to cutie require a task property. This tells cutie which previously added task to perform. The task callback receives the message object and a done callback. Task callbacks must always call the done method within 2 minutes, which it expects to be the Default Visibility Timeout of your queue. See the Changing the Timeout section if you need to extend the timeout. It is very important that every code path in your task always completes by calling the done callback. The done callback takes an error parameter. If you pass an error parameter to the done callback, cutie will not remove the message from the SQS queue; it will remain in the queue to be reprocessed.

cutie.addTask("userRegistrationNotification", function(message, done) {
	// message is the object passed to send.
	var user = message.user;
	
	// Do stuff in some async method...
	asyncMethod(user, function(err) {
    	if (err)
        	return done(err); // message will NOT be removed from queue
        
        done(); // message will be removed from queue
	});
});

Start polling

cutie.start();

Sending messages to queue

// The send method will continue to retry up to 100 times if send fails when no callback is provided.
cutie.send({
	task: "userRegistrationNotification",
	user: user
});

// If you provide a callback and optional context, cutie will not retry to send.
cutie.send(message, function(error, data) { /* Do stuff */ }, this);

Sending message batch to queue

cutie.send([
	{
		task: "userRegistrationNotification",
		user: user1,
	},
	{
		task: "userRegistrationNotification",
		user: user2,
	}
	// ... etc.
]);

// When an array parameter is passed in, cutie acutally calls sendBatch(batch [, callback, context])

Changing the Timeout

Task callbacks will recieve a third object parameter that includes the changeTimeout method. Calling changeTimeout will extend the time that cuite and SQS allow for the task to complete. SQS will not make the message available again, until the new timeout interval has elapsed. This should be done at the very beginning of your callback. In the example, we'll give the task 10 minutes to complete which we pass in as seconds.

cutie.addTask("userRegistrationNotification", function(message, done, options) {
	var taskTimeoutSeconds = 10 * 60;
	options.changeTimeout(taskTimeoutSeconds);
	// Do other stuff...
});

Multiple queues

As of 3.0 cutie can be configured with multiple queues in order of priority. When ready to process a new message, cutie checks the queues in order of priority.

Configuring

To configure cutie to check multiple queues in order of priority, pass an array of queue URLs sorted by priority where the highest priority is at index zero.

var cutie = new Cutie(["http://queue.url.priority", "http://queue.url.normal"]); // URL from AWS

Sending

The send method takes an optional priority parameter, which should match the index into the array of priority sorted queues. Cutie will limit the range of the priority argument to valid array indices instead of giving an error, so if you pass in a priority 2 and the array only has one queue at index 0, it will use index 0. If you omit the priority argument index 0 will always be used.

var priorityQueueIndex = 0;
var normalQueueIndex = 1;

cutie.send(normalQueueIndex, message);

Task locking

// Assuming your callback parameter is named done, you may indicate that a task cannot be completed,
// but needs to be tried later and is not a real error to be logged like this:

if (taskIsLocked)
	return done({cutieMessage: "Task Locked"});