warren 0.8.9

data/lib/warren/filters/shared_secret.rb

@@ -0,0 +1,70 @@
+begin
+  require "hmac-sha2"
+rescue LoadError => e
+  puts "Error loading the `ruby-hmac` gem."
+  exit!
+end
+
+module Warren
+  class MessageFilter
+    # Hashes the message using a secret salt, stores the hash
+    # in the message and then checks its the same when pulled
+    # off the other end.
+    #
+    # Basic trust implementation to make sure the message
+    # hasn't been tampered with in transit and came from
+    # an "authorised" app.
+    #
+    # Make sure both the publisher and subscriber use the same
+    # key else you'll get KeyValidationError error raised.
+    #
+    class SharedSecret
+      # Raised when no key (salt) is provided
+      class NoKeyError < Exception; end
+      # Raised when there is a key mismatch error
+      class KeyValidationError < Exception; end
+
+      # Sets the key to use
+      def self.key= key
+        @@key = key
+      end
+
+      # Returns the current key
+      # Raises NoKeyError if no key has been assigned yet
+      def self.key
+        raise NoKeyError if @@key.nil?
+        @@key
+      end
+
+      # Returns the hashed message
+      #
+      # Expects that msg#to_s returns a string
+      # to hash against.
+      #
+      def self.secret msg
+        HMAC::SHA256.hexdigest(self.key, msg.to_s)
+      end
+
+      # Called when the message is being packed for
+      # transit. Returns a hash.
+      def self.pack msg
+        # Make sure its a hash
+        msg = {:secret_msg => msg} unless msg.is_a? Hash
+        # And add our secret into the hash
+        msg[:secret] = self.secret(msg.to_s)
+        msg
+      end
+
+      # Called when unpacking the message from transit.
+      # Returns the original object.
+      def self.unpack msg
+        # Check the secret exists in the msg and matches the secret_string
+        raise KeyValidationError unless msg.delete(:secret) == self.secret(msg)
+        # see if its a hash we created, it'll only contain the key "secret_msg" if it is
+        msg = msg[:secret_msg] if msg.keys == [:secret_msg]
+        msg
+      end
+
+    end
+  end
+end

data/lib/warren/filters/yaml.rb

@@ -0,0 +1,20 @@
+require "yaml"
+
+module Warren
+  class MessageFilter
+    # Packs the message into a YAML string
+    # for transferring safely across the wire
+    class Yaml < MessageFilter
+
+      # Returns a YAML string
+      def self.pack msg
+        YAML.dump(msg)
+      end
+
+      # Returns original message
+      def self.unpack msg
+        YAML.load(msg)
+      end
+    end
+  end
+end

data/lib/warren/message_filter.rb

@@ -0,0 +1,76 @@
+module Warren
+  # Handles filtering messages going onto/coming off the queue
+  class MessageFilter
+    # Array of filters to be run on the message before its
+    # pushed to rabbit.
+    #
+    # NB: These get called in reverse order from the array -
+    # the last filter to be added gets called first.
+    @@filters = []
+
+    class << self
+      # Adds a filter to the list
+      #
+      # A valid filter is just a class that defines
+      # <tt>self.pack</tt> and <tt>self.unpack</tt>
+      # methods, which both accept a single argument,
+      # act upon it, and return the output.
+      #
+      # Example filter class (See also message_filters/*.rb)
+      #
+      #     class Foo
+      #       def self.pack msg
+      #         msg.reverse # Assumes msg responds to reverse
+      #       end
+      #
+      #       def self.unpack msg
+      #         msg.reverse # Does the opposite of Foo#pack
+      #       end
+      #     end
+      #
+      def << filter
+        @@filters << filter
+      end
+      alias :add_filter :<<
+    end
+
+    # Called when a subclass is created, adds the subclass to the queue
+    def self.inherited klass
+      add_filter klass
+    end
+
+    # Returns current array of filters
+    def self.filters
+      @@filters
+    end
+
+    # Resets the filters to default
+    def self.reset_filters
+      @@filters = [Warren::MessageFilter::Yaml]
+    end
+
+    # Runs the raw message through all the filters
+    # and returns the filtered version
+    def self.pack msg
+      @@filters.reverse.each do |f|
+        # puts "Packing with #{f}"
+        msg = f.send(:pack, msg)
+      end
+      msg
+    end
+
+    # Runs the filtered message through all the
+    # filters and returns the raw version
+    def self.unpack msg
+      @@filters.each do |f|
+        # puts "Unpacking with #{f}"
+        msg = f.unpack(msg)
+      end
+      msg
+    end
+
+  end
+end
+
+# Make sure the YAML filter is added first
+require File.expand_path(File.dirname(__FILE__) + "/filters/yaml")

