amq-client 0.7.0.alpha35 → 0.8.0

data/lib/amq/client/async/exchange.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
+require "amq/client/exceptions"
 require "amq/client/entity"
 require "amq/client/server_named_entity"
 
@@ -13,13 +14,8 @@ module AMQ
         include ServerNamedEntity
         extend ProtocolMethodHandlers
 
-        TYPES = [:fanout, :direct, :topic, :headers].freeze
+        BUILTIN_TYPES = [:fanout, :direct, :topic, :headers].freeze
 
-        class IncompatibleExchangeTypeError < StandardError
-          def initialize(types, given)
-            super("#{given.inspect} exchange type is unknown. Standard types are #{TYPES.inspect}, custom exchange types must begin with x-, for example: x-recent-history")
-          end
-        end
 
 
         #
@@ -30,45 +26,81 @@ module AMQ
         attr_reader :channel
 
         # Exchange name. May be server-generated or assigned directly.
+        # @return [String]
         attr_reader :name
 
         # @return [Symbol] One of :direct, :fanout, :topic, :headers
         attr_reader :type
 
+        # @return [Hash] Additional arguments given on queue declaration. Typically used by AMQP extensions.
+        attr_reader :arguments
+
+
+
         def initialize(connection, channel, name, type = :fanout)
-          if !(TYPES.include?(type.to_sym) || type.to_s =~ /^x-.+/i)
-            raise IncompatibleExchangeTypeError.new(TYPES, type)
+          if !(BUILTIN_TYPES.include?(type.to_sym) || type.to_s =~ /^x-.+/i)
+            raise UnknownExchangeTypeError.new(BUILTIN_TYPES, type)
           end
 
-          @connection  = connection
-          @channel = channel
-          @name    = name
-          @type    = type
+          @connection = connection
+          @channel    = channel
+          @name       = name
+          @type       = type
 
           # register pre-declared exchanges
-          if @name == AMQ::Protocol::EMPTY_STRING || @name =~ /^amq\.(fanout|topic)/
+          if @name == AMQ::Protocol::EMPTY_STRING || @name =~ /^amq\.(direct|fanout|topic|match|headers)/
             @channel.register_exchange(self)
           end
 
           super(connection)
         end
 
-
+        # @return [Boolean] true if this exchange is of type `fanout`
+        # @api public
         def fanout?
           @type == :fanout
         end
 
+        # @return [Boolean] true if this exchange is of type `direct`
+        # @api public
         def direct?
           @type == :direct
         end
 
+        # @return [Boolean] true if this exchange is of type `topic`
+        # @api public
         def topic?
           @type == :topic
         end
 
+        # @return [Boolean] true if this exchange is of type `headers`
+        # @api public
+        def headers?
+          @type == :headers
+        end
+
+        # @return [Boolean] true if this exchange is of a custom type (begins with x-)
+        # @api public
+        def custom_type?
+          @type.to_s =~ /^x-.+/i
+        end # custom_type?
+
+        # @return [Boolean] true if this exchange is a pre-defined one (amq.direct, amq.fanout, amq.match and so on)
+        def predefined?
+          @name && !!(@name =~ /^amq\.(direct|fanout|topic|headers|match)/i)
+        end # predefined?
 
 
+        # @group Declaration
+
+        # @api public
         def declare(passive = false, durable = false, auto_delete = false, nowait = false, arguments = nil, &block)
+          # for re-declaration
+          @passive     = passive
+          @durable     = durable
+          @auto_delete = auto_delete
+          @arguments   = arguments
+
           @connection.send_frame(Protocol::Exchange::Declare.encode(@channel.id, @name, @type.to_s, passive, durable, auto_delete, false, nowait, arguments))
 
           unless nowait
@@ -80,6 +112,23 @@ module AMQ
         end
 
 
