agni 0.0.3

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+# Gem's dependencies are in messenger.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,33 @@
+Copyright (c) 2012-2013, ApartmentList
+All rights reserved.
+
+This software is made available under the terms of the three-clause
+BSD license:
+
+http://opensource.org/licenses/BSD-3-Clause
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.  Neither the name 'ApartmentList' nor the names of
+    its contributors may be used to endorse or promote products
+    derived from this software without specific prior written
+    permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,120 @@
+# Agni
+
+## Introduction
+
+Agni is a gem that wraps around the Ruby AMQP gem that provides
+a very simple API for publishing and subscribing to messages.
+
+### Simple
+You'll need only two things to make use of Agni:
+ - The URL to an AMQP instance
+ - The name of a queue that you'll be writing to and/or reading from
+
+That's it!
+
+If you know a lot about AMQP, you'll notice that the use cases for
+this class remove the notion of channels, consumers, exchanges,
+bindings, routes, route keys and other primitives used by AMQP.  This
+is intentional; the goal of Agni is to provide the simplest
+useful API for messaging.  That API is subject to change to the extent
+it stays in line with the original design goals.
+
+### Each message is consumed exactly once
+
+Agni is designed for a simple, but very useful, configuration
+of AMQP that is designed to allow 1:1, 1:n and m:n configurations for
+message passing between Ruby VMs running across many machines.
+
+One guiding principle of this queue is that each message will only
+ever be consumed once.  There are use cases where that behavior is not
+desirable, and for those use cases Agni should be specialized or
+another approach should be used altogether.
+
+Another guiding principle is that messages should be durable; that is,
+they should survive the restart of the AMQP infrastructure.
+Similarly, messages require acknowledgment.  Agni takes care of
+this for you, but it means that if your receiving code throws an
+exception or crashes before it gets a chance to process the exception
+fully, it will be re-queued for later processing.
+
+### Prioritization
+
+One of the main features of Agni is that it supports a form of
+message prioritization.  This allows systems that experience bursty
+message traffic to remain responsive by prioritizing messages that
+can't wait for every message ahead of them to be processed.  See below
+for examples of prioritization.
+
+Currently, Agni supports priority levels 0 through 9 (inclusive),
+with 0 being the highest priority.  There's nothing inherent in
+Agni's architecture that limits it to 10 priority levels, but we
+haven't needed more than that, yet. =)
+
+### Example uses
+
+One example use case of Agni is to deliver data between stages of a
+backend application (for example, data retrieval and data processing).
+Each Ruby VM that wants to participate can instantiate an Agni
+messenger with the same AMQP URL and all publish/subscribe to the same
+queue name.
+
+Agni could also conceivably be used to push messages onto queues
+that represent units of work that need to be performed, allowing for
+an arbitrary number of requesters and workers to broker work via a
+single queue.
+
+Another use case would utilize Agni to create a scalable,
+asynchronous messaging architecture, allowing many components spanning
+a dozen services to communicate exclusively via various Agni
+queues to schedule work, report status, update data, and collect
+metrics.  Agni should, even in its current humble state, support
+such a use case.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'messenger'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install messenger
+
+## Usage
+
+If you're running an AMQP instance locally for testing, try the following.
+
+Set up a subscriber:
+
+    require 'messenger'
+    m = Agni::Messenger.new('amqp://localhost')
+    m.subscribe('test_queue') {|m,p| printf p}
+
+Set up a publisher (in another Ruby instance, on another machine, etc.):
+
+    require 'messenger'
+    m = Agni::Messenger.new('amqp://localhost')
+
+It's easy to send some messages.  If you don't specify a priority,
+they will default to a priority of 4.
+
+    1.upto(100).each{|n| m.publish("test#{n}", 'test_queue')}
+
+It's equally easy to specify a priority.  This will add 100,000
+messages evenly across all 10 priorities.  If you have e.g. a RabbitMQ
+dashboard handy, you can watch as the queues get emptied in priority
+order.
+
+    1.upto(100000).each{|n| m.publish("test#{n}", 'test_queue', n%10)}
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/agni.gemspec

@@ -0,0 +1,29 @@
+# -*- mode: ruby; encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'agni/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "agni"
+  gem.version       = Agni::VERSION
+  gem.authors       = ["Rick Dillon"]
+  gem.email         = ["rpdillon@apartmentlist.com"]
+  gem.description   = %q{A wrapper around the AMQP gem to support easy messaging between applications.}
+  gem.summary       = %q{Easy RabbitMQ Messaging}
+  gem.license       = '3-Clause BSD'
+  gem.homepage      = "https://github.com/apartmentlist/agni"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency('rake')
+  gem.add_dependency('amqp')
+  gem.add_dependency('algorithms')
+  gem.add_dependency('log_mixin')
+
+  gem.add_development_dependency('rspec')
+  gem.add_development_dependency('pry')
+  gem.add_development_dependency('mocha')
+end

data/lib/agni.rb

@@ -0,0 +1,29 @@
+require 'log_mixin'
+require 'amqp'
+require 'algorithms'
+require 'agni/version'
+require 'agni/queue'
+require 'agni/messenger'
+require 'agni/agni_error'
+
+module Agni
+  # Enforce durability-by-default at the queue and message level
+  DEFAULT_QUEUE_OPTS = {durable: true}.freeze
+  DEFAULT_MESSAGE_OPTS = {persistent: true}.freeze
+  DEFAULT_CHANNEL_OPTS = {
+    auto_recovery: true,
+  }.freeze
+  DEFAULT_CONNECTION_OPTS = {
+    auto_recovery: true,
+    # Log cases in which we're unexpectedly disconnected from the server
+    on_tcp_connection_failure: ->{ warning("TCP connection failure detected") }
+  }
+  # Each logical queue has 10 AMQP queues backing it to support
+  # prioritization.  Those priorities are numbered 0 (highest)
+  # through 9 (lowest).
+  PRIORITY_LEVELS = (0..9).to_a.freeze
+  # To allow room above and below the default, we put it in the middle
+  DEFAULT_PRIORITY = 4
+  DEFAULT_PREFETCH = 50
+  DEFAULT_THREADPOOL_SIZE = 5
+end

data/lib/agni/agni_error.rb

@@ -0,0 +1,9 @@
+module Agni
+
+  # Error class used to denote error conditions specific to the
+  # agni infrastructure, and not those due to, for example,
+  # missing arguments.
+  class AgniError < StandardError
+  end
+
+end

data/lib/agni/messenger.rb

@@ -0,0 +1,191 @@
+module Agni
+  class Messenger
+    include LogMixin
+
+    attr_reader :connection
+
+    # Creates a Messenger, connecting to the supplied URL.
+    #
+    # @param amqp_url [String] the url to the AMQP instance this
+    #   Messenger should connect to.  Should begin with 'amqp://'.
+    def initialize(amqp_url)
+      if amqp_url.nil? || amqp_url.empty?
+        raise ArgumentError, "AMQP url is required to create a Messenger"
+      end
+      self.configure_logs
+      # Start EventMachine if needed
+      unless EventMachine.reactor_running?
+        @em_thread = Thread.new { EventMachine.run }
+      end
+
+      # Block until EventMachine has started
+      info("Waiting for EventMachine to start")
+      spin_until { EventMachine.reactor_running? }
+      info("EventMachine start detected")
+
+      EventMachine.threadpool_size = ENV.fetch('EM_THREADPOOL_SIZE', DEFAULT_THREADPOOL_SIZE).to_i
+
+      unless @connection = AMQP.connect(amqp_url, DEFAULT_CONNECTION_OPTS)
+        raise AgniError, "Unable to connect to AMQP instance at #{amqp_url}"
+      end
+
+      # A hash which maps queue names to Agni::Queue objects.
+      # Tracks what queues we have access to.
+      @queues = {}
+    end
+
+    # Gets a queue with the given options.  If no options are
+    # provided, a default set of options will be used that makes the
+    # queue save its messages to disk so that they won't be lost if
+    # the AMQP service is restarted.
+    #
+    # @return [Agni::Queue] the queue with the provided name
+    # @raise ArgumentError if the queue name is not provided
+    # @raise AgniError if the queue has already been created with
+    #        an incompatible set of options.
+    def get_queue(queue_name, options={})
+      @queues.fetch(queue_name) do |queue_name|
+        queue = Queue.new(queue_name, self, options)
+        @queues[queue_name] = queue
+      end
+    end
+
+    # @return [TrueClass, FalseClass] whether or not a queue with the
+    #   given name is known to this Messenger instance.
+    def queue?(queue_name)
+      @queues.key?(queue_name)
+    end
+
+    # Get and return the number of messages in a given queue.
+    #
+    # @param queue_name [String] the name of the queue for which the
+    #   the message count should be fetched.
+    # @return [Fixnum] the number of messages in the queue with
+    #   provided queue name.  If the queue is not yet created, the
+    #   method will return +nil+.
+    # @raise ArgumentError if the queue_name is not supplied
+    def queue_messages(queue_name)
+      get_queue(queue_name).message_count if queue?(queue_name)
+    end
+
+    # @param queue_name [String] the name of the queue for which the
+    #   the consumer count should be fetched.
+    # @return [Fixnum] the number of consumers for the queue with
+    #   provided queue name.  If the queue is not yet created, it will
+    #   be created when this method is called.
+    # @raise ArgumentError if the queue_name is not supplied
+    def queue_consumers(queue_name)
+      get_queue(queue_name).consumer_count if queue?(queue_name)
+    end
+
+    # Convenience method that publishes a message to the given queue
+    # name.
+    #
+    # One of the main uses of the options hash is to specify a message
+    # priority between 0 and 9:
+    #
+    #    messenger.publish("Hello World", "test_queue", priority: 7)
+    #
+    # But the default priority is 4, so this would be published with a
+    # priority of 4:
+    #
+    #    messenger.publish("Hello World", "test_queue")
+    #
+    # @param msg [String] the message to enqueue
+    # @param queue_name [String] the name of the queue to publish to
+    # @param options [Hash] optional -- options that will be passed to
+    #   the underlying AMQP queue during publishing.  All keys should
+    #   be symbols.
+    # @option :priority [FixNum] the priority of the message
+    #   0(high) - 9(low)
+    def publish(msg, queue_name, options={})
+      priority = options.delete(:priority) || DEFAULT_PRIORITY
+      get_queue(queue_name).publish(msg, priority, options)
+    end
+
+    # @note The block passed to this method must not block, since it
+    #   will be run in a single-threaded context.
+    #
+    # Convenience method that takes a queue name (creating the queue
+    # if necessary) and accepts a block that it will yield to for each
+    # incoming message.  The block passed in to this method should
+    # accept two arguments: the metadata of the message being
+    # received, as well as the payload of the message.
+    #
+    # This method is non-blocking, and if at any time the Messenger
+    # should no longer yield to the provided block when new messages
+    # arrive, the +unsubscribe+ method can be called on the Messenger
+    # and given the queue name to unsubscribe from.
+    #
+    # If no block is passed to this method, it will simply subscribe
+    # to the queue and drain it of messages as they come in.
+    #
+    # To prevent lossage, this method will set up the subscription
+    # with the AMQP server to require acking of the messages by the
+    # client.  As far as the end user is concerned, this means that if
+    # the messenger dies an untimely death, any unprocessed messages
+    # that remained in the buffer will be requeued on the server.
+    # Messenger will take care of the acking for the user, unless an
+    # option is passed to indicate that the user will handle acking in
+    # the provided block.
+    #
+    # @param queue_name [String] The name of the queue that should be
+    #        examined for messages
+    # @param options [Hash] (optional) A hash of options
+    # @option options [TrueClass, FalseClass] :ack Whether messenger
+    #         should ack incoming messages for this subscription.  If
+    #         set to +false+, the block passed to this method must ack
+    #         messages when they have been processed.  Defaults to
+    #         +true+.
+    # @yield handler [metadata, payload] a block that handles the incoming message
+    # @return [Agni::Queue] the queue that has been subscribed
+    def subscribe(queue_name, options={}, &handler)
+      if queue_name.nil? || queue_name.empty?
+        raise ArgumentError, 'Queue name must be present when subscribing'
+      end
+      queue = get_queue(queue_name)
+      if queue.subscribed?
+        raise AgniError, "Queue #{queue_name} is already subscribed!"
+      end
+      queue.subscribe(handler, options)
+      # spin_until { queue.subscribed?  }
+    end
+
+    # Unsubscribe this messenger from the queue associated with the
+    # given name.
+    #
+    # @raise ArgumentError if the queue name is empty
+    # @raise AgniError if the queue does not exist
+    def unsubscribe(queue_name)
+      if queue_name.nil? || queue_name.empty?
+        raise ArgumentError, 'Queue name must be present when unsubscribing'
+      end
+      if queue = get_queue(queue_name)
+        queue.unsubscribe
+      end
+    end
+
+    # This method allows a client of the messenger to block on the
+    # execution of the EventMachine, so it can run in a context that
+    # is dedicated to running for the purpose of receiving messages.
+    def wait
+      @em_thread.join
+    end
+
+    # Returns +true+ if the messenger is connected to AMQP, +false+
+    # otherwise.
+    def connected?
+      return @connection.connected?
+    end
+
+    private
+
+   def spin_until
+      while not yield
+        sleep(0.1)
+      end
+    end
+
+  end
+
+end