data/lib/warren/queue.rb

@@ -0,0 +1,89 @@
+module Warren
+  class Queue
+    @@connection = nil
+    @@adapter    = nil
+
+    #
+    # Raised if no connection has been defined yet.
+    #
+    NoConnectionDetails = Class.new(Exception)
+
+    #
+    # Raised if a block is expected by the method but none is given.
+    #
+    NoBlockGiven = Class.new(Exception)
+
+    # 
+    # Raised if an adapter isn't set
+    # 
+    NoAdapterSet = Class.new(Exception)
+
+    # 
+    # Raised if the adapter is missing a method
+    # Check the message for details of the missing method.
+    # 
+    InvalidAdapter = Class.new(Exception)
+
+    # 
+    # Sets the current connection
+    # 
+    def self.connection= conn
+      @@connection = (conn.is_a?(Warren::Connection) ? conn : Warren::Connection.new(conn) )
+    end
+
+    #
+    # Returns the current connection details
+    #
+    def self.connection
+      @@connection ||= Warren::Connection.new
+    end
+
+    # 
+    # Sets the adapter when this class is subclassed.
+    # 
+    def self.inherited klass
+      @@adapter = klass
+    end
+
+    # 
+    # Sets the adapter manually
+    # 
+    def self.adapter= klass
+      @@adapter = klass
+    end
+
+    # 
+    # Returns the current adapter or raises NoAdapterSet exception
+    # 
+    def self.adapter
+      @@adapter || raise(NoAdapterSet)
+    end
+
+    # 
+    # Publishes the message to the queue
+    # 
+    def self.publish *args, &blk
+      raise(InvalidAdapter, "publish method missing") unless @@adapter.respond_to?(:publish)
+      self.adapter.publish(*args, &blk)
+    end
+
+    # 
+    # Sends the subscribe message to the adapter class
+    # 
+    def self.subscribe *args, &blk
+      raise(InvalidAdapter.new("subscribe method missing")) unless @@adapter.respond_to?(:subscribe)
+      self.adapter.subscribe(*args, &blk)
+    end
+
+		def self.logger
+			unless @@logger
+				@@logger = Logger.new(nil)
+			end
+			@@logger
+		end
+
+		def self.logger=(l)
+			@@logger = l
+		end
+  end
+end

data/lib/warren.rb

@@ -0,0 +1,23 @@
+require "yaml"
+require "logger"
+#
+# Library for pushing messages onto RabbitMQ queues,
+# and receiving them at the other end.
+#
+# It handles authentication + filtering messages with custom
+# classes if needed.
+#
+# Start with Warren::Queue for details and see also
+# examples/
+#
+module Warren
+end
+
+WARREN_ENV = ENV['WARREN_ENV'] || ((defined?(RAILS_ENV) ? RAILS_ENV : "development")) unless defined?(WARREN_ENV)
+WARREN_ROOT = (defined?(RAILS_ROOT) ? RAILS_ROOT : File.dirname($0)) unless defined?(WARREN_ROOT)
+WARREN_LIB_ROOT = File.expand_path(File.dirname(__FILE__)) unless defined? WARREN_LIB_ROOT
+
+# Require everything in the lib folder
+Dir["#{WARREN_LIB_ROOT}/warren/*.rb"].each do |file|
+  require file
+end

