pivotal-moqueue 0.1.0.200907241602

data/README.rdoc

@@ -0,0 +1,57 @@
+= Moqueue
+Moqueue is a library for mocking the various objects that make up the ruby AMQP[http://github.com/tmm1/amqp] library. It allows you to use the AMQP library naturally and test your code easily without running an AMQP broker. If you want a higher level of control, you can use your favorite mocking and stubbing library to modify individual calls to MQ.queue and the like so that they return Moqueue's mock up versions. If you want to go all-in, you can tell Moqueue to overload the MQ and AMQP. This allows you to use MQ and AMQP as normal, while Moqueue works behind the scenes to wire everything together.
+
+= Getting started
+
+  require "moqueue"
+  overload_amqp
+  
+  mq = MQ.new
+  => #<MQ:0x1197ae8>
+  
+  queue = mq.queue("mocktacular")
+  => #<Moqueue::MockQueue:0x1194550 @name="mocktacular">
+  
+  topic = mq.topic("lolz")
+  => #<Moqueue::MockExchange:0x11913dc @topic="lolz">
+  
+  queue.bind(topic, :key=> "cats.*")
+  => #<Moqueue::MockQueue:0x1194550 @name="mocktacular">
+  
+  queue.subscribe {|header, msg| puts [header.routing_key, msg]}
+  => nil
+  
+  topic.publish("eatin ur foodz", :key => "cats.inUrFridge")
+  # cats.inUrFridge
+  # eatin ur foodz
+  
+Note that in this example, we didn't have to deal with <tt>AMQP.start</tt> or <tt>EM.run</tt>. This should be ample evidence that you should run higher level tests without any mocks or stubs so you can be sure everything works with real MQ objects. With that said, <tt>#overload_amqp</tt> does overload the <tt>AMQP.start</tt> method, so you can use Moqueue for mid-level testing if desired. Have a look at the spec/examples directory to see Moqueue running some of AMQP's examples in overload mode for more demonstration of this.
+
+= Custom Rspec Matchers
+For Test::Unit users, Moqueue's default syntax should be a good fit with <tt>assert()</tt>:
+  assert(queue.received_message?("eatin ur foodz"))
+Rspec users will probably want something a bit more natural language-y. You got it:
+  queue.should have_received("a message")
+  queue.should have_ack_for("a different message")
+
+= What's Working? What's Not?
+As you can tell from the example above, quite a bit is working. This includes direct exchanges where you call <tt>#publish</tt> and <tt>#subscribe</tt> on the same queue, acknowledgements, topic exchanges, and fanout exchanges.
+
+What's not working: 
+* RPC exchanges. 
+* The routing key matching algorithm works for common cases, including "*" and "#" wildcards in the binding key. If you need anything more complicated than that, Moqueue is not guaranteed to do the right thing.
+* Receiving acks when using topic exchanges works only if you subscribe before publishing.
+
+There are some things that Moqueue may never be able to do. As one prominent example, for queues that are configured to expect acknowledgements (the <tt>:ack=>true</tt> option), the behavior on shutdown is not emulated correctly.
+
+== TODOs
+* Mocha-style expectation syntax, i.e. <tt>queue.expects_message("yessss").with_routing_key("awesome.yesItIs")</tt>
+* Support for RPC exchanges
+* Make it pretty on the inside.
+
+== Moar
+I wrote an introductory post on my blog, it's probably the best source of high-level discussion right now. Visit: http://kallistec.com/2009/06/21/introducing-moqueue/
+
+If you prefer code over drivel, look at the specs under spec/examples. There you'll find some of the examples from the amqp library running completely Moqueue-ified; the basic_usage_spec.rb shows some lower-level use.
+
+As always, you're invited to git yer fork on if you want to work on any of these. If you find a bug that you can't source or want to send love or hate mail, you can contact me directly at dan@kallistec.com

data/Rakefile

@@ -0,0 +1,25 @@
+require "spec/rake/spectask"
+
+task :default => :spec
+
+desc "Run all of the specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "\"spec/spec.opts\""]
+  t.fail_on_error = false
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "moqueue"
+    s.summary = "Mocktacular Companion to AMQP Library. Happy TATFTing!"
+    s.email = "dan@kallistec.com"
+    s.homepage = "http://github.com/danielsdeleo/moqueue"
+    s.description = "Mocktacular Companion to AMQP Library. Happy TATFTing!"
+    s.authors = ["Daniel DeLeo"]
+    s.files =  FileList["[A-Za-z]*", "{lib,spec}/**/*"]
+  end
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 0