+        # @api public
+        def redeclare(&block)
+          nowait = block.nil?
+          @connection.send_frame(Protocol::Exchange::Declare.encode(@channel.id, @name, @type.to_s, @passive, @durable, @auto_delete, false, nowait, @arguments))
+
+          unless nowait
+            self.define_callback(:declare, &block)
+            @channel.exchanges_awaiting_declare_ok.push(self)
+          end
+
+          self
+        end # redeclare(&block)
+
+        # @endgroup
+
+
+        # @api public
         def delete(if_unused = false, nowait = false, &block)
           @connection.send_frame(Protocol::Exchange::Delete.encode(@channel.id, @name, if_unused, nowait))
 
@@ -94,22 +143,94 @@ module AMQ
         end # delete(if_unused = false, nowait = false)
 
 
+
+        # @group Publishing Messages
+
+        # @api public
         def publish(payload, routing_key = AMQ::Protocol::EMPTY_STRING, user_headers = {}, mandatory = false, immediate = false, frame_size = nil)
           headers = { :priority => 0, :delivery_mode => 2, :content_type => "application/octet-stream" }.merge(user_headers)
-          @connection.send_frameset(Protocol::Basic::Publish.encode(@channel.id, payload, headers, @name, routing_key, mandatory, immediate, (frame_size || @connection.frame_max)))
+          @connection.send_frameset(Protocol::Basic::Publish.encode(@channel.id, payload, headers, @name, routing_key, mandatory, immediate, (frame_size || @connection.frame_max)), @channel)
 
           self
         end
 
 
+        # @api public
         def on_return(&block)
           self.redefine_callback(:return, &block)
 
           self
         end # on_return(&block)
 
+        # @endgroup
+
 
 
+        # @group Error Handling and Recovery
+
+
+        # Defines a callback that will be executed after TCP connection is interrupted (typically because of a network failure).
+        # Only one callback can be defined (the one defined last replaces previously added ones).
+        #
+        # @api public
+        def on_connection_interruption(&block)
+          self.redefine_callback(:after_connection_interruption, &block)
+        end # on_connection_interruption(&block)
+        alias after_connection_interruption on_connection_interruption
+
+        # @private
+        def handle_connection_interruption(method = nil)
+          self.exec_callback_yielding_self(:after_connection_interruption)
+        end # handle_connection_interruption
+
+
+
+        # Defines a callback that will be executed after TCP connection is recovered after a network failure
+        # but before AMQP connection is re-opened.
+        # Only one callback can be defined (the one defined last replaces previously added ones).
+        #
+        # @api public
+        def before_recovery(&block)
+          self.redefine_callback(:before_recovery, &block)
+        end # before_recovery(&block)
+
+        # @private
+        def run_before_recovery_callbacks
+          self.exec_callback_yielding_self(:before_recovery)
+        end
+
+
+        # Defines a callback that will be executed when AMQP connection is recovered after a network failure..
+        # Only one callback can be defined (the one defined last replaces previously added ones).
+        #
+        # @api public
+        def on_recovery(&block)
+          self.redefine_callback(:after_recovery, &block)
+        end # on_recovery(&block)
+        alias after_recovery on_recovery
+
+        # @private
+        def run_after_recovery_callbacks
+          self.exec_callback_yielding_self(:after_recovery)
+        end
+
+
+        # Called by associated connection object when AMQP connection has been re-established
+        # (for example, after a network failure).
+        #
+        # @api plugin
+        def auto_recover
+          self.redeclare unless predefined?
+        end # auto_recover
+
+        # @endgroup
+
+
+
+        #
+        # Implementation
+        #
+
 
         def handle_declare_ok(method)
           @name = method.exchange if self.anonymous?
@@ -151,7 +272,7 @@ module AMQ
           exchange.exec_callback(:return, method, header, body)
         end
 
-      end # Exchange      
+      end # Exchange
     end # Async
   end # Client
 end # AMQ

data/lib/amq/client/async/extensions/rabbitmq/confirm.rb

@@ -100,11 +100,11 @@ module AMQ
               # @see #confirm
               def confirm_select(nowait = false, &block)
                 if nowait && block
-                  raise "You can't use Confirm.Select with nowait=true and a callback at the same time."
+                  raise ArgumentError, "confirm.select with nowait = true and a callback makes no sense"
                 end
 
                 @uses_publisher_confirmations = true