data/readme.rdoc

@@ -0,0 +1,46 @@
+= 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.

data/spec/spec.opts

@@ -0,0 +1,3 @@
+--colour
+--format progress
+--loadby mtime

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require File.join(File.dirname(__FILE__) + "/../lib/warren")
+
+# Hacky and I hate it, but needed to 
+# change constants in tests
+# from http://is.gd/12JVp
+def silently(&block)
+  warn_level = $VERBOSE
+  $VERBOSE = nil
+  result = block.call
+  $VERBOSE = warn_level
+  result
+end

data/spec/warren/adapters/test_adapter_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+require "#{File.dirname(__FILE__)}/../../../lib/warren/adapters/test_adapter.rb"
+
+describe TestAdapter do
+
+  before(:all) do
+    @file_name = "#{WARREN_ROOT}/tmp/warren.txt"
+  end
+
+  it "should return true from publish without a tmp file" do
+    TestAdapter.publish(:queue_name, :payload).should == true
+  end
+
+  it "should return true from publish with a tmp file which doesn't say \"FAIL\"" do
+    File.should_receive(:exists?).with(@file_name).and_return(true)
+    File.should_receive(:read).with(@file_name, 4).and_return("blah")
+
+    TestAdapter.publish(:queue_name, :payload).should == true
+  end
+
+  it "should raise an error when tmp file exists and says \"FAIL\"" do
+    File.should_receive(:exists?).with(@file_name).and_return(true)
+    File.should_receive(:read).with(@file_name, 4).and_return("FAIL")
+
+    lambda { TestAdapter.publish(:queue_name, :payload) }.
+    should raise_error(TestAdapter::ConnectionFailed)
+  end
+
+end

data/spec/warren/connection_spec.rb

@@ -0,0 +1,122 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Warren::Connection do
+
+  before(:each) do
+    setup_adapter
+  end
+
+  it "should read from warren.yml" do
+    setup_config_file
+
+    Warren::Connection.new
+  end
+
+  it "should read from an arbitrary file" do
+    File.should_receive(:exists?).with("my_awesome_config.yml").and_return(true)
+    YAML.should_receive(:load_file).with("my_awesome_config.yml").and_return({"development" => {}})
+
+    Warren::Connection.new("my_awesome_config.yml")
+  end
+
+  describe "parsing config with file" do
+
+    before do
+      setup_config_file
+    end
+
+    it "should parse the right config out" do
+      conn = Warren::Connection.new
+      WARREN_ENV.should == "development"
+      conn.instance_variable_get("@options").should == {
+        :user => "rspec",
+        :pass => "password",
+        :host => "localhost",
+        :logging => false,
+      }
+    end
+    
+    it "should raise if no details for current environment" do
+      silently { WARREN_ENV = "rspec" }
+      
+      lambda { Warren::Connection.new }.
+      should raise_error(
+        Warren::Connection::InvalidConnectionDetails,
+        "No details for current environment 'rspec'"
+      )
+      
+      silently { WARREN_ENV = "development" }
+    end
+
+    it "should symbolize keys in a hash" do
+      conn = Warren::Connection.new
+      hash = {"one" => "two", "three" => {"four" => 7}, :five => "six"}
+      conn.send(:symbolize_keys, hash).should == {
+        :one   => "two",
+        :three => {:four => 7},
+        :five  => "six"
+      }
+    end
+
+    it "should raise if no adapter set to check against" do
+      Warren::Queue.adapter = nil
+      lambda { Warren::Connection.new }.
+      should raise_error(Warren::Queue::NoAdapterSet)
+    end
+
+    it "should successfully check against adapter" do
+      _adapter = mock 'queue', :check_connection_details => true
+      _adapter.should_receive(:check_connection_details)
+      Warren::Queue.adapter = _adapter
+      
+      Warren::Connection.new
+    end
+
+    it "should raise errors for missing connection details" do
+      _adapter = stub 'queue', :check_connection_details => ["one", "two"]
+
+      Warren::Connection.new
+    end
+
+    it "should raise errors for other prerequisits in the adapter" do
+      Adapter = Class.new(Warren::Queue) do
+        def self.check_connection_details params
+          raise Warren::Connection::InvalidConnectionDetails, "Missing prerequisites"
+        end
+      end
+
+      lambda { Warren::Connection.new }.
+      should raise_error(Warren::Connection::InvalidConnectionDetails, "Missing prerequisites")
+    end
+
+  end
+
+  def setup_config_file
+    config_file = "#{File.dirname($0)}/config/warren.yml"
+    File.should_receive(:exists?).with(config_file).and_return(true)
+    YAML.should_receive(:load_file).with(config_file).and_return(yaml_data)
+  end
+
+  def setup_adapter
+    _adapter = stub 'queue'
+    Warren::Queue.adapter = _adapter
+  end
+
+  def yaml_data
+    {
+      "development" => {
+        "host" => "localhost",
+        "user" => "rspec",
+        "pass" => "password",
+        "logging" => false
+      },
+      "test" => {
+        "host" => "localhost-test",
+        "user" => "rspec-test",
+        "pass" => "password-test",
+        "logging" => true
+      }
+    }
+  end
+
+end

