amq-client 0.5.0

data/lib/amq/client/entity.rb

@@ -0,0 +1,117 @@
+# encoding: utf-8
+
+require "amq/client/mixins/status"
+
+module AMQ
+  module Client
+    # AMQ entities, as implemented by AMQ::Client, have callbacks and can run them
+    # when necessary.
+    #
+    # @note Exchanges and queues implementation is based on this class.
+    #
+    # @abstract
+    class Entity
+
+      #
+      # Behaviors
+      #
+
+      include StatusMixin
+
+      #
+      # API
+      #
+
+      # @return [Array<#call>]
+      attr_reader :callbacks
+
+      @@handlers ||= Hash.new
+
+      def self.handle(klass, &block)
+        @@handlers[klass] = block
+      end
+
+      def self.handlers
+        @@handlers
+      end
+
+
+
+
+      def initialize(client)
+        @client    = client
+        # Be careful with default values for #ruby hashes: h = Hash.new(Array.new); h[:key] ||= 1
+        # won't assign anything to :key. MK.
+        @callbacks = Hash.new
+      end
+
+
+      def redefine_callback(event, callable = nil, &block)
+        f = (callable || block)
+        # yes, re-assign!
+        @callbacks[event] = [f]
+
+        self
+      end
+
+      def define_callback(event, callable = nil, &block)
+        f = (callable || block)
+
+        @callbacks[event] ||= []
+        @callbacks[event] << f if f
+
+        self
+      end # define_callback(event, &block)
+      alias append_callback define_callback
+
+      def prepend_callback(event, &block)
+        @callbacks[event] ||= []
+        @callbacks[event].unshift(block)
+
+        self
+      end # prepend_callback(event, &block)
+
+      def clear_callbacks(event)
+        @callbacks[event].clear if @callbacks[event]
+      end # clear_callbacks(event)
+
+
+      def exec_callback(name, *args, &block)
+        callbacks = Array(self.callbacks[name])
+        callbacks.map { |c| c.call(*args, &block) } if callbacks.any?
+      end
+
+      def exec_callback_once(name, *args, &block)
+        callbacks = Array(self.callbacks.delete(name))
+        callbacks.map { |c| c.call(*args, &block) } if callbacks.any?
+      end
+
+      def exec_callback_yielding_self(name, *args, &block)
+        callbacks = Array(self.callbacks[name])
+        callbacks.map { |c| c.call(self, *args, &block) } if callbacks.any?
+      end
+
+      def exec_callback_once_yielding_self(name, *args, &block)
+        callbacks = Array(self.callbacks.delete(name))
+        callbacks.map { |c| c.call(self, *args, &block) } if callbacks.any?
+      end
+
+
+
+      def error(exception)
+        if client.sync? # DO NOT DO THIS, just add a default errback to do exactly this, so if someone wants to use begin/rescue, he'll just ignore the errbacks.
+          # Synchronous error handling.
+          # Just use begin/rescue in the main loop.
+          raise exception
+        else
+          # Asynchronous error handling.
+          # Set callback for given class (Queue for example)
+          # or for the Connection class (or instance, of course).
+          callbacks = [self.callbacks[:close], self.client.connection.callbacks[:close]].flatten.compact
+
+          callbacks.map { |c| c.call(exception) } if callbacks.any?
+        end
+      end
+    end
+  end
+end