-                self.redefine_callback(:confirm_select, &block)
+                self.redefine_callback(:confirm_select, &block) unless nowait
                 @connection.send_frame(Protocol::Confirm::Select.encode(@id, nowait))
 
                 self
@@ -220,9 +220,9 @@ module AMQ
               # @see AMQ::Client::Exchange#publish
               # @see AMQ::Client::Extensions::RabbitMQ::Channel#publisher_index
               # @return [self] self
-              def publish(*args)
+              def publish(*args, &block)
                 super(*args)
-                @channel.after_publish(*args)
+                @channel.after_publish(*args, &block)
 
                 self
               end # publish

data/lib/amq/client/async/queue.rb

@@ -3,7 +3,9 @@
 require "amq/client/async/entity"
 require "amq/client/adapter"
 require "amq/client/server_named_entity"
+
 require "amq/protocol/get_response"
+require "amq/client/async/consumer"
 
 module AMQ
   module Client
@@ -24,13 +26,26 @@ module AMQ
         #
 
         # Qeueue name. May be server-generated or assigned directly.
+        # @return [String]
         attr_reader :name
 
         # Channel this queue belongs to.
+        # @return [AMQ::Client::Channel]
         attr_reader :channel
 
-        # Consumer tag identifies subscription for message delivery. It is nil for queues that are not subscribed for messages. See AMQ::Client::Queue#subscribe.
-        attr_reader :consumer_tag
+        # @return [Array<Hash>] All consumers on this queue.
+        attr_reader :consumers
+
+        # @return [AMQ::Client::Consumer] Default consumer (registered with {Queue#consume}).
+        attr_reader :default_consumer
+
+        # @return [Hash] Additional arguments given on queue declaration. Typically used by AMQP extensions.
+        attr_reader :arguments
+
+        # @return [Array<Hash>]
+        attr_reader :bindings
+
+
 
         # @param  [AMQ::Client::Adapter]  AMQ networking adapter to use.
         # @param  [AMQ::Client::Channel]  AMQ channel this queue object uses.
@@ -41,18 +56,22 @@ module AMQ
 
           super(connection)
 
-          @name    = name
-          @channel = channel
-        end
-
-        def dup
-          if @name.empty?
-            raise RuntimeError.new("You can't clone anonymous queue until it receives server-generated name. Move the code with #dup to the callback for the #declare method.")
+          @name         = name
+          # this has to stay true even after queue.declare-ok arrives. MK.
+          @server_named = @name.empty?
+          if @server_named
+            self.on_connection_interruption do
+              # server-named queue need to get new names after recovery. MK.
+              @name = AMQ::Protocol::EMPTY_STRING
+            end
           end
 
-          o = super
-          o.reset_consumer_tag!
-          o
+          @channel      = channel
+
+          # primarily for autorecovery. MK.
+          @bindings  = Array.new
+
+          @consumers = Hash.new
         end
 
 
@@ -75,6 +94,8 @@ module AMQ
         end # auto_delete?
 
 
+        # @group Declaration
+
         # Declares this queue.
         #
         #
@@ -85,9 +106,14 @@ module AMQ
         def declare(passive = false, durable = false, exclusive = false, auto_delete = false, nowait = false, arguments = nil, &block)
           raise ArgumentError, "declaration with nowait does not make sense for server-named queues! Either specify name other than empty string or use #declare without nowait" if nowait && self.anonymous?
 
+          # these two are for autorecovery. MK.
+          @passive      = passive
+          @server_named = @name.empty?
+
           @durable     = durable
           @exclusive   = exclusive
           @auto_delete = auto_delete
+          @arguments   = arguments
 
           nowait = true if !block && !@name.empty?
           @connection.send_frame(Protocol::Queue::Declare.encode(@channel.id, @name, passive, durable, exclusive, auto_delete, nowait, arguments))
@@ -100,6 +126,31 @@ module AMQ
           self
         end
 
