amqp-boilerplate 0.0.1 → 0.0.2

data/.gitignore

@@ -3,5 +3,7 @@
 *.swp
 .bundle
 .rvmrc
+.yardoc
+doc/*
 Gemfile.lock
 pkg/*

data/amqp-boilerplate.gemspec

@@ -22,5 +22,6 @@ Gem::Specification.new do |s|
   # specify any dependencies here; for example:
   s.add_development_dependency "rake", "~> 0.9"
   s.add_development_dependency "rspec", "~> 2.6"
+  s.add_development_dependency "yard", "~> 0.7"
   s.add_runtime_dependency "amqp", "~> 0.8"
 end

data/lib/amqp/boilerplate/consumer.rb

@@ -5,6 +5,7 @@ module AMQP
         def amqp_queue(name=AMQ::Protocol::EMPTY_STRING, options={})
           @queue_name = name
           @queue_options = options
+          AMQP::Boilerplate.register_consumer(self)
         end
 
         def amqp_subscription(options={})
@@ -19,6 +20,8 @@ module AMQP
 
           queue = channel.queue(@queue_name, @queue_options)
           queue.subscribe(@subscription_options, &consumer.method(:handle_message))
+
+          AMQP::Boilerplate.logger.info("[#{self.name}.start] Started consumer '#{self.name}'")
         end
       end
 

data/lib/amqp/boilerplate/consumer_registry.rb

@@ -0,0 +1,32 @@
+module AMQP
+  module Boilerplate
+    module ConsumerRegistry
+      attr_writer :consumer_paths
+
+      def consumer_paths
+        @consumer_paths ||= []
+      end
+
+      def load_consumers
+        consumer_paths.each do |dir|
+          Dir[File.join(dir, "*.rb")].each {|f| require f}
+        end
+      end
+
+      def registry
+        @registry ||= []
+      end
+
+      def register_consumer(klass)
+        AMQP::Boilerplate.logger.info("[#{self.name}#register_consumer] Registered consumer '#{klass.name}'")
+        registry << klass
+      end
+
+      def start_consumers
+        registry.each do |consumer|
+          consumer.start
+        end
+      end
+    end
+  end
+end

data/lib/amqp/boilerplate/producer.rb

@@ -1,32 +1,84 @@
 module AMQP
   module Boilerplate
+    # Use this module to turn a class into a potential producer that can
+    # deliver messages to an AMQP exchange.
+    #
+    # @example Getting started
+    #   class MyProducer
+    #     extend AMQP::Boilerplate::Producer
+    #
+    #     amqp :routing_key => "hello.world"
+    #     amqp_message :message
+    #
+    #     def message
+    #       "Look! I am a string that will be posted to the exchange."
+    #     end
+    #   end
+    #
+    # @example Configuring exchange
+    #   class MyProducer
+    #     extend AMQP::Boilerplate::Producer
+    #
+    #     amqp :routing_key => "hello.world"
+    #     amqp_exchange :fanout, "amq.fanout", :durable => true
+    #     amqp_message :message
+    #
+    #     def message
+    #       "Look! I am a string that will be posted to the exchange."
+    #     end
+    #   end
     module Producer
-      def amqp(options={})
+      # Macro that sets up amqp for a class.
+      #
+      # @param [Hash] opts Options that will be passed to +AMQP::Exchange#publish
+      # @return [void]
+      def amqp(opts={})
         send :include, InstanceMethods
-        @amqp_boilerplate_options = options
+        @amqp_boilerplate_options = opts
       end
 
-      def amqp_exchange(type=:direct, name=AMQ::Protocol::EMPTY_STRING, options={})
-        @amqp_boilerplate_exchange = [type, name, options]
+      # Configuration for the exchange to be used
+      #
+      # @param [Symbol] type Exchange type
+      # @param [String] name Exchange name
+      # @param [Hash] opts a customizable set of options
+      # @see AMQP::Exchange#initialize
+      # @return [void]
+      def amqp_exchange(type=:direct, name=AMQ::Protocol::EMPTY_STRING, opts={})
+        @amqp_boilerplate_exchange = [type, name, opts]
       end
 
+      # Choose the method that will return the actual message (payload) to be
+      # delivered to the exchange
+      #
+      # This method SHOULD return a string.
+      #
+      # @param [Symbol] method_name Name of method that generates message
+      # @return [void]
       def amqp_message(method_name)
         @amqp_boilerplate_message = method_name
       end
 
+      # TODO Can we do this in a nicer way?
       def amqp_boilerplate_options
         @amqp_boilerplate_options
       end
 
+      # TODO Can we do this in a nicer way?
       def amqp_boilerplate_exchange
         @amqp_boilerplate_exchange || amqp_exchange
       end
 
+      # TODO Can we do this in a nicer way?
       def amqp_boilerplate_message
         @amqp_boilerplate_message
       end
 
       module InstanceMethods
+        # Publishes a message to the exchange
+        #
+        # @see AMQP::Exchange#publish
+        # @return [void]
         def publish
           message = send(self.class.amqp_boilerplate_message.to_sym)
           exchange.publish(message, self.class.amqp_boilerplate_options) do
@@ -36,6 +88,11 @@ module AMQP
 
       private
 
+        # Instantiates a new exchange, additional configuration can be given
+        # through the +amqp_exchange+ class macro.
+        #
+        # @see AMQP::Exchange#initialize
+        # @return [AMQP::Exchange]
         def exchange
           AMQP::Exchange.new(AMQP.channel, *self.class.amqp_boilerplate_exchange)
         end

data/lib/amqp/boilerplate/version.rb

@@ -1,5 +1,5 @@
 module AMQP
   module Boilerplate
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

data/lib/amqp/boilerplate.rb

@@ -1,17 +1,61 @@
 require 'amqp'
+require 'amqp/utilities/event_loop_helper'
 
 require 'amqp/boilerplate/version'
 
 require 'amqp/boilerplate/consumer'
+require 'amqp/boilerplate/consumer_registry'
 require 'amqp/boilerplate/logging'
 require 'amqp/boilerplate/producer'
 
 module AMQP
   module Boilerplate
+    extend ConsumerRegistry
     extend Logging
 
+    def self.boot
+      if defined?(PhusionPassenger)
+        PhusionPassenger.on_event(:starting_worker_process) do |forked|
+          if forked
+            amqp_thread = Thread.new {
+              AMQP::Boilerplate.start
+            }
+            amqp_thread.abort_on_exception = true
+          end
+        end
+      else
+        AMQP::Utilities::EventLoopHelper.run do
+          AMQP::Boilerplate.start
+        end
+      end
+
+      sleep(0.25)
+
+      AMQP::Boilerplate.logger.info("[#{self.name}.boot] Started AMQP (Server Type: #{AMQP::Utilities::EventLoopHelper.server_type})")
+
+      EventMachine.next_tick do
+        AMQP.channel ||= AMQP::Channel.new(AMQP.connection)
+
+        load_consumers
+        start_consumers
+      end
+    end
+
+    # TODO Documentation!
     def self.configure
       yield self if block_given?
     end
+
+    def self.connection_options
+      @connection_options
+    end
+
+    def self.connection_options=(options)
+      @connection_options = options
+    end
+
+    def self.start
+      AMQP.start self.connection_options
+    end
   end
 end

data/spec/amqp/boilerplate/consumer_registry_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe AMQP::Boilerplate::ConsumerRegistry do
+  before(:each) do
+    AMQP::Boilerplate.stub(:logger).and_return(mock.as_null_object)
+  end
+
+  describe "#consumer_paths" do
+    it "should be an Array" do
+      AMQP::Boilerplate.consumer_paths.should be_an(Array)
+    end
+
+    it "should always return the same Array" do
+      consumer_paths = AMQP::Boilerplate.consumer_paths
+      AMQP::Boilerplate.consumer_paths.should equal(consumer_paths)
+    end
+
+    it "should default to an empty Array" do
+      AMQP::Boilerplate.consumer_paths.should be_empty
+    end
+  end
+
+  describe "#load_consumers" do
+    before(:each) do
+      AMQP::Boilerplate.stub(:registry).and_return([])
+    end
+
+    it "should require all files in configured consumer_paths" do
+      AMQP::Boilerplate.consumer_paths << File.expand_path(File.join(File.dirname(__FILE__), '..', '..', "fixtures/consumers"))
+
+      defined?(DummyConsumer).should be_nil
+      AMQP::Boilerplate.load_consumers
+      defined?(DummyConsumer).should_not be_nil
+    end
+  end
+
+  describe "#register_consumer" do
+    before(:each) do
+      AMQP::Boilerplate.stub(:registry).and_return(Array.new)
+    end
+
+    it "should call #registry" do
+      AMQP::Boilerplate.should_receive(:registry).once
+      AMQP::Boilerplate.register_consumer(mock.as_null_object)
+    end
+
+    it "should add classes to registry" do
+      expect {
+        AMQP::Boilerplate.register_consumer(mock.as_null_object)
+      }.to change(AMQP::Boilerplate.registry, :size).by(1)
+    end
+  end
+
+  describe "#registry" do
+    it "should return an Array" do
+      AMQP::Boilerplate.registry.should be_an(Array)
+    end
+
+    it "should always return the same array" do
+      registry = AMQP::Boilerplate.registry
+      AMQP::Boilerplate.registry.should equal(registry)
+    end
+  end
+
+  describe "#start_consumers" do
+    it "should call .start on all registered consumer classes" do
+      FooConsumer.should_receive(:start)
+      BarConsumer.should_receive(:start)
+      AMQP::Boilerplate.start_consumers
+    end
+  end
+end

data/spec/amqp/boilerplate/consumer_spec.rb

@@ -1,16 +1,9 @@
 require 'spec_helper'
 
-class DummyConsumer < AMQP::Boilerplate::Consumer
-  amqp_queue "queue.name.here", :durable => true
-  amqp_subscription :ack => true
-end
-
-class FooConsumer < AMQP::Boilerplate::Consumer
-  amqp_queue
-end
-
+# NOTE See spec_helper for Consumer definitions
 describe AMQP::Boilerplate::Consumer do
   before(:each) do
+    AMQP::Boilerplate.stub(:logger).and_return(mock.as_null_object)
     @channel = mock(AMQP::Channel)
     @channel.stub(:on_error).and_return(true)
   end
@@ -21,9 +14,9 @@ describe AMQP::Boilerplate::Consumer do
     end
 
     it "should log the code and message" do
-      AMQP::Boilerplate.logger.should_receive(:error).with("[DummyConsumer#handle_channel_error] Code = #{@channel_close.reply_code}, message = #{@channel_close.reply_text}")
+      AMQP::Boilerplate.logger.should_receive(:error).with("[BarConsumer#handle_channel_error] Code = #{@channel_close.reply_code}, message = #{@channel_close.reply_text}")
 
-      DummyConsumer.new.handle_channel_error(@channel, @channel_close)
+      BarConsumer.new.handle_channel_error(@channel, @channel_close)
     end
   end
 
@@ -58,8 +51,8 @@ describe AMQP::Boilerplate::Consumer do
 
   describe ".start" do
     before(:each) do
-      @consumer = DummyConsumer.new
-      DummyConsumer.stub(:new).and_return(@consumer)
+      @consumer = BarConsumer.new
+      BarConsumer.stub(:new).and_return(@consumer)
 
       AMQP.stub(:channel).and_return(@channel)
 
@@ -70,32 +63,32 @@ describe AMQP::Boilerplate::Consumer do
 
     it "should use a channel" do
       AMQP.should_receive(:channel).and_return(@channel)
-      DummyConsumer.start
+      BarConsumer.start
     end
 
     it "should instantiate a consumer" do
-      DummyConsumer.should_receive(:new).and_return(@consumer)
-      DummyConsumer.start
+      BarConsumer.should_receive(:new).and_return(@consumer)
+      BarConsumer.start
     end
 
     it "should register a channel error handler" do
       @channel.should_receive(:on_error)
-      DummyConsumer.start
+      BarConsumer.start
     end
 
     it "should instantiate a queue with the proper queue name" do
       @channel.should_receive(:queue).with("queue.name.here", anything)
-      DummyConsumer.start
+      BarConsumer.start
     end
 
     it "should instantiate a queue provided with options" do
       @channel.should_receive(:queue).with(anything, :durable => true)
-      DummyConsumer.start
+      BarConsumer.start
     end
 
     it "should subscribe to the queue" do
       @queue.should_receive(:subscribe).with(:ack => true)
-      DummyConsumer.start
+      BarConsumer.start
     end
   end
 end

data/spec/amqp/boilerplate/logging_spec.rb

@@ -9,7 +9,7 @@ describe AMQP::Boilerplate::Logging do
   describe "#logger" do
     it "should set the logger to use" do
       MyLogger = Class.new
-      AMQP::Boilerplate.logger = MyLogger # { |config| config.logger = MyLogger }
+      AMQP::Boilerplate.logger = MyLogger
       AMQP::Boilerplate.logger.should == MyLogger
     end
 

data/spec/amqp/boilerplate/producer_spec.rb

@@ -1,28 +1,6 @@
 require 'spec_helper'
 
-class DummyProducer
-  extend AMQP::Boilerplate::Producer
-
-  amqp :routing_key => "some.routing.key"
-  amqp_exchange :fanout, "amq.fanout", { :durable => true }
-  amqp_message :message
-
-  def message
-    "hello world!"
-  end
-end
-
-class FooProducer
-  extend AMQP::Boilerplate::Producer
-
-  amqp :routing_key => "another.routing.key"
-  amqp_message :some_method
-
-  def some_method
-    'Foo Bar'
-  end
-end
-
+# NOTE See spec_helper for Producer definitions
 describe AMQP::Boilerplate::Producer do
   before(:each) do
     AMQP::Boilerplate.stub(:logger).and_return(mock.as_null_object)
@@ -31,7 +9,7 @@ describe AMQP::Boilerplate::Producer do
     @exchange.stub(:publish).and_yield
     AMQP::Exchange.stub!(:new).and_return(@exchange)
 
-    @producer = DummyProducer.new
+    @producer = BarProducer.new
   end
 
   describe ".amqp_exchange" do
@@ -63,11 +41,11 @@ describe AMQP::Boilerplate::Producer do
     end
 
     it "should pass options to AMQP::Exchange#publish" do
-      DummyProducer.amqp({ :routing_key => "some.routing.key", :mandatory => true })
+      BarProducer.amqp({ :routing_key => "some.routing.key", :mandatory => true })
       @exchange.should_receive(:publish).with(@producer.message, :routing_key => "some.routing.key", :mandatory => true)
       @producer.publish
 
-      DummyProducer.amqp({ :routing_key => "some.routing.key", :mandatory => true, :immediate => true })
+      BarProducer.amqp({ :routing_key => "some.routing.key", :mandatory => true, :immediate => true })
       @exchange.should_receive(:publish).with(@producer.message, :routing_key => "some.routing.key", :mandatory => true, :immediate => true)
       @producer.publish
     end
@@ -89,7 +67,7 @@ describe AMQP::Boilerplate::Producer do
       end
 
       it "should use defaults for exchange configuration" do
-        DummyProducer.amqp_exchange()
+        BarProducer.amqp_exchange()
 
         AMQP::Exchange.should_receive(:new).with(@channel, :direct, AMQ::Protocol::EMPTY_STRING, {})
         @producer.publish

data/spec/amqp/boilerplate_spec.rb

@@ -1,6 +1,62 @@
 require 'spec_helper'
 
 describe AMQP::Boilerplate do
+  describe ".boot" do
+    before(:each) do
+      AMQP::Boilerplate.stub(:logger).and_return(mock.as_null_object)
+
+      EventMachine.stub(:next_tick).and_yield
+
+      AMQP::Boilerplate.stub(:start_consumers)
+      AMQP::Boilerplate.stub(:load_consumers)
+    end
+
+    it "should load all consumers" do
+      AMQP::Boilerplate.should_receive(:load_consumers)
+      AMQP::Boilerplate.boot
+    end
+
+    it "should start all consumers" do
+      AMQP::Boilerplate.should_receive(:start_consumers)
+      AMQP::Boilerplate.boot
+    end
+
+    it "should connect to AMQP" do
+      AMQP::Boilerplate.should_receive(:start)
+      AMQP::Boilerplate.boot
+    end
+
+    describe "when using passenger" do
+      before(:each) do
+        PhusionPassenger = Class.new
+        PhusionPassenger.stub(:on_event).and_yield(true)
+
+        @thread = mock(Thread, :abort_on_exception= => nil)
+        Thread.stub(:new).and_yield.and_return(@thread)
+      end
+
+      # Don't try this at home!
+      after(:each) do
+        Object.send(:remove_const, "PhusionPassenger")
+      end
+
+      it "should register to starting_worker_process event" do
+        PhusionPassenger.should_receive(:on_event).with(:starting_worker_process)
+        AMQP::Boilerplate.boot
+      end
+
+      it "should start new thread after process forked" do
+        Thread.should_receive(:new)
+        AMQP::Boilerplate.boot
+      end
+
+      it "should abort thread on exception" do
+        @thread.should_receive(:abort_on_exception=).with(true)
+        AMQP::Boilerplate.boot
+      end
+    end
+  end
+
   describe ".configure" do
     after(:each) do
       AMQP::Boilerplate.logger = nil
@@ -11,5 +67,30 @@ describe AMQP::Boilerplate do
       AMQP::Boilerplate.configure { |config| config.logger = MyFunkyLogger }
       AMQP::Boilerplate.logger.should == MyFunkyLogger
     end
+
+    it "should let us choose where consumers can be found" do
+      consumer_path = 'app/consumers'
+      AMQP::Boilerplate.configure { |config| config.consumer_paths << consumer_path }
+      AMQP::Boilerplate.consumer_paths.should include(consumer_path)
+    end
+
+    it "should allow us to set connection options" do
+      connection_options = { :host => "localhost", :port => 5672 }
+      AMQP::Boilerplate.configure { |config| config.connection_options = connection_options }
+      AMQP::Boilerplate.connection_options.should == connection_options
+    end
+  end
+
+  describe ".start" do
+    it "should start AMQP" do
+      AMQP.should_receive(:start)
+      AMQP::Boilerplate.start
+    end
+
+    it "should use the connection options" do
+      AMQP::Boilerplate.connection_options = { :host => "localhost", :port => 5672 }
+      AMQP.should_receive(:start).with(AMQP::Boilerplate.connection_options)
+      AMQP::Boilerplate.start
+    end
   end
 end

data/spec/fixtures/consumers/dummy_consumer.rb

@@ -0,0 +1,3 @@
+class DummyConsumer < AMQP::Boilerplate::Consumer
+  amqp_queue
+end

data/spec/spec_helper.rb

@@ -5,3 +5,38 @@ require 'amqp/boilerplate'
 RSpec.configure do |c|
   c.mock_with :rspec
 end
+
+# "Test" consumers
+class FooConsumer < AMQP::Boilerplate::Consumer
+  amqp_queue
+end
+
+class BarConsumer < AMQP::Boilerplate::Consumer
+  amqp_queue "queue.name.here", :durable => true
+  amqp_subscription :ack => true
+end
+
+# "Test" producers
+class FooProducer
+  extend AMQP::Boilerplate::Producer
+
+  amqp :routing_key => "another.routing.key"
+  amqp_message :some_method
+
+  def some_method
+    'Foo Bar'
+  end
+end
+
+class BarProducer
+  extend AMQP::Boilerplate::Producer
+
+  amqp :routing_key => "some.routing.key"
+  amqp_exchange :fanout, "amq.fanout", { :durable => true }
+  amqp_message :message
+
+  def message
+    "hello world!"
+  end
+end
+

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: amqp-boilerplate
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Patrick Baselier
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-12 00:00:00 +02:00
+date: 2011-09-13 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -49,10 +49,25 @@ dependencies:
         version: "2.6"
   prerelease: false
   requirement: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 0
+        - 7
+        version: "0.7"
+  prerelease: false
+  requirement: *id003
 - !ruby/object:Gem::Dependency 
   name: amqp
   type: :runtime
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -63,7 +78,7 @@ dependencies:
         - 8
         version: "0.8"
   prerelease: false
-  requirement: *id003
+  requirement: *id004
 description: Collection of modules that aid in setting up AMQP producers and consumers.
 email: 
 - patrick@kabisa.nl
@@ -84,13 +99,16 @@ files:
 - lib/amqp-boilerplate.rb
 - lib/amqp/boilerplate.rb
 - lib/amqp/boilerplate/consumer.rb
+- lib/amqp/boilerplate/consumer_registry.rb
 - lib/amqp/boilerplate/logging.rb
 - lib/amqp/boilerplate/producer.rb
 - lib/amqp/boilerplate/version.rb
+- spec/amqp/boilerplate/consumer_registry_spec.rb
 - spec/amqp/boilerplate/consumer_spec.rb
 - spec/amqp/boilerplate/logging_spec.rb
 - spec/amqp/boilerplate/producer_spec.rb
 - spec/amqp/boilerplate_spec.rb
+- spec/fixtures/consumers/dummy_consumer.rb
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: ""
@@ -127,8 +145,10 @@ signing_key:
 specification_version: 3
 summary: Helper modules for quickly setting up AMQP producers/consumers
 test_files: 
+- spec/amqp/boilerplate/consumer_registry_spec.rb
 - spec/amqp/boilerplate/consumer_spec.rb
 - spec/amqp/boilerplate/logging_spec.rb
 - spec/amqp/boilerplate/producer_spec.rb
 - spec/amqp/boilerplate_spec.rb
+- spec/fixtures/consumers/dummy_consumer.rb
 - spec/spec_helper.rb