data/lib/amq/client/exceptions.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+
+module AMQ
+  module Client
+
+    #
+    # Adapters
+    #
+
+    # Base exception class for data consistency and framing errors.
+    class InconsistentDataError < StandardError
+    end
+
+    # Raised by adapters when frame does not end with {final octet AMQ::Protocol::Frame::FINAL_OCTET}.
+    # This suggest that there is a bug in adapter or AMQ broker implementation.
+    #
+    # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 2.3)
+    class NoFinalOctetError < InconsistentDataError
+      def initialize
+        super("Frame doesn't end with #{AMQ::Protocol::Frame::FINAL_OCTET} as it must, which means the size is miscalculated.")
+      end
+    end
+
+    # Raised by adapters when actual frame payload size in bytes is not equal
+    # to the size specified in that frame's header.
+    # This suggest that there is a bug in adapter or AMQ broker implementation.
+    #
+    # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 2.3)
+    class BadLengthError < InconsistentDataError
+      def initialize(expected_length, actual_length)
+        super("Frame payload should be #{expected_length} long, but it's #{actual_length} long.")
+      end
+    end
+
+    #
+    # Client
+    #
+
+    class MissingInterfaceMethodError < NotImplementedError
+      def initialize(method_name)
+        super("Method #{method_name} is supposed to be overriden by adapter")
+      end
+    end
+
+    class MissingHandlerError < StandardError
+      def initialize(frame)
+        super("No callback registered for #{frame.method_class}")
+      end
+    end
+
+    class ConnectionClosedError < StandardError
+      def initialize(frame)
+        if frame.respond_to?(:method_class)
+          super("Trying to send frame through a closed connection. Frame is #{frame.inspect}")
+        else
+          super("Trying to send frame through a closed connection. Frame is #{frame.inspect}, method class is #{frame.method_class}")
+        end
+      end # initialize
+    end # class ConnectionClosedError
+
+    module Logging
+      # Raised when logger object passed to {AMQ::Client::Adapter.logger=} does not
+      # provide API it supposed to provide.
+      #
+      # @see AMQ::Client::Adapter.logger=
+      class IncompatibleLoggerError < StandardError
+        def initialize(required_methods)
+          super("Logger has to respond to the following methods: #{required_methods.inspect}")
+        end
+      end
+    end # Logging
+
+
+    class PossibleAuthenticationFailureError < StandardError
+
+      #
+      # API
+      #
+
+      def initialize(settings)
+        super("AMQP broker closed TCP connection before authentication succeeded: this usually means authentication failure due to misconfiguration. Settings are #{settings.inspect}")
+      end # initialize(settings)
+    end # PossibleAuthenticationFailureError
+
+  end # Client
+end # AMQ

data/lib/amq/client/exchange.rb

@@ -0,0 +1,163 @@
+# encoding: utf-8
+
+require "amq/client/entity"
+require "amq/client/mixins/anonymous_entity"
+
+module AMQ
+  module Client
+    class Exchange < Entity
+      include AnonymousEntityMixin
+
+      TYPES = [:fanout, :direct, :topic, :headers].freeze
+
+      class IncompatibleExchangeTypeError < StandardError
+        def initialize(types, given)
+          super("Exchange types are #{TYPES.inspect}, #{given.inspect} given.")
+        end
+      end
+
+
+      #
+      # API
+      #
+
+      # Channel this exchange belongs to.
+      attr_reader :channel
+
+      # Exchange name. May be server-generated or assigned directly.
+      attr_reader :name
+
+      # @return [Symbol] One of :direct, :fanout, :topic, :headers
+      attr_reader :type
+
+      def initialize(client, channel, name, type = :fanout)
+        unless TYPES.include?(type.to_sym)
+          raise IncompatibleExchangeTypeError.new(TYPES, type)
+        end
+
+        @client  = client
+        @channel = channel
+        @name    = name
+        @type    = type
+
+        # register pre-declared exchanges
+        if @name == AMQ::Protocol::EMPTY_STRING || @name =~ /^amq\.(fanout|topic)/
+          @channel.register_exchange(self)
+        end
+
+        super(client)
+      end
+
+
+      def fanout?
+        @type == :fanout
+      end
+
+      def direct?
+        @type == :direct
+      end
+
+      def topic?
+        @type == :topic
+      end
+
+
+
+      def declare(passive = false, durable = false, exclusive = false, auto_delete = false, nowait = false, arguments = nil, &block)
+        @client.send(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
+
+
+        if @client.sync?
+          @client.read_until_receives(Protocol::Exchange::DeclareOk) unless nowait
+        end
+
+        self
+      end
+
+
+      def delete(if_unused = false, nowait = false, &block)
+        @client.send(Protocol::Exchange::Delete.encode(@channel.id, @name, if_unused, nowait))
+
+        unless nowait
+          self.define_callback(:delete, &block)
+
+          # TODO: delete itself from exchanges cache
+          @channel.exchanges_awaiting_delete_ok.push(self)
+        end
+
+        self
+      end # delete(if_unused = false, nowait = false)
+
+
+      def publish(payload, routing_key = AMQ::Protocol::EMPTY_STRING, user_headers = {}, mandatory = false, immediate = false, frame_size = nil, &block)
+        headers = { :priority => 0, :delivery_mode => 2, :content_type => "application/octet-stream" }.merge(user_headers)
+        @client.send_frameset(Protocol::Basic::Publish.encode(@channel.id, payload, headers, @name, routing_key, mandatory, immediate, (frame_size || @client.connection.frame_max)))
+
+        block.call if block
+
+        self
+      end
+
+
+      def on_return(&block)
+        self.redefine_callback(:return, &block)
+
+        self
+      end # on_return(&block)
+
+
+
+
+      def handle_declare_ok(method)
+        @name = method.exchange if self.anonymous?
+        @channel.register_exchange(self)
+
+        self.exec_callback_once_yielding_self(:declare, method)
+      end
+
+      def handle_delete_ok(method)
+        self.exec_callback_once(:delete, method)
+      end # handle_delete_ok(method)
+
+
+
+      # === Handlers ===
+      # Get the first exchange which didn't receive Exchange.Declare-Ok yet and run its declare callback.
+      # The cache includes only exchanges with {nowait: false}.
+      self.handle(Protocol::Exchange::DeclareOk) do |client, frame|
+        method = frame.decode_payload
+
+        # We should have cache API, so it'll be easy to change caching behaviour easily.
+        # So in the amq-client we don't want to cache more than just the last instance per each channel,
+        # whereas more opinionated clients might want to have every single instance in the cache,
+        # so they can iterate over it etc.
+        channel = client.connection.channels[frame.channel]
+        exchange = channel.exchanges_awaiting_declare_ok.shift
+
+        exchange.handle_declare_ok(method)
+      end # handle
+
+
+      self.handle(Protocol::Exchange::DeleteOk) do |client, frame|
+        channel  = client.connection.channels[frame.channel]
+        exchange = channel.exchanges_awaiting_delete_ok.shift
+        exchange.handle_delete_ok(frame.decode_payload)
+      end # handle
+
+
+      self.handle(Protocol::Basic::Return) do |client, frame|
+        channel  = client.connection.channels[frame.channel]
+        method   = frame.decode_payload
+        exchange = channel.find_exchange(method.exchange)
+
+        exchange.exec_callback(:return, method)
+      end
+
+    end # Exchange
+  end # Client
+end # AMQ

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

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+# http://www.rabbitmq.com/extensions.html
+require "amq/client/extensions/rabbitmq/basic"
+require "amq/client/extensions/rabbitmq/confirm"

data/lib/amq/client/extensions/rabbitmq/basic.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+require "amq/client/channel"
+
+# Basic.Nack
+module AMQ
+  module Client
+    module Extensions
+      module RabbitMQ
+        module Basic
+          module ChannelMixin
+
+            # Overrides {AMQ::Client::Channel#reject} behavior to use basic.nack.
+            #
+            # @api public
+            # @see http://www.rabbitmq.com/amqp-0-9-1-quickref.html#basic.nack
+            def reject(delivery_tag, requeue = true, multi = false)
+              if multi
+                @client.send(Protocol::Basic::Nack.encode(self.id, delivery_tag, multi, requeue))
+              else
+                super(delivery_tag, requeue)
+              end
+            end # reject
+
+          end # ChannelMixin
+        end # Basic
+      end # RabbitMQ
+    end # Extensions
+
+    class Channel
+      # use modules, a native Ruby way of extension of existing classes,
+      # instead of reckless monkey-patching. MK.      
+      include Extensions::RabbitMQ::Basic::ChannelMixin
+    end
+  end # Client
+end # AMQ

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

@@ -0,0 +1,254 @@
+# encoding: utf-8
+
+# === Purpose === #
+# In case that the broker crashes, some messages can get lost.
+# Thanks to this extension, broker sends Basic.Ack when the message
+# is processed by the broker. In case of persistent messages, it must
+# be written to disk or ack'd on all the queues it was delivered to.
+# However it doesn't have to be necessarily 1:1, because the broker
+# can send Basic.Ack with multi flag to acknowledge multiple messages.
+#
+# So it provides clients a lightweight way of keeping track of which
+# messages have been processed by the broker and which would need
+# re-publishing in case of broker shutdown or network failure.
+#
+# Transactions are solving the same problem, but they are very slow:
+# confirmations are more than 100 times faster.
+#
+# === Workflow === #
+# * Client asks broker to confirm messages on given channel (Confirm.Select).
+# * Broker sends back Confirm.Select-Ok, unless we sent Confirm.Select with nowait=true.
+# * After each published message, the client receives Basic.Ack from the broker.
+# * If something bad happens inside the broker, it sends Basic.Nack.
+#
+# === Gotchas === #
+# Note that we don't keep track of messages awaiting confirmation.
+# It'd add a huge overhead and it's impossible to come up with one-suits-all solution.
+# If you want to create such module, you'll probably want to redefine Channel#after_publish,
+# so it will put messages into a queue and then handlers for Basic.Ack and Basic.Nack.
+# This is the reason why we pass every argument from Exchange#publish to Channel#after_publish.
+# You should not forget though, that both of these methods can have multi flag!
+#
+# Transactional channel cannot be put into confirm mode and a confirm
+# mode channel cannot be made transactional.
+#
+# If the connection between the publisher and broker drops with outstanding
+# confirms, it does not necessarily mean that the messages were lost, so
+# republishing may result in duplicate messages.
+
+# === Links === #
+# http://www.rabbitmq.com/blog/2011/02/10/introducing-publisher-confirms
+# http://www.rabbitmq.com/amqp-0-9-1-quickref.html#class.confirm
+# http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.ack
+
+puts "in confirm.rb"
+
+module AMQ
+  module Client
+    module Extensions
+      module RabbitMQ
+        module Confirm
+          module ChannelMixin
+            # Boolean value expressing whether confirmations are
+            # on or off, aka whether Confirm.Select was sent or not.
+            #
+            # @api public
+            # @return [Boolean] Whether confirmations are on or off.
+            attr_reader :confirmations
+
+            # Change publisher index. Publisher index is incremented
+            # by 1 after each Basic.Publish starting at 1. This is done
+            # on both client and server, hence this acknowledged messages
+            # can be matched via its delivery-tag.
+            #
+            # @api private
+            attr_writer :publisher_index
+
+            # Publisher index is an index of the last message since
+            # the confirmations were activated, started with 1. It's
+            # incremented by 1 after each Basic.Publish starting at 1.
+            # This is done on both client and server, hence this
+            # acknowledged messages can be matched via its delivery-tag.
+            #
+            # @return [Integer] Current publisher index.
+            # @api public
+            def publisher_index
+              @publisher_index ||= 1
+            end
+
+            # Resets publisher index to 0
+            #
+            # @api plugin
+            def reset_publisher_index!
+              @publisher_index = 0
+            end
+
+
+            # This method is executed after publishing of each message via {Exchage#publish}.
+            # Currently it just increments publisher index by 1, so messages
+            # can be actually matched.
+            #
+            # @api plugin
+            def after_publish(*args)
+              self.publisher_index += 1
+            end
+
+            # Turn on confirmations for this channel and, if given,
+            # register callback for Confirm.Select-Ok.
+            #
+            # @raise [RuntimeError] Occurs when confirmations are already activated.
+            # @raise [RuntimeError] Occurs when nowait is true and block is given.
+            #
+            # @param [Boolean] nowait Whether we expect Confirm.Select-Ok to be returned by the broker or not.
+            # @yield [method] Callback which will be executed once we receive Confirm.Select-Ok.
+            # @yieldparam [AMQ::Protocol::Confirm::SelectOk] method Protocol method class instance.
+            #
+            # @return [self] self.
+            #
+            # @see #confirm
+            def confirmations(nowait = false, &block)
+              if @confirmations
+                raise "Confirmations are already activated!"
+              end
+
+              if nowait && block
+                raise "You can't use Confirm.Select with nowait=true and a callback at the same time."
+              end
+
+              @confirmations = true
+              self.redefine_callback(:confirmations, &block)
+              @client.send(Protocol::Confirm::Select.encode(@id, nowait))
+
+              self
+            end
+
+
+            # Turn on confirmations for this channel and, if given,
+            # register callback for basic.ack from the broker.
+            #
+            # @raise [RuntimeError] Occurs when confirmations are already activated.
+            # @raise [RuntimeError] Occurs when nowait is true and block is given.
+            # @param [Boolean] nowait Whether we expect Confirm.Select-Ok to be returned by the broker or not.
+            #
+            # @yield [basick_ack] Callback which will be executed every time we receive Basic.Ack from the broker.
+            # @yieldparam [AMQ::Protocol::Basic::Ack] basick_ack Protocol method class instance.
+            #
+            # @return [self] self.
+            def confirm(nowait = false, &block)
+              self.confirmations unless @confirmations
+
+              self.define_callback(:ack, &block) if block
+
+              self
+            end
+
+
+            # Register error callback for Basic.Nack. It's called
+            # when the broker reject given message(s).
+            #
+            # @return [self] self
+            def confirm_failed(&block)
+              self.define_callback(:nack, &block) if block
+
+              self
+            end
+
+
+
+
+            # Handler for Confirm.Select-Ok. By default, it just
+            # executes hook specified via the #confirmations method
+            # with a single argument, a protocol method class
+            # instance (an instance of AMQ::Protocol::Confirm::SelectOk)
+            # and then it deletes the callback, since Confirm.Select
+            # is supposed to be sent just once.
+            #
+            # @api plugin
+            def handle_select_ok(method)
+              self.exec_callback_once(:confirmations, method)
+            end
+
+            # Handler for Basic.Ack. By default, it just
+            # executes hook specified via the #confirm method
+            # with a single argument, a protocol method class
+            # instance (an instance of AMQ::Protocol::Basic::Ack).
+            #
+            # @api plugin
+            def handle_basic_ack(method)
+              self.exec_callback(:ack, method)
+            end
+
+
+            # Handler for Basic.Nack. By default, it just
+            # executes hook specified via the #confirm_failed method
+            # with a single argument, a protocol method class
+            # instance (an instance of AMQ::Protocol::Basic::Nack).
+            #
+            # @api plugin
+            def handle_basic_nack(method)
+              self.exec_callback(:nack, method)
+            end
+
+
+            def reset_state!
+              super
+
+              @confirmations = false
+            end
+
+
+            def self.included(host)
+              host.handle(Protocol::Confirm::SelectOk) do |client, frame|
+                method  = frame.decode_payload
+                channel = client.connection.channels[frame.channel]
+                channel.handle_select_ok(method)
+              end
+
+              host.handle(Protocol::Basic::Ack) do |client, frame|
+                method  = frame.decode_payload
+                channel = client.connection.channels[frame.channel]
+                channel.handle_basic_ack(method)
+              end
+
+              host.handle(Protocol::Basic::Nack) do |client, frame|
+                method  = frame.decode_payload
+                channel = client.connection.channels[frame.channel]
+                channel.handle_basic_nack(method)
+              end
+            end # self.included(host)
+          end # ChannelMixin
+
+
+          module ExchangeMixin
+            # Publish message and then run #after_publish on channel belonging
+            # to the exchange. This is used for incrementing the publisher index.
+            #
+            # @api public
+            # @see AMQ::Client::Exchange#publish
+            # @see AMQ::Client::Extensions::RabbitMQ::Channel#publisher_index
+            # @return [self] self
+            def publish(*args)
+              super(*args)
+              @channel.after_publish(*args)
+
+              self
+            end # publish
+          end # ExchangeMixin
+        end # Confirm
+      end # RabbitMQ
+    end # Extensions
+
+
+    class Channel
+      # use modules, a native Ruby way of extension of existing classes,
+      # instead of reckless monkey-patching. MK.
+      include Extensions::RabbitMQ::Confirm::ChannelMixin
+    end # Channel
+
+    class Exchange
+      # use modules, a native Ruby way of extension of existing classes,
+      # instead of reckless monkey-patching. MK.
+      include Extensions::RabbitMQ::Confirm::ExchangeMixin
+    end # Exchange
+  end # Client
+end # AMQ