Bunny: A synchronous Ruby AMQP client

Latest News

• Release v0.6.0 (formerly known as 0.5.4) is now available from Downloads, as well as Rubyforge and Gemcutter

What is Bunny?

Bunny is a Ruby library that enables you to interact with an AMQP-compliant message broker/server, such as RabbitMQ, in a synchronous way. Want to create a queue, bind to an exchange or consume a message? Bunny tries to make it easy for you to do those things. It is based on a great deal of code from amqp by Aman Gupta and Carrot by Amos Elliston. All of the difficult stuff comes from those projects, without which Bunny would have been roadkill.

Why does it exist?

I have used and administered Websphere MQ ( a messaging middleware solution from IBM) in the past. A few years ago I started looking for a FLOSS (Free, Libre and Open Source) equivalent, but didn’t really find anything that appealed to me. Subsequently, I found RabbitMQ and as a result of that discovery, AMQP.

So, having found a messaging solution, I needed to learn about it and the best way for me to learn something is to use it. I really enjoy using Ruby, therefore I looked for a way to talk to RabbitMQ via Ruby. That lead me to amqp and Carrot. What I wanted was something that I could use to perform all of the common messaging functions as simply as possible. As a result, I tended toward Carrot instead of amqp with its use of eventmachine.

After playing with Carrot for a little while, I found that there were changes that I wanted to make. I wanted access to all of the common AMQP functionality, including Basic.Consume, which is asynchronous in nature. Also, whenever possible, I wanted to know whether an AMQP method call succeeded or failed before trying to do something else. So I had a choice, create a fork of Carrot or start a new project. I felt that the changes were going to be significant enough to warrant a new project and so Bunny was born.

How do I get it?

If you have Rubygems then do the following -

Install the gem from Rubyforge:

sudo gem install bunny

If you have no luck with that then you can try to get it from here on GitHub -

Add the GitHub gem repository to your sources list (if you haven’t already done it) :

gem sources -a http://gems.github.com

Install the GitHub gem:

sudo gem install celldee-bunny

If you don’t use Rubygems then you can download the latest source from Rubyforge -

http://rubyforge.org/projects/bunny-amqp

or from here on GitHub -

http://github.com/celldee/bunny/downloads

You should now be ready to get Bunny jumping.

What can I do with it?

The best way to get a feel for how Bunny works is to give it a try, so let’s do it. First of all please make sure that you have an AMQP-compliant message broker/server up and running. I’m using RabbitMQ on my local machine for the following walkthrough.

OK let’s go through a little demonstration using irb :

If you are using Rubygems start irb and enter -

>> require 'rubygems'

and then

>> require 'bunny'

If you are running from the source code navigate to the ‘bunny/lib’ folder then start irb and enter -

>> load 'bunny.rb'

or

>> require 'bunny'

Hopefully you should have received the response -

=> true

Next let’s create a Bunny instance to play with -

>> b = Bunny.new

The response should have been something like this -

=> #<Bunny:0x11c1654 @client=#<AMQP::Client:0x11c15f0 @logging=false, @port=5672, @vhost="/", @insist=nil, @pass="guest", @status=:not_connected, @user="guest", @host="localhost">>

Bunny tries to use sensible defaults where possible so it has entered a default user name, password, host, port and vhost. If any of these are incorrect you can specify them as options in your ‘Bunny.new’ call for example -

b = Bunny.new(:user => 'fred', :pass => 'secret_password')

Now we need to start a communication session with the server -

b.start

And the response if all went well -

=> :connected

So let’s create a queue -

>> q = b.queue('bunny_q')

The response should be similar to -

=> #<Queue:0x11aafd0>

Now to send a message -

>> q.publish('I liked Watership Down')

The response was -

=> nil

Don’t worry! Let’s check to see if there is a message on the queue -

q.message_count

And the welcome response -

=> 1

OK let’s get the message from the queue -

>> q.pop

Yes, it returned the message that you put in -

=> "I liked Watership Down"

Check the message count again to make sure the message has been removed from the queue -

q.message_count

And the expected response -

=> 0

To wrap up let’s close the connection -

>> b.stop

And the reply -

=> :not_connected

That’s the end of your first messaging session with Bunny. Please play around with it and have fun!

For a more in depth introduction take a look at Using Bunny