amqp-client 1.2.0 → 2.0.0

data/lib/amqp/client/errors.rb

@@ -5,30 +5,37 @@ module AMQP
     # All errors raised inherit from this class
     class Error < StandardError
       # Raised when a frame that wasn't expected arrives
-      class UnexpectedFrame < Error
+      class UnexpectedFrameType < Error
         def initialize(expected, actual)
-          super "Expected frame type '#{expected}' but got '#{actual}'"
+          super("Expected frame type '#{expected}' but got '#{actual}'")
         end
       end
 
       # Raised when a frame doesn't end with 206
       class UnexpectedFrameEnd < Error
         def initialize(actual)
-          super "Expected frame end 206 but got '#{actual}'"
+          super("Expected frame end 206 but got '#{actual}'")
         end
       end
 
       # Should never be raised as we support all official frame types
       class UnsupportedFrameType < Error
         def initialize(type)
-          super "Unsupported frame type '#{type}'"
+          super("Unsupported frame type '#{type}'")
         end
       end
 
       # Raised if a frame is received but not implemented
       class UnsupportedMethodFrame < Error
         def initialize(class_id, method_id)
-          super "Unsupported class/method: #{class_id} #{method_id}"
+          super("Unsupported class/method: #{class_id} #{method_id}")
+        end
+      end
+
+      # Raised if a message published with confirms enabled was not confirmed (nacked)
+      class PublishNotConfirmed < Error
+        def initialize
+          super("Message was not confirmed by the broker")
         end
       end
 
@@ -37,25 +44,93 @@ module AMQP
         def self.new(id, level, code, reason, classid = 0, methodid = 0)
           case level
           when :connection
-            ConnectionClosed.new(code, reason, classid, methodid)
+            build_connection_error(code, reason, classid, methodid)
           when :channel
-            ChannelClosed.new(id, code, reason, classid, methodid)
+            build_channel_error(id, code, reason, classid, methodid)
           else raise ArgumentError, "invalid level '#{level}'"
           end
         end
+
+        private_class_method def self.build_connection_error(code, reason, classid, methodid)
+          klass = case code
+                  when 320
+                    ConnectionForced
+                  when 501
+                    FrameError
+                  when 503
+                    CommandInvalid
+                  when 504
+                    ChannelError
+                  when 505
+                    UnexpectedFrame
+                  when 506
+                    ResourceError
+                  when 530
+                    NotAllowedError
+                  when 541
+                    InternalError
+                  else
+                    ConnectionClosed
+                  end
+          klass.new(code, reason, classid, methodid)
+        end
+
+        private_class_method def self.build_channel_error(id, code, reason, classid, methodid)
+          klass = case code
+                  when 403
+                    AccessRefused
+                  when 404
+                    NotFound
+                  when 405
+                    ResourceLocked
+                  when 406
+                    PreconditionFailed
+                  else
+                    ChannelClosed
+                  end
+          klass.new(id, code, reason, classid, methodid)
+        end
       end
 
       # Raised if channel is already closed
       class ChannelClosed < Error
         def initialize(id, code, reason, classid = 0, methodid = 0)
-          super "Channel[#{id}] closed (#{code}) #{reason} (#{classid}/#{methodid})"
+          super("Channel[#{id}] closed (#{code}) #{reason} (#{classid}/#{methodid})")
         end
       end
 
       # Raised if connection is unexpectedly closed
       class ConnectionClosed < Error
         def initialize(code, reason, classid = 0, methodid = 0)
-          super "Connection closed (#{code}) #{reason} (#{classid}/#{methodid})"
+          super("Connection closed (#{code}) #{reason} (#{classid}/#{methodid})")
+        end
+      end
+
+      class AccessRefused < ChannelClosed; end
+      class NotFound < ChannelClosed; end
+      class ResourceLocked < ChannelClosed; end
+      class PreconditionFailed < ChannelClosed; end
+
+      class ConnectionForced < ConnectionClosed; end
+      class FrameError < ConnectionClosed; end
+      class CommandInvalid < ConnectionClosed; end
+      class ChannelError < ConnectionClosed; end
+      class UnexpectedFrame < ConnectionClosed; end
+      class ResourceError < ConnectionClosed; end
+      class NotAllowedError < ConnectionClosed; end
+      class InternalError < ConnectionClosed; end
+
+      # Raised if trying to parse a message with an unsupported content type
+      class UnsupportedContentType < Error
+        def initialize(content_type)
+          super("Unsupported content type #{content_type}")
+        end
+      end
+
+      # Raised if trying to parse a message with an unsupported content encoding
+      class UnsupportedContentEncoding < Error
+        def initialize(content_encoding)
+          super("Unsupported content encoding #{content_encoding}")
         end
       end
     end