+        # Re-declares queue with the same attributes
+        # @api public
+        def redeclare(&block)
+          nowait = true if !block && !@name.empty?
+
+          # server-named queues get their new generated names.
+          new_name = if @server_named
+                       AMQ::Protocol::EMPTY_STRING
+                     else
+                       @name
+                     end
+          @connection.send_frame(Protocol::Queue::Declare.encode(@channel.id, new_name, @passive, @durable, @exclusive, @auto_delete, false, @arguments))
+
+          if !nowait
+            self.append_callback(:declare, &block)
+            @channel.queues_awaiting_declare_ok.push(self)
+          end
+
+          self
+        end
+
+        # @endgroup
+
+
+
         # Deletes this queue.
         #
         # @param [Boolean] if_unused  delete only if queue has no consumers (subscribers).
@@ -123,6 +174,10 @@ module AMQ
           self
         end # delete(channel, queue, if_unused, if_empty, nowait, &block)
 
+
+
+        # @group Binding
+
         #
         # @return [Queue]  self
         #
@@ -141,11 +196,14 @@ module AMQ
 
           if !nowait
             self.append_callback(:bind, &block)
-
-            # TODO: handle channel & connection-level exceptions
             @channel.queues_awaiting_bind_ok.push(self)
           end
 
+          # store bindings for automatic recovery, but BE VERY CAREFUL to
+          # not cause an infinite rebinding loop here when we recover. MK.
+          binding = { :exchange => exchange_name, :routing_key => routing_key, :arguments => arguments }
+          @bindings.push(binding) unless @bindings.include?(binding)
+
           self
         end
 
@@ -165,12 +223,34 @@ module AMQ
           @connection.send_frame(Protocol::Queue::Unbind.encode(@channel.id, @name, exchange_name, routing_key, arguments))
 
           self.append_callback(:unbind, &block)
-          # TODO: handle channel & connection-level exceptions
           @channel.queues_awaiting_unbind_ok.push(self)
 
+
+          @bindings.delete_if { |b| b[:exchange] == exchange_name }
+
           self
         end
 
+        # Used by automatic recovery machinery.
+        # @private
+        # @api plugin
+        def rebind(&block)
+          @bindings.each { |b| self.bind(b[:exchange], b[:routing_key], true, b[:arguments]) }
+        end
+
+        # @endgroup
+
+
+
+
+        # @group Consuming messages
+
+        # @return [Class] AMQ::Client::Consumer or other class implementing consumer API. Used by libraries like {https://github.com/ruby-amqp/amqp Ruby amqp gem}.
+        # @api plugin
+        def self.consumer_class
+          AMQ::Client::Async::Consumer
+        end # self.consumer_class
+
 
         #
         # @return [Queue]  self
@@ -178,46 +258,44 @@ module AMQ
         # @api public
         # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.8.3.3.)
         def consume(no_ack = false, exclusive = false, nowait = false, no_local = false, arguments = nil, &block)
-          raise RuntimeError.new("This instance is already being consumed! Create another one using #dup.") if @consumer_tag
+          raise RuntimeError.new("This queue already has default consumer. Please instantiate AMQ::Client::Consumer directly to register additional consumers.") if @default_consumer
 
-          nowait        = true unless block
-          @consumer_tag = generate_consumer_tag(name)
-          @connection.send_frame(Protocol::Basic::Consume.encode(@channel.id, @name, @consumer_tag, no_local, no_ack, exclusive, nowait, arguments))
+          nowait            = true unless block
+          @default_consumer = self.class.consumer_class.new(@channel, self, generate_consumer_tag(@name), exclusive, no_ack, arguments, no_local, &block)
+          @default_consumer.consume(nowait, &block)
 
-          @channel.consumers[@consumer_tag] = self
+          self
+        end
 
-          if !nowait
-            # unlike #get, here it is reasonable to expect more than one callback
-            # so we use #append_callback
-            self.append_callback(:consume, &block)
+        # Unsubscribes from message delivery.
+        # @return [Queue]  self
+        #
+        # @api public
+        # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.8.3.5.)
+        def cancel(nowait = false, &block)
+          raise "There is no default consumer for this queue. This usually means that you are trying to unsubscribe a queue that never was subscribed for messages in the first place." if @default_consumer.nil?
 
-            @channel.queues_awaiting_consume_ok.push(self)
-          end
+          @default_consumer.cancel(nowait, &block)
 
           self