data/lib/agni/queue.rb

@@ -0,0 +1,152 @@
+module Agni
+  class Queue
+    include LogMixin
+
+    # Core method responsible for catching queue name problems, like
+    # nil values and empty strings.
+    #
+    # @param queue_name [String] the name of this queue
+    # @param messenger [Agni::Messenger] the messenger object
+    #   with which this queue is associated
+    # @param options [Hash] options that will be passed to the AMQP
+    #   gem during queue creation
+    def initialize(queue_name, messenger, options={})
+      if queue_name.nil? || queue_name.empty?
+        raise ArgumentError, 'Queue name must be present when creating a queue'
+      end
+      self.configure_logs
+      @logical_queue_name = queue_name
+
+      begin
+        @queues = PRIORITY_LEVELS.map do |priority|
+          create_queue(messenger, priority, options)
+        end
+      rescue AMQP::IncompatibleOptionsError
+        raise AgniError,
+        "One of the queues needed to create #{@logical_queue_name} " +
+          "has already been created with different options!"
+      end
+
+      # The in-memory queue we use to prioritize incoming messages of
+      # different priorities
+      @queue_mutex = Mutex.new
+      @memory_queue = Containers::MinHeap.new
+    end
+
+    # Subscribes to this queue, handling each incoming message with
+    # the provided +handler+.
+    # @param handler [Proc] accepts two arguments:
+    #   metadata [Hash] a hash of attributes as it is provided by the
+    #   underlying AMQP implementation.
+    #   payload [String] the message itself, as was provided by the
+    #   publisher
+    #   The return value from the handler will be discarded.
+    def subscribe(handler, options={})
+      if subscribed?
+        raise AgniError, 'Queue #{queue_name} is already subscribed'
+      end
+      ack = options[:ack].nil? ? true : options[:ack]
+      handle_func = lambda do
+        metadata, payload = pop
+        handler[metadata, payload] if handler
+        EventMachine.next_tick{ metadata.ack } if ack
+      end
+      @queues.each do |q|
+        queue = q[:queue]
+        priority = q[:priority]
+        queue.subscribe(:ack => true) do |metadata, payload|
+          @queue_mutex.synchronize do
+            @memory_queue.push(priority, [metadata, payload])
+          end
+          EventMachine.next_tick { EventMachine.defer(handle_func) }
+        end
+      end
+      self
+    end
+
+    def unsubscribe
+      unless subscribed?
+        raise AgniError, 'Queue #{queue_name} is not subscribed'
+      end
+      @queues.each do |q|
+        q[:queue].unsubscribe
+      end
+    end
+
+    # @return [True] iff every AMQP queue is +subscribed+?
+    def subscribed?
+      @queues.map{|q| q[:queue].default_consumer}.all?{|c| c.subscribed? if c}
+    end
+
+    # Publishes a payload to this queue.
+    #
+    # @param payload [String] the payload of the message to publish
+    # @param priority [FixNum] must be one between 0 and 9, inclusive.
+    # @param options [Hash]
+    def publish(payload, priority=DEFAULT_PRIORITY, options={})
+      unless PRIORITY_LEVELS.include? priority
+        raise ArgumentError, "Invalid priority #{priority}, must be between 0 and 9"
+      end
+      queue_name = create_queue_name(@logical_queue_name, priority)
+      @queues[priority][:exchange].publish(payload, DEFAULT_MESSAGE_OPTS.merge(options).
+                                           merge(:routing_key => queue_name))
+    end
+
+    # Given a base name and a priority, creates a queue name suitable
+    # for use in naming an underlying AMQP queue.
+    #
+    # @param base_name [String] the base name of the queue.  This is
+    #   typcially just the queue name used when creating this
+    #   +Agni::Queue+ object.
+    # @param priority [String] valid priorities are in the range 0
+    #   through 9 inclusive.
+    def create_queue_name(base_name, priority)
+      "#{base_name}.#{priority}"
+    end
+
+    private
+
+    # Internal use utility method to create queue hashes.  No checking
+    # is performed to ensure that the queue does not already exist,
+    # for example.  Its only use right now is during initialization of
+    # the Agni::Queue class.
+    def create_queue(messenger, priority, options)
+      name = create_queue_name(@logical_queue_name, priority)
+      unless channel = AMQP::Channel.new(messenger.connection,
+                                         DEFAULT_CHANNEL_OPTS.
+                                         merge({prefetch: DEFAULT_PREFETCH}))
+        raise AgniError,
+        "Unable to obtain a channel from AMQP instance at #{amqp_url}"
+      end
+      # Get a handle to the default exchange. The default exchange
+      # automatically binds messages with a given routing key to a
+      # queue with the same name, eliminating the need to create
+      # specific direct bindings for each queue.
+      queue = channel.queue(name, DEFAULT_QUEUE_OPTS.
+                            merge(options))
+
+      exchange = channel.default_exchange
+      # Each 'queue' in the queue array is a hash.  Here's how each
+      # hash is laid out:
+      {
+        priority:  priority,
+        name:      name,
+        channel:   channel,
+        queue:     queue,
+        exchange:  exchange
+      }
+    end
+
+    # Removes and returns an item from the priority queue in a
+    # thread-safe manner.  Thread safety reasoning: all calls to
+    # shared queue are locked by a single mutex.
+    def pop
+      val = []
+      @queue_mutex.synchronize do
+        val = @memory_queue.pop
+      end
+      val
+    end
+
+  end
+end

