Messaging gateway API with adapters for different messaging systems available in Ruby.
Ruby
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead, 77 commits behind bmabey:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
features
lib
spec
.gitignore
History.txt
MIT-LICENSE.txt
README.rdoc
Rakefile
VERSION.yml
cucumber.yml
init.rb
rosetta_queue.gemspec

README.rdoc

Rosetta Queue

Rosetta Queue is a messaging gateway API with adapters for many messaging systems available in Ruby. Messaging systems can be easily switched out with a small configuration change. Code for testing on the object and application level is also provided.

The adapters provided currently are for stomp, amqp, and beanstalk. We would like to add adapters for other messaging gateways. The stomp adapter has been used in production along side with Apache's ActiveMQ. The amqp adapter currently works along side RabbitMQ and passes the acceptance tests but as of yet has not been used in production.

Quick Tutorial

Note: The API will most likely change until we reach 1.0. We will be moving to a more concise API (i.e. queue(:test_queue) << message, etc…) We will also be changing how exceptions are handled.

When using Rosetta Queue in an application you will need to configure the queues, adapters, and filters (optional). These configurations should be placed in a file that gets loaded once when your program starts. If you are using Rails then a good place for this is config/initializers/rosetta_queue.rb.

To set up destinations to produce messages to and consume messages from:

RosettaQueue::Destinations.define do |queue|

queue.map :test_queue, '/queue/my_test_queue'

end

Defining your adapter:

RosettaQueue::Adapter.define do |a|
  a.user = ""
  a.password = ""
  a.host = "localhost"
  a.port = 61613
  a.type = "stomp"
end

Define a logger for Rosetta Queue to use. The logger should be a standard ruby logger:

RosettaQueue.logger = Logger.new('/my_project/rosetta_queue.log')

You can optionally set up filters that are applied to all messages that are sent and received. For example, if you want to use hashes as messages and serialize them as JSON the following filters (along with ActiveSupport) would accomplish this:

RosettaQueue::Filters.define do |filter_for|
  filter_for.receiving { |message| ActiveSupport::JSON.decode(message) }
  filter_for.sending { |hash| hash.to_json }
end

To publish a message:

message = {"hello" => "world!"}  # Assuming you have a filter setup
RosettaQueue::Producer.publish(:test_queue, message)

When consuming messages from a queue you will generally want to create a consumer to handle the messages:

class TestConsumer
  include RosettaQueue::MessageHandler

  subscribes_to :vendor_status
  options :persistent => true

  def on_message(message)
    puts "We consumed a message: #{message.inspect}"
  end

end

To fire the consumers up you will want to run a separate process create a manager with all of your consumers.

require 'rosetta_queue'
require 'rosetta_queue/consumer_managers/threaded'
require 'test_consumer'

RosettaQueue::ThreadedManager.create do |m|
  m.add(TestConsumer.new)
  m.start
end

It is recommended that you set your adapter to the 'null' adapter for your specs and then include RosettaQueue::Matchers in any example group you are needing to specify behaviour with RosettaQueue. The matchers currently switch out the null adapter for the fake adapter to verify the behaviour. All the matchers for the unit tests are lambda based, like so:

lambda { model.save }.should publish("foo", :to => :test_queue).

Please look at the publishing matchers for more information. For examples on how to write acceptance tests for your Rosetta Queue's code please see RosettaQueue's own Cucumber features and read this blog post.

How to contribute


Gems you will need: cucumber, rspec, yaml, stomp, tmm1-amqp, beanstalk-client

You should be able to run the rspec code examples (specs) without any brokers running with autospec or 'rake spec'.

To run the cucumber features you will need the a messaging system setup that can speak stomp and AMQP. We have been using the following brokers in testing:

Apache ActiveMQ (for the stomp adapter)

Go to activemq.apache.org/download.html to download the latest version, and see activemq.apache.org/getting-started.html for installation and configuration instructions. The stomp client and features should work with ApacheMQ out of the box. If you are running any ApacheMQ servers in production on your network you will want to disable the multicast autodiscovery in conf/activemq.xml. (Around lines 56 and 98.)

RabbitMQ (for the amqp adapter)

Download the right tar from here: www.rabbitmq.com/download.html and follow the installation directions that comes with it. The features rely on a user of 'rosetta' being setup with the password of 'password' and added to the default virtualhost. You can set them up like so:

rabbitmqctl add_user rosetta password
rabbitmqctl map_user_vhost rosetta /

Beanstalk (for the beanstalk adapter) ===

You should set up and run a local instance of beanstalk for your tests.

beanstalkd ====

Mac OSX users can install beanstalkd from ports. Linux users should check their package manager of choice. This is probably the optimal method.

Diehards can clone git://github.com/kr/beanstalkd and build it from source. It is nontrivial.

Once installed, you can launch beanstalk by running

beanstalkd -p 11300

This will make it listen on localhost on the standard port 11300, which the specs use. You might also want to daemonize beanstalk with the -d option but for testing this is not recommended, as the queue can get stuck with old messages, which will break your specs.

beanstalk-client ====

You will also need the Ruby beanstalk-client gem.

sudo gem install beanstalk-client