amqp-client 1.0.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ea2743bb81c4615d1445ee6ce25a5234a95f9f859ca4926ff5437228af1e02
-  data.tar.gz: 4739cd429d9cf55a631c36c9100f78c6d2da65d4aa18535297d69b8ec0ca6e56
+  metadata.gz: baa9c2034e80f56aa375a7abb7394109d2f4e84e4a4c04ae8bcb053d299d6dcc
+  data.tar.gz: 7857e1d6ddf96a64df664956da02eac2098fe144a5d2eea1364bd14ba5d41b7c
 SHA512:
-  metadata.gz: 12d2650fbf4be1f3d1449c4c035e8e12be88a64f3e4eeb2f4588558d294816e36510f53cb37f8217e2754ca3fb6b1acb021df25b63f34c7710f267de6186123c
-  data.tar.gz: 4b44974681cacc7956c73983cebd61315684c35adb5d98851469eaa7677e4a5149cc582cfeb3ec6561f1a036b0b80d7623197e8e1881400f6e00fff1305a4362
+  metadata.gz: 4deaecc1cdce66be71316e3046c5df0832c20a876ad0d3f5884c6e6313ece2d7fad8262f8ee83daad78500ca411648618642eb551c63279e8b84ec727d1f5633
+  data.tar.gz: 4136f5ce5c98610361a673f348fd531a93c34c7989275e7858bfc9694d7368adcbd17beb910fae30cd1fceb29163b7411d4ee0dc235f9c655bfdf960a9de4602

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', 'jruby', 'truffleruby']
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
@@ -31,5 +31,5 @@ jobs:
         bundle install
         bundle exec rake
       env:
+        TESTOPTS: --exclude=/_tls$/
         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

data/.rubocop_todo.yml

@@ -1,15 +1,27 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2021-09-06 19:39:47 UTC using RuboCop version 1.19.1.
+# on 2021-10-15 13:44:24 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: 18
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 132
+
+# Offense count: 1
+Lint/RescueException:
+  Exclude:
+    - 'lib/amqp/client/connection.rb'
+
+# Offense count: 32
 # Configuration parameters: IgnoredMethods, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 179
+  Max: 175
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
@@ -22,27 +34,32 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 5
+# Offense count: 6
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 400
+  Max: 497
 
-# Offense count: 9
+# Offense count: 10
 # Configuration parameters: IgnoredMethods.
 Metrics/CyclomaticComplexity:
-  Max: 44
+  Max: 46
 
-# Offense count: 40
+# Offense count: 67
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 Metrics/MethodLength:
-  Max: 170
+  Max: 169
 
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 500
+  Max: 486
+
+# Offense count: 1
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 13
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: IgnoredMethods.
 Metrics/PerceivedComplexity:
-  Max: 22
+  Max: 23

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [1.1.2] - 2021-10-15
+
+- Added: Support for JRuby and TruffleRuby
+
+## [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/

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,58 +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.
 
-## Documentation
+It's small, only ~1800 lines of code, and without any dependencies. Other Ruby clients are about 4 times bigger. But without trading functionallity.
 
-[API reference](https://cloudamqp.github.io/amqp-client.rb/)
+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.
 
-## Installation
+## Support
 
-Add this line to your application's Gemfile:
+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.
 
-```ruby
-gem 'amqp-client'
-```
-
-And then execute:
+## Documentation
 
-    $ bundle install
+[API reference](https://cloudamqp.github.io/amqp-client.rb/)
 
-Or install it yourself as:
+## Usage
 
-    $ gem install amqp-client
+The client has two APIs.
 
-## Usage
+### Low level API
 
-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
@@ -60,13 +69,39 @@ 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
+- jruby
+- truffleruby
+
+## 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.
@@ -75,7 +110,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

@@ -55,7 +55,7 @@ module AMQP
           return if @closed
 
           write_bytes FrameBytes.channel_close(@id, reason, code)
-          @closed = [code, reason]
+          @closed = [:channel, code, reason]
           expect :channel_close_ok
           @replies.close
           @basic_gets.close
@@ -64,11 +64,12 @@ module AMQP
           nil
         end
 
-        # Called when channel is closed by server
+        # Called when channel is closed by broker
+        # @param level [Symbol] :connection or :channel
         # @return [nil]
         # @api private
-        def closed!(code, reason, classid, methodid)
-          @closed = [code, reason, classid, methodid]
+        def closed!(level, code, reason, classid, methodid)
+          @closed = [level, code, reason, classid, methodid]
           @replies.close
           @basic_gets.close
           @unconfirmed_empty.close
@@ -77,7 +78,7 @@ module AMQP
         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
+        # @yield [ReturnMessage] Messages returned by the broker when a publish has failed
         # @return nil
         def on_return(&block)
           @on_return = block
@@ -105,7 +106,7 @@ module AMQP
         # 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
+        # @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)
@@ -174,7 +175,7 @@ module AMQP
         # @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
+        # @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)
@@ -197,7 +198,7 @@ module AMQP
 
         # Purge a queue
         # @param name [String] Name of the queue
-        # @param no_wait [Boolean] Don't wait for a server confirmation if true
+        # @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)
@@ -214,6 +215,7 @@ module AMQP
         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
 
         # @!endgroup
@@ -229,7 +231,7 @@ module AMQP
           case (msg = @basic_gets.pop)
           when Message then msg
           when :basic_get_empty then nil
-          when nil              then raise Error::ChannelClosed.new(@id, *@closed)
+          when nil              then raise Error::Closed.new(@id, *@closed)
           end
         end
 
@@ -238,6 +240,8 @@ module AMQP
         # @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
@@ -253,7 +257,7 @@ module AMQP
         # @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
+          body_max = @connection.frame_max - 8
           id = @id
           mandatory = properties.delete(:mandatory) || false
           case properties.delete(:persistent)
@@ -261,7 +265,7 @@ module AMQP
           when false then properties[:delivery_mode] = 1
           end
 
-          if body.bytesize.between?(1, frame_max)
+          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)
@@ -273,7 +277,7 @@ module AMQP
                       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
+            len = [body_max, body.bytesize - pos].min
             body_part = body.byteslice(pos, len)
             write_bytes FrameBytes.body(id, body_part)
             pos += len
@@ -284,7 +288,9 @@ module AMQP
 
         # 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)
@@ -293,12 +299,13 @@ module AMQP
 
         # 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 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 to the consumer
+        # @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 be blocked
+        #   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
@@ -325,7 +332,7 @@ module AMQP
 
         # 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
+        # @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)
@@ -377,7 +384,7 @@ module AMQP
 
         # 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
+        #   if true to any consumer
         # @return [nil]
         def basic_recover(requeue: false)
           write_bytes FrameBytes.basic_recover(@id, requeue: requeue)
@@ -388,8 +395,8 @@ module AMQP
         # @!endgroup
         # @!group 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
+        # 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
@@ -405,14 +412,13 @@ module AMQP
         def wait_for_confirms
           return true if @unconfirmed.empty?
 
-          case @unconfirmed_empty.pop
-          when true then true
-          when false then false
-          else raise Error::ChannelClosed.new(@id, *@closed)
-          end
+          ok = @unconfirmed_empty.pop
+          raise Error::Closed.new(@id, *@closed) if ok.nil?
+
+          ok
         end
 
-        # Called by Connection when received ack/nack from server
+        # Called by Connection when received ack/nack from broker
         # @api private
         def confirm(args)
           ack_or_nack, delivery_tag, multiple = *args
@@ -427,9 +433,8 @@ module AMQP
           end
           return unless @unconfirmed.empty?
 
-          @unconfirmed_empty.num_waiting.times do
-            @unconfirmed_empty << (ack_or_nack == :ack)
-          end
+          ok = ack_or_nack == :ack
+          @unconfirmed_empty.push(ok) until @unconfirmed_empty.num_waiting.zero?
         end
 
         # @!endgroup
@@ -468,12 +473,12 @@ module AMQP
 
         # @api private
         def message_returned(reply_code, reply_text, exchange, routing_key)
-          @next_msg = ReturnMessage.new(reply_code, reply_text, exchange, routing_key, nil, "")
+          @next_msg = ReturnMessage.new(reply_code, reply_text, exchange, routing_key)
         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)
+          @next_msg = Message.new(self, consumer_tag, delivery_tag, exchange, routing_key, redelivered)
         end
 
         # @api private
@@ -504,6 +509,7 @@ module AMQP
         # @api private
         def close_consumer(tag)
           @consumers.fetch(tag).close
+          nil
         end
 
         private
@@ -522,19 +528,20 @@ module AMQP
             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
 
         def write_bytes(*bytes)
-          raise Error::ChannelClosed.new(@id, *@closed) if @closed
+          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::ChannelClosed.new(@id, *@closed) if frame_type.nil?
+          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