data/lib/agni/version.rb

@@ -0,0 +1,3 @@
+module Agni
+  VERSION = "0.0.3"
+end

data/spec/lib/messenger_spec.rb

@@ -0,0 +1,142 @@
+require 'agni'
+require 'spec_helper'
+
+describe Agni::Messenger do
+  let (:amqp_url) { "amqp://localhost" }
+  # An Agni object using mocked AMQP methods
+  let (:connection) { mock('connection') }
+  let (:channel) { mock('channel') }
+  let (:exchange) { mock('exchange') }
+  let (:messenger) {
+    EventMachine.stubs(:reactor_running?).returns(true)
+    AMQP.expects(:connect).with(amqp_url, is_a(Hash)).returns(connection)
+    Agni::Messenger.new(amqp_url)
+  }
+
+  describe 'construction' do
+    it 'should create a connection, channel and exchange on instantiation' do
+      messenger.class.should == Agni::Messenger
+    end
+
+    it 'should throw an exception given a blank url' do
+      lambda{Agni::Messenger.new('')}.should raise_error(ArgumentError)
+    end
+
+    it 'should set the EventMachine threadpool size from the environment' do
+      ENV['EM_THREADPOOL_SIZE'] = '13'
+      EventMachine.expects(:threadpool_size=).with(13)
+      m = messenger
+      ENV.delete('EM_THREADPOOL_SIZE')
+    end
+
+    it 'should use a default threadpool size if the env var is not set' do
+      ENV['EM_THREADPOOL_SIZE'].should == nil
+      EventMachine.expects(:threadpool_size=).with(Agni::DEFAULT_THREADPOOL_SIZE)
+      m = messenger
+    end
+  end
+
+  describe 'get_queue' do
+
+    it 'should raise an error if the queue name is blank' do
+      lambda{ messenger.get_queue('') }.should raise_error(ArgumentError)
+    end
+
+    it 'should create the queue on the channel' do
+      queue_name = 'test_queue'
+      Agni::Queue.stubs(:new).with(queue_name,
+                                        is_a(Agni::Messenger),
+                                        {})
+      messenger.get_queue(queue_name)
+    end
+
+    it 'should not create the queue if it exists' do
+      queue_name = "test_queue"
+      queues = messenger.instance_variable_get(:@queues)
+      queues[queue_name] = mock
+      Agni::Queue.expects(:new).never
+      messenger.get_queue(queue_name)
+    end
+
+    it "should create the queue if it doesn't exist" do
+      queue_name = 'test_queue'
+      Agni::Queue.expects(:new).with(queue_name,
+                                        is_a(Agni::Messenger),
+                                        {})
+      messenger.get_queue(queue_name)
+    end
+
+  end
+
+  describe 'publish' do
+    let (:queue_name) { "test_queue" }
+    let (:message)    { "test message" }
+
+    it 'should raise an error when attempting to publish to a nameless queue' do
+      lambda {messenger.publish(message, '')}.should raise_error(ArgumentError)
+    end
+
+    context 'with good data' do
+
+      it 'should create a queue and publish to it' do
+        queue_name = 'test_queue'
+        queue = mock('queue')
+        queue.expects(:publish).with(message, Agni::DEFAULT_PRIORITY, {})
+        messenger.expects(:get_queue).with(queue_name).returns(queue)
+        messenger.publish(message, queue_name)
+      end
+
+      it 'should pass custom headers to queue object' do
+        test_headers = {:headers => {:operation => "TEST_OPERATION"}}
+        queue = mock('queue')
+        queue.expects(:publish).with(message, Agni::DEFAULT_PRIORITY, test_headers)
+        messenger.expects(:get_queue).with(queue_name).returns(queue)
+        messenger.publish(message, queue_name, options=test_headers)
+      end
+
+    end
+  end
+
+  describe 'subscribe and unsubscribe' do
+    it 'should raise an error if attempting to subscribe to a nameless queue' do
+      lambda{messenger.subscribe('')}.should raise_error(ArgumentError)
+    end
+
+    it 'should raise an error if attempting to subscribe to a nil queue' do
+      lambda{messenger.subscribe}.should raise_error(ArgumentError)
+    end
+
+    it 'should raise an error if attempting to unsubscribe from a nameless queue' do
+      lambda{messenger.unsubscribe('')}.should raise_error(ArgumentError)
+    end
+
+    it 'should raise an error if attempting to unsubscribe from a nil queue' do
+      lambda{messenger.unsubscribe}.should raise_error(ArgumentError)
+    end
+
+    context 'with good data' do
+      let (:queue_name) { 'test_queue' }
+      let (:queue)      { mock('queue') }
+
+      it 'should should subscribe to the queue associated with the queue name provided' do
+        queue.expects(:subscribed?).returns(false)
+        queue.expects(:subscribe).with(is_a(Proc), is_a(Hash))
+        messenger.expects(:get_queue).with(queue_name).returns(queue)
+        messenger.subscribe(queue_name) { |m,p| puts 'ohai'}
+      end
+
+      it 'should unsubscribe from a subscribed queue' do
+        queue.expects(:unsubscribe)
+        messenger.expects(:get_queue).with(queue_name).returns(queue)
+        messenger.unsubscribe(queue_name)
+      end
+
+      it 'should not attempt to unsubscribe from a queue that does not exist' do
+        messenger.expects(:get_queue).with(queue_name).returns(nil)
+        messenger.unsubscribe(queue_name)
+      end
+
+    end
+  end
+
+end