data/spec/warren/queue_spec.rb

@@ -0,0 +1,91 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Warren::Queue do
+  
+  describe "connection" do
+    
+    before(:all) do
+      @conn = stub 'connection'
+    end
+    
+    it "should create a new Warren::Connection if one doesn't exist" do
+      Warren::Connection.should_receive(:new).and_return(@conn)
+      
+      Warren::Queue.connection.should == @conn
+    end
+    
+    it "should only create a connection once" do
+      # Already created the connection object in the first it
+      Warren::Connection.should_not_receive(:new)
+      
+      Warren::Queue.connection.should == @conn
+      Warren::Queue.connection.should == @conn
+    end
+  end
+
+  describe "adapter" do
+
+    before(:each) do
+      @adapter = mock 'adapter', :publish => "publish", :subscribe => "subscribe"
+      Warren::Queue.adapter = @adapter
+    end
+
+    it "should have an adapter set" do
+      Warren::Queue.adapter.should == @adapter
+    end
+
+    it "should have a publish method" do
+      my_adapter = mock 'adapter'
+      Warren::Queue.adapter = my_adapter
+
+      lambda { Warren::Queue.publish }.should \
+      raise_error(Warren::Queue::InvalidAdapter, "publish method missing")
+    end
+
+    it "should have a subscribe method" do
+      my_adapter = mock 'adapter'
+      Warren::Queue.adapter = my_adapter
+      
+      Warren::Queue.adapter.should == my_adapter
+
+      lambda { Warren::Queue.subscribe}.should \
+      raise_error(Warren::Queue::InvalidAdapter, "subscribe method missing")
+    end
+
+    it "should pass publish through to the adapter" do
+      @adapter.should_receive(:publish)
+      Warren::Queue.publish.should == "publish"
+    end
+
+    it "should pass arguments through to adapter#publish" do
+      @adapter.should_receive(:publish).with("foo", "bar")
+
+      Warren::Queue.publish("foo", "bar").should == "publish"
+    end
+
+    it "should pass a block through to adapter#publish" do
+      block = lambda { true }
+      @adapter.should_receive(:publish).with("foo", "bar", block)
+
+      Warren::Queue.publish("foo", "bar", block).should == "publish"
+    end
+
+    it "should pass subscribe through to the adapter" do
+      @adapter.should_receive(:subscribe)
+      Warren::Queue.subscribe.should == "subscribe"
+    end
+
+    it "should pass arguments through to adapter#subscribe" do
+      @adapter.should_receive(:subscribe).with("foo", "bar")
+
+      Warren::Queue.subscribe("foo", "bar").should == "subscribe"
+    end
+
+    it "should pass a block through to adapter#subscribe" do
+      block = lambda { true }
+      @adapter.should_receive(:subscribe).with("foo", "bar", block)
+
+      Warren::Queue.subscribe("foo", "bar", block).should == "subscribe"
+    end
+  end
+end

