Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Adding documentation

  • Loading branch information...
commit e271472793ae76a289be9e38a93fca76c423cc26 1 parent ea3c40d
@caius caius authored
View
11 lib/warren.rb
@@ -2,7 +2,18 @@
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__), ".."))
View
10 lib/warren/connection.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 @@ def initialize opts = {}
@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 @@ def options
}
end
+ # Raised if connection details are missing or invalid
+ # Check the error message for more details
class InvalidConnectionDetails < Exception
end
end
View
29 lib/warren/message_filter.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 @@ class MessageFilter
# 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 @@ def self.filters
@@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 @@ def self.pack msg
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}"
View
33 lib/warren/message_filters/shared_secret.rb
@@ -7,23 +7,46 @@
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 @@ def self.pack msg
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
View
5 lib/warren/message_filters/yaml.rb
@@ -2,16 +2,19 @@
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
View
8 lib/warren/queue.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 @@ def self.set_connection params
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 @@ def self.publish queue_name, payload, &blk
#
# 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
View
6 readme.rdoc
@@ -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
View
4 tasks/rdoc.rake
@@ -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
Please sign in to comment.
Something went wrong with that request. Please try again.