-        end
+        end # cancel(&block)
 
-        # Unique string supposed to be used as a consumer tag.
-        #
-        # @return [String]  Unique string.
-        # @api plugin
-        def generate_consumer_tag(name)
-          "#{name}-#{Time.now.to_i * 1000}-#{Kernel.rand(999_999_999_999)}"
-        end
+        # @endgroup
 
-        # Resets consumer tag by setting it to nil.
-        # @return [String]  Consumer tag this queue previously used.
-        #
-        # @api plugin
-        def reset_consumer_tag!
-          ct = @consumer_tag.dup
-          @consumer_tag = nil
 
-          ct
-        end
 
 
-        #
+        # @group Working With Messages
+
+
+        # @api public
+        # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Sections 1.8.3.9)
+        def on_delivery(&block)
+          @default_consumer.on_delivery(&block)
+        end # on_delivery(&block)
+
+
+        # Fetches messages from the queue.
         # @return [Queue]  self
         #
         # @api public
@@ -236,28 +314,9 @@ module AMQ
           self
         end # get(no_ack = false, &block)
 
-        #
-        # @return [Queue]  self
-        #
-        # @api public
-        # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.8.3.5.)
-        def cancel(nowait = false, &block)
-          raise "There is no consumer tag for this queue. This usually means that you are trying to unsubscribe a queue that never was subscribed for messages in the first place." if @consumer_tag.nil?
-
-          @connection.send_frame(Protocol::Basic::Cancel.encode(@channel.id, @consumer_tag, nowait))
-          @consumer_tag = nil
-          self.clear_callbacks(:delivery)
-          self.clear_callbacks(:consume)
 
-          if !nowait
-            self.redefine_callback(:cancel, &block)
-            @channel.queues_awaiting_cancel_ok.push(self)
-          end
 
-          self
-        end # cancel(&block)
-
-        #
+        # Purges (removes all messagse from) the queue.
         # @return [Queue]  self
         #
         # @api public
@@ -275,7 +334,13 @@ module AMQ
           self
         end # purge(nowait = false, &block)
 
-        #
+        # @endgroup
+
+
+
+        # @group Acknowledging & Rejecting Messages
+
+        # Acknowledge a delivery tag.
         # @return [Queue]  self
         #
         # @api public
@@ -297,22 +362,103 @@ module AMQ
           self
         end # reject(delivery_tag, requeue = true)
 
+        # @endgroup
+
+
 
 
+        # @group Error Handling & Recovery
+
+        # Defines a callback that will be executed after TCP connection is interrupted (typically because of a network failure).
+        # Only one callback can be defined (the one defined last replaces previously added ones).
+        #
         # @api public
-        # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Sections 1.8.3.9)
-        def on_delivery(&block)
-          self.append_callback(:delivery, &block)
-        end # on_delivery(&block)
+        def on_connection_interruption(&block)
+          self.redefine_callback(:after_connection_interruption, &block)
+        end # on_connection_interruption(&block)
+        alias after_connection_interruption on_connection_interruption
+
+        # @private
+        def handle_connection_interruption(method = nil)
+          @consumers.each { |tag, consumer| consumer.handle_connection_interruption(method) }
+
+          self.exec_callback_yielding_self(:after_connection_interruption)
+        end # handle_connection_interruption
+
+        # Defines a callback that will be executed after TCP connection is recovered after a network failure
+        # but before AMQP connection is re-opened.
+        # Only one callback can be defined (the one defined last replaces previously added ones).
+        #
+        # @api public
+        def before_recovery(&block)
+          self.redefine_callback(:before_recovery, &block)
+        end # before_recovery(&block)
+
+        # @private
+        def run_before_recovery_callbacks
+          self.exec_callback_yielding_self(:before_recovery)
+
+          @consumers.each { |tag, c| c.run_before_recovery_callbacks }
+        end
+
+
+        # Defines a callback that will be executed when AMQP connection is recovered after a network failure..
+        # Only one callback can be defined (the one defined last replaces previously added ones).
+        #
+        # @api public
+        def on_recovery(&block)
+          self.redefine_callback(:after_recovery, &block)
+        end # on_recovery(&block)
+        alias after_recovery on_recovery
+
+        # @private
+        def run_after_recovery_callbacks
+          self.exec_callback_yielding_self(:after_recovery)
+
+          @consumers.each { |tag, c| c.run_after_recovery_callbacks }
+        end
+
+
+
+        # Called by associated connection object when AMQP connection has been re-established
+        # (for example, after a network failure).
+        #
+        # @api plugin
+        def auto_recover
+          self.exec_callback_yielding_self(:before_recovery)
+          self.redeclare do
+            self.rebind
+
+            @consumers.each { |tag, consumer| consumer.auto_recover }
 