data/spec/warren/warren_spec.rb

@@ -0,0 +1,9 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Warren do
+  
+  it "should have a default environment" do
+    WARREN_ENV.should == "development"
+  end
+
+end

data/tasks/rdoc.rake

@@ -0,0 +1,7 @@
+require "rake/rdoctask"
+
+Rake::RDocTask.new do |rd|
+  rd.main = "lib/warren.rb"
+  rd.rdoc_files.include("lib/**/*.rb")
+  rd.rdoc_dir = "doc"
+end

data/tasks/rspec.rake

@@ -0,0 +1,24 @@
+# Borrowed from http://github.com/rsim/ruby-plsql/tree/master/tasks/rspec.rake
+# Github++
+begin
+  require "spec"
+rescue LoadError
+  require "rubygems"
+  require "spec"
+end
+
+begin
+  require "spec/rake/spectask"
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+  [sudo] gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run the specs under spec/*"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ["--options", "spec/spec.opts"]
+  t.spec_files = FileList["spec/**/*_spec.rb"]
+end

data/warren.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{warren}
+  s.version = "0.8.9"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Caius Durling, David Smalley"]
+  s.date = %q{2009-10-15}
+  s.description = %q{Library for pushing messages onto and off RabbitMQ queues}
+  s.email = %q{support@brightbox.co.uk}
+  s.extra_rdoc_files = ["CHANGELOG", "lib/warren/adapters/amqp_adapter.rb", "lib/warren/adapters/bunny_adapter.rb", "lib/warren/adapters/dummy_adapter.rb", "lib/warren/adapters/test_adapter.rb", "lib/warren/connection.rb", "lib/warren/filters/shared_secret.rb", "lib/warren/filters/yaml.rb", "lib/warren/message_filter.rb", "lib/warren/queue.rb", "lib/warren.rb", "LICENSE", "tasks/rdoc.rake", "tasks/rspec.rake"]
+  s.files = ["CHANGELOG", "examples/authed/receiver.rb", "examples/authed/secret.rb", "examples/authed/sender.rb", "examples/simple/amqp_mass_sender.rb", "examples/simple/amqp_receiver.rb", "examples/simple/amqp_sender.rb", "examples/simple/bunny_receiver.rb", "examples/simple/bunny_sender.rb", "lib/warren/adapters/amqp_adapter.rb", "lib/warren/adapters/bunny_adapter.rb", "lib/warren/adapters/dummy_adapter.rb", "lib/warren/adapters/test_adapter.rb", "lib/warren/connection.rb", "lib/warren/filters/shared_secret.rb", "lib/warren/filters/yaml.rb", "lib/warren/message_filter.rb", "lib/warren/queue.rb", "lib/warren.rb", "LICENSE", "Manifest", "Rakefile", "readme.rdoc", "spec/spec.opts", "spec/spec_helper.rb", "spec/warren/adapters/test_adapter_spec.rb", "spec/warren/connection_spec.rb", "spec/warren/queue_spec.rb", "spec/warren/warren_spec.rb", "tasks/rdoc.rake", "tasks/rspec.rake", "warren.gemspec"]
+  s.homepage = %q{http://github.com/brightbox/warren}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Warren", "--main", "readme.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{warren}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Library for pushing messages onto and off RabbitMQ queues}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<amqp>, [">= 0.6.0"])
+    else
+      s.add_dependency(%q<amqp>, [">= 0.6.0"])
+    end
+  else
+    s.add_dependency(%q<amqp>, [">= 0.6.0"])
+  end
+end