schoefmax-warren 0.8.8

data/lib/warren/adapters/dummy_adapter.rb

@@ -0,0 +1,12 @@
+require "rubygems"
+
+class DummyAdapter < Warren::Queue
+  def self.publish queue_name, payload, &blk
+    puts "publishing #{payload.inspect} to #{queue_name}"
+  end
+
+  def self.subscribe queue_name, &block
+    puts "subscribing to #{queue_name}"
+  end
+end
+

data/lib/warren/adapters/test_adapter.rb

@@ -0,0 +1,27 @@
+require "rubygems"
+
+class TestAdapter < Warren::Queue
+  ConnectionFailed = Class.new(Exception)
+  # 
+  def self.publish queue_name, payload, &blk
+    raise TestAdapter::ConnectionFailed if fail?
+    true
+  end
+
+  # 
+  # def self.subscribe queue_name, &block
+  #   puts "subscribing to #{queue_name}"
+  # end
+  # 
+  
+  private
+  
+  def self.fail?
+    File.exists?(file_name) && (File.read(file_name, 4) == "FAIL")
+  end
+  
+  def self.file_name
+    "#{WARREN_ROOT}/tmp/warren.txt"
+  end
+end
+

data/lib/warren/connection.rb

@@ -0,0 +1,140 @@
+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.
+    #
+    #   Warren::Connection.new # reads WARREN_ROOT/config/warren.yml
+    #   Warren::Connection.new("file.yml")       # reads file.yml
+    #   Warren::Connection.new({"foo" => "bar"}) # uses the hash
+    #
+    # 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.
+    #
+    # todo: fail nicely if the env isn't defined
+    #
+    def initialize params = nil
+      get_connection_details(params)
+      # Make the details publically accessible
+      @options = @opts
+    end
+
+    #
+    # Raised if connection details are missing or invalid
+    # Check the error message for more details
+    #
+    InvalidConnectionDetails = Class.new(Exception)
+
+    private
+
+    #
+    # Short version: This is the brain of this class and sets everything up.
+    #
+    # Long version: Works out where the connection details need to come from
+    # (params or yml) and parses them from there. Then figures out if the details
+    # are there for the current env and raises a nice error if there aren't any
+    # detail for the current env. Then we symblize all the keys and get the adapter
+    # to check its happy with the connection details we have.
+    #
+    def get_connection_details params
+      case params
+      when NilClass
+        # Read from config/warren.yml
+        read_config_file
+
+      when String
+        # See if it exists as a file
+        parse_config_file(params)
+
+      when Hash
+        # Use it as-is
+        @opts = params
+
+      else
+        # See if it responds to :read
+        if respond_to?(:read)
+          # Parse it as yaml
+          parse_config(params)
+        else
+          # Have no idea what to do with it
+          raise InvalidConnectionDetails, "Don't know what to do with the params passed. Please pass a hash, filename or nothing."
+        end
+      end
+
+      # Make sure the hash keys are symbols
+      @opts = symbolize_keys(@opts)
+      # Parse out the current environment
+      parse_environment
+      # Call the adapter to figure out if the details are alright
+      check_connection_details
+    end
+
+    #
+    # Reads in either config/warren.yml or the passed argument as a YAML file
+    #
+    def read_config_file filename=nil
+      filename ||= "#{WARREN_ROOT}/config/warren.yml"
+      parse_config_file(filename)
+    end
+
+    #
+    # Parses the config file into a hash from yaml.
+    #
+    def parse_config_file filename
+      if File.exists?(filename)
+        @opts = YAML.load_file(filename)
+      else
+        raise InvalidConnectionDetails, "File not found: '#{filename}'"
+      end
+    end
+
+    #
+    # Parses the object using YAML#load
+    #
+    def parse_config obj
+      @opts = YAML.load(obj)
+    end
+
+    #
+    # Modifies the hash into just the details for the
+    # current environment, or raises InvalidConnectionDetails
+    #
+    def parse_environment
+      # keys are symbolified already
+      unless @opts.has_key?(WARREN_ENV.to_sym)
+        raise InvalidConnectionDetails, "No details for current environment '#{WARREN_ENV}'"
+      end
+      @opts = @opts[WARREN_ENV.to_sym]
+    end
+
+    #
+    # Changes all keys into symbols
+    #
+    def symbolize_keys(hash)
+      hash.each do |key, value|
+        hash.delete(key)
+        # Make it recursive
+        hash[key.to_sym] = (value.is_a?(Hash) ? symbolize_keys(value) : value)
+      end
+      hash
+    end
+
+    #
+    # Calls the adapter to check the connection details
+    # Returns true or raises InvalidConnectionDetails
+    #
+    def check_connection_details
+      return true unless Warren::Queue.adapter.respond_to?(:check_connection_details)
+      Warren::Queue.adapter.send(:check_connection_details, @opts)
+    end
+
+  end
+end

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,71 @@
+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)
+
+    # 
+    # 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
+      self.adapter.publish(*args, &blk)
+    end
+
+    # 
+    # Sends the subscribe message to the adapter class
+    # 
+    def self.subscribe *args, &blk
+      self.adapter.subscribe(*args, &blk)
+    end
+
+  end
+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.