Jungle
http://jungle.rubyforge.org/
by Tom Preston-Werner

== DESCRIPTION:

Jungle is a client library for the Amazon SQS (Simple Queue Service). It provides an intuitive, well documented API and a fully tested codebase.

== INSTALLATION:

Jungle can be installed via RubyGems:

$ sudo gem install jungle

== USAGE:

In order to use Jungle to interface with Amazon web services, you must first sign up for a web services account at http://amazonaws.com. Once you have an account, you'll need to locate your access key (20 bytes long) and secret access key (40 bytes long). It is important to keep your secret access key secure (take necessary precautions when deploying code that contains your AWS credentials). With your credentials handy, you can create a Jungle client.

require 'rubygems'
require 'jungle'

client = Jungle::Client.new('1234567890ABCDEFGHIJ', '1234567890abcdefghijklmnopqrstuvwxyz1234')

From the client, you can get access to an SQS client, on which you can execute SQS commands.

The first thing you'll need to do is create a queue:

client.sqs.create_queue('foo')

Once you've created the queue, you can send messages to it:

client.sqs.send_message('foo', "Help, I'm trapped in a REPL!")

Messages are always placed on the back of the queue. To retrieve a message from the front of the queue:

message = client.sqs.receive_message('foo')

The call to Jungle::SQSClient#receive_message will return a single Jungle::SQSMessage by default. From this you can get the message's id and body.

message.id #=> "1AM3Q5BE7ZZRNQD8MEY6|3H4AA8J7EJKM0DQZR7E1|9CBMKVD6TTQX44QJ1S30"
message.body #=> "Help, I'm trapped in a REPL!"

When you make a call to Jungle::SQSClient#receive_message, the message(s) that are returned will be invisible to other receive_message calls for 30 seconds. This prevents two clients from receiving the same message, but still allows the message to be handled after the timeout. You can specify a different visibility timeout when you create the queue:

client.sqs.create_queue('bar', { :visibility_timeout => '60' })

Alternatively, you can specify a visibility timeout for a specific message when you place it on the queue.

client.sqs.send_message('foo', { :visibility_timeout => '15' })

If you have the id of a message handy and you'd like to get that message without locking it, you can peek at it:

unlocked_message = client.sqs.peek_message('foo', message.id)

unlocked_message.id #=> "1AM3Q5BE7ZZRNQD8MEY6|3H4AA8J7EJKM0DQZR7E1|9CBMKVD6TTQX44QJ1S30"
unlocked_message.body #=> "Help, I'm trapped in a REPL!"

Once you've handled the message, you'll want to remove it permanently from the queue:

client.sqs.delete_message('foo', message.id)

You need to specify both the queue and the message id in order to delete the message.