amqp-client 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e6dd3fef130c286e97eadd9bb6d3d4de0fa67599361604cec3560879b9b4bdf
-  data.tar.gz: c2ce00f897c68d3085427854b08cc98d3487b40bb5327ce38bb216c98357e366
+  metadata.gz: 0e248898d176ad9c3d785226ed37c0335052ef701ee16a16bff483089be65dd8
+  data.tar.gz: 89b58399edb11b30b05db86e9e4b0a617438e3ed52e63b3e76ae3a4c8cb361fc
 SHA512:
-  metadata.gz: 9b62e8ee74ec542be5617b08fbd0e36e5fc16294f99cd0ec61781c7c7425005c426e8358a74abf45a1a24ecb88451b94ef50ee7524403ac7097748b2e94b55b5
-  data.tar.gz: 5c3e63369578923e20b441fbe9728b374e18150c75ed155291b802c42f80f668b704b39e80b144b90346a8d769d9b71f031b9fca712e6ac52c100a88e46380e3
+  metadata.gz: 4500bec819ea9de9546f001eed682ac040ea3c2f93904dabb24afdbbda966d3352d8b1e33687a82c482ce835e7d650172dd906d9ef4ec2efc17f1dea31947314
+  data.tar.gz: 62ea49dc2782122146dd2613cd51b1c4132b3eef9d48c5573e9369b0af96042018f104a84cfe2aa2f173cf6d10f5ca3e427baa3ef61faed7029cd7328148a762

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/.github/workflows/main.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['2.7', '3.0']
+        ruby: ['2.6', '2.7', '3.0']
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
@@ -32,4 +32,3 @@ jobs:
         bundle exec rake
       env:
         AMQP_PORT: ${{ job.services.rabbitmq.ports[5672] }}
-

data/.rubocop.yml

@@ -1,7 +1,7 @@
 inherit_from: .rubocop_todo.yml
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.6
 
 Style/StringLiterals:
   Enabled: true
@@ -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,32 @@
 ## [Unreleased]
 
+## [1.1.1] - 2021-09-15
+
+- Added: Examples in the documentation
+- Added: Faster Properties and Table encoding and decoding
+
+## [1.1.0] - 2021-09-08
+
+- Fixed: Due to a race condition publishers could get stuck waiting for publish confirms
+- Change: Message, ReturnMessage and Properties are now classes and not structs (for performance reasons)
+- Added: Ruby 2.6 support
+- Added: RBS signatures in sig/amqp-client.rbs
+
+## [1.0.2] - 2021-09-07
+
+- Changed: Raise ConnectionClosed and ChannelClosed correctly (previous always ChannelClosed)
+- Fixed: Respect Connection#blocked sent by the broker, will block all writes/requests
+
+## [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/Gemfile

@@ -10,3 +10,7 @@ gem "rake", "~> 13.0"
 gem "minitest", "~> 5.0"
 
 gem "rubocop", "~> 1.7"
+
+gem "yard", require: false
+
+gem "rubocop-minitest", require: false

data/README.md

@@ -1,54 +1,67 @@
 # AMQP::Client
 
-An AMQP 0-9-1 Ruby client, trying to keep things as simple as possible.
+A modern AMQP 0-9-1 Ruby client. Very fast (just as fast as the Java client, and >4x than other Ruby clients), fully thread-safe, blocking operations and straight-forward error handling.
 
-## Installation
-
-Add this line to your application's Gemfile:
+It's small, only ~1800 lines of code, and without any dependencies. Other Ruby clients are about 4 times bigger. But without trading functionallity.
 
-```ruby
-gem 'amqp-client'
-```
+It's safe by default, messages are published as persistent, and is waiting for confirmation from the broker. That can of course be disabled if performance is a priority.
 
-And then execute:
+## Support
 
-    $ bundle install
+The library is fully supported by [CloudAMQP](https://www.cloudamqp.com), the largest RabbitMQ hosting provider in the world. Open [an issue](https://github.com/cloudamqp/amqp-client.rb/issues) or [email our support](mailto:support@cloudamqp.com) if you have problems or questions.
 
-Or install it yourself as:
+## Documentation
 
-    $ gem install amqp-client
+[API reference](https://cloudamqp.github.io/amqp-client.rb/)
 
 ## Usage
 
-Low level API
+The client has two APIs.
+
+### Low level API
+
+This API matches the AMQP protocol very well, it can do everything the protocol allows, but requires some knowledge about the protocol, and doesn't handle reconnects.
 
 ```ruby
 require "amqp-client"
 
-c = AMQP::Client.new("amqp://guest:guest@localhost")
-conn = c.connect
+# Opens and establishes a connection
+conn = AMQP::Client.new("amqp://guest:guest@localhost").connect
+
+# Open a channel
 ch = conn.channel
+
+# Create a temporary queue
 q = ch.queue_declare
-ch.basic_publish "Hello World!", "", q[:queue_name]
-msg = ch.basic_get q[:queue_name]
+
+# Publish a message to said queue
+ch.basic_publish_confirm "Hello World!", "", q.queue_name, persistent: true
+
+# Poll the queue for a message
+msg = ch.basic_get(q.queue_name)
+
+# Print the message's body to STDOUT
 puts msg.body
 ```
 
-High level API, is an easier and safer API, that only deal with durable queues and persisted messages. All methods are blocking in the case of connection loss etc. It's also fully thread-safe. Don't expect it to have extreme throughput, but expect 100% delivery guarantees (messages might be delivered twice, in the unlikely event of connection loss between message publish and message confirmation by the server).
+### High level API
+
+The library provides a high-level API that is a bit easier to get started with, and also handles reconnection automatically.
 
 ```ruby
-amqp = AMQP::Client.new("amqp://localhost")
-amqp.start
+# Start the client, it will connect and once connected it will reconnect if that connection is lost
+# Operation pending when the connection is lost will raise an exception (not timeout)
+amqp = AMQP::Client.new("amqp://localhost").start
 
 # Declares a durable queue
-q = amqp.queue("myqueue")
+myqueue = amqp.queue("myqueue")
 
 # Bind the queue to any exchange, with any binding key
-q.bind("amq.topic", "my.events.*")
+myqueue.bind("amq.topic", "my.events.*")
 
-# The message will be reprocessed if the client loses connection to the server
+# The message will be reprocessed if the client loses connection to the broker
 # between message arrival and when the message was supposed to be ack'ed.
-q.subscribe(prefetch: 20) do |msg|
+myqueue.subscribe(prefetch: 20) do |msg|
   process(JSON.parse(msg.body))
   msg.ack
 rescue
@@ -56,13 +69,37 @@ rescue
 end
 
 # Publish directly to the queue
-q.publish { foo: "bar" }.to_json, content_type: "application/json"
+myqueue.publish({ foo: "bar" }.to_json, content_type: "application/json")
 
 # Publish to any exchange
 amqp.publish("my message", "amq.topic", "topic.foo", headers: { foo: 'bar' })
 amqp.publish(Zlib.gzip("an event"), "amq.topic", "my.event", content_encoding: 'gzip')
 ```
 
+## Supported Ruby versions
+
+All maintained Ruby versions are supported.
+
+- 3.0
+- 2.7
+- 2.6
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'amqp-client'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install amqp-client
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -71,7 +108,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/cloudamqp/amqp-client.rb
+Bug reports and pull requests are welcome on GitHub at [https://github.com/cloudamqp/amqp-client.rb](https://github.com/cloudamqp/amqp-client.rb/)
 
 ## License
 

data/Rakefile

@@ -11,6 +11,8 @@ end
 
 require "rubocop/rake_task"
 
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new do |task|
+  task.requires << "rubocop-minitest"
+end
 
 task default: %i[test rubocop]

data/amqp-client.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = "Work in progress"
   spec.homepage      = "https://github.com/cloudamqp/amqp-client.rb"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "#{spec.homepage}.git"

data/lib/amqp/client/channel.rb

@@ -3,338 +3,550 @@
 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 = [:channel, 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 broker
+        # @param level [Symbol] :connection or :channel
+        # @return [nil]
+        # @api private
+        def closed!(level, code, reason, classid, methodid)
+          @closed = [level, 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 broker 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 broker 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 broker 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 broker 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
+          nil
+        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::Closed.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 [Boolean] mandatory The message will be returned if the message can't be routed to a queue
+        # @option properties [Boolean] persistent Same as delivery_mode: 2
+        # @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)
+          body_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, body_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 = [body_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)
+        # @option (see #basic_publish)
+        # @return [Boolean] True if the message was successfully published
+        # @raise (see #basic_publish)
+        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 broker if empty.
+        #   Has to be uniqe among this channel's consumers only
+        # @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 for the consumer
+        # @param worker_threads [Integer] Number of threads processing messages,
+        #   0 means that the thread calling this method will process the messages and thus this method will block
+        # @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 broker 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 true 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 broker
+        # @param no_wait [Boolean] If false the method will block until the broker 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
+          ok = @unconfirmed_empty.pop
+          raise Error::Closed.new(@id, *@closed) if ok.nil?
 
-    # 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?
+          ok
+        end
 
-      @unconfirmed_empty.num_waiting.times do
-        @unconfirmed_empty << (ack_or_nack == :ack)
-      end
-    end
+        # Called by Connection when received ack/nack from broker
+        # @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?
 
-    def tx_select
-      write_bytes FrameBytes.tx_select(@id)
-      expect :tx_select_ok
-    end
+          ok = ack_or_nack == :ack
+          @unconfirmed_empty.push(ok) until @unconfirmed_empty.num_waiting.zero?
+        end
 
-    def tx_commit
-      write_bytes FrameBytes.tx_commit(@id)
-      expect :tx_commit_ok
-    end
+        # @!endgroup
+        # @!group Transaction
 
-    def tx_rollback
-      write_bytes FrameBytes.tx_rollback(@id)
-      expect :tx_rollback_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 on_return(&block)
-      @on_return = block
-    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 reply(args)
-      @replies.push(args)
-    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 message_returned(reply_code, reply_text, exchange, routing_key)
-      @next_msg = ReturnMessage.new(reply_code, reply_text, exchange, routing_key, nil, "")
-    end
+        # @!endgroup
 
-    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 reply(args)
+          @replies.push(args)
+        end
 
-    def basic_get_empty
-      @basic_gets.push :basic_get_empty
-    end
+        # @api private
+        def message_returned(reply_code, reply_text, exchange, routing_key)
+          @next_msg = ReturnMessage.new(reply_code, reply_text, exchange, routing_key)
+        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 message_delivered(consumer_tag, delivery_tag, redelivered, exchange, routing_key)
+          @next_msg = Message.new(self, consumer_tag, delivery_tag, exchange, routing_key, redelivered)
+        end
 
-    def body_delivered(body_part)
-      @next_body.write(body_part)
-      return unless @next_body.pos == @next_body_size
+        # @api private
+        def basic_get_empty
+          @basic_gets.push :basic_get_empty
+        end
 
-      @next_msg.body = @next_body.string
-      next_message_finished!
-    end
+        # @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
 
-    def close_consumer(tag)
-      @consumers.fetch(tag).close
-    end
+        # @api private
+        def body_delivered(body_part)
+          @next_body.write(body_part)
+          return unless @next_body.pos == @next_body_size
 
-    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
+          @next_msg.body = @next_body.string
+          next_message_finished!
+        end
 
-    def write_bytes(*bytes)
-      raise AMQP::Client::ChannelClosedError.new(@id, *@closed) if @closed
+        # @api private
+        def close_consumer(tag)
+          @consumers.fetch(tag).close
+          nil
+        end
 
-      @connection.write_bytes(*bytes)
-    end
+        private
 
-    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 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
+          nil
+        ensure
+          @next_msg = @next_body = @next_body_size = nil
+        end
 
-      args
+        def write_bytes(*bytes)
+          raise Error::Closed.new(@id, *@closed) if @closed
+
+          @connection.write_bytes(*bytes)
+        end
+
+        def expect(expected_frame_type)
+          frame_type, *args = @replies.pop
+          raise Error::Closed.new(@id, *@closed) if frame_type.nil?
+          raise Error::UnexpectedFrame.new(expected_frame_type, frame_type) unless frame_type == expected_frame_type
+
+          args
+        end
+      end
     end
   end
 end