data/spec/lib/queue_spec.rb

@@ -0,0 +1,116 @@
+require 'agni'
+require 'pry'
+require 'spec_helper'
+
+describe Agni::Queue do
+
+  let (:channel) { mock('channel') }
+  let (:connection) { mock('connection') }
+  let (:messenger) do
+    mock('messenger').tap do |m|
+      m.stubs(:channel).returns(channel)
+      m.stubs(:connection).returns(connection)
+    end
+  end
+  let (:channel) { mock('channel') }
+  let (:exchange) { mock('exchange') }
+  let (:amqp_queue) { mock('amqp_queue') }
+  let (:queue_name) { 'test_queue' }
+  let (:queue) do
+    AMQP::Channel.stubs(:new).returns(channel)
+    channel.stubs(:default_exchange).returns(exchange)
+    channel.expects(:queue).times(Agni::PRIORITY_LEVELS.size)
+    Agni::Queue.new(queue_name, messenger)
+  end
+
+  describe :initialize do
+    it 'should raise an exeception if a the queue name is nil' do
+      lambda { Agni::Queue.new(nil, messenger) }.should raise_exception(ArgumentError)
+    end
+
+    it 'should construct an AMQP queue for each priority level' do
+      queue
+    end
+  end
+
+  describe :subscribe do
+    it 'should raise an exception if the queue is already subscribed' do
+      queue.expects(:subscribed?).returns(true)
+      lambda { queue.subscribe(nil) }.should raise_exception(Agni::AgniError)
+    end
+
+    it 'should invoke subscribe for each queue' do
+      queue.expects(:subscribed?).returns(false)
+      mock_queues = (0..9).map do |n|
+        {:queue =>
+          mock("mockqueue-#{n}").tap do |q|
+            q.expects(:subscribe).with(is_a(Hash))
+          end,
+          :priority => n
+        }
+      end
+      queue.instance_variable_set(:@queues, mock_queues)
+      test_handler = lambda {}
+      queue.subscribe(test_handler)
+    end
+  end
+
+  describe :unsubscribe do
+    it 'should raise an exception if the queue is not subscribed' do
+      queue.expects(:subscribed?).returns(false)
+      lambda { queue.unsubscribe }.should raise_exception(Agni::AgniError)
+    end
+  end
+
+  describe :subscribed? do
+    it 'should return true if all consumers are subscribed' do
+      mock_queues = (0..9).map do |n|
+        {:queue =>
+          mock("mockqueue-#{n}").tap do |q|
+            consumer = mock("mockconsumer-#{n}").tap do |c|
+              c.expects(:subscribed?).returns(true)
+            end
+            q.expects(:default_consumer).returns(consumer)
+          end
+        }
+      end
+      queue.instance_variable_set(:@queues, mock_queues)
+      queue.subscribed?.should be_true
+    end
+
+    it 'should return false if one consumer is not subscribed' do
+      mock_queues = (0..9).map do |n|
+        {:queue =>
+          mock("mockqueue-#{n}").tap do |q|
+            consumer = mock("mockconsumer-#{n}").tap do |c|
+              c.expects(:subscribed?).returns(n == 9 ? false : true)
+            end
+            q.expects(:default_consumer).returns(consumer)
+          end
+        }
+      end
+      queue.instance_variable_set(:@queues, mock_queues)
+      queue.subscribed?.should be_false
+    end
+  end
+
+  describe :publish do
+    it 'should raise and exception if the priority is out of range' do
+      lambda { queue.publish('test', 11)}.should raise_exception(ArgumentError)
+    end
+
+    it 'should publish only to the proper priority level' do
+      mock_queues = (0..9).map do |n|
+        {:exchange => mock("mockexchange-#{n}")}
+      end
+      test_priority = 7
+      mock_queues[test_priority][:exchange].expects(:publish).with("Hello", is_a(Hash))
+      ((0..9).to_a - [test_priority]).each do |n|
+        mock_queues[n][:exchange].expects(:publish).never
+      end
+      queue.instance_variable_set(:@queues, mock_queues)
+      queue.publish("Hello", test_priority)
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+RSpec.configure do |config|
+  config.mock_with :mocha
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: agni
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+  prerelease: 
+platform: ruby
+authors:
+- Rick Dillon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &5495860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *5495860
+- !ruby/object:Gem::Dependency
+  name: amqp
+  requirement: &5495260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *5495260
+- !ruby/object:Gem::Dependency
+  name: algorithms
+  requirement: &5510580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *5510580
+- !ruby/object:Gem::Dependency
+  name: log_mixin
+  requirement: &5509260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *5509260
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &5507900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *5507900
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: &5506460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *5506460
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: &5505340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *5505340
+description: A wrapper around the AMQP gem to support easy messaging between applications.
+email:
+- rpdillon@apartmentlist.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- agni.gemspec
+- lib/agni.rb
+- lib/agni/agni_error.rb
+- lib/agni/messenger.rb
+- lib/agni/queue.rb
+- lib/agni/version.rb
+- spec/lib/messenger_spec.rb
+- spec/lib/queue_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/apartmentlist/agni
+licenses:
+- 3-Clause BSD
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Easy RabbitMQ Messaging
+test_files:
+- spec/lib/messenger_spec.rb
+- spec/lib/queue_spec.rb
+- spec/spec_helper.rb