amqp 0.6.7 → 0.7.0.pre

data/lib/mq/collection.rb

@@ -0,0 +1,132 @@
+# encoding: utf-8
+
+class MQ
+  class Collection < ::Array
+    class IncompatibleItemError < ArgumentError
+      def initialize(item)
+        super("Instance of #{item.class} doesn't respond to #name!")
+      end
+    end
+
+    def [](name)
+      self.find do |object|
+        object.name == name
+      end
+    end
+
+    # Collection#[]= doesn't really make any sense, as we can't
+    # redefine already existing Queues and Exchanges (we can declare
+    # them multiple times, but if the queue resp. exchange is already
+    # in the collection, it doesn't make sense to do so and we can't
+    # run declare twice in order to change options, because the AMQP
+    # broker closes the connection if we try to do so).
+
+    # Use Collection#<< for adding items to the collection.
+    undef_method :[]=
+
+    def <<(item)
+      if (item.name rescue nil).nil? || ! self[item.name]
+        self.add!(item)
+      end
+
+      return item
+    end
+
+    alias_method :__push__, :push
+    alias_method :push, :<<
+
+    def add!(item)
+      unless item.respond_to?(:name)
+        raise IncompatibleItemError.new(item)
+      end
+
+      __push__(item)
+      return item
+    end
+  end
+end
+
+if $0 =~ /bacon/ or $0 == __FILE__
+  require "bacon"
+
+  Item = Struct.new(:name)
+
+  describe MQ::Collection do
+    before do
+      @items = 3.times.map { |int| Item.new("name-#{int}") }
+      @collection = MQ::Collection.new(@items)
+    end
+
+    describe "accessors" do
+      should "be accessible by its name" do
+        @collection["name-1"].should.not.be.nil
+        @collection["name-1"].should.eql(@items[1])
+      end
+
+      should "not allow to change already existing object" do
+        lambda { @collection["name-1"] = Item.new("test") }.should.raise(NoMethodError)
+      end
+    end
+
+    describe "#<<" do
+      should "raise IncompatibleItemError if the argument doesn't have method :name" do
+        lambda { @collection << nil }.should.raise(MQ::Collection::IncompatibleItemError)
+      end
+
+      should "add an item into the collection" do
+        length = @collection.length
+        @collection << Item.new("test")
+        @collection.length.should.eql(length + 1)
+      end
+
+      should "not add an item to the collection if another item with given name already exists and the name IS NOT nil" do
+        @collection << Item.new("test")
+        length = @collection.length
+        @collection << Item.new("test")
+        @collection.length.should.eql(length)
+      end
+
+      should "add an item to the collection if another item with given name already exists and the name IS nil" do
+        @collection << Item.new(nil)
+        length = @collection.length
+        @collection << Item.new(nil)
+        @collection.length.should.eql(length + 1)
+      end
+
+      should "return the item" do
+        item = Item.new("test")
+        (@collection << item).should.eql item
+      end
+
+      should "return the item even if it already existed" do
+        item = Item.new("test")
+        @collection << item
+        (@collection << item).should.eql item
+      end
+    end
+
+    describe "#add!" do
+      should "raise IncompatibleItemError if the argument doesn't have method :name" do
+        lambda { @collection << nil }.should.raise(MQ::Collection::IncompatibleItemError)
+      end
+
+      should "add an item into the collection" do
+        length = @collection.length
+        @collection << Item.new("test")
+        @collection.length.should.eql(length + 1)
+      end
+
+      should "add an item to the collection if another item with given name already exists" do
+        @collection.add! Item.new("test")
+        length = @collection.length
+        @collection.add! Item.new("test")
+        @collection.length.should.eql(length + 1)
+      end
+
+      should "return the item" do
+        item = Item.new("test")
+        (@collection << item).should.eql item
+      end
+    end
+  end
+end

data/lib/mq/exchange.rb

@@ -10,7 +10,7 @@ class MQ
   # There are three (3) supported Exchange types: direct, fanout and topic.
   #
   # As part of the standard, the server _must_ predeclare the direct exchange
-  # 'amq.direct' and the fanout exchange 'amq.fanout' (all exchange names 
+  # 'amq.direct' and the fanout exchange 'amq.fanout' (all exchange names
   # starting with 'amq.' are reserved). Attempts to declare an exchange using
   # 'amq.' as the name will raise an MQ:Error and fail. In practice these
   # default exchanges are never used directly by client code.