data/lib/amqp/client/exchange.rb

@@ -4,6 +4,8 @@ module AMQP
   class Client
     # High level representation of an exchange
     class Exchange
+      attr_reader :name
+
       # Should only be initialized from the Client
       # @api private
       def initialize(client, name)
@@ -11,47 +13,47 @@ module AMQP
         @name = name
       end
 
-      # Publish to the exchange
-      # @param body [String] The message body
-      # @param routing_key [String] The routing key of the message,
-      #   the exchange may use this when routing the message to bound queues
-      # @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
+      # Publish to the exchange, wait for confirm
+      # @param body [Object] The message body
+      #   will be encoded if any matching codec is found in the client's codec registry
+      # @param routing_key [String] Routing key for the message
+      # @option (see Client#publish)
+      # @raise (see Client#publish)
+      # @return [Exchange] self
+      def publish(body, routing_key: "", **properties)
+        @client.publish(body, exchange: @name, routing_key:, **properties)
+        self
+      end
+
+      # Publish to the exchange, without waiting for confirm
+      # @param (see Exchange#publish)
+      # @option (see Exchange#publish)
+      # @raise (see Exchange#publish)
       # @return [Exchange] self
-      def publish(body, routing_key, **properties)
-        @client.publish(body, @name, routing_key, **properties)
+      def publish_and_forget(body, routing_key: "", **properties)
+        @client.publish_and_forget(body, exchange: @name, routing_key:, **properties)
         self
       end
 
       # Bind to another exchange
-      # @param exchange [String] Name of the exchange to bind to
-      # @param binding_key [String] Binding key on which messages that match might be routed (depending on exchange type)
+      # @param source [String, Exchange] Name of the exchange to bind to, or the exchange object itself
+      # @param binding_key [String] Binding key on which messages that match might be routed (defaults to empty string)
       # @param arguments [Hash] Message headers to match on (only relevant for header exchanges)
       # @return [Exchange] self
-      def bind(exchange, binding_key, arguments: {})
-        @client.exchange_bind(@name, exchange, binding_key, arguments: arguments)
+      def bind(source, binding_key: "", arguments: {})
+        source = source.name unless source.is_a?(String)
+        @client.exchange_bind(source:, destination: @name, binding_key:, arguments:)
         self
       end
 
       # Unbind from another exchange
-      # @param exchange [String] Name of the exchange to unbind from
-      # @param binding_key [String] Binding key which the queue is bound to the exchange with
+      # @param source [String, Exchange] Name of the exchange to unbind from, or the exchange object itself
+      # @param binding_key [String] Binding key which the queue is bound to the exchange with (defaults to empty string)
       # @param arguments [Hash] Arguments matching the binding that's being removed
       # @return [Exchange] self
-      def unbind(exchange, binding_key, arguments: {})
-        @client.exchange_unbind(@name, exchange, binding_key, arguments: arguments)
+      def unbind(source, binding_key: "", arguments: {})
+        source = source.name unless source.is_a?(String)
+        @client.exchange_unbind(source:, destination: @name, binding_key:, arguments:)
         self
       end
 

data/lib/amqp/client/frame_bytes.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "./properties"
-require_relative "./table"
+require_relative "properties"
+require_relative "table"
 
 module AMQP
   class Client
@@ -370,9 +370,8 @@ module AMQP
         ].pack("C S> L> a* C")
       end
 
-      def self.basic_consume(id, queue, tag, no_ack, exclusive, arguments)
+      def self.basic_consume(id, queue, tag, no_ack, exclusive, no_wait, arguments)
         no_local = false
-        no_wait = false
         bits = 0
         bits |= (1 << 0) if no_local
         bits |= (1 << 1) if no_ack

data/lib/amqp/client/message.rb

@@ -14,8 +14,12 @@ module AMQP
         @redelivered = redelivered
         @properties = nil
         @body = ""
+        @ack_or_reject_sent = false
+        @parsed = nil
       end
 
+      DeliveryInfo = Struct.new(:consumer_tag, :delivery_tag, :redelivered, :exchange, :routing_key, :channel)
+
       # The channel the message was deliviered to
       # @return [Connection::Channel]
       attr_reader :channel
@@ -49,17 +53,36 @@ module AMQP
       # @return [String]
       attr_accessor :body
 
+      def delivery_info
+        @delivery_info ||= DeliveryInfo.new(
+          consumer_tag:,
+          delivery_tag:,
+          redelivered:,
+          exchange:,
+          routing_key:,
+          channel:
+        )
+      end
+
       # Acknowledge the message
       # @return [nil]
       def ack
+        return if @ack_or_reject_sent
+
         @channel.basic_ack(@delivery_tag)
+        @ack_or_reject_sent = true
+        nil
       end
 
       # Reject the message
       # @param requeue [Boolean] If true the message will be put back into the queue again, ready to be redelivered
       # @return [nil]
       def reject(requeue: false)
-        @channel.basic_reject(@delivery_tag, requeue: requeue)
+        return if @ack_or_reject_sent
+
+        @channel.basic_reject(@delivery_tag, requeue:)
+        @ack_or_reject_sent = true
+        nil
       end
 
       # @see #exchange
@@ -69,6 +92,48 @@ module AMQP
       def exchange_name
         @exchange
       end
+
+      # @!group Message coding
+
+      # Parse the message body based on content_type and content_encoding
+      # @raise [Error::UnsupportedContentEncoding] If the content encoding is not supported
+      # @raise [Error::UnsupportedContentType] If the content type is not supported
+      # @return [Object] The parsed message body
+      def parse
+        return @parsed unless @parsed.nil?
+
+        registry = @channel.connection.codec_registry
+        strict = @channel.connection.strict_coding
+        decoded = decode
+        ct = @properties&.content_type
+        parser = registry&.find_parser(ct)
+
+        return @parsed = parser.parse(decoded, @properties) if parser
+
+        is_unsupported = ct && ct != "" && ct != "text/plain"
+        raise Error::UnsupportedContentType, ct if is_unsupported && strict
+
+        @parsed = decoded
+      end
+
+      # Decode the message body based on content_encoding
+      # @raise [Error::UnsupportedContentEncoding] If the content encoding is not supported
+      # @return [String] The decoded message body
+      def decode
+        registry = @channel.connection.codec_registry
+        strict = @channel.connection.strict_coding
+        ce = @properties&.content_encoding
+        coder = registry&.find_coder(ce)
+
+        return coder.decode(@body, @properties) if coder
+
+        is_unsupported = ce && ce != ""
+        raise Error::UnsupportedContentEncoding, ce if is_unsupported && strict
+
+        @body
+      end
+
+      # @!endgroup
     end
 
     # A published message returned by the broker due to some error

data/lib/amqp/client/message_codec_registry.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module AMQP
+  class Client
+    # Internal registry that stores content_type parsers and content_encoding coders.
+    # Only exact content_type and content_encoding matches are supported.
+    class MessageCodecRegistry
+      def initialize
+        @parsers = {} # content_type => handler
+        @coders = {} # content_encoding => handler
+      end
+
+      # Register a parser for a content_type
+      # @param content_type [String] The content_type to match
+      # @param parser [Object] The parser object,
+      #   must respond to parse(data, properties) and serialize(obj, properties)
+      # @return [self]
+      def register_parser(content_type:, parser:)
+        validate_parser!(parser)
+        @parsers[content_type] = parser
+        self
+      end
+
+      # Register a coder for a specific content_encoding
+      # @param content_encoding [String] The content_encoding to match
+      # @param coder [Object] The coder object,
+      #   must respond to encode(data, properties) and decode(data, properties)
+      # @return [self]
+      def register_coder(content_encoding:, coder:)
+        validate_coder!(coder)
+        @coders[content_encoding] = coder
+        self
+      end
+
+      # Find parser handler based on message properties
+      # @param content_type [String] The content_type to match
+      # @return [Object, nil] The parser object or nil if not found
+      def find_parser(content_type)
+        @parsers[content_type]
+      end
+
+      # Find coder handler based on content_encoding
+      # @param content_encoding [String] The content_encoding to match
+      # @return [Object, nil] The coder object or nil if not found
+      def find_coder(content_encoding)
+        @coders[content_encoding]
+      end
+
+      # Introspection helper to list all registered content types
+      # @return [Array<String>] List of registered content types
+      def list_content_types
+        @parsers.keys
+      end
+
+      # Introspection helper to list all registered content encodings
+      # @return [Array<String>] List of registered content encodings
+      def list_content_encodings
+        @coders.keys
+      end
+
+      # Enable built-in parsers for common content types
+      # @return [self]
+      def enable_builtin_parsers
+        register_parser(content_type: "text/plain", parser: Parsers::Plain)
+        register_parser(content_type: "application/json", parser: Parsers::JSONParser)
+        self
+      end
+
+      # Enable built-in coders for common content encodings
+      # @return [self]
+      def enable_builtin_coders
+        register_coder(content_encoding: "gzip", coder: Coders::Gzip)
+        register_coder(content_encoding: "deflate", coder: Coders::Deflate)
+        self
+      end
+
+      # Enable all built-in codecs (parsers and coders)
+      # @return [self]
+      def enable_builtin_codecs
+        enable_builtin_parsers.enable_builtin_coders
+      end
+
+      # Lightweight cloning: registry contents duplicated (shallow copy of handler references)
+      def dup
+        copy = self.class.new
+        @parsers.each { |k, v| copy.register_parser(content_type: k, parser: v) }
+        @coders.each { |k, v| copy.register_coder(content_encoding: k, coder: v) }
+        copy
+      end
+
+      private
+
+      def validate_parser!(parser)
+        return if parser.respond_to?(:parse) && parser.respond_to?(:serialize)
+
+        raise ArgumentError, "parser must respond to parse(data, properties) and serialize(obj, properties)"
+      end
+
+      def validate_coder!(coder)
+        return if coder.respond_to?(:encode) && coder.respond_to?(:decode)
+
+        raise ArgumentError, "coder must respond to encode(data, properties) and decode(data, properties)"
+      end
+    end
+  end
+end

data/lib/amqp/client/message_codecs.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "zlib"
+
+module AMQP
+  class Client
+    module Parsers
+      # Plain text passthrough parser
+      Plain = Class.new do
+        def parse(data, _properties) = data
+        def serialize(obj, _properties) = obj.is_a?(String) ? obj : obj.to_s
+      end.new
+
+      JSONParser = Class.new do
+        def parse(data, _properties) = ::JSON.parse(data, symbolize_names: true)
+        def serialize(obj, _properties) = ::JSON.dump(obj)
+      end.new
+    end
+
+    module Coders
+      Gzip = Class.new do
+        def encode(data, _properties)
+          return data if data.encoding == Encoding::BINARY
+
+          Zlib.gzip(data)
+        end
+
+        def decode(data, _properties) = Zlib.gunzip(data)
+      end.new
+
+      Deflate = Class.new do
+        def encode(data, _properties)
+          return data if data.encoding == Encoding::BINARY
+
+          Zlib.deflate(data)
+        end
+
+        def decode(data, _properties) = Zlib.inflate(data)
+      end.new
+    end
+  end
+end

data/lib/amqp/client/properties.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "./table"
+require_relative "table"
 
 module AMQP
   class Client
@@ -30,19 +30,19 @@ module AMQP
       # @return [Hash] Properties
       def to_h
         {
-          content_type: content_type,
-          content_encoding: content_encoding,
-          headers: headers,
-          delivery_mode: delivery_mode,
-          priority: priority,
-          correlation_id: correlation_id,
-          reply_to: reply_to,
-          expiration: expiration,
-          message_id: message_id,
-          timestamp: timestamp,
-          type: type,
-          user_id: user_id,
-          app_id: app_id
+          content_type:,
+          content_encoding:,
+          headers:,
+          delivery_mode:,
+          priority:,
+          correlation_id:,
+          reply_to:,
+          expiration:,
+          message_id:,
+          timestamp:,
+          type:,
+          user_id:,
+          app_id:
         }
       end
 
@@ -184,7 +184,8 @@ module AMQP
         end
 
         if (timestamp = properties[:timestamp])
-          timestamp.is_a?(Integer) || timestamp.is_a?(Time) || raise(ArgumentError, "timestamp must be an Integer or a Time")
+          timestamp.is_a?(Integer) || timestamp.is_a?(Time) ||
+            raise(ArgumentError, "timestamp must be an Integer or a Time")
 
           flags |= (1 << 6)
           arr << timestamp.to_i

data/lib/amqp/client/queue.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "consumer"
+
 module AMQP
   class Client
     # Queue abstraction
     class Queue
+      attr_reader :name
+
       # Should only be initialized from the Client
       # @api private
       def initialize(client, name)
@@ -12,45 +16,79 @@ module AMQP
       end
 
       # Publish to the queue, wait for confirm
-      # @param (see Client#publish)
+      # @param body [Object] The message body
+      #   will be encoded if any matching codec is found in the client's codec registry
       # @option (see Client#publish)
       # @raise (see Client#publish)
-      # @return [self]
+      # @return [Queue] self
       def publish(body, **properties)
-        @client.publish(body, "", @name, **properties)
+        @client.publish(body, exchange: "", routing_key: @name, **properties)
+        self
+      end
+
+      # Publish to the queue, without waiting for confirm
+      # @param (see Queue#publish)
+      # @option (see Queue#publish)
+      # @raise (see Queue#publish)
+      # @return [Queue] self
+      def publish_and_forget(body, **properties)
+        @client.publish_and_forget(body, exchange: "", routing_key: @name, **properties)
         self
       end
 
       # Subscribe/consume from the queue
-      # @param no_ack [Boolean] When false messages have to be manually acknowledged (or rejected)
+      # @param no_ack [Boolean] If true, messages are automatically acknowledged by the server upon delivery.
+      #   If false, messages are acknowledged only after the block completes successfully; if the block raises
+      #   an exception, the message is rejected and can be optionally requeued.
+      #   You can of course handle the ack/reject in the block yourself. (Default: false)
+      # @param exclusive [Boolean] When true only a single consumer can consume from the queue at a time
       # @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 requeue_on_reject [Boolean] If true, messages that are rejected due to an exception in the block
+      #   will be requeued. Only relevant if no_ack is false. (Default: true)
+      # @param on_cancel [Proc] Optional proc that will be called if the consumer is cancelled by the broker
+      #   The proc will be called with the consumer tag as the only argument
       # @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
+      # @return [Consumer] The consumer object, which can be used to cancel the consumer
+      def subscribe(no_ack: false, exclusive: false, prefetch: 1, worker_threads: 1, requeue_on_reject: true,
+                    on_cancel: nil, arguments: {})
+        @client.subscribe(@name, no_ack:, exclusive:, prefetch:, worker_threads:, on_cancel:, arguments:) do |message|
+          yield message
+          message.ack unless no_ack
+        rescue StandardError => e
+          message.reject(requeue: requeue_on_reject) unless no_ack
+          raise e
+        end
+      end
+
+      # Get a message from the queue
+      # @param no_ack [Boolean] When false the message has to be manually acknowledged (or rejected) (default: false)
+      # @return [Message, nil] The message from the queue or nil if the queue is empty
+      def get(no_ack: false)
+        @client.get(@name, no_ack:)
       end
 
       # Bind the queue to an exchange
-      # @param exchange [String] Name of the exchange to bind to
+      # @param exchange [String, Exchange] Name of the exchange to bind to, or the exchange object itself
       # @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 [self]
-      def bind(exchange, binding_key, arguments: {})
-        @client.bind(@name, exchange, binding_key, arguments: arguments)
+      def bind(exchange, binding_key: "", arguments: {})
+        exchange = exchange.name unless exchange.is_a?(String)
+        @client.bind(queue: @name, exchange:, binding_key:, arguments:)
         self
       end
 
       # Unbind the queue from an exchange
-      # @param exchange [String] Name of the exchange to unbind from
+      # @param exchange [String, Exchange] Name of the exchange to unbind from, or the exchange object itself
       # @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 [self]
-      def unbind(exchange, binding_key, arguments: {})
-        @client.unbind(@name, exchange, binding_key, arguments: arguments)
+      def unbind(exchange, binding_key: "", arguments: {})
+        exchange = exchange.name unless exchange.is_a?(String)
+        @client.unbind(queue: @name, exchange:, binding_key:, arguments:)
         self
       end