@@ -2,7 +2,18 @@ require "yaml" require "rubygems" require "mq" +# +# 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 + @@foo = "" end WARREN_ROOT = File.expand_path(File.join(File.dirname(__FILE__), "..")) lib/warren.rb @@ -1,5 +1,8 @@ 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) @@ -8,11 +11,14 @@ class Warren::Connection @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], @@ -24,6 +30,8 @@ class Warren::Connection } end + # Raised if connection details are missing or invalid + # Check the error message for more details class InvalidConnectionDetails < Exception end end \ No newline at end of file lib/warren/connection.rb @@ -1,6 +1,7 @@ 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. @@ -9,8 +10,26 @@ module Warren # the last filter to be added gets called first. @@filters = [Warren::MessageFilter::Yaml] - # Adds a filter to the list 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 @@ -22,12 +41,13 @@ module Warren @@filters end - # Resets the filters to nowt + # Resets the filters to default def self.reset_filters @@filters = [Warren::MessageFilter::Yaml] end - # Returns a packed message + # 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}" @@ -36,7 +56,8 @@ module Warren msg end - # Unpacks the message + # 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}" lib/warren/message_filter.rb @@ -7,23 +7,46 @@ 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 - def self.secret string - HMAC::SHA256.hexdigest(self.key, string) + # 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 @@ -32,9 +55,11 @@ module Warren 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.to_s) + 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 lib/warren/message_filters/shared_secret.rb @@ -2,16 +2,19 @@ require "yaml" module Warren class MessageFilter + # Packs the message into a YAML string + # for transferring safely across the wire class Yaml + # 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 \ No newline at end of file lib/warren/message_filters/yaml.rb @@ -1,9 +1,11 @@ class Warren::Queue @@connection = nil + # Raised if no connection has been defined yet. class NoConnectionDetails < Exception end + # Raised if a block is expected by the method but none is given. class NoBlockGiven < Exception end @@ -13,10 +15,14 @@ class Warren::Queue self.connection = params end + # Sets the connection details def self.connection= params @@connection = params.is_a?(Warren::Connection) ? params : Warren::Connection.new(params) 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." @@ -56,6 +62,8 @@ class Warren::Queue # # Warren::Queue.subscribe("example") {|msg| puts msg } # + # Expects a block and raises NoBlockGiven if no block is given. + # def self.subscribe queue_name, &block raise NoBlockGiven unless block_given? queue_name = self.connection.queue_name if queue_name == :default lib/warren/queue.rb @@ -1,5 +1,11 @@ = Warren +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/ + == Released under the MIT Licence Copyright (c) 2008 Brightbox Systems Ltd readme.rdoc @@ -1,7 +1,7 @@ require "rake/rdoctask" Rake::RDocTask.new do |rd| - rd.main = "warren.rb" - rd.rdoc_files.include("warren.rb", "lib/*.rb", "examples/*.rb") + rd.main = "lib/warren.rb" + rd.rdoc_files.include("lib/**/*.rb") rd.rdoc_dir = "doc" end tasks/rdoc.rake ea3c40dc5f86a50ca18b3d7829b063bb89e2f0e7 Caius Durling dev@caius.name http://github.com/brightbox/warren/commit/e271472793ae76a289be9e38a93fca76c423cc26 e271472793ae76a289be9e38a93fca76c423cc26 2009-03-13T09:39:51-07:00 2009-03-13T09:39:51-07:00 Adding documentation bd735912c64b82c43a29a5c27066617b547dc624 Caius Durling dev@caius.name