@@ -28,7 +28,7 @@ class MQ
     # There are three (3) supported Exchange types: direct, fanout and topic.
     #
     # As part of the standard, the server _must_ predeclare the direct exchange
-    # 'amq.direct' and the fanout exchange 'amq.fanout' (all exchange names 
+    # 'amq.direct' and the fanout exchange 'amq.fanout' (all exchange names
     # starting with 'amq.' are reserved). Attempts to declare an exchange using
     # 'amq.' as the name will raise an MQ:Error and fail. In practice these
     # default exchanges are never used directly by client code.
@@ -36,8 +36,8 @@ class MQ
     # == Direct
     # A direct exchange is useful for 1:1 communication between a publisher and
     # subscriber. Messages are routed to the queue with a binding that shares
-    # the same name as the exchange. Alternately, the messages are routed to 
-    # the bound queue that shares the same name as the routing key used for 
+    # the same name as the exchange. Alternately, the messages are routed to
+    # the bound queue that shares the same name as the routing key used for
     # defining the exchange. This exchange type does not honor the :key option
     # when defining a new instance with a name. It _will_ honor the :key option
     # if the exchange name is the empty string. This is because an exchange
@@ -57,14 +57,14 @@ class MQ
     #  queue.pop { |data| puts "received data [#{data}]" }
     #
     # == Fanout
-    # A fanout exchange is useful for 1:N communication where one publisher 
-    # feeds multiple subscribers. Like direct exchanges, messages published 
-    # to a fanout exchange are delivered to queues whose name matches the 
-    # exchange name (or are bound to that exchange name). Each queue gets 
+    # A fanout exchange is useful for 1:N communication where one publisher
+    # feeds multiple subscribers. Like direct exchanges, messages published
+    # to a fanout exchange are delivered to queues whose name matches the
+    # exchange name (or are bound to that exchange name). Each queue gets
     # its own copy of the message.
     #
-    # Like the direct exchange type, this exchange type does not honor the 
-    # :key option when defining a new instance with a name. It _will_ honor 
+    # Like the direct exchange type, this exchange type does not honor the
+    # :key option when defining a new instance with a name. It _will_ honor
     # the :key option if the exchange name is the empty string. Fanout exchanges
     # defined with the empty string as the name use the default 'amq.fanout'.
     # In this case it needs to use :key to do its matching.
@@ -91,20 +91,20 @@ class MQ
     #  end
     #
     # == Topic
-    # A topic exchange allows for messages to be published to an exchange 
+    # A topic exchange allows for messages to be published to an exchange
     # tagged with a specific routing key. The Exchange uses the routing key
-    # to determine which queues to deliver the message. Wildcard matching 
-    # is allowed. The topic must be declared using dot notation to separate 
+    # to determine which queues to deliver the message. Wildcard matching
+    # is allowed. The topic must be declared using dot notation to separate
     # each subtopic.
     #
     # This is the only exchange type to honor the :key parameter.
     #
-    # As part of the AMQP standard, each server _should_ predeclare a topic 
+    # As part of the AMQP standard, each server _should_ predeclare a topic
     # exchange called 'amq.topic' (this is not required by the standard).
     #
     # The classic example is delivering market data. When publishing market
-    # data for stocks, we may subdivide the stream based on 2 
-    # characteristics: nation code and trading symbol. The topic tree for 
+    # data for stocks, we may subdivide the stream based on 2
+    # characteristics: nation code and trading symbol. The topic tree for
     # Apple Computer would look like:
     #  'stock.us.aapl'
     # For a foreign stock, it may look like:
@@ -139,10 +139,10 @@ class MQ
     #    end
     #  end
     #
-    # For matching, the '*' (asterisk) wildcard matches against one 
-    # dot-separated item only. The '#' wildcard (hash or pound symbol) 
-    # matches against 0 or more dot-separated items. If none of these 
-    # symbols are used, the exchange performs a comparison looking for an 
+    # For matching, the '*' (asterisk) wildcard matches against one
+    # dot-separated item only. The '#' wildcard (hash or pound symbol)
+    # matches against 0 or more dot-separated items. If none of these
+    # symbols are used, the exchange performs a comparison looking for an
     # exact match.
     #
     # == Options
@@ -150,12 +150,12 @@ class MQ
     # If set, the server will not create the exchange if it does not
     # already exist. The client can use this to check whether an exchange
     # exists without modifying  the server state.
-    # 
+    #
     # * :durable => true | false (default false)
     # If set when creating a new exchange, the exchange will be marked as
     # durable.  Durable exchanges remain active when a server restarts.
     # Non-durable exchanges (transient exchanges) are purged if/when a
-    # server restarts. 
+    # server restarts.
     #
     # A transient exchange (the default) is stored in memory-only
     # therefore it is a good choice for high-performance and low-latency
@@ -183,26 +183,56 @@ class MQ
     # not wait for a reply method.  If the server could not complete the
     # method it will raise a channel or connection exception.
     #
+    # * :no_declare => true | false (default false)
+    # If set, the exchange will not be declared to the
+    # AMQP broker at instantiation-time. This allows the AMQP
+    # client to send messages to exchanges that were
+    # already declared by someone else, e.g. if the client
+    # does not have sufficient privilege to declare (create)
+    # an exchange. Use with caution, as binding to an exchange
+    # with the no-declare option causes your system to become
+    # sensitive to the ordering of clients' actions!
+    #
     # == Exceptions
     # Doing any of these activities are illegal and will raise MQ:Error.
     # * redeclare an already-declared exchange to a different type
     # * :passive => true and the exchange does not exist (NOT_FOUND)
     #
-    def initialize mq, type, name, opts = {}
+    def initialize mq, type, name, opts = {}, &block
       @mq = mq
-      @type, @name, @opts = type, name, opts
-      @mq.exchanges[@name = name] ||= self
+      @type, @opts = type, opts
+      @opts = { :exchange => name, :type => type, :nowait => block.nil? }.merge(opts)
       @key = opts[:key]
-      
+      @name = name unless name.empty?
+      @status = :unknown
+
+      # The AMQP 0.8 specification (as well as 0.9.1) in 1.1.4.2 mentiones
+      # that Exchange.Declare-Ok confirms the name of the exchange (because
+      # of automatically­named), which is logical to interpret that this
+      # functionality should be the same as for Queue (though it isn't
+      # explicitely told in the specification). In fact, RabbitMQ (and
+      # probably other implementations as well) doesn't support it and
+      # there is a default exchange with an empty name (so-called default
+      # or nameless exchange), so if we'd send Exchange.Declare(exchange=""),
+      # then RabbitMQ interpret it as if we'd try to redefine this default
+      # exchange so it'd produce an error.
       unless name == "amq.#{type}" or name == '' or opts[:no_declare]