data/lib/moqueue.rb

@@ -0,0 +1,15 @@
+unless defined?(MOQUEUE_ROOT)
+  MOQUEUE_ROOT = File.dirname(__FILE__) + "/"
+end
+require MOQUEUE_ROOT + "moqueue/fibers18"
+
+require MOQUEUE_ROOT + "moqueue/mock_exchange"
+require MOQUEUE_ROOT + "moqueue/mock_queue"
+require MOQUEUE_ROOT + "moqueue/mock_headers"
+require MOQUEUE_ROOT + "moqueue/mock_broker"
+
+require MOQUEUE_ROOT + "moqueue/object_methods"
+require MOQUEUE_ROOT + "moqueue/matchers"
+
+module Moqueue  
+end

data/lib/moqueue/fibers18.rb

@@ -0,0 +1,57 @@
+# Courtesy Aman Gupta's (original) em-spec library
+unless defined? Fiber
+  require 'thread'
+
+  class FiberError < StandardError; end
+
+  class Fiber
+    def initialize
+      raise ArgumentError, 'new Fiber requires a block' unless block_given?
+
+      @yield = Queue.new
+      @resume = Queue.new
+
+      @thread = Thread.new{ @yield.push [ *yield(*@resume.pop) ] }
+      @thread.abort_on_exception = true
+      @thread[:fiber] = self
+    end
+    attr_reader :thread
+    
+    def alive?
+      @thread.alive?
+    end
+    
+    def resume *args
+      raise FiberError, 'dead fiber called' unless @thread.alive?
+      raise FiberError, 'double resume' if @thread == Thread.current
+      @resume.push(args)
+      result = @yield.pop
+      result.size > 1 ? result : result.first
+    end
+    
+    def resume!
+      @resume.push []
+    end
+    
+    def yield *args
+      @yield.push(args)
+      result = @resume.pop
+      result.size > 1 ? result : result.first
+    end
+    
+    def self.yield *args
+      raise FiberError, "can't yield from root fiber" unless fiber = Thread.current[:fiber]
+      fiber.yield(*args)
+    end
+
+    def self.current
+      Thread.current[:fiber] or raise FiberError, 'not inside a fiber'
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{self.object_id.to_s(16)}>"
+    end
+  end
+else
+  require 'fiber' unless Fiber.respond_to?(:current)
+end

data/lib/moqueue/matchers.rb

@@ -0,0 +1,74 @@
+module Moqueue
+  module Matchers
+    
+    class HasReceived
+      
+      def initialize(expected_msg)
+        @expected_msg = expected_msg
+      end
+      
+      def matches?(queue)
+        if queue.respond_to?(:received_message?)
+          @queue = queue
+          @queue.received_message?(@expected_msg)
+        else
+          raise NoMethodError, 
+          "Grrr. you can't use ``should have_received_message'' on #{queue.inspect} " +
+          "because it doesn't respond_to :received_message?"
+        end
+      end
+      
+      def failure_message_for_should
+        "expected #{@queue.inspect} to have received message ``#{@expected_msg}''"
+      end
+
+      def failure_message_for_should_not
+        "expected #{@queue.inspect} to not have received message ``#{@expected_msg}''"
+      end
+
+    end
+    
+    class HasAcked
+      
+      def initialize(msg_expecting_ack)
+        @msg_expecting_ack = msg_expecting_ack
+      end
+      
+      def matches?(queue_or_exchange)
+        if queue_or_exchange.respond_to?(:received_ack_for_message?)
+          @queue_or_exchange = queue_or_exchange
+          @queue_or_exchange.received_ack_for_message?(@msg_expecting_ack)
+        else
+          raise NoMethodError,
+          "Grrr. you can't use ``should have_received_ack_for'' on #{queue_or_exchange.inspect} " +
+          "because it doesn't respond_to :received_ack_for_message?"
+        end
+      end
+      
+      def failure_message_for_should
+        "expected #{@queue_or_exchange.inspect} to have received an ack for the message ``#{@msg_expecting_ack}''"
+      end
+      
+      def failure_message_for_should_not
+        "expected #{@queue_or_exchange.inspect} to not have received an ack for the message ``#{@msg_expecting_ack}''"
+      end
+    end
+    
+    def have_received_message(expected_msg)
+      HasReceived.new(expected_msg)
+    end
+    
+    def have_received_ack_for(expected_msg)
+      HasAcked.new(expected_msg)
+    end
+    
+    alias_method :have_received, :have_received_message
+    alias_method :have_ack_for, :have_received_ack_for
+  end
+end
+
+if defined?(::Spec::Runner)
+  Spec::Runner.configure do |config|
+    config.include(::Moqueue::Matchers)
+  end
+end

