amq-client 0.5.0

data/lib/amq/client/framing/io/frame.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+require "amq/client/exceptions"
+
+module AMQ
+  module Client
+    module Framing
+      module IO
+
+        class Frame < AMQ::Protocol::Frame
+          def self.decode(io)
+            header = io.read(7)
+            type, channel, size = self.decode_header(header)
+            data = io.read(size + 1)
+            payload, frame_end = data[0..-2], data[-1, 1]
+            # TODO: this will hang if the size is bigger than expected or it'll leave there some chars -> make it more error-proof:
+            # BTW: socket#eof?
+            raise NoFinalOctetError.new if frame_end != AMQ::Protocol::Frame::FINAL_OCTET
+            self.new(type, payload, channel)
+          end # self.from
+
+        end # Frame
+      end # IO
+    end # Framing
+  end # Client
+end # AMQ
+
+class AMQ::Protocol::Frame
+  def final?
+    true ####### HACK for testing, implement & move to amq-protocol!
+  end
+end

data/lib/amq/client/framing/string/frame.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+# This will be probably used by all the async libraries like EventMachine.
+# It expects the whole frame as one string, so if library of your choice
+# gives you input chunk-by-chunk, you'll need to have something like this:
+#
+# class Client
+#   include EventMachine::Deferrable
+#
+#   def receive_data(chunk)
+#     if @payload.nil?
+#       self.decode_from_string(chunk[0..6])
+#       @payload = ""
+#     elsif @payload && chunk[-1] != FINAL_OCTET
+#       @payload += chunk
+#       @size += chunk.bytesize
+#     else
+#       check_size(@size, @payload.bytesize)
+#       Frame.decode(@payload) # we need the whole payload
+#       @size, @payload = nil
+#     end
+#   end
+#
+#   NOTE: the client should also implement waiting for another frames, in case that some header/body frames are expected.
+# end
+
+require "amq/client/exceptions"
+
+module AMQ
+  module Client
+    module Framing
+      module String
+        class Frame < AMQ::Protocol::Frame
+          ENCODINGS_SUPPORTED = defined? Encoding
+          HEADER_SLICE = (0..6).freeze
+          DATA_SLICE = (7..-1).freeze
+          PAYLOAD_SLICE = (0..-2).freeze
+
+          def self.decode(string)
+            header              = string[HEADER_SLICE]
+            type, channel, size = self.decode_header(header)
+            data                = string[DATA_SLICE]
+            payload             = data[PAYLOAD_SLICE]
+            frame_end           = data[-1, 1]
+
+            frame_end.force_encoding(AMQ::Protocol::Frame::FINAL_OCTET.encoding) if ENCODINGS_SUPPORTED
+
+            # 1) the size is miscalculated
+            if payload.bytesize != size
+              raise BadLengthError.new(size, payload.bytesize)
+            end
+
+            # 2) the size is OK, but the string doesn't end with FINAL_OCTET
+            raise NoFinalOctetError.new if frame_end != AMQ::Protocol::Frame::FINAL_OCTET
+
+            self.new(type, payload, channel)
+          end # self.from
+        end # Frame
+      end # String
+    end # Framing
+  end # Client
+end # AMQ

data/lib/amq/client/logging.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+# You can use arbitrary logger which responds to #debug, #info, #error and #fatal methods, so for example the logger from standard library will work fine:
+#
+# AMQ::Client.logging = true
+# AMQ::Client.logger  = MyLogger.new(STDERR)
+#
+# AMQ::Client.logger defaults to a new instance of Ruby stdlib logger.
+#
+# If you want to be able to log messages just from specified classes or even instances, just make the instance respond to #logging and set it to desired value. So for example <tt>Queue.class_eval { def logging; true; end }</tt> will turn on logging for the whole Queue class whereas <tt>queue = Queue.new; def queue.logging; false; end</tt> will disable logging for given Queue instance.
+
+module AMQ
+  module Client
+    module Logging
+      def self.included(klass)
+        unless klass.method_defined?(:client)
+          raise NotImplementedError.new("Class #{klass} has to provide #client method!")
+        end
+      end
+
+      def self.logging
+        @logging ||= false
+      end
+
+      def self.logging=(boolean)
+        @logging = boolean
+      end
+
+      REQUIRED_METHODS = [:debug, :info, :error, :fatal].freeze
+
+      def debug(message)
+        log(:debug, message)
+      end
+
+      def info(message)
+        log(:info, message)
+      end
+
+      def error(message)
+        log(:error, message)
+      end
+
+      def fatal(message)
+        log(:fatal, message)
+      end
+
+      protected
+      def log(method, message)
+        if self.respond_to?(:logging) ? self.logging : AMQ::Client::Logging.logging
+          self.client.logger.__send__(method, message)
+          message
+        end
+      end
+    end
+  end
+end

data/lib/amq/client/mixins/anonymous_entity.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+module AMQ
+  module Client
+    # Common behavior of AMQ entities that can be either client or server-named, for example, exchanges and queues.
+    module AnonymousEntityMixin
+
+      # @return [Boolean] true if this entity is anonymous (server-named)
+      def anonymous?
+        @name.nil? or @name.empty?
+      end
+
+      def dup
+        if anonymous?
+          raise RuntimeError.new("You can't clone anonymous queue until it receives back the name in Queue.Declare-Ok response. Move the code with #dup to the callback for the #declare method.") # TODO: that's not true in all cases, imagine the user didn't call #declare yet.
+        end
+        super
+      end
+    end # AnonymousEntityMixin
+  end # Client
+end # AMQ

data/lib/amq/client/mixins/status.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+module AMQ
+  module Client
+    module StatusMixin
+      VALUES = [:opened, :closed, :opening, :closing].freeze
+
+      class ImproperStatusError < ArgumentError
+        def initialize(value)
+          super("Value #{value.inspect} isn't permitted. Choose one of: #{AMQ::Client::StatusMixin::VALUES.inspect}")
+        end
+      end
+
+      attr_reader :status
+      def status=(value)
+        if VALUES.include?(value)
+          @status = value
+        else
+          raise ImproperStatusError.new(value)
+        end
+      end
+
+      def opened?
+        @status == :opened
+      end
+      alias open? opened?
+
+      def closed?
+        @status == :closed
+      end
+
+
+
+      def opening?
+        @status == :opening
+      end
+
+      def closing?
+        @status == :closing
+      end
+
+
+      def opened!
+        @status = :opened
+      end # opened!
+
+      def closed!
+        @status = :closed
+      end # closed!
+
+
+
+      def opening!
+        @status = :opening
+      end # opening!
+
+      def closing!
+        @status = :closing
+      end # closing!
+    end
+  end
+end

data/lib/amq/client/protocol/get_response.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+# Purpose of this class is to simplify work with GetOk and GetEmpty.
+module AMQ
+  module Protocol
+    class GetResponse
+      attr_reader :method
+      def initialize(method)
+        @method = method
+      end
+
+      def empty?
+        @method.is_a?(::AMQ::Protocol::Basic::GetEmpty)
+      end
+
+      # GetOk attributes
+      def delivery_tag
+        if @method.respond_to?(:delivery_tag)
+          @method.delivery_tag
+        end
+      end
+
+      def redelivered
+        if @method.respond_to?(:redelivered)
+          @method.redelivered
+        end
+      end
+
+      def exchange
+        if @method.respond_to?(:exchange)
+          @method.exchange
+        end
+      end
+
+      def routing_key
+        if @method.respond_to?(:routing_key)
+          @method.routing_key
+        end
+      end
+
+      def message_count
+        if @method.respond_to?(:message_count)
+          @method.message_count
+        end
+      end
+
+      # GetEmpty attributes
+      def cluster_id
+        if @method.respond_to?(:cluster_id)
+          @method.cluster_id
+        end
+      end
+    end
+  end
+end

data/lib/amq/client/queue.rb

@@ -0,0 +1,450 @@
+# encoding: utf-8
+
+require "amq/client/entity"
+require "amq/client/adapter"
+require "amq/client/mixins/anonymous_entity"
+require "amq/client/protocol/get_response"
+
+module AMQ
+  module Client
+    class Queue < Entity
+
+      #
+      # Behaviors
+      #
+
+      include AnonymousEntityMixin
+
+
+      #
+      # API
+      #
+
+      # Qeueue name. May be server-generated or assigned directly.
+      attr_reader :name
+
+      # Channel this queue belongs to.
+      attr_reader :channel
+
+      # @param  [AMQ::Client::Adapter]  AMQ networking adapter to use.
+      # @param  [AMQ::Client::Channel]  AMQ channel this queue object uses.
+      # @param  [String]                Queue name. Please note that AMQP spec does not require brokers to support Unicode for queue names.
+      # @api public
+      def initialize(client, channel, name = AMQ::Protocol::EMPTY_STRING)
+        super(client)
+
+        @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.")
+        end
+
+        o = super
+        o.reset_consumer_tag!
+        o
+      end
+
+
+      # @return [Boolean] true if this queue was declared as durable (will survive broker restart).
+      # @api public
+      def durable?
+        @durable
+      end # durable?
+
+      # @return [Boolean] true if this queue was declared as exclusive (limited to just one consumer)
+      # @api public
+      def exclusive?
+        @exclusive
+      end # exclusive?
+
+      # @return [Boolean] true if this queue was declared as automatically deleted (deleted as soon as last consumer unbinds).
+      # @api public
+      def auto_delete?
+        @auto_delete
+      end # auto_delete?
+
+
+      # Declares this queue.
+      #
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.7.2.1.)
+      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?
+
+        @durable     = durable
+        @exclusive   = exclusive
+        @auto_delete = auto_delete
+
+        nowait = true if !block && !@name.empty?
+        @client.send(Protocol::Queue::Declare.encode(@channel.id, @name, passive, durable, exclusive, auto_delete, nowait, arguments))
+
+        if !nowait
+          self.append_callback(:declare, &block)
+          @channel.queues_awaiting_declare_ok.push(self)
+        end
+
+        if @client.sync?
+          @client.read_until_receives(Protocol::Queue::DeclareOk) unless nowait
+        end
+
+        self
+      end
+
+      # Deletes this queue.
+      #
+      # @param [Boolean] if_unused  delete only if queue has no consumers (subscribers).
+      # @param [Boolean] if_empty   delete only if queue has no messages in it.
+      # @param [Boolean] nowait     Don't wait for reply from broker.
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.7.2.9.)
+      def delete(if_unused = false, if_empty = false, nowait = false, &block)
+        nowait = true unless block
+        @client.send(Protocol::Queue::Delete.encode(@channel.id, @name, if_unused, if_empty, nowait))
+
+        if !nowait
+          self.append_callback(:delete, &block)
+
+          # TODO: delete itself from queues cache
+          @channel.queues_awaiting_delete_ok.push(self)
+        end
+
+        self
+      end # delete(channel, queue, if_unused, if_empty, nowait, &block)
+
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.7.2.3.)
+      def bind(exchange, routing_key = AMQ::Protocol::EMPTY_STRING, nowait = false, arguments = nil, &block)
+        nowait = true unless block
+        exchange_name = if exchange.respond_to?(:name)
+                          exchange.name
+                        else
+
+                          exchange
+                        end
+
+        @client.send(Protocol::Queue::Bind.encode(@channel.id, @name, exchange_name, routing_key, nowait, arguments))
+
+        if !nowait
+          self.append_callback(:bind, &block)
+
+          # TODO: handle channel & connection-level exceptions
+          @channel.queues_awaiting_bind_ok.push(self)
+        end
+
+        self
+      end
+
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.7.2.5.)
+      def unbind(exchange, routing_key = AMQ::Protocol::EMPTY_STRING, arguments = nil, &block)
+        exchange_name = if exchange.respond_to?(:name)
+                          exchange.name
+                        else
+
+                          exchange
+                        end
+
+        @client.send(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)
+
+        self
+      end
+
+
+      #
+      # @return [Queue]  self
+      #
+      # @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
+
+        nowait        = true unless block
+        @consumer_tag = generate_consumer_tag(name)
+        @client.send(Protocol::Basic::Consume.encode(@channel.id, @name, @consumer_tag, no_local, no_ack, exclusive, nowait, arguments))
+
+        @channel.consumers[@consumer_tag] = self
+
+        if !nowait
+          # unlike #get, here it is reasonable to expect more than one callback
+          # so we use #append_callback
+          self.append_callback(:consume, &block)
+
+          @channel.queues_awaiting_consume_ok.push(self)
+        end
+
+        self
+      end
+
+      # 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
+
+      # 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
+
+
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.8.3.10.)
+      def get(no_ack = false, &block)
+        @client.send(Protocol::Basic::Get.encode(@channel.id, @name, no_ack))
+
+        # most people only want one callback per #get call. Consider the following example:
+        #
+        # 100.times { queue.get { ... } }
+        #
+        # most likely you won't expect 100 callback runs per messages here. MK.
+        self.redefine_callback(:get, &block)
+        @channel.queues_awaiting_get_response.push(self)
+
+        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 "This instance isn't being consumed!" if @consumer_tag.nil?
+
+        @client.send(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)
+
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.7.2.7.)
+      def purge(nowait = false, &block)
+        nowait = true unless block
+        @client.send(Protocol::Queue::Purge.encode(@channel.id, @name, nowait))
+
+        if !nowait
+          self.redefine_callback(:purge, &block)
+          # TODO: handle channel & connection-level exceptions
+          @channel.queues_awaiting_purge_ok.push(self)
+        end
+
+        self
+      end # purge(nowait = false, &block)
+
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.8.3.13.)
+      def acknowledge(delivery_tag)
+        @channel.acknowledge(delivery_tag)
+
+        self
+      end # acknowledge(delivery_tag)
+
+      #
+      # @return [Queue]  self
+      #
+      # @api public
+      # @see http://bit.ly/htCzCX AMQP 0.9.1 protocol documentation (Section 1.8.3.14.)
+      def reject(delivery_tag, requeue = true)
+        @channel.reject(delivery_tag, requeue)
+
+        self
+      end # reject(delivery_tag, requeue = true)
+
+
+
+      # @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)
+
+
+
+      #
+      # Implementation
+      #
+
+      def handle_declare_ok(method)
+        @name = method.queue if self.anonymous?
+        @channel.register_queue(self)
+
+        self.exec_callback_once_yielding_self(:declare, method)
+      end
+
+      def handle_delete_ok(method)
+        self.exec_callback(:delete, method)
+      end # handle_delete_ok(method)
+
+      def handle_consume_ok(method)
+        self.exec_callback(:consume, method)
+      end # handle_consume_ok(method)
+
+      def handle_purge_ok(method)
+        self.exec_callback(:purge, method)
+      end # handle_purge_ok(method)
+
+      def handle_bind_ok(method)
+        self.exec_callback(:bind)
+      end # handle_bind_ok(method)
+
+      def handle_unbind_ok(method)
+        self.exec_callback(:unbind)
+      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(: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)
+      end # handle_get_ok(method, header, payload)
+
+      def handle_get_empty(method)
+        method = Protocol::GetResponse.new(method)
+        self.exec_callback(:get, method)
+      end # handle_get_empty(method)
+
+
+
+      # Get the first queue which didn't receive Queue.Declare-Ok yet and run its declare callback.
+      # The cache includes only queues with {nowait: false}.
+      self.handle(Protocol::Queue::DeclareOk) do |client, frame|
+        method  = frame.decode_payload
+
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_declare_ok.shift
+
+        queue.handle_declare_ok(method)
+      end
+
+
+      self.handle(Protocol::Queue::DeleteOk) do |client, frame|
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_delete_ok.shift
+        queue.handle_delete_ok(frame.decode_payload)
+      end
+
+
+      self.handle(Protocol::Queue::BindOk) do |client, frame|
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_bind_ok.shift
+
+        queue.handle_bind_ok(frame.decode_payload)
+      end
+
+
+      self.handle(Protocol::Queue::UnbindOk) do |client, frame|
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_unbind_ok.shift
+
+        queue.handle_unbind_ok(frame.decode_payload)
+      end
+
+
+      self.handle(Protocol::Basic::ConsumeOk) do |client, frame|
+        channel = client.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 |client, frame|
+        channel = client.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 |client, method_frame, content_frames|
+        channel  = client.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 |client, frame|
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_purge_ok.shift
+
+        queue.handle_purge_ok(frame.decode_payload)
+      end
+
+
+      self.handle(Protocol::Basic::GetOk) do |client, frame, content_frames|
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_get_response.shift
+        method  = frame.decode_payload
+
+        header  = content_frames.shift
+        body    = content_frames.map {|frame| frame.payload }.join
+
+        queue.handle_get_ok(method, header, body) if queue
+      end
+
+
+      self.handle(Protocol::Basic::GetEmpty) do |client, frame|
+        channel = client.connection.channels[frame.channel]
+        queue   = channel.queues_awaiting_get_response.shift
+
+        queue.handle_get_empty(frame.decode_payload)
+      end
+    end # Queue
+  end # Client
+end # AMQ