+            self.exec_callback_yielding_self(:after_recovery)
+          end
+        end # auto_recover
+
+        # @endgroup
 
 
         #
         # Implementation
         #
 
+
+        # Unique string supposed to be used as a consumer tag.
+        #
+        # @return [String]  Unique string.
+        # @api plugin
+        def generate_consumer_tag(name)
+          "#{name}-#{Time.now.to_i * 1000}-#{Kernel.rand(999_999_999_999)}"
+        end
+
+
+        def handle_connection_interruption(method = nil)
+          @consumers.each { |tag, c| c.handle_connection_interruption(method) }
+        end # handle_connection_interruption(method = nil)
+
+
         def handle_declare_ok(method)
-          @name = method.queue if self.anonymous?
+          @name = method.queue if @name.empty?
           @channel.register_queue(self)
 
           self.exec_callback_once_yielding_self(:declare, method)
@@ -322,10 +468,6 @@ module AMQ
           self.exec_callback_once(:delete, method)
         end # handle_delete_ok(method)
 
-        def handle_consume_ok(method)
-          self.exec_callback_once(:consume, method)
-        end # handle_consume_ok(method)
-
         def handle_purge_ok(method)
           self.exec_callback_once(:purge, method)
         end # handle_purge_ok(method)
@@ -338,15 +480,6 @@ module AMQ
           self.exec_callback_once(:unbind, method)
         end # handle_unbind_ok(method)
 
-        def handle_delivery(method, header, payload)
-          self.exec_callback(:delivery, method, header, payload)
-        end # handle_delivery
-
-        def handle_cancel_ok(method)
-          @consumer_tag = nil
-          self.exec_callback_once(:cancel, method)
-        end # handle_cancel_ok(method)
-
         def handle_get_ok(method, header, payload)
           method = Protocol::GetResponse.new(method)
           self.exec_callback(:get, method, header, payload)
@@ -394,35 +527,6 @@ module AMQ
         end
 
 
-        self.handle(Protocol::Basic::ConsumeOk) do |connection, frame|
-          channel = connection.channels[frame.channel]
-          queue   = channel.queues_awaiting_consume_ok.shift
-
-          queue.handle_consume_ok(frame.decode_payload)
-        end
-
-
-        self.handle(Protocol::Basic::CancelOk) do |connection, frame|
-          channel = connection.channels[frame.channel]
-          queue   = channel.queues_awaiting_cancel_ok.shift
-
-          queue.handle_consume_ok(frame.decode_payload)
-        end
-
-
-        # Basic.Deliver
-        self.handle(Protocol::Basic::Deliver) do |connection, method_frame, content_frames|
-          channel  = connection.channels[method_frame.channel]
-          method   = method_frame.decode_payload
-          queue    = channel.consumers[method.consumer_tag]
-
-          header = content_frames.shift
-          body   = content_frames.map { |frame| frame.payload }.join
-          queue.handle_delivery(method, header, body)
-          # TODO: ack if necessary
-        end
-
-
         self.handle(Protocol::Queue::PurgeOk) do |connection, frame|
           channel = connection.channels[frame.channel]
           queue   = channel.queues_awaiting_purge_ok.shift
@@ -449,7 +553,7 @@ module AMQ
 
           queue.handle_get_empty(frame.decode_payload)
         end
-      end # Queue      
+      end # Queue
     end # Async
   end # Client
 end # AMQ