brightbox-warren

= Warren

Library for sending and receiving messages, complete with en/decrypting messages on either side of the transport.

It was written to handle sending messages between two nodes using RabbitMQ, which is why the two default adapters are for synchronous and asynchronous rabbitmq client libraries. You can delegate the sending & receiving to any custom class you want, simply by subclassing Warren::Queue. (Isn't ruby magic marvelous!)

The filtering works in much the same way as the adapter class. There is a default YAML filter that is always called last before sending the message and first when receiving the message, simply to make sure the message is a string when sent + received. You can then add custom classes onto the stack in any order you want, simply by subclassing Warren::MessageFilter. Add them in the same order on the receiving side and warren takes care of calling them in reverse order.

Start by looking at examples/ to see how to use it, and then lib/warren/adapters/ to see how to implement your own adapter class and lib/warren/filters to see how to implement your own filters.

== Installation

gem install brightbox-warren

== Usage

require "rubygems"
require "warren"
# Use the bunny adapter to connect to RabbitMQ (Bunny is an AMQP client that works with Rails/Passenger apps)
require "warren/adapters/bunny_adapter"
# If you're running in development and don't want to actually push messages onto the queue then instead of loading the bunny adapter use the dummy adapter
require "warren/adapters/dummy_adapter" 

# See examples/ for more

== Rails

Add this to your environment.rb

config.gem "brightbox-warren", :lib => "warren", :version => ">= 0.8"

Add the config into config/warren.yml with the details for each environment. Works just the same as database.yml:

development:
    user: rabbit
    pass: carrots53
    host: rabbit.warren
    logging: false

And then in an initializer file (or bottom of environment.rb) require the adapter you want to use (for rabbitmq I suggest bunny - amqp uses eventmachine and was giving me issues under passenger.) And then any filters you want to use.

require "warren/adapters/bunny_adapter"

== License

Licensed under the MIT license. See LICENSE for more details.