data/lib/moqueue/mock_broker.rb

@@ -0,0 +1,44 @@
+require "singleton"
+
+module Moqueue
+  class MockBroker
+    include Singleton
+    
+    attr_reader :registered_queues
+    
+    def initialize
+      reset!
+    end
+    
+    def reset!
+      @registered_queues = {}
+      @registered_topic_exchanges = {}
+      @registered_fanout_exchanges = {}
+    end
+    
+    def find_queue(name)
+      @registered_queues[name]
+    end
+    
+    def register_queue(queue)
+      @registered_queues[queue.name] = queue
+    end
+    
+    def register_topic_exchange(exchange)
+      @registered_topic_exchanges[exchange.topic] = exchange
+    end
+    
+    def find_topic_exchange(topic)
+      @registered_topic_exchanges[topic]
+    end
+    
+    def register_fanout_exchange(exchange)
+      @registered_fanout_exchanges[exchange.fanout] = exchange
+    end
+    
+    def find_fanout_exchange(fanout_name)
+      @registered_fanout_exchanges[fanout_name]
+    end
+    
+  end
+end

data/lib/moqueue/mock_exchange.rb

@@ -0,0 +1,114 @@
+module Moqueue
+  
+  class MockExchange
+    attr_reader :topic, :fanout
+    
+    class << self
+      
+      def new(opts={})
+        if opts[:topic] && topic_exchange = MockBroker.instance.find_topic_exchange(opts[:topic])
+          return topic_exchange
+        end
+        
+        if opts[:fanout] && fanout = MockBroker.instance.find_fanout_exchange(opts[:fanout])
+          return fanout
+        end
+        
+        super
+      end
+      
+    end
+    
+    def initialize(opts={})
+      if @topic = opts[:topic]
+        MockBroker.instance.register_topic_exchange(self)
+      elsif @fanout = opts[:fanout]
+        MockBroker.instance.register_fanout_exchange(self)
+      end
+    end
+    
+    def attached_queues
+      @attached_queues ||= []
+    end
+    
+    def acked_messages
+      @acked_messages ||= []
+    end
+    
+    def attach_queue(queue, opts={})
+      if topic
+        attached_queues << [queue, BindingKey.new(opts[:key])]
+      else
+        attached_queues << queue
+      end
+    end
+    
+    def publish(message, opts={})
+      require_routing_key(opts) if topic
+      matching_queues(opts).each do |q| 
+        ack_message(q.receive(message, prepare_header_opts(opts)))
+      end
+    end
+    
+    def received_ack_for_message?(message)
+      acked_messages.include?(message)
+    end
+        
+    private
+    
+    def ack_message(message)
+      acked_messages << message if message
+    end
+    
+    def routing_keys_match?(binding_key, message_key)
+      BindingKey.new(binding_key).matches?(message_key)
+    end
+    
+    def matching_queues(opts={})
+      return attached_queues unless topic
+      attached_queues.map {|q, binding| binding.matches?(opts[:key]) ? q : nil}.compact
+    end
+    
+    def prepare_header_opts(opts={})
+      header_opts = opts.dup
+      if routing_key = header_opts.delete(:key)
+        header_opts[:routing_key] = routing_key
+      end
+      header_opts
+    end
+    
+    def require_routing_key(opts={})
+      unless opts.has_key?(:key)
+        raise ArgumentError, "you must provide a key when publishing to a topic exchange"
+      end
+    end
+    
+    public
+    
+    class BindingKey
+      attr_reader :key
+
+      def initialize(key_string)
+        @key = key_string.to_s.split(".")
+      end
+
+      def ==(other)
+        other.respond_to?(:key) && other.key == @key
+      end
+
+      def matches?(message_key)
+        message_key, binding_key = message_key.split("."), key.dup
+
+        match = true
+        while match 
+          binding_token, message_token = binding_key.shift, message_key.shift
+          break if (binding_token.nil? && message_token.nil?) || (binding_token == "#")
+          match = ((binding_token == message_token) || (binding_token == '*') || (message_token == '*'))
+        end
+        match
+      end
+
+    end
+  end
+  
+end

