amqp-client 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e6dd3fef130c286e97eadd9bb6d3d4de0fa67599361604cec3560879b9b4bdf
-  data.tar.gz: c2ce00f897c68d3085427854b08cc98d3487b40bb5327ce38bb216c98357e366
+  metadata.gz: 89ea2743bb81c4615d1445ee6ce25a5234a95f9f859ca4926ff5437228af1e02
+  data.tar.gz: 4739cd429d9cf55a631c36c9100f78c6d2da65d4aa18535297d69b8ec0ca6e56
 SHA512:
-  metadata.gz: 9b62e8ee74ec542be5617b08fbd0e36e5fc16294f99cd0ec61781c7c7425005c426e8358a74abf45a1a24ecb88451b94ef50ee7524403ac7097748b2e94b55b5
-  data.tar.gz: 5c3e63369578923e20b441fbe9728b374e18150c75ed155291b802c42f80f668b704b39e80b144b90346a8d769d9b71f031b9fca712e6ac52c100a88e46380e3
+  metadata.gz: 12d2650fbf4be1f3d1449c4c035e8e12be88a64f3e4eeb2f4588558d294816e36510f53cb37f8217e2754ca3fb6b1acb021df25b63f34c7710f267de6186123c
+  data.tar.gz: 4b44974681cacc7956c73983cebd61315684c35adb5d98851469eaa7677e4a5149cc582cfeb3ec6561f1a036b0b80d7623197e8e1881400f6e00fff1305a4362

data/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0
+      - name: Install yard
+        run: gem install yard
+      - name: Generate docs
+        run: yard doc
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@4.1.5
+        with:
+          branch: gh-pages
+          folder: doc

data/.rubocop.yml

@@ -12,4 +12,15 @@ Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
 Layout/LineLength:
-  Max: 120
+  Max: 130
+
+Naming/FileName:
+  Exclude:
+    - 'lib/amqp-client.rb'
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/amqp/client/properties.rb'
+
+Metrics/ParameterLists:
+  Max: 8

data/.rubocop_todo.yml

@@ -1,92 +1,48 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2021-06-01 23:54:39 UTC using RuboCop version 1.15.0.
+# on 2021-09-06 19:39:47 UTC using RuboCop version 1.19.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
-# URISchemes: http, https
-Layout/LineLength:
-  Max: 123
-
-# Offense count: 15
+# Offense count: 18
 # Configuration parameters: IgnoredMethods, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 142
+  Max: 179
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 # IgnoredMethods: refine
 Metrics/BlockLength:
-  Max: 37
+  Max: 40
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: CountBlocks.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 2
+# Offense count: 5
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 191
+  Max: 400
 
 # Offense count: 9
 # Configuration parameters: IgnoredMethods.
 Metrics/CyclomaticComplexity:
-  Max: 30
+  Max: 44
 
-# Offense count: 26
+# Offense count: 40
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 Metrics/MethodLength:
-  Max: 124
+  Max: 170
 
-# Offense count: 3
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 300
-
-# Offense count: 5
-# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
-Metrics/ParameterLists:
-  Max: 7
+  Max: 500
 
-# Offense count: 7
+# Offense count: 4
 # Configuration parameters: IgnoredMethods.
 Metrics/PerceivedComplexity:
-  Max: 18
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, IgnoredMethods.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
-  Exclude:
-    - 'spec/**/*'
-    - 'lib/amqp/client/channel.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: implicit, explicit
-Style/RescueStandardError:
-  Exclude:
-    - 'lib/amqp/client.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: forbid_for_all_comparison_operators, forbid_for_equality_operators_only, require_for_all_comparison_operators, require_for_equality_operators_only
-Style/YodaCondition:
-  Exclude:
-    - 'lib/amqp/client/channel.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
-# URISchemes: http, https
-Layout/LineLength:
-  Max: 123
+  Max: 22

data/.yardopts

@@ -0,0 +1 @@
+--no-api - LICENSE.txt CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [1.0.1] - 2021-09-06
+
+- The API is fully documented! https://cloudamqp.github.io/amqp-client.rb/
+- Fixed: Socket writing is now thread-safe
+- Change: Block while waiting for basic_cancel by default
+- Added: Can specify channel_max, heartbeat and frame_max as options to the Client/Connection
+- Added: Reuse channel 1 to declare high level queues/exchanges
+- Fixed: Only wait for exchange_delete confirmation if not no_wait is set
+- Fixed: Don't raise if Connection#close detects a closed socket (expected)
+
 ## [1.0.0] - 2021-08-27
 
 - Verify TLS certificate matches hostname

data/README.md

@@ -2,6 +2,10 @@
 
 An AMQP 0-9-1 Ruby client, trying to keep things as simple as possible.
 
+## Documentation
+
+[API reference](https://cloudamqp.github.io/amqp-client.rb/)
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/amqp/client/channel.rb

@@ -3,338 +3,543 @@
 require_relative "./message"
 
 module AMQP
-  # AMQP Channel
-  class Channel
-    def initialize(connection, id)
-      @connection = connection
-      @id = id
-      @replies = ::Queue.new
-      @consumers = {}
-      @closed = nil
-      @open = false
-      @on_return = nil
-      @confirm = nil
-      @unconfirmed = ::Queue.new
-      @unconfirmed_empty = ::Queue.new
-      @basic_gets = ::Queue.new
-    end
-
-    def inspect
-      "#<#{self.class} @id=#{@id} @open=#{@open} @closed=#{@closed} confirm_selected=#{!@confirm.nil?}"\
-        " consumer_count=#{@consumers.size} replies_count=#{@replies.size} unconfirmed_count=#{@unconfirmed.size}>"
-    end
-
-    attr_reader :id
-
-    def open
-      return self if @open
+  class Client
+    class Connection
+      # AMQP Channel
+      class Channel
+        # Should only be called from Connection
+        # @param connection [Connection] The connection this channel belongs to
+        # @param id [Integer] ID of the channel
+        # @see Connection#channel
+        # @api private
+        def initialize(connection, id)
+          @connection = connection
+          @id = id
+          @replies = ::Queue.new
+          @consumers = {}
+          @closed = nil
+          @open = false
+          @on_return = nil
+          @confirm = nil
+          @unconfirmed = ::Queue.new
+          @unconfirmed_empty = ::Queue.new
+          @basic_gets = ::Queue.new
+        end
 
-      @open = true
-      write_bytes FrameBytes.channel_open(@id)
-      expect(:channel_open_ok)
-      self
-    end
+        # Override #inspect
+        # @api private
+        def inspect
+          "#<#{self.class} @id=#{@id} @open=#{@open} @closed=#{@closed} confirm_selected=#{!@confirm.nil?}"\
+            " consumer_count=#{@consumers.size} replies_count=#{@replies.size} unconfirmed_count=#{@unconfirmed.size}>"
+        end
 
-    def close(reason = "", code = 200)
-      return if @closed
+        # Channel ID
+        # @return [Integer]
+        attr_reader :id
 
-      write_bytes FrameBytes.channel_close(@id, reason, code)
-      @closed = [code, reason]
-      expect :channel_close_ok
-      @replies.close
-      @basic_gets.close
-      @unconfirmed_empty.close
-      @consumers.each_value(&:close)
-    end
+        # Open the channel (called from Connection)
+        # @return [Channel] self
+        # @api private
+        def open
+          return self if @open
 
-    # Called when channel is closed by server
-    def closed!(code, reason, classid, methodid)
-      @closed = [code, reason, classid, methodid]
-      @replies.close
-      @basic_gets.close
-      @unconfirmed_empty.close
-      @consumers.each_value(&:close)
-    end
+          @open = true
+          write_bytes FrameBytes.channel_open(@id)
+          expect(:channel_open_ok)
+          self
+        end
 
-    def exchange_declare(name, type, passive: false, durable: true, auto_delete: false, internal: false, arguments: {})
-      write_bytes FrameBytes.exchange_declare(@id, name, type, passive, durable, auto_delete, internal, arguments)
-      expect :exchange_declare_ok
-    end
+        # Gracefully close a connection
+        # @return [nil]
+        def close(reason: "", code: 200)
+          return if @closed
+
+          write_bytes FrameBytes.channel_close(@id, reason, code)
+          @closed = [code, reason]
+          expect :channel_close_ok
+          @replies.close
+          @basic_gets.close
+          @unconfirmed_empty.close
+          @consumers.each_value(&:close)
+          nil
+        end
 
-    def exchange_delete(name, if_unused: false, no_wait: false)
-      write_bytes FrameBytes.exchange_delete(@id, name, if_unused, no_wait)
-      expect :exchange_delete_ok
-    end
+        # Called when channel is closed by server
+        # @return [nil]
+        # @api private
+        def closed!(code, reason, classid, methodid)
+          @closed = [code, reason, classid, methodid]
+          @replies.close
+          @basic_gets.close
+          @unconfirmed_empty.close
+          @consumers.each_value(&:close)
+          nil
+        end
 
-    def exchange_bind(destination, source, binding_key, arguments: {})
-      write_bytes FrameBytes.exchange_bind(@id, destination, source, binding_key, false, arguments)
-      expect :exchange_bind_ok
-    end
+        # Handle returned messages in this block.  If not set the message will just be logged to STDERR
+        # @yield [ReturnMessage] Messages returned by the server when a publish has failed
+        # @return nil
+        def on_return(&block)
+          @on_return = block
+          nil
+        end
 
-    def exchange_unbind(destination, source, binding_key, arguments: {})
-      write_bytes FrameBytes.exchange_unbind(@id, destination, source, binding_key, false, arguments)
-      expect :exchange_unbind_ok
-    end
+        # @!group Exchange
+
+        # Declare an exchange
+        # @param name [String] Name of the exchange
+        # @param type [String] Type of exchange (amq.direct, amq.fanout, amq.topic, amq.headers, etc.)
+        # @param passive [Boolean] If true raise an exception if the exchange doesn't already exists
+        # @param durable [Boolean] If true the exchange will persist between broker restarts,
+        #   also a requirement for persistent messages
+        # @param auto_delete [Boolean] If true the exchange will be deleted when the last queue/exchange is unbound
+        # @param internal [Boolean] If true the exchange can't be published to directly
+        # @param arguments [Hash] Custom arguments
+        # @return [nil]
+        def exchange_declare(name, type, passive: false, durable: true, auto_delete: false, internal: false, arguments: {})
+          write_bytes FrameBytes.exchange_declare(@id, name, type, passive, durable, auto_delete, internal, arguments)
+          expect :exchange_declare_ok
+          nil
+        end
 
-    QueueOk = Struct.new(:queue_name, :message_count, :consumer_count)
+        # Delete an exchange
+        # @param name [String] Name of the exchange
+        # @param if_unused [Boolean] If true raise an exception if queues/exchanges is bound to this exchange
+        # @param no_wait [Boolean] If true don't wait for a server confirmation
+        # @return [nil]
+        def exchange_delete(name, if_unused: false, no_wait: false)
+          write_bytes FrameBytes.exchange_delete(@id, name, if_unused, no_wait)
+          expect :exchange_delete_ok unless no_wait
+          nil
+        end
 
-    def queue_declare(name = "", passive: false, durable: true, exclusive: false, auto_delete: false, arguments: {})
-      durable = false if name.empty?
-      exclusive = true if name.empty?
-      auto_delete = true if name.empty?
+        # Bind an exchange to another 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, but only when bound to header exchanges
+        # @return [nil]
+        def exchange_bind(destination, source, binding_key, arguments: {})
+          write_bytes FrameBytes.exchange_bind(@id, destination, source, binding_key, false, arguments)
+          expect :exchange_bind_ok
+          nil
+        end
 
-      write_bytes FrameBytes.queue_declare(@id, name, passive, durable, exclusive, auto_delete, arguments)
-      name, message_count, consumer_count = expect(:queue_declare_ok)
+        # Unbind an exchange from another 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 queue 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: {})
+          write_bytes FrameBytes.exchange_unbind(@id, destination, source, binding_key, false, arguments)
+          expect :exchange_unbind_ok
+          nil
+        end
 
-      QueueOk.new(name, message_count, consumer_count)
-    end
+        # @!endgroup
+        # @!group Queue
+
+        # Response when declaring a Queue
+        # @!attribute queue_name
+        #   @return [String] The name of the queue
+        # @!attribute message_count
+        #   @return [Integer] Number of messages in the queue at the time of declaration
+        # @!attribute consumer_count
+        #   @return [Integer] Number of consumers subscribed to the queue at the time of declaration
+        QueueOk = Struct.new(:queue_name, :message_count, :consumer_count)
+
+        # Create a queue (operation is idempotent)
+        # @param name [String] Name of the queue, can be empty, but will then be generated by the broker
+        # @param passive [Boolean] If true an exception will be raised if the queue doesn't already exists
+        # @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 exclusive [Boolean] If true the queue will be deleted when the channel is closed
+        # @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 [QueueOk] The QueueOk struct got `queue_name`, `message_count` and `consumer_count` properties
+        def queue_declare(name = "", passive: false, durable: true, exclusive: false, auto_delete: false, arguments: {})
+          durable = false if name.empty?
+          exclusive = true if name.empty?
+          auto_delete = true if name.empty?
+
+          write_bytes FrameBytes.queue_declare(@id, name, passive, durable, exclusive, auto_delete, arguments)
+          name, message_count, consumer_count = expect(:queue_declare_ok)
+
+          QueueOk.new(name, message_count, consumer_count)
+        end
 
-    def queue_delete(name, if_unused: false, if_empty: false, no_wait: false)
-      write_bytes FrameBytes.queue_delete(@id, name, if_unused, if_empty, no_wait)
-      message_count, = expect :queue_delete
-      message_count
-    end
+        # 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
+        # @param no_wait [Boolean] Don't wait for a server confirmation if true
+        # @return [Integer] Number of messages in queue when deleted
+        # @return [nil] If no_wait was set true
+        def queue_delete(name, if_unused: false, if_empty: false, no_wait: false)
+          write_bytes FrameBytes.queue_delete(@id, name, if_unused, if_empty, no_wait)
+          message_count, = expect :queue_delete unless no_wait
+          message_count
+        end
 
-    def queue_bind(name, exchange, binding_key, arguments: {})
-      write_bytes FrameBytes.queue_bind(@id, name, exchange, binding_key, false, arguments)
-      expect :queue_bind_ok
-    end
+        # Bind a queue to an exchange
+        # @param name [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, but only when bound to header exchanges
+        # @return [nil]
+        def queue_bind(name, exchange, binding_key, arguments: {})
+          write_bytes FrameBytes.queue_bind(@id, name, exchange, binding_key, false, arguments)
+          expect :queue_bind_ok
+          nil
+        end
 
-    def queue_purge(name, no_wait: false)
-      write_bytes FrameBytes.queue_purge(@id, name, no_wait)
-      expect :queue_purge_ok unless no_wait
-    end
+        # Purge a queue
+        # @param name [String] Name of the queue
+        # @param no_wait [Boolean] Don't wait for a server confirmation if true
+        # @return [nil]
+        def queue_purge(name, no_wait: false)
+          write_bytes FrameBytes.queue_purge(@id, name, no_wait)
+          expect :queue_purge_ok unless no_wait
+          nil
+        end
 
-    def queue_unbind(name, exchange, binding_key, arguments: {})
-      write_bytes FrameBytes.queue_unbind(@id, name, exchange, binding_key, arguments)
-      expect :queue_unbind_ok
-    end
+        # Unbind a queue from an exchange
+        # @param name [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 queue_unbind(name, exchange, binding_key, arguments: {})
+          write_bytes FrameBytes.queue_unbind(@id, name, exchange, binding_key, arguments)
+          expect :queue_unbind_ok
+        end
 
-    def basic_get(queue_name, no_ack: true)
-      write_bytes FrameBytes.basic_get(@id, queue_name, no_ack)
-      case (msg = @basic_gets.pop)
-      when Message then msg
-      when :basic_get_empty then nil
-      when nil              then raise AMQP::Client::ChannelClosedError.new(@id, *@closed)
-      end
-    end
+        # @!endgroup
+        # @!group Basic
+
+        # Get a message from a queue (by polling)
+        # @param queue_name [String]
+        # @param no_ack [Boolean] When false the message have to be manually acknowledged
+        # @return [Message] If the queue had a message
+        # @return [nil] If the queue doesn't have any messages
+        def basic_get(queue_name, no_ack: true)
+          write_bytes FrameBytes.basic_get(@id, queue_name, no_ack)
+          case (msg = @basic_gets.pop)
+          when Message then msg
+          when :basic_get_empty then nil
+          when nil              then raise Error::ChannelClosed.new(@id, *@closed)
+          end
+        end
 
-    def basic_publish(body, exchange, routing_key, **properties)
-      frame_max = @connection.frame_max - 8
-      id = @id
-      mandatory = properties.delete(:mandatory) || false
-      case properties.delete(:persistent)
-      when true then properties[:delivery_mode] = 2
-      when false then properties[:delivery_mode] = 1
-      end
+        # Publishes a message to an exchange
+        # @param body [String] The body, can be a string or a byte array
+        # @param exchange [String] Name of the exchange to publish to
+        # @param routing_key [String] The routing key that the exchange might use to route the message to a queue
+        # @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 [nil]
+        def basic_publish(body, exchange, routing_key, **properties)
+          frame_max = @connection.frame_max - 8
+          id = @id
+          mandatory = properties.delete(:mandatory) || false
+          case properties.delete(:persistent)
+          when true then properties[:delivery_mode] = 2
+          when false then properties[:delivery_mode] = 1
+          end
 
-      if body.bytesize.between?(1, frame_max)
-        write_bytes FrameBytes.basic_publish(id, exchange, routing_key, mandatory),
-                    FrameBytes.header(id, body.bytesize, properties),
-                    FrameBytes.body(id, body)
-        @unconfirmed.push @confirm += 1 if @confirm
-        return
-      end
+          if body.bytesize.between?(1, frame_max)
+            write_bytes FrameBytes.basic_publish(id, exchange, routing_key, mandatory),
+                        FrameBytes.header(id, body.bytesize, properties),
+                        FrameBytes.body(id, body)
+            @unconfirmed.push @confirm += 1 if @confirm
+            return
+          end
 
-      write_bytes FrameBytes.basic_publish(id, exchange, routing_key, mandatory),
-                  FrameBytes.header(id, body.bytesize, properties)
-      pos = 0
-      while pos < body.bytesize # split body into multiple frame_max frames
-        len = [frame_max, body.bytesize - pos].min
-        body_part = body.byteslice(pos, len)
-        write_bytes FrameBytes.body(id, body_part)
-        pos += len
-      end
-      @unconfirmed.push @confirm += 1 if @confirm
-      nil
-    end
+          write_bytes FrameBytes.basic_publish(id, exchange, routing_key, mandatory),
+                      FrameBytes.header(id, body.bytesize, properties)
+          pos = 0
+          while pos < body.bytesize # split body into multiple frame_max frames
+            len = [frame_max, body.bytesize - pos].min
+            body_part = body.byteslice(pos, len)
+            write_bytes FrameBytes.body(id, body_part)
+            pos += len
+          end
+          @unconfirmed.push @confirm += 1 if @confirm
+          nil
+        end
 
-    def basic_publish_confirm(body, exchange, routing_key, **properties)
-      confirm_select(no_wait: true)
-      basic_publish(body, exchange, routing_key, **properties)
-      wait_for_confirms
-    end
+        # Publish a message and block until the message has confirmed it has received it
+        # @param (see #basic_publish)
+        # @return [Boolean] True if the message was successfully published
+        def basic_publish_confirm(body, exchange, routing_key, **properties)
+          confirm_select(no_wait: true)
+          basic_publish(body, exchange, routing_key, **properties)
+          wait_for_confirms
+        end
 
-    # Consume from a queue
-    # worker_threads: 0 => blocking, messages are executed in the thread calling this method
-    def basic_consume(queue, tag: "", no_ack: true, exclusive: false, arguments: {}, worker_threads: 1)
-      write_bytes FrameBytes.basic_consume(@id, queue, tag, no_ack, exclusive, arguments)
-      tag, = expect(:basic_consume_ok)
-      q = @consumers[tag] = ::Queue.new
-      if worker_threads.zero?
-        loop do
-          yield (q.pop || break)
-        end
-      else
-        threads = Array.new(worker_threads) do
-          Thread.new do
+        # Consume messages from a queue
+        # @param queue [String] Name of the queue to subscribe to
+        # @param tag [String] Custom consumer tag, will be auto assigned by the server if empty
+        # @param no_ack [Boolean] When false messages have to be manually acknowledged (or rejected)
+        # @param exclusive [Boolean] When true only a single consumer can consume from the queue at a time
+        # @param arguments [Hash] Custom arguments to the consumer
+        # @param worker_threads [Integer] Number of threads processing messages,
+        #   0 means that the thread calling this method will be blocked
+        # @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 basic_consume(queue, tag: "", no_ack: true, exclusive: false, arguments: {}, worker_threads: 1)
+          write_bytes FrameBytes.basic_consume(@id, queue, tag, no_ack, exclusive, arguments)
+          tag, = expect(:basic_consume_ok)
+          q = @consumers[tag] = ::Queue.new
+          if worker_threads.zero?
             loop do
               yield (q.pop || break)
             end
+            nil
+          else
+            threads = Array.new(worker_threads) do
+              Thread.new do
+                loop do
+                  yield (q.pop || break)
+                end
+              end
+            end
+            [tag, threads]
           end
         end
-        [tag, threads]
-      end
-    end
 
-    def basic_cancel(consumer_tag, no_wait: false)
-      consumer = @consumers.fetch(consumer_tag)
-      return if consumer.closed?
+        # Cancel/abort/stop a consumer
+        # @param consumer_tag [String] Tag of the consumer to cancel
+        # @param no_wait [Boolean] Will wait for a confirmation from the server that the consumer is cancelled
+        # @return [nil]
+        def basic_cancel(consumer_tag, no_wait: false)
+          consumer = @consumers.fetch(consumer_tag)
+          return if consumer.closed?
+
+          write_bytes FrameBytes.basic_cancel(@id, consumer_tag)
+          expect(:basic_cancel_ok) unless no_wait
+          consumer.close
+          nil
+        end
 
-      write_bytes FrameBytes.basic_cancel(@id, consumer_tag)
-      expect(:basic_cancel_ok) unless no_wait
-      consumer.close
-    end
+        # Specify how many messages to prefetch for consumers with `no_ack: false`
+        # @param prefetch_count [Integer] Number of messages to maxium keep in flight
+        # @param prefetch_size [Integer] Number of bytes to maxium keep in flight
+        # @param global [Boolean] If true the limit will apply to channel rather than the consumer
+        # @return [nil]
+        def basic_qos(prefetch_count, prefetch_size: 0, global: false)
+          write_bytes FrameBytes.basic_qos(@id, prefetch_size, prefetch_count, global)
+          expect :basic_qos_ok
+          nil
+        end
 
-    def basic_qos(prefetch_count, prefetch_size: 0, global: false)
-      write_bytes FrameBytes.basic_qos(@id, prefetch_size, prefetch_count, global)
-      expect :basic_qos_ok
-    end
+        # Acknowledge a message
+        # @param delivery_tag [Integer] The delivery tag of the message to acknowledge
+        # @return [nil]
+        def basic_ack(delivery_tag, multiple: false)
+          write_bytes FrameBytes.basic_ack(@id, delivery_tag, multiple)
+          nil
+        end
 
-    def basic_ack(delivery_tag, multiple: false)
-      write_bytes FrameBytes.basic_ack(@id, delivery_tag, multiple)
-    end
+        # Negatively acknowledge a message
+        # @param delivery_tag [Integer] The delivery tag of the message to acknowledge
+        # @param multiple [Boolean] Nack all messages up to this message
+        # @param requeue [Boolean] Requeue the message
+        # @return [nil]
+        def basic_nack(delivery_tag, multiple: false, requeue: false)
+          write_bytes FrameBytes.basic_nack(@id, delivery_tag, multiple, requeue)
+          nil
+        end
 
-    def basic_nack(delivery_tag, multiple: false, requeue: false)
-      write_bytes FrameBytes.basic_nack(@id, delivery_tag, multiple, requeue)
-    end
+        # Reject a message
+        # @param delivery_tag [Integer] The delivery tag of the message to acknowledge
+        # @param requeue [Boolean] Requeue the message into the queue again
+        # @return [nil]
+        def basic_reject(delivery_tag, requeue: false)
+          write_bytes FrameBytes.basic_reject(@id, delivery_tag, requeue)
+          nil
+        end
 
-    def basic_reject(delivery_tag, requeue: false)
-      write_bytes FrameBytes.basic_reject(@id, delivery_tag, requeue)
-    end
+        # Recover all the unacknowledge messages
+        # @param requeue [Boolean] If false the currently unack:ed messages will be deliviered to this consumer again,
+        #   if false to any consumer
+        # @return [nil]
+        def basic_recover(requeue: false)
+          write_bytes FrameBytes.basic_recover(@id, requeue: requeue)
+          expect :basic_recover_ok
+          nil
+        end
 
-    def basic_recover(requeue: false)
-      write_bytes FrameBytes.basic_recover(@id, requeue: requeue)
-      expect :basic_recover_ok
-    end
+        # @!endgroup
+        # @!group Confirm
 
-    def confirm_select(no_wait: false)
-      return if @confirm
+        # Put the channel in confirm mode, each published message will then be confirmed by the server
+        # @param no_wait [Boolean] If false the method will block until the server has confirmed the request
+        # @return [nil]
+        def confirm_select(no_wait: false)
+          return if @confirm
 
-      write_bytes FrameBytes.confirm_select(@id, no_wait)
-      expect :confirm_select_ok unless no_wait
-      @confirm = 0
-    end
+          write_bytes FrameBytes.confirm_select(@id, no_wait)
+          expect :confirm_select_ok unless no_wait
+          @confirm = 0
+          nil
+        end
 
-    # Block until all publishes messages are confirmed
-    def wait_for_confirms
-      return true if @unconfirmed.empty?
+        # Block until all publishes messages are confirmed
+        # @return [Boolean] True if all message where positivly acknowledged, false if not
+        def wait_for_confirms
+          return true if @unconfirmed.empty?
 
-      case @unconfirmed_empty.pop
-      when true then true
-      when false then false
-      else raise AMQP::Client::ChannelClosedError.new(@id, *@closed)
-      end
-    end
+          case @unconfirmed_empty.pop
+          when true then true
+          when false then false
+          else raise Error::ChannelClosed.new(@id, *@closed)
+          end
+        end
 
-    # Called by Connection when received ack/nack from server
-    def confirm(args)
-      ack_or_nack, delivery_tag, multiple = *args
-      loop do
-        tag = @unconfirmed.pop(true)
-        break if tag == delivery_tag
-        next if multiple && tag < delivery_tag
-
-        @unconfirmed << tag # requeue
-      rescue ThreadError
-        break
-      end
-      return unless @unconfirmed.empty?
+        # Called by Connection when received ack/nack from server
+        # @api private
+        def confirm(args)
+          ack_or_nack, delivery_tag, multiple = *args
+          loop do
+            tag = @unconfirmed.pop(true)
+            break if tag == delivery_tag
+            next if multiple && tag < delivery_tag
+
+            @unconfirmed << tag # requeue
+          rescue ThreadError
+            break
+          end
+          return unless @unconfirmed.empty?
 
-      @unconfirmed_empty.num_waiting.times do
-        @unconfirmed_empty << (ack_or_nack == :ack)
-      end
-    end
+          @unconfirmed_empty.num_waiting.times do
+            @unconfirmed_empty << (ack_or_nack == :ack)
+          end
+        end
 
-    def tx_select
-      write_bytes FrameBytes.tx_select(@id)
-      expect :tx_select_ok
-    end
+        # @!endgroup
+        # @!group Transaction
 
-    def tx_commit
-      write_bytes FrameBytes.tx_commit(@id)
-      expect :tx_commit_ok
-    end
+        # Put the channel in transaction mode, make sure that you #tx_commit or #tx_rollback after publish
+        # @return [nil]
+        def tx_select
+          write_bytes FrameBytes.tx_select(@id)
+          expect :tx_select_ok
+          nil
+        end
 
-    def tx_rollback
-      write_bytes FrameBytes.tx_rollback(@id)
-      expect :tx_rollback_ok
-    end
+        # Commmit a transaction, requires that the channel is in transaction mode
+        # @return [nil]
+        def tx_commit
+          write_bytes FrameBytes.tx_commit(@id)
+          expect :tx_commit_ok
+          nil
+        end
 
-    def on_return(&block)
-      @on_return = block
-    end
+        # Rollback a transaction, requires that the channel is in transaction mode
+        # @return [nil]
+        def tx_rollback
+          write_bytes FrameBytes.tx_rollback(@id)
+          expect :tx_rollback_ok
+          nil
+        end
 
-    def reply(args)
-      @replies.push(args)
-    end
+        # @!endgroup
 
-    def message_returned(reply_code, reply_text, exchange, routing_key)
-      @next_msg = ReturnMessage.new(reply_code, reply_text, exchange, routing_key, nil, "")
-    end
+        # @api private
+        def reply(args)
+          @replies.push(args)
+        end
 
-    def message_delivered(consumer_tag, delivery_tag, redelivered, exchange, routing_key)
-      @next_msg = Message.new(self, delivery_tag, exchange, routing_key, nil, "", redelivered, consumer_tag)
-    end
+        # @api private
+        def message_returned(reply_code, reply_text, exchange, routing_key)
+          @next_msg = ReturnMessage.new(reply_code, reply_text, exchange, routing_key, nil, "")
+        end
 
-    def basic_get_empty
-      @basic_gets.push :basic_get_empty
-    end
+        # @api private
+        def message_delivered(consumer_tag, delivery_tag, redelivered, exchange, routing_key)
+          @next_msg = Message.new(self, delivery_tag, exchange, routing_key, nil, "", redelivered, consumer_tag)
+        end
 
-    def header_delivered(body_size, properties)
-      @next_msg.properties = properties
-      if body_size.zero?
-        next_message_finished!
-      else
-        @next_body = StringIO.new(String.new(capacity: body_size))
-        @next_body_size = body_size
-      end
-    end
+        # @api private
+        def basic_get_empty
+          @basic_gets.push :basic_get_empty
+        end
 
-    def body_delivered(body_part)
-      @next_body.write(body_part)
-      return unless @next_body.pos == @next_body_size
+        # @api private
+        def header_delivered(body_size, properties)
+          @next_msg.properties = properties
+          if body_size.zero?
+            next_message_finished!
+          else
+            @next_body = StringIO.new(String.new(capacity: body_size))
+            @next_body_size = body_size
+          end
+        end
 
-      @next_msg.body = @next_body.string
-      next_message_finished!
-    end
+        # @api private
+        def body_delivered(body_part)
+          @next_body.write(body_part)
+          return unless @next_body.pos == @next_body_size
 
-    def close_consumer(tag)
-      @consumers.fetch(tag).close
-    end
+          @next_msg.body = @next_body.string
+          next_message_finished!
+        end
 
-    private
-
-    def next_message_finished!
-      next_msg = @next_msg
-      if next_msg.is_a? ReturnMessage
-        if @on_return
-          Thread.new { @on_return.call(next_msg) }
-        else
-          warn "AMQP-Client message returned: #{msg.inspect}"
-        end
-      elsif next_msg.consumer_tag.nil?
-        @basic_gets.push next_msg
-      else
-        Thread.pass until (consumer = @consumers[next_msg.consumer_tag])
-        consumer.push next_msg
-      end
-    ensure
-      @next_msg = @next_body = @next_body_size = nil
-    end
+        # @api private
+        def close_consumer(tag)
+          @consumers.fetch(tag).close
+        end
 
-    def write_bytes(*bytes)
-      raise AMQP::Client::ChannelClosedError.new(@id, *@closed) if @closed
+        private
 
-      @connection.write_bytes(*bytes)
-    end
+        def next_message_finished!
+          next_msg = @next_msg
+          if next_msg.is_a? ReturnMessage
+            if @on_return
+              Thread.new { @on_return.call(next_msg) }
+            else
+              warn "AMQP-Client message returned: #{msg.inspect}"
+            end
+          elsif next_msg.consumer_tag.nil?
+            @basic_gets.push next_msg
+          else
+            Thread.pass until (consumer = @consumers[next_msg.consumer_tag])
+            consumer.push next_msg
+          end
+        ensure
+          @next_msg = @next_body = @next_body_size = nil
+        end
+
+        def write_bytes(*bytes)
+          raise Error::ChannelClosed.new(@id, *@closed) if @closed
+
+          @connection.write_bytes(*bytes)
+        end
 
-    def expect(expected_frame_type)
-      frame_type, *args = @replies.pop
-      raise AMQP::Client::ChannelClosedError.new(@id, *@closed) if frame_type.nil?
-      raise AMQP::Client::UnexpectedFrame.new(expected_frame_type, frame_type) unless frame_type == expected_frame_type
+        def expect(expected_frame_type)
+          frame_type, *args = @replies.pop
+          raise Error::ChannelClosed.new(@id, *@closed) if frame_type.nil?
+          raise Error::UnexpectedFrame.new(expected_frame_type, frame_type) unless frame_type == expected_frame_type
 
-      args
+          args
+        end
+      end
     end
   end
 end