-        @mq.callback{
-          @mq.send Protocol::Exchange::Declare.new({ :exchange => name,
-                                                     :type => type,
-                                                     :nowait => true }.merge(opts))
+        @status = :unfinished
+        @mq.callback {
+          @mq.send Protocol::Exchange::Declare.new(@opts)
         }
+      else
+        # Call the callback immediately, as given exchange is already
+        # declared.
+        @status = :finished
+        block.call(self)
       end
+
+      self.callback = block
     end
-    attr_reader :name, :type, :key
+
+    attr_reader :name, :type, :key, :status
+    attr_accessor :opts, :callback
 
     # This method publishes a staged file message to a specific exchange.
     # The file message will be routed to queues as defined by the exchange
@@ -212,7 +242,7 @@ class MQ
     #  exchange = MQ.direct('name', :key => 'foo.bar')
     #  exchange.publish("some data")
     #
-    # The method takes several hash key options which modify the behavior or 
+    # The method takes several hash key options which modify the behavior or
     # lifecycle of the message.
     #
     # * :routing_key => 'string'
@@ -236,7 +266,7 @@ class MQ
     # no guarantee that it will ever be consumed.
     #
     #  * :persistent
-    # True or False. When true, this message will remain in the queue until 
+    # True or False. When true, this message will remain in the queue until
     # it is consumed (if the queue is durable). When false, the message is
     # lost if the server restarts and the queue is recreated.
     #
@@ -254,7 +284,7 @@ class MQ
         data = data.to_s
 
         out << Protocol::Header.new(Protocol::Basic,
-                                    data.length, { :content_type => 'application/octet-stream',
+                                    data.bytesize, { :content_type => 'application/octet-stream',
                                                    :delivery_mode => (opts[:persistent] ? 2 : 1),
                                                    :priority => 0 }.merge(opts))
 
@@ -286,7 +316,7 @@ class MQ
     # If set, the server will only delete the exchange if it has no queue
     # bindings. If the exchange has queue bindings the server does not
     # delete it but raises a channel exception instead (MQ:Error).
-    #    
+    #
     def delete opts = {}
       @mq.callback{
         @mq.send Protocol::Exchange::Delete.new({ :exchange => name,
@@ -300,5 +330,9 @@ class MQ
       @deferred_status = nil
       initialize @mq, @type, @name, @opts
     end
+
+    def receive_response response
+      self.callback && self.callback.call(self)
+    end
   end
-end
+end

data/lib/mq/queue.rb

@@ -1,7 +1,7 @@
 class MQ
   class Queue
     include AMQP
-    
+
     # Queues store and forward messages.  Queues can be configured in the server
     # or created at runtime.  Queues must be attached to at least one exchange
     # in order to receive messages from publishers.
@@ -10,7 +10,7 @@ class MQ
     # internal use. Attempts to create queue names in violation of this
     # reservation will raise MQ:Error (ACCESS_REFUSED).
     #
-    # When a queue is created without a name, the server will generate a 
+    # When a queue is created without a name, the server will generate a
     # unique name internally (not currently supported in this library).
     #
     # == Options
@@ -18,7 +18,7 @@ class MQ
     # If set, the server will not create the exchange if it does not
     # already exist. The client can use this to check whether an exchange
     # exists without modifying  the server state.
-    # 
+    #
     # * :durable => true | false (default false)
     # If set when creating a new queue, the queue will be marked as
     # durable.  Durable queues remain active when a server restarts.
@@ -47,7 +47,7 @@ class MQ
     # If set, the queue is deleted when all consumers have finished
     # using it. Last consumer can be cancelled either explicitly or because
     # its channel is closed. If there was no consumer ever on the queue, it
-    # won't be deleted. 
+    # won't be deleted.
     #
     # The server waits for a short period of time before
     # determining the queue is unused to give time to the client code
@@ -61,17 +61,21 @@ class MQ
     # not wait for a reply method.  If the server could not complete the
     # method it will raise a channel or connection exception.
     #
-    def initialize mq, name, opts = {}
+    def initialize mq, name, opts = {}, &block
       @mq = mq
-      @opts = opts
+      @opts = { :queue => name, :nowait => block.nil? }.merge(opts)
       @bindings ||= {}
-      @mq.queues[@name = name] ||= self
-      @mq.callback{
-        @mq.send Protocol::Queue::Declare.new({ :queue => name,
-                                                :nowait => true }.merge(opts))
+      @name = name unless name.empty?
+      @status = @opts[:nowait] ? :unknown : :unfinished
+      @mq.callback {
+        @mq.send Protocol::Queue::Declare.new(@opts)
       }
+
+      self.callback = block
     end
+
     attr_reader :name
+    attr_accessor :opts, :callback, :bind_callback
 
     # This method binds a queue to an exchange.  Until a queue is
     # bound it will not receive any messages.  In a classic messaging
@@ -106,7 +110,8 @@ class MQ
     # not wait for a reply method.  If the server could not complete the
     # method it will raise a channel or connection exception.
     #
-    def bind exchange, opts = {}
+    def bind exchange, opts = {}, &block
+      @status = :unbound
       exchange = exchange.respond_to?(:name) ? exchange.name : exchange
       @bindings[exchange] = opts
 
@@ -114,13 +119,14 @@ class MQ
         @mq.send Protocol::Queue::Bind.new({ :queue => name,
                                              :exchange => exchange,
                                              :routing_key => opts[:key],
-                                             :nowait => true }.merge(opts))
+                                             :nowait => block.nil? }.merge(opts))
       }
+      self.bind_callback = block
       self
     end
 
     # Remove the binding between the queue and exchange. The queue will
-    # not receive any more messages until it is bound to another 
+    # not receive any more messages until it is bound to another
     # exchange.
     #
     # Due to the asynchronous nature of the protocol, it is possible for
@@ -197,7 +203,7 @@ class MQ
     #    EM.add_periodic_timer(1) do
     #      exchange.publish("random number #{rand(1000)}")
     #    end
-    #    
+    #
     #    # note that #bind is never called; it is implicit because
     #    # the exchange and queue names match
     #    queue = MQ.queue('foo queue')
@@ -215,9 +221,9 @@ class MQ
     #    EM.add_periodic_timer(1) do
     #      exchange.publish("random number #{rand(1000)}")
     #    end
-    #    
+    #
     #    queue = MQ.queue('foo queue')
-    #    queue.pop do |header, body| 
+    #    queue.pop do |header, body|
     #      p header
     #      puts "received payload [#{body}]"
     #    end
@@ -268,7 +274,7 @@ class MQ
     #    EM.add_periodic_timer(1) do
     #      exchange.publish("random number #{rand(1000)}")
     #    end
-    #    
+    #
     #    queue = MQ.queue('foo queue')
     #    queue.subscribe { |body| puts "received payload [#{body}]" }
     #  end
@@ -282,11 +288,11 @@ class MQ
     #    EM.add_periodic_timer(1) do
     #      exchange.publish("random number #{rand(1000)}")
     #    end
-    #    
+    #
     #    # note that #bind is never called; it is implicit because
     #    # the exchange and queue names match
     #    queue = MQ.queue('foo queue')
-    #    queue.subscribe do |header, body| 
+    #    queue.subscribe do |header, body|
     #      p header
     #      puts "received payload [#{body}]"
     #    end
@@ -340,11 +346,11 @@ class MQ
     # Those messages will be serviced by the last block used in a
     # #subscribe or #pop call.
     #
-    # Additionally, if the queue was created with _autodelete_ set to 
+    # Additionally, if the queue was created with _autodelete_ set to
     # true, the server will delete the queue after its wait period
     # has expired unless the queue is bound to an active exchange.
     #
-    # The method accepts a block which will be executed when the 
+    # The method accepts a block which will be executed when the
     # unsubscription request is acknowledged as complete by the server.
     #
     # * :nowait => true | false (default true)
@@ -363,21 +369,21 @@ class MQ
     def publish data, opts = {}
       exchange.publish(data, opts)
     end
-    
+
     # Boolean check to see if the current queue has already been subscribed
-    # to an exchange. 
+    # to an exchange.
     #
     # Attempts to #subscribe multiple times to any exchange will raise an
-    # Exception. Only a single block at a time can be associated with any 
+    # Exception. Only a single block at a time can be associated with any
     # one queue for processing incoming messages.
     #
     def subscribed?
       !!@on_msg
     end
 
-    # Passes the message to the block passed to pop or subscribe. 
+    # Passes the message to the block passed to pop or subscribe.
     #
-    # Performs an arity check on the block's parameters. If arity == 1, 
+    # Performs an arity check on the block's parameters. If arity == 1,
     # pass only the message body. If arity != 1, pass the headers and
     # the body to the block.
     #
@@ -385,7 +391,7 @@ class MQ
     # the headers parameter. See #pop or #subscribe for a code example.
     #
     def receive headers, body
-      headers = MQ::Header.new(@mq, headers)
+      headers = MQ::Header.new(@mq, headers) unless headers.nil?
 
       if cb = (@on_msg || @on_pop)
         cb.call *(cb.arity == 1 ? [body] : [headers, body])
@@ -399,6 +405,8 @@ class MQ
     #  }
     #
     def status opts = {}, &blk
+      return @status if opts.empty? && blk.nil?
+
       @on_status = blk
       @mq.callback{
         @mq.send Protocol::Queue::Declare.new({ :queue => name,
@@ -408,6 +416,13 @@ class MQ
     end
 
     def receive_status declare_ok
+      @name = declare_ok.queue
+      @status = :finished
+
+      if self.callback
+        self.callback.call(self, declare_ok.message_count, declare_ok.consumer_count)
+      end
+
       if @on_status
         m, c = declare_ok.message_count, declare_ok.consumer_count
         @on_status.call *(@on_status.arity == 1 ? [m] : [m, c])
@@ -415,6 +430,13 @@ class MQ
       end
     end
 
+    def after_bind bind_ok
+      @status = :bound
+      if self.bind_callback
+        self.bind_callback.call(self)
+      end
+    end
+
     def confirm_subscribe
       @on_confirm_subscribe.call if @on_confirm_subscribe
       @on_confirm_subscribe = nil
@@ -424,6 +446,7 @@ class MQ
       @on_cancel.call if @on_cancel
       @on_cancel = @on_msg = nil
       @mq.consumers.delete @consumer_tag
+      @mq.queues.delete(@name) if @opts[:auto_delete]
       @consumer_tag = nil
     end
 
@@ -444,11 +467,11 @@ class MQ
         pop @on_pop_opts, &@on_pop
       end
     end
-  
+
     private
-    
+
     def exchange
       @exchange ||= Exchange.new(@mq, :direct, '', :key => name)
     end
   end
-end
+end