data/lib/moqueue/mock_headers.rb

@@ -0,0 +1,31 @@
+module Moqueue
+  
+  class MockHeaders
+    attr_accessor :size, :weight
+    
+    def initialize(properties={})
+      @properties = properties
+    end
+    
+    def ack
+      @received_ack = true
+    end
+    
+    def received_ack?
+      @received_ack || false
+    end
+        
+    def properties
+      @properties
+    end
+    
+    def to_frame
+      nil
+    end
+    
+    def method_missing method, *args, &blk
+      @properties.has_key?(method) ? @properties[method] : super
+    end
+  end
+  
+end

data/lib/moqueue/mock_queue.rb

@@ -0,0 +1,126 @@
+module Moqueue
+  
+  class DoubleSubscribeError < StandardError
+  end
+  
+  class MockQueue
+    attr_reader :name
+    
+    class << self
+      
+      def new(name)
+        if existing_queue = MockBroker.instance.find_queue(name)
+          return existing_queue
+        end
+        super
+      end
+      
+    end
+    
+    def initialize(name)
+      @name = name
+      MockBroker.instance.register_queue(self)
+    end
+    
+    def subscribe(opts={}, &block)
+      if @subscribe_block 
+        raise DoubleSubscribeError, "you can't subscribe to the same queue twice"
+      end
+      @subscribe_block = block
+      @ack_msgs = opts[:ack] || false
+      process_unhandled_messages
+    end
+    
+    def receive(message, header_opts={})
+      if callback = message_handler_callback
+        headers = MockHeaders.new(header_opts)
+        callback.call(*(callback.arity == 1 ? [message] : [headers, message]))
+        received_messages << message
+        @ack_msgs && headers.received_ack? ? message : nil
+      else
+        receive_message_later(message, header_opts)
+      end
+    end
+    
+    def received_message?(message_content)
+      received_messages.include?(message_content)
+    end
+    
+    def unsubscribe
+      true
+    end
+    
+    def received_ack_for_message?(message_content)
+      acked_messages.include?(message_content)
+    end
+    
+    def publish(message)
+      if message_handler_callback
+        real_publish(message)
+      else
+        deferred_publishing_fibers << Fiber.new do
+          real_publish(message)
+        end
+      end
+    end
+    
+    def bind(exchange, key=nil)
+      exchange.attach_queue(self, key)
+      self
+    end
+    
+    def received_messages
+      @received_messages ||= []
+    end
+    
+    def acked_messages
+      @acked_messages ||= []
+    end
+    
+    def run_callback(*args)
+      callback = message_handler_callback
+      callback.call(*(callback.arity == 1 ? [args.first] : args))
+    end
+    
+    def callback_defined?
+      !!message_handler_callback
+    end
+    
+    # configures a do-nothing subscribe block to force
+    # received messages to be processed and stored in
+    # #received_messages
+    def null_subscribe
+      subscribe {|msg| nil}
+      self
+    end
+    
+    private
+    
+    def receive_message_later(message, header_opts)
+      deferred_publishing_fibers << Fiber.new do
+        self.receive(message, header_opts)
+      end
+    end
+    
+    def deferred_publishing_fibers
+      @deferred_publishing_fibers ||= []
+    end
+    
+    def message_handler_callback
+      @subscribe_block || @pop_block || false
+    end
+    
+    def process_unhandled_messages
+      while fiber = deferred_publishing_fibers.shift
+        fiber.resume
+      end
+    end
+    
+    def real_publish(message)
+      response = receive(message)
+      acked_messages << response if response
+    end
+    
+  end
+  
+end