amqp-client 1.0.0 → 1.0.1

data/lib/amqp/client/queue.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module AMQP
+  class Client
+    # Queue abstraction
+    class Queue
+      # Should only be initialized from the Client
+      # @api private
+      def initialize(client, name)
+        @client = client
+        @name = name
+      end
+
+      # Publish to the queue
+      # @param body [String] The message body
+      # @param properties [Properties]
+      # @option properties [String] content_type Content type of the message body
+      # @option properties [String] content_encoding Content encoding of the body
+      # @option properties [Hash<String, Object>] headers Custom headers
+      # @option properties [Integer] delivery_mode 2 for persisted message, transient messages for all other values
+      # @option properties [Integer] priority A priority of the message (between 0 and 255)
+      # @option properties [Integer] correlation_id A correlation id, most often used used for RPC communication
+      # @option properties [String] reply_to Queue to reply RPC responses to
+      # @option properties [Integer, String] expiration Number of seconds the message will stay in the queue
+      # @option properties [String] message_id Can be used to uniquely identify the message, e.g. for deduplication
+      # @option properties [Date] timestamp Often used for the time the message was originally generated
+      # @option properties [String] type Can indicate what kind of message this is
+      # @option properties [String] user_id Can be used to verify that this is the user that published the message
+      # @option properties [String] app_id Can be used to indicates which app that generated the message
+      # @return [Queue] self
+      def publish(body, **properties)
+        @client.publish(body, "", @name, **properties)
+        self
+      end
+
+      # Subscribe/consume from the queue
+      # @return [Queue] self
+      def subscribe(no_ack: false, prefetch: 1, worker_threads: 1, arguments: {}, &blk)
+        @client.subscribe(@name, no_ack: no_ack, prefetch: prefetch, worker_threads: worker_threads, arguments: arguments, &blk)
+        self
+      end
+
+      # Bind the queue to an exchange
+      # @param exchange [String] Name of the exchange to bind to
+      # @param binding_key [String] Binding key on which messages that match might be routed (depending on exchange type)
+      # @param arguments [Hash] Message headers to match on (only relevant for header exchanges)
+      # @return [Queue] self
+      def bind(exchange, binding_key, arguments: {})
+        @client.bind(@name, exchange, binding_key, arguments: arguments)
+        self
+      end
+
+      # Unbind the queue from an exchange
+      # @param exchange [String] Name of the exchange to unbind from
+      # @param binding_key [String] Binding key which the queue is bound to the exchange with
+      # @param arguments [Hash] Arguments matching the binding that's being removed
+      # @return [Queue] self
+      def unbind(exchange, binding_key, arguments: {})
+        @client.unbind(@name, exchange, binding_key, arguments: arguments)
+        self
+      end
+
+      # Purge/empty the queue
+      # @return [Queue] self
+      def purge
+        @client.purge(@name)
+        self
+      end
+
+      # Delete the queue
+      # @return [nil]
+      def delete
+        @client.delete_queue(@name)
+        nil
+      end
+    end
+  end
+end

data/lib/amqp/client/table.rb

@@ -1,122 +1,133 @@
 # frozen_string_literal: true
 
 module AMQP
-  # Encode/decode AMQP Tables
-  module Table
-    module_function
+  class Client
+    # Encode and decode an AMQP table to/from hash, only used internally
+    # @api private
+    module Table
+      module_function
 
-    def encode(hash)
-      tbl = ""
-      hash.each do |k, v|
-        key = k.to_s
-        tbl += [key.bytesize, key, encode_field(v)].pack("C a* a*")
+      # Encodes a hash into a byte array
+      # @return [String] Byte array
+      def encode(hash)
+        tbl = StringIO.new
+        hash.each do |k, v|
+          key = k.to_s
+          tbl.write [key.bytesize, key].pack("Ca*")
+          tbl.write encode_field(v)
+        end
+        tbl.string
       end
-      tbl
-    end
-
-    def decode(bytes)
-      h = {}
-      pos = 0
 
-      while pos < bytes.bytesize
-        key_len = bytes[pos].ord
-        pos += 1
-        key = bytes.byteslice(pos, key_len).force_encoding("utf-8")
-        pos += key_len
-        rest = bytes.byteslice(pos, bytes.bytesize - pos)
-        len, value = decode_field(rest)
-        pos += len + 1
-        h[key] = value
+      # Decodes an AMQP table into a hash
+      # @return [Hash<String, Object>]
+      def decode(bytes)
+        hash = {}
+        pos = 0
+        while pos < bytes.bytesize
+          key_len = bytes[pos].ord
+          pos += 1
+          key = bytes.byteslice(pos, key_len).force_encoding("utf-8")
+          pos += key_len
+          rest = bytes.byteslice(pos, bytes.bytesize - pos)
+          len, value = decode_field(rest)
+          pos += len + 1
+          hash[key] = value
+        end
+        hash
       end
-      h
-    end
 
-    def encode_field(value)
-      case value
-      when Integer
-        if value > 2**31
-          ["l", value].pack("a q>")
-        else
-          ["I", value].pack("a l>")
+      # Encoding a single value in a table
+      # @api private
+      def encode_field(value)
+        case value
+        when Integer
+          if value > 2**31
+            ["l", value].pack("a q>")
+          else
+            ["I", value].pack("a l>")
+          end
+        when Float
+          ["d", value].pack("a G")
+        when String
+          ["S", value.bytesize, value].pack("a L> a*")
+        when Time
+          ["T", value.to_i].pack("a Q>")
+        when Array
+          bytes = value.map { |e| encode_field(e) }.join
+          ["A", bytes.bytesize, bytes].pack("a L> a*")
+        when Hash
+          bytes = Table.encode(value)
+          ["F", bytes.bytesize, bytes].pack("a L> a*")
+        when true
+          ["t", 1].pack("a C")
+        when false
+          ["t", 0].pack("a C")
+        when nil
+          ["V"].pack("a")
+        else raise ArgumentError, "unsupported table field type: #{value.class}"
         end
-      when Float
-        ["d", value].pack("a G")
-      when String
-        ["S", value.bytesize, value].pack("a L> a*")
-      when Time
-        ["T", value.to_i].pack("a Q>")
-      when Array
-        bytes = value.map { |e| encode_field(e) }.join
-        ["A", bytes.bytesize, bytes].pack("a L> a*")
-      when Hash
-        bytes = Table.encode(value)
-        ["F", bytes.bytesize, bytes].pack("a L> a*")
-      when true
-        ["t", 1].pack("a C")
-      when false
-        ["t", 0].pack("a C")
-      when nil
-        ["V"].pack("a")
-      else raise "unsupported table field type: #{value.class}"
       end
-    end
 
-    # returns [length of field including type, value of field]
-    def decode_field(bytes)
-      type = bytes[0]
-      pos = 1
-      case type
-      when "S"
-        len = bytes.byteslice(pos, 4).unpack1("L>")
-        pos += 4
-        [4 + len, bytes.byteslice(pos, len).force_encoding("utf-8")]
-      when "F"
-        len = bytes.byteslice(pos, 4).unpack1("L>")
-        pos += 4
-        [4 + len, decode(bytes.byteslice(pos, len))]
-      when "A"
-        len = bytes.byteslice(pos, 4).unpack1("L>")
-        a = []
-        while pos < len
-          length, value = decode_field(bytes.byteslice(pos, -1))
-          pos += length + 1
-          a << value
+      # Decodes a single value
+      # @return [Array<Integer, Object>] Bytes read and the parsed object
+      # @api private
+      def decode_field(bytes)
+        type = bytes[0]
+        pos = 1
+        case type
+        when "S"
+          len = bytes.byteslice(pos, 4).unpack1("L>")
+          pos += 4
+          [4 + len, bytes.byteslice(pos, len).force_encoding("utf-8")]
+        when "F"
+          len = bytes.byteslice(pos, 4).unpack1("L>")
+          pos += 4
+          [4 + len, decode(bytes.byteslice(pos, len))]
+        when "A"
+          len = bytes.byteslice(pos, 4).unpack1("L>")
+          a = []
+          while pos < len
+            length, value = decode_field(bytes.byteslice(pos, -1))
+            pos += length + 1
+            a << value
+          end
+          [4 + len, a]
+        when "t"
+          [1, bytes[pos].ord == 1]
+        when "b"
+          [1, bytes.byteslice(pos, 1).unpack1("c")]
+        when "B"
+          [1, bytes.byteslice(pos, 1).unpack1("C")]
+        when "s"
+          [2, bytes.byteslice(pos, 2).unpack1("s")]
+        when "u"
+          [2, bytes.byteslice(pos, 2).unpack1("S")]
+        when "I"
+          [4, bytes.byteslice(pos, 4).unpack1("l>")]
+        when "i"
+          [4, bytes.byteslice(pos, 4).unpack1("L>")]
+        when "l"
+          [8, bytes.byteslice(pos, 8).unpack1("q>")]
+        when "f"
+          [4, bytes.byteslice(pos, 4).unpack1("g")]
+        when "d"
+          [8, bytes.byteslice(pos, 8).unpack1("G")]
+        when "D"
+          scale = bytes[pos].ord
+          pos += 1
+          value = bytes.byteslice(pos, 4).unpack1("L>")
+          d = value / 10**scale
+          [5, d]
+        when "x"
+          len = bytes.byteslice(pos, 4).unpack1("L>")
+          [4 + len, bytes.byteslice(pos, len)]
+        when "T"
+          [8, Time.at(bytes.byteslice(pos, 8).unpack1("Q>"))]
+        when "V"
+          [0, nil]
+        else raise ArgumentError, "unsupported table field type: #{type}"
         end
-        [4 + len, a]
-      when "t"
-        [1, bytes[pos].ord == 1]
-      when "b"
-        [1, bytes.byteslice(pos, 1).unpack1("c")]
-      when "B"
-        [1, bytes.byteslice(pos, 1).unpack1("C")]
-      when "s"
-        [2, bytes.byteslice(pos, 2).unpack1("s")]
-      when "u"
-        [2, bytes.byteslice(pos, 2).unpack1("S")]
-      when "I"
-        [4, bytes.byteslice(pos, 4).unpack1("l>")]
-      when "i"
-        [4, bytes.byteslice(pos, 4).unpack1("L>")]
-      when "l"
-        [8, bytes.byteslice(pos, 8).unpack1("q>")]
-      when "f"
-        [4, bytes.byteslice(pos, 4).unpack1("g")]
-      when "d"
-        [8, bytes.byteslice(pos, 8).unpack1("G")]
-      when "D"
-        scale = bytes[pos].ord
-        pos += 1
-        value = bytes.byteslice(pos, 4).unpack1("L>")
-        d = value / 10**scale
-        [5, d]
-      when "x"
-        len = bytes.byteslice(pos, 4).unpack1("L>")
-        [4 + len, bytes.byteslice(pos, len)]
-      when "T"
-        [8, Time.at(bytes.byteslice(pos, 8).unpack1("Q>"))]
-      when "V"
-        [0, nil]
-      else raise "unsupported table field type: #{type}"
       end
     end
   end

data/lib/amqp/client/version.rb

@@ -2,6 +2,7 @@
 
 module AMQP
   class Client
-    VERSION = "1.0.0"
+    # Version of the client library
+    VERSION = "1.0.1"
   end
 end

data/lib/amqp/client.rb

@@ -3,10 +3,26 @@
 require "set"
 require_relative "client/version"
 require_relative "client/connection"
+require_relative "client/exchange"
+require_relative "client/queue"
 
+# AMQP 0-9-1 Protocol, this library only implements the Client
+# @see Client
 module AMQP
   # AMQP 0-9-1 Client
+  # @see Connection
   class Client
+    # Create a new Client object, this won't establish a connection yet, use {#connect} or {#start} for that
+    # @param uri [String] URL on the format amqp://username:password@hostname/vhost,
+    #   use amqps:// for encrypted connection
+    # @option options [Boolean] connection_name (PROGRAM_NAME) Set a name for the connection to be able to identify
+    #   the client from the broker
+    # @option options [Boolean] verify_peer (true) Verify broker's TLS certificate, set to false for self-signed certs
+    # @option options [Integer] heartbeat (0) Heartbeat timeout, defaults to 0 and relies on TCP keepalive instead
+    # @option options [Integer] frame_max (131_072) Maximum frame size,
+    #    the smallest of the client's and the broker's values will be used
+    # @option options [Integer] channel_max (2048) Maxium number of channels the client will be allowed to have open.
+    #   Maxium allowed is 65_536.  The smallest of the client's and the broker's value will be used.
     def initialize(uri, **options)
       @uri = uri
       @options = options
@@ -17,12 +33,17 @@ module AMQP
       @connq = SizedQueue.new(1)
     end
 
-    # Opens an AMQP connection, does not try to reconnect
+    # @!group Connect and disconnect
+
+    # Establishes a new AMQP connection, does not try to reconnect
+    # @see Connection.connect
+    # @return [Connection]
     def connect(read_loop_thread: true)
       Connection.connect(@uri, read_loop_thread: read_loop_thread, **@options)
     end
 
-    # Opens an AMQP connection using the high level API, will try to reconnect
+    # Opens an AMQP connection using the high level API, will try to reconnect if successfully connected at first
+    # @return [self]
     def start
       @stopped = false
       Thread.new(connect(read_loop_thread: false)) do |conn|
@@ -42,7 +63,7 @@ module AMQP
             @connq << conn
           end
           conn.read_loop # blocks until connection is closed, then reconnect
-        rescue AMQP::Client::Error => e
+        rescue Error => e
           warn "AMQP-Client reconnect error: #{e.inspect}"
           sleep @options[:reconnect_interval] || 1
         ensure
@@ -52,76 +73,56 @@ module AMQP
       self
     end
 
+    # Close the currently open connection
+    # @return [nil]
     def stop
+      return if @stopped
+
       @stopped = true
       conn = @connq.pop
       conn.close
       nil
     end
 
-    def queue(name, durable: true, exclusive: false, auto_delete: false, arguments: {})
+    # @!endgroup
+    # @!group High level objects
+
+    # Declare a queue
+    # @param name [String] Name of the queue
+    # @param durable [Boolean] If true the queue will survive broker restarts,
+    #   messages in the queue will only survive if they are published as persistent
+    # @param auto_delete [Boolean] If true the queue will be deleted when the last consumer stops consuming
+    #   (it won't be deleted until at least one consumer has consumed from it)
+    # @param arguments [Hash] Custom arguments, such as queue-ttl etc.
+    # @return [Queue]
+    def queue(name, durable: true, auto_delete: false, arguments: {})
       raise ArgumentError, "Currently only supports named, durable queues" if name.empty?
 
       @queues.fetch(name) do
         with_connection do |conn|
-          conn.with_channel do |ch| # use a temp channel in case the declaration fails
-            ch.queue_declare(name, durable: durable, exclusive: exclusive, auto_delete: auto_delete, arguments: arguments)
-          end
+          conn.channel(1).queue_declare(name, durable: durable, auto_delete: auto_delete, arguments: arguments)
         end
         @queues[name] = Queue.new(self, name)
       end
     end
 
+    # Declare an exchange and return a high level Exchange object
+    # @return [Exchange]
     def exchange(name, type, durable: true, auto_delete: false, internal: false, arguments: {})
       @exchanges.fetch(name) do
         with_connection do |conn|
-          conn.with_channel do |ch|
-            ch.exchange_declare(name, type, durable: durable, auto_delete: auto_delete, internal: internal, arguments: arguments)
-          end
+          conn.channel(1).exchange_declare(name, type, durable: durable, auto_delete: auto_delete,
+                                                       internal: internal, arguments: arguments)
         end
         @exchanges[name] = Exchange.new(self, name)
       end
     end
 
-    # High level representation of an exchange
-    class Exchange
-      def initialize(client, name)
-        @client = client
-        @name = name
-      end
-
-      def publish(body, routing_key, arguments: {})
-        @client.publish(body, @name, routing_key, arguments: arguments)
-      end
-
-      # Bind to another exchange
-      def bind(exchange, routing_key, arguments: {})
-        @client.exchange_bind(@name, exchange, routing_key, arguments: arguments)
-      end
-
-      # Unbind from another exchange
-      def unbind(exchange, routing_key, arguments: {})
-        @client.exchange_unbind(@name, exchange, routing_key, arguments: arguments)
-      end
-
-      def delete
-        @client.delete_exchange(@name)
-      end
-    end
-
-    def subscribe(queue_name, no_ack: false, prefetch: 1, worker_threads: 1, arguments: {}, &blk)
-      @subscriptions.add? [queue_name, no_ack, prefetch, worker_threads, arguments, blk]
-
-      with_connection do |conn|
-        ch = conn.channel
-        ch.basic_qos(prefetch)
-        ch.basic_consume(queue_name, no_ack: no_ack, worker_threads: worker_threads, arguments: arguments) do |msg|
-          blk.call(msg)
-        end
-      end
-    end
+    # @!endgroup
+    # @!group Publish
 
     # Publish a (persistent) message and wait for confirmation
+    # @return [nil]
     def publish(body, exchange, routing_key, **properties)
       with_connection do |conn|
         properties = { delivery_mode: 2 }.merge!(properties)
@@ -130,6 +131,7 @@ module AMQP
     end
 
     # Publish a (persistent) message but don't wait for a confirmation
+    # @return [nil]
     def publish_and_forget(body, exchange, routing_key, **properties)
       with_connection do |conn|
         properties = { delivery_mode: 2 }.merge!(properties)
@@ -137,94 +139,125 @@ module AMQP
       end
     end
 
+    # Wait for unconfirmed publishes
+    # @return [Boolean] True if successful, false if any message negatively acknowledged
     def wait_for_confirms
       with_connection do |conn|
         conn.channel(1).wait_for_confirms
       end
     end
 
-    def bind(queue, exchange, routing_key, arguments: {})
-      with_connection do |conn|
-        conn.channel(1).queue_bind(queue, exchange, routing_key, arguments: arguments)
-      end
-    end
+    # @!endgroup
+    # @!group Queue actions
+
+    # Consume messages from a queue
+    # @param queue [String] Name of the queue to subscribe to
+    # @param no_ack [Boolean] When false messages have to be manually acknowledged (or rejected)
+    # @param prefetch [Integer] Specify how many messages to prefetch for consumers with no_ack is false
+    # @param worker_threads [Integer] Number of threads processing messages,
+    #   0 means that the thread calling this method will be blocked
+    # @param arguments [Hash] Custom arguments to the consumer
+    # @yield [Message] Delivered message from the queue
+    # @return [Array<(String, Array<Thread>)>] Returns consumer_tag and an array of worker threads
+    # @return [nil] When `worker_threads` is 0 the method will return when the consumer is cancelled
+    def subscribe(queue, no_ack: false, prefetch: 1, worker_threads: 1, arguments: {}, &blk)
+      @subscriptions.add? [queue, no_ack, prefetch, worker_threads, arguments, blk]
 
-    def unbind(queue, exchange, routing_key, arguments: {})
       with_connection do |conn|
-        conn.channel(1).queue_unbind(queue, exchange, routing_key, arguments: arguments)
+        ch = conn.channel
+        ch.basic_qos(prefetch)
+        ch.basic_consume(queue, no_ack: no_ack, worker_threads: worker_threads, arguments: arguments) do |msg|
+          blk.call(msg)
+        end
       end
     end
 
-    def exchange_bind(destination, source, routing_key, arguments: {})
+    # Bind a queue to an exchange
+    # @param queue [String] Name of the queue to bind
+    # @param exchange [String] Name of the exchange to bind to
+    # @param binding_key [String] Binding key on which messages that match might be routed (depending on exchange type)
+    # @param arguments [Hash] Message headers to match on (only relevant for header exchanges)
+    # @return [nil]
+    def bind(queue, exchange, binding_key, arguments: {})
       with_connection do |conn|
-        conn.channel(1).exchange_bind(destination, source, routing_key, arguments: arguments)
+        conn.channel(1).queue_bind(queue, exchange, binding_key, arguments: arguments)
       end
     end
 
-    def exchange_unbind(destination, source, routing_key, arguments: {})
+    # Unbind a queue from an exchange
+    # @param queue [String] Name of the queue to unbind
+    # @param exchange [String] Name of the exchange to unbind from
+    # @param binding_key [String] Binding key which the queue is bound to the exchange with
+    # @param arguments [Hash] Arguments matching the binding that's being removed
+    # @return [nil]
+    def unbind(queue, exchange, binding_key, arguments: {})
       with_connection do |conn|
-        conn.channel(1).exchange_unbind(destination, source, routing_key, arguments: arguments)
+        conn.channel(1).queue_unbind(queue, exchange, binding_key, arguments: arguments)
       end
     end
 
+    # Purge a queue
+    # @param queue [String] Name of the queue
+    # @return [nil]
     def purge(queue)
       with_connection do |conn|
         conn.channel(1).queue_purge(queue)
       end
     end
 
-    def delete_queue(name)
+    # Delete a queue
+    # @param name [String] Name of the queue
+    # @param if_unused [Boolean] Only delete if the queue doesn't have consumers, raises a ChannelClosed error otherwise
+    # @param if_empty [Boolean] Only delete if the queue is empty, raises a ChannelClosed error otherwise
+    # @return [Integer] Number of messages in the queue when deleted
+    def delete_queue(name, if_unused: false, if_empty: false)
       with_connection do |conn|
-        conn.channel(1).queue_delete(name)
+        msgs = conn.channel(1).queue_delete(name, if_unused: if_unused, if_empty: if_empty)
         @queues.delete(name)
+        msgs
       end
     end
 
-    def delete_exchange(name)
+    # @!endgroup
+    # @!group Exchange actions
+
+    # Bind an exchange to an exchange
+    # @param destination [String] Name of the exchange to bind
+    # @param source [String] Name of the exchange to bind to
+    # @param binding_key [String] Binding key on which messages that match might be routed (depending on exchange type)
+    # @param arguments [Hash] Message headers to match on (only relevant for header exchanges)
+    # @return [nil]
+    def exchange_bind(destination, source, binding_key, arguments: {})
       with_connection do |conn|
-        conn.channel(1).exchange_delete(name)
-        @exchanges.delete(name)
+        conn.channel(1).exchange_bind(destination, source, binding_key, arguments: arguments)
       end
     end
 
-    # Queue abstraction
-    class Queue
-      def initialize(client, name)
-        @client = client
-        @name = name
-      end
-
-      def publish(body, **properties)
-        @client.publish(body, "", @name, **properties)
-        self
-      end
-
-      def subscribe(no_ack: false, prefetch: 1, worker_threads: 1, arguments: {}, &blk)
-        @client.subscribe(@name, no_ack: no_ack, prefetch: prefetch, worker_threads: worker_threads, arguments: arguments, &blk)
-        self
-      end
-
-      def bind(exchange, routing_key, **headers)
-        @client.bind(@name, exchange, routing_key, **headers)
-        self
-      end
-
-      def unbind(exchange, routing_key, **headers)
-        @client.unbind(@name, exchange, routing_key, **headers)
-        self
-      end
-
-      def purge
-        @client.purge(@name)
-        self
+    # Unbind an exchange from an exchange
+    # @param destination [String] Name of the exchange to unbind
+    # @param source [String] Name of the exchange to unbind from
+    # @param binding_key [String] Binding key which the exchange is bound to the exchange with
+    # @param arguments [Hash] Arguments matching the binding that's being removed
+    # @return [nil]
+    def exchange_unbind(destination, source, binding_key, arguments: {})
+      with_connection do |conn|
+        conn.channel(1).exchange_unbind(destination, source, binding_key, arguments: arguments)
       end
+    end
 
-      def delete
-        @client.delete_queue(@name)
+    # Delete an exchange
+    # @param name [String] Name of the exchange
+    # @return [nil]
+    def delete_exchange(name)
+      with_connection do |conn|
+        conn.channel(1).exchange_delete(name)
+        @exchanges.delete(name)
         nil
       end
     end
 
+    # @!endgroup
+
     private
 
     def with_connection