brightbox-warren 0.5 → 0.7

data/lib/warren/connection.rb

@@ -1,37 +1,59 @@
-class Warren::Connection
-  
-  # Creates a new connection with the options passed in.
-  # Requires at least a :user, :pass and :vhost else will raise
-  # InvalidConnectionDetails.
-  def initialize opts = {}
-    # Check they've passed in the stuff without a default on it
-    unless opts.has_key?(:user) && opts.has_key?(:pass) && opts.has_key?(:vhost)
-      raise InvalidConnectionDetails, "Missing a username, password or vhost."
+require "yaml"
+module Warren
+  class Connection
+    
+    attr_reader :options
+
+    #
+    # Creates a new connection by reading the options from
+    # WARREN_ROOT/config/warren.yml or specify the file to read as an
+    # argument or by passing a hash of connection details in.
+    #
+    # Reads WARREN_ENV out of the yaml'd hash (just like ActiveRecord)
+    # "development" by default (and RAILS_ENV if running under rails)
+    #
+    # Raises InvalidConnectionDetails if no params are found for the current
+    # environment.
+    #
+    def initialize params = nil
+      if params.nil? || !params.is_a?(Hash)
+        file ||= WARREN_ROOT << "/config" << "/warren.yml"
+        raise InvalidConnectionDetails, "Config file not found: #{file}" unless File.exists?(file)
+        opts = YAML.load(file)
+      end
+      opts ||= params
+      
+      opts = symbolize_keys(opts[WARREN_ENV])
+      check_connection_details(opts)
+      @options = opts
     end
-    @opts = opts
-  end
-  
-  # Returns the default queue name or returns InvalidConnectionDetails
-  # if no default queue is defined
-  def queue_name
-    raise InvalidConnectionDetails, "Missing a default queue name." unless @opts.has_key?(:default_queue)
-    @opts[:default_queue]
-  end
-  
-  # Returns a hash of the connection options
-  def options
-    {
-      :user  => @opts[:user],
-      :pass  => @opts[:pass],
-      :vhost => @opts[:vhost],
-      :host  => (@opts[:host] || "localhost"),
-      :port  => (@opts[:port] || ::AMQP::PORT.to_i),
-      :logging => (@opts[:logging] || false)
-    }
-  end
-  
-  # Raised if connection details are missing or invalid
-  # Check the error message for more details
-  class InvalidConnectionDetails < Exception
+
+    #
+    # Raised if connection details are missing or invalid
+    # Check the error message for more details
+    #
+    InvalidConnectionDetails = Class.new(Exception)
+
+    private
+
+    #
+    # Changes all keys into symbols
+    #
+    def symbolize_keys(hash)
+      hash.each do |key, value|
+        hash.delete(key)
+        hash[key.to_sym] = value
+      end
+    end
+    
+    # 
+    # Calls the adapter to check the connection details
+    # Returns true or raises InvalidConnectionDetails
+    # 
+    def check_connection_details params
+      return true unless Warren::Queue.adapter.respond_to?(:check_connection_details)
+      Warren::Queue.adapter.send(:check_connection_details, params)
+    end
+
   end
 end

data/lib/warren/{message_filters → filters}/shared_secret.rb

@@ -10,41 +10,41 @@ module Warren
     # 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
@@ -54,7 +54,7 @@ module Warren
         msg[:secret] = self.secret(msg.to_s)
         msg
       end
-      
+
       # Called when unpacking the message from transit.
       # Returns the original object.
       def self.unpack msg
@@ -62,9 +62,9 @@ module Warren
         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        
+        msg
       end
-            
+
     end
   end
 end

data/lib/warren/{message_filters → filters}/yaml.rb

@@ -4,13 +4,13 @@ module Warren
   class MessageFilter
     # Packs the message into a YAML string
     # for transferring safely across the wire
-    class Yaml
-      
+    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)

data/lib/warren/message_filter.rb

@@ -1,46 +1,49 @@
-require File.expand_path(File.dirname(__FILE__) + "/message_filters/yaml")
-
 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 - 
+    #
+    # NB: These get called in reverse order from the array -
     # the last filter to be added gets called first.
-    @@filters = [Warren::MessageFilter::Yaml]
+    @@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> 
+      # <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]
@@ -65,6 +68,9 @@ module Warren
       end
       msg
     end
-    
+
   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

@@ -1,85 +1,69 @@
 class Warren::Queue
   @@connection = nil
-  
+  @@adapter    = nil
+
+  #
   # Raised if no connection has been defined yet.
-  class NoConnectionDetails < Exception
-  end
-  
+  #
+  NoConnectionDetails = Class.new(Exception)
+
+  #
   # Raised if a block is expected by the method but none is given.
-  class NoBlockGiven < Exception
-  end
-    
-  # Sets the connection details
-  def self.connection= params
-    @@connection = params.is_a?(Warren::Connection) ? params : Warren::Connection.new(params)
+  #
+  NoBlockGiven = Class.new(Exception)
+  
+  # 
+  # Raised if an adapter isn't set
+  # 
+  NoAdapterSet = 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
-  # Raises NoConnectionDetails if no connection details have been
-  # assigned yet.
+  #
   def self.connection
-    if @@connection.nil?
-      raise NoConnectionDetails, "You need to set the connection details."
-    end
-    @@connection
+    @@connection ||= Warren::Connection.new
+  end
+
+  # 
+  # Sets the adapter when this class is subclassed.
+  # 
+  def self.inherited klass
+    @@adapter = klass
   end
   
-  #
-  # Sends a message to a queue. If successfully sent it returns
-  # true, unless callback block is passed (see below)
   # 
-  #   Warren::Queue.publish(:queue_name, {:foo => "name"})
+  # Sets the adapter manually
   # 
-  # Can also pass a block which is fired after the message
-  # is sent. If a block is passed, then the return value of the block
-  # is returned from this method.
+  def self.adapter= klass
+    @@adapter = klass
+  end
+
   # 
-  #   Warren::Queue.publish(:queue_name, {:foo => "name"}) { puts "foo" }
+  # Returns the current adapter or raises NoAdapterSet exception
   # 
-  def self.publish queue_name, payload, &blk
-    queue_name = self.connection.queue_name if queue_name == :default
-    # Create a message object if it isn't one already
-    msg = Warren::MessageFilter.pack(payload)
-        
-    do_connect(true, blk) do
-      queue = MQ::Queue.new(MQ.new, queue_name)
-      queue.publish msg.to_s
-    end
+  def self.adapter
+    @@adapter || raise(NoAdapterSet)
+  end
 
+  # 
+  # Publishes the message to the queue
+  # 
+  def self.publish *args, &blk
+    self.adapter.publish(*args, &blk)
   end
   
-  #
-  # Subscribes to a queue and runs the block
-  # for each message received
-  # 
-  #   Warren::Queue.subscribe("example") {|msg| puts msg }
   # 
-  # Expects a block and raises NoBlockGiven if no block is given.
+  # Sends the subscribe message to the adapter class
   # 
-  def self.subscribe queue_name, &block
-    raise NoBlockGiven unless block_given?
-    queue_name = self.connection.queue_name if queue_name == :default
-    # todo: check if its a valid queue?
-    do_connect(false) do
-      queue = MQ::Queue.new(MQ.new, queue_name)
-      queue.subscribe do |msg|
-        msg = Warren::MessageFilter.unpack(msg)
-        block.call(msg)
-      end
-    end
+  def self.subscribe *args, &blk
+    self.adapter.subscribe(*args, &blk)
   end
 
-
-  private
-  
-  # Connects and does the stuff its told to!
-  def self.do_connect should_stop = true, callback = nil, &block
-    AMQP.start(self.connection.options) do
-      block.call
-      AMQP.stop { EM.stop_event_loop } if should_stop
-    end
-    # Returns the block return value or true
-    callback.nil? ? true : callback.call
-  end
-  
 end

data/readme.rdoc

@@ -1,19 +1,26 @@
 = Warren
 
-Library for pushing messages onto RabbitMQ queues, and receiving them at the other end.
+Library for sending and receiving messages, complete with en/decrypting messages on either side of the transport. 
 
-It handles authentication + filtering messages with custom classes if needed.
+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!)
 
-Start with Warren::Queue for details and see also examples/
+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.
 
-== Released under the MIT Licence
+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.
 
-Copyright (c) 2008 Brightbox Systems Ltd 
+== Installation
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+    gem install brightbox-warren
 
-* The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+== Usage
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+    require "rubygems"
+    require "warren"
+    # Pull in the bunny adapter
+    require "warren/adapters/bunny_adapter"
+    
+    # See examples/ for more
 
-See http://www.brightbox.co.uk/ for contact details.  
+== License
+
+Licensed under the MIT license. See LICENSE for more details.

data/spec/spec_helper.rb

@@ -1,4 +1 @@
 require File.join(File.dirname(__FILE__) + "/../lib/warren")
-
-# Hash#only and Hash#except
-require File.join(File.dirname(__FILE__) + "/hash_extend")

data/spec/warren/connection_spec.rb

@@ -3,68 +3,87 @@ require File.dirname(__FILE__) + '/../spec_helper'
 describe Warren::Connection do
   
   before(:each) do
-    @c = Warren::Connection.new(details)
+    @file = stub 'io', :read => yaml_data
+    setup_adapter
   end
-  
-  it "should require a username" do
-    lambda {
-      Warren::Connection.new(details.except(:user))
-    }.should raise_error(Warren::Connection::InvalidConnectionDetails)
-  end
-  
-  it "should require a password" do
-    lambda {
-      Warren::Connection.new(details.except(:pass))
-    }.should raise_error(Warren::Connection::InvalidConnectionDetails)
-  end
-  
-  it "should require a queue name if none specified" do
-    lambda {
-      conn = Warren::Connection.new(details)
-      conn.queue_name
-    }.should raise_error(Warren::Connection::InvalidConnectionDetails)
+    
+  it "should read from a config file" do
+    YAML.should_receive(:load).with("#{File.dirname($0)}/config/warren.yml").and_return({"development" => {}})
+
+    Warren::Connection.new
   end
-  
-  it "should return a default host" do
-    @c.options[:host].should == "localhost"
+
+  it "should parse the right config out" do    
+    conn = Warren::Connection.new(@file)
+    conn.instance_variable_get("@opts").should == {
+      :host    => "localhost",
+      :user    => "rspec",
+      :pass    => "password",
+      :logging => false
+    }
   end
   
-  it "should return a given host" do
-    c = Warren::Connection.new(details.merge({:host => "caius"}))
-    c.options[:host].should == "caius"
+  it "should symbolize keys in a hash" do
+    conn = Warren::Connection.new(@file)
+    hash = {"one" => "two", "three" => "four", :five => "six"}
+    conn.send(:symbolize_keys, hash).should == {
+      :one   => "two",
+      :three => "four",
+      :five  => "six"
+    }
   end
   
-  it "should return a default port" do
-    @c.options[:port].should == 5672
+  it "should raise if no adapter set to check against" do
+    Warren::Queue.adapter = nil
+    lambda {
+      Warren::Connection.new(@file)
+    }.should raise_error(Warren::Queue::NoAdapterSet)
   end
   
-  it "should return a given port" do
-    c = Warren::Connection.new(details.merge({:port => 1}))
-    c.options[:port].should == 1
+  it "should successfully check against adapter" do
+    _adapter = stub 'queue', :check_connection_details => true
+    
+    Warren::Connection.new(@file)
   end
   
-  it "should return a default logging param" do
-    @c.options[:logging].should == false
+  it "should raise errors for missing connection details" do
+    _adapter = stub 'queue', :check_connection_details => ["one", "two"]
+    
+    Warren::Connection.new(@file)
   end
   
-  it "should return a given logging param" do
-    c = Warren::Connection.new(details.merge({:logging => true}))
-    c.options[:logging].should == true
+  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(@file)
+    }.should raise_error(Warren::Connection::InvalidConnectionDetails, "Missing prerequisites")
   end
 
-  it "should return the given queue name" do
-    conn = Warren::Connection.new(details.merge({:default_queue => "queue"}))
-    conn.queue_name.should == "queue"
+  def setup_adapter
+    _adapter = stub 'queue'
+    Warren::Queue.adapter = _adapter
   end
 
-  private
+  def yaml_data
+    a = <<-EOF
+---
+development:
+  host: localhost
+  user: rspec
+  pass: password
+  logging: false
 
-  def details
-    {
-      :user  => "user",
-      :pass  => "pass",
-      :vhost => "main",
-    }
+test:
+  host: localhost
+  user: rspec
+  pass: password
+  logging: true
+EOF
   end
-  
+
 end