amqp-client 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ea2743bb81c4615d1445ee6ce25a5234a95f9f859ca4926ff5437228af1e02
-  data.tar.gz: 4739cd429d9cf55a631c36c9100f78c6d2da65d4aa18535297d69b8ec0ca6e56
+  metadata.gz: 59f619f7aec324221f4c5dd66a10e5e30b1904a224d34702f94f9f75ac19f1c3
+  data.tar.gz: 4d3e3fc1234f44ab741b15b61156617a7f8f181ce5fdc2aacbbc4c07a787129e
 SHA512:
-  metadata.gz: 12d2650fbf4be1f3d1449c4c035e8e12be88a64f3e4eeb2f4588558d294816e36510f53cb37f8217e2754ca3fb6b1acb021df25b63f34c7710f267de6186123c
-  data.tar.gz: 4b44974681cacc7956c73983cebd61315684c35adb5d98851469eaa7677e4a5149cc582cfeb3ec6561f1a036b0b80d7623197e8e1881400f6e00fff1305a4362
+  metadata.gz: 6ade93665b42b3c64ebed869be2af64cde53b259a6f376483c8c4d7e9de6432e2453be88caddf58655c249ae0d531a924348eb97c92b0a6a21b13a3276e3019b
+  data.tar.gz: '0479fe0b0c6f120e4bf0c5b72b905d7946037f8b5e1d83f462c18c2df790c8ed67ff5e32be693deac570d7d82dc9411875f252384364feea3b6e8b85c6abd27d'

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [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/README.md

@@ -38,7 +38,7 @@ msg = ch.basic_get q[:queue_name]
 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, 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 broker).
 
 ```ruby
 amqp = AMQP::Client.new("amqp://localhost")
@@ -50,7 +50,7 @@ q = amqp.queue("myqueue")
 # Bind the queue to any exchange, with any binding key
 q.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|
   process(JSON.parse(msg.body))

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)
@@ -229,7 +230,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 +239,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 +256,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 +264,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 +276,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 +287,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 +298,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 +331,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 +383,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 +394,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
@@ -408,11 +414,11 @@ module AMQP
           case @unconfirmed_empty.pop
           when true then true
           when false then false
-          else raise Error::ChannelClosed.new(@id, *@closed)
+          else raise Error::Closed.new(@id, *@closed)
           end
         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
@@ -527,14 +533,14 @@ module AMQP
         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

data/lib/amqp/client/connection.rb

@@ -59,9 +59,10 @@ module AMQP
         @frame_max = frame_max
         @heartbeat = heartbeat
         @channels = {}
-        @closed = false
+        @closed = nil
         @replies = ::Queue.new
         @write_lock = Mutex.new
+        @blocked = nil
         Thread.new { read_loop } if read_loop_thread
       end
 
@@ -115,17 +116,21 @@ module AMQP
       def close(reason: "", code: 200)
         return if @closed
 
-        @closed = true
-        write_bytes FrameBytes.connection_close(code, reason)
-        @channels.each_value { |ch| ch.closed!(code, reason, 0, 0) }
-        expect(:close_ok)
+        @closed = [code, reason]
+        @channels.each_value { |ch| ch.closed!(:connection, code, reason, 0, 0) }
+        if @blocked
+          @socket.close
+        else
+          write_bytes FrameBytes.connection_close(code, reason)
+          expect(:close_ok)
+        end
         nil
       end
 
       # True if the connection is closed
       # @return [Boolean]
       def closed?
-        @closed
+        !@closed.nil?
       end
 
       # Write byte array(s) directly to the socket (thread-safe)
@@ -133,10 +138,15 @@ module AMQP
       # @return [Integer] number of bytes written
       # @api private
       def write_bytes(*bytes)
+        blocked = @blocked
+        warn "AMQP-Client blocked by broker: #{blocked}" if blocked
         @write_lock.synchronize do
+          warn "AMQP-Client unblocked by broker" if blocked
           @socket.write(*bytes)
         end
       rescue IOError, OpenSSL::OpenSSLError, SystemCallError => e
+        raise Error::ConnectionClosed.new(*@closed) if @closed
+
         raise Error, "Could not write to socket, #{e.message}"
       end
 
@@ -167,10 +177,10 @@ module AMQP
         end
         nil
       rescue IOError, OpenSSL::OpenSSLError, SystemCallError => e
-        warn "AMQP-Client read error: #{e.inspect}"
+        @closed ||= [400, "read error: #{e.message}"]
         nil # ignore read errors
       ensure
-        @closed = true
+        @closed ||= [400, "unknown"]
         @replies.close
         begin
           @socket.close
@@ -191,11 +201,11 @@ module AMQP
 
             case method_id
             when 50 # connection#close
-              @closed = true
               code, text_len = buf.unpack("@4 S> C")
               text = buf.byteslice(7, text_len).force_encoding("utf-8")
               error_class_id, error_method_id = buf.byteslice(7 + text_len, 4).unpack("S> S>")
-              @channels.each_value { |ch| ch.closed!(code, text, error_class_id, error_method_id) }
+              @closed = [code, text, error_class_id, error_method_id]
+              @channels.each_value { |ch| ch.closed!(:connection, code, text, error_class_id, error_method_id) }
               begin
                 write_bytes FrameBytes.connection_close_ok
               rescue Error
@@ -203,9 +213,16 @@ module AMQP
               end
               return false
             when 51 # connection#close-ok
-              @closed = true
               @replies.push [:close_ok]
               return false
+            when 60 # connection#blocked
+              reason_len = buf.unpack1("@4 C")
+              reason = buf.byteslice(5, reason_len).force_encoding("utf-8")
+              @blocked = reason
+              @write_lock.lock
+            when 61 # connection#unblocked
+              @blocked = nil
+              @write_lock.unlock
             else raise Error::UnsupportedMethodFrame, class_id, method_id
             end
           when 20 # channel
@@ -217,7 +234,7 @@ module AMQP
               reply_text = buf.byteslice(7, reply_text_len).force_encoding("utf-8")
               classid, methodid = buf.byteslice(7 + reply_text_len, 4).unpack("S> S>")
               channel = @channels.delete(channel_id)
-              channel.closed!(reply_code, reply_text, classid, methodid)
+              channel.closed!(:channel, reply_code, reply_text, classid, methodid)
               write_bytes FrameBytes.channel_close_ok(channel_id)
             when 41 # channel#close-ok
               channel = @channels.delete(channel_id)

data/lib/amqp/client/errors.rb

@@ -32,6 +32,19 @@ module AMQP
         end
       end
 
+      # Depending on close level a ConnectionClosed or ChannelClosed error is returned
+      class Closed < Error
+        def self.new(id, level, code, reason, classid = 0, methodid = 0)
+          case level
+          when :connection
+            ConnectionClosed.new(code, reason, classid, methodid)
+          when :channel
+            ChannelClosed.new(id, code, reason, classid, methodid)
+          else raise ArgumentError, "invalid level '#{level}'"
+          end
+        end
+      end
+
       # Raised if channel is already closed
       class ChannelClosed < Error
         def initialize(id, code, reason, classid = 0, methodid = 0)
@@ -40,7 +53,11 @@ module AMQP
       end
 
       # Raised if connection is unexpectedly closed
-      class ConnectionClosed < Error; end
+      class ConnectionClosed < Error
+        def initialize(code, reason, classid = 0, methodid = 0)
+          super "Connection closed (#{code}) #{reason} (#{classid}/#{methodid})"
+        end
+      end
     end
   end
 end

data/lib/amqp/client/queue.rb

@@ -11,30 +11,24 @@ module AMQP
         @name = name
       end
 
-      # Publish to the queue
-      # @param body [String] The message body
-      # @param properties [Properties]
-      # @option properties [String] content_type Content type of the message body
-      # @option properties [String] content_encoding Content encoding of the body
-      # @option properties [Hash<String, Object>] headers Custom headers
-      # @option properties [Integer] delivery_mode 2 for persisted message, transient messages for all other values
-      # @option properties [Integer] priority A priority of the message (between 0 and 255)
-      # @option properties [Integer] correlation_id A correlation id, most often used used for RPC communication
-      # @option properties [String] reply_to Queue to reply RPC responses to
-      # @option properties [Integer, String] expiration Number of seconds the message will stay in the queue
-      # @option properties [String] message_id Can be used to uniquely identify the message, e.g. for deduplication
-      # @option properties [Date] timestamp Often used for the time the message was originally generated
-      # @option properties [String] type Can indicate what kind of message this is
-      # @option properties [String] user_id Can be used to verify that this is the user that published the message
-      # @option properties [String] app_id Can be used to indicates which app that generated the message
-      # @return [Queue] self
+      # Publish to the queue, wait for confirm
+      # @param (see Client#publish)
+      # @option (see Client#publish)
+      # @raise (see Client#publish)
+      # @return [self]
       def publish(body, **properties)
         @client.publish(body, "", @name, **properties)
         self
       end
 
       # Subscribe/consume from the queue
-      # @return [Queue] self
+      # @param no_ack [Boolean] When false messages have to be manually acknowledged (or rejected)
+      # @param prefetch [Integer] Specify how many messages to prefetch for consumers with no_ack is false
+      # @param worker_threads [Integer] Number of threads processing messages,
+      #   0 means that the thread calling this method will be blocked
+      # @param arguments [Hash] Custom arguments to the consumer
+      # @yield [Message] Delivered message from the queue
+      # @return [self]
       def subscribe(no_ack: false, prefetch: 1, worker_threads: 1, arguments: {}, &blk)
         @client.subscribe(@name, no_ack: no_ack, prefetch: prefetch, worker_threads: worker_threads, arguments: arguments, &blk)
         self
@@ -44,7 +38,7 @@ module AMQP
       # @param exchange [String] Name of the exchange to bind to
       # @param binding_key [String] Binding key on which messages that match might be routed (depending on exchange type)
       # @param arguments [Hash] Message headers to match on (only relevant for header exchanges)
-      # @return [Queue] self
+      # @return [self]
       def bind(exchange, binding_key, arguments: {})
         @client.bind(@name, exchange, binding_key, arguments: arguments)
         self
@@ -54,14 +48,14 @@ module AMQP
       # @param exchange [String] Name of the exchange to unbind from
       # @param binding_key [String] Binding key which the queue is bound to the exchange with
       # @param arguments [Hash] Arguments matching the binding that's being removed
-      # @return [Queue] self
+      # @return [self]
       def unbind(exchange, binding_key, arguments: {})
         @client.unbind(@name, exchange, binding_key, arguments: arguments)
         self
       end
 
       # Purge/empty the queue
-      # @return [Queue] self
+      # @return [self]
       def purge
         @client.purge(@name)
         self

data/lib/amqp/client/version.rb

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

data/lib/amqp/client.rb

@@ -122,7 +122,10 @@ module AMQP
     # @!group Publish
 
     # Publish a (persistent) message and wait for confirmation
-    # @return [nil]
+    # @param (see Connection::Channel#basic_publish_confirm)
+    # @option (see Connection::Channel#basic_publish_confirm)
+    # @return (see Connection::Channel#basic_publish_confirm)
+    # @raise (see Connection::Channel#basic_publish_confirm)
     def publish(body, exchange, routing_key, **properties)
       with_connection do |conn|
         properties = { delivery_mode: 2 }.merge!(properties)
@@ -131,7 +134,10 @@ module AMQP
     end
 
     # Publish a (persistent) message but don't wait for a confirmation
-    # @return [nil]
+    # @param (see Connection::Channel#basic_publish)
+    # @option (see Connection::Channel#basic_publish)
+    # @return (see Connection::Channel#basic_publish)
+    # @raise (see Connection::Channel#basic_publish)
     def publish_and_forget(body, exchange, routing_key, **properties)
       with_connection do |conn|
         properties = { delivery_mode: 2 }.merge!(properties)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amqp-client
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Carl Hörberg
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-06 00:00:00.000000000 Z
+date: 2021-09-07 00:00:00.000000000 Z
 dependencies: []
 description: Work in progress
 email: