amqp-client 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec3129a38420f19de4c0225aea1eaefc320463c6e032c54990a998f7654f8347
-  data.tar.gz: 3c8da5fccb818730958f47fdaf78837524381b116a322adaf585ee02d0492b2d
+  metadata.gz: 0e248898d176ad9c3d785226ed37c0335052ef701ee16a16bff483089be65dd8
+  data.tar.gz: 89b58399edb11b30b05db86e9e4b0a617438e3ed52e63b3e76ae3a4c8cb361fc
 SHA512:
-  metadata.gz: 24b592bb7fc50f29499e32ca6348f2aa25bac9837e694740346fa24e1fe6c45c9f9ab6497f066ca6491c6f09e558b29ac3a1d84f5b31a3b2b68bb8c28cdf76e7
-  data.tar.gz: 6ad3e059d311894f4a023d75df89c72beb4508a2abc83083a47f4f7a07cc6f98edc157e06b5ed42eda55458612d89206de1cce4b0cc94fd598facad4433083e9
+  metadata.gz: 4500bec819ea9de9546f001eed682ac040ea3c2f93904dabb24afdbbda966d3352d8b1e33687a82c482ce835e7d650172dd906d9ef4ec2efc17f1dea31947314
+  data.tar.gz: 62ea49dc2782122146dd2613cd51b1c4132b3eef9d48c5573e9369b0af96042018f104a84cfe2aa2f173cf6d10f5ca3e427baa3ef61faed7029cd7328148a762

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [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

data/README.md

@@ -2,6 +2,10 @@
 
 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.
 
+It's small, only ~1800 lines of code, and without any dependencies. Other Ruby clients are about 4 times bigger. But without trading functionallity.
+
+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.
+
 ## Support
 
 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.
@@ -31,10 +35,10 @@ ch = conn.channel
 q = ch.queue_declare
 
 # Publish a message to said queue
-ch.basic_publish "Hello World!", "", q.queue_name
+ch.basic_publish_confirm "Hello World!", "", q.queue_name, persistent: true
 
 # Poll the queue for a message
-msg = ch.basic_get q.queue_name
+msg = ch.basic_get(q.queue_name)
 
 # Print the message's body to STDOUT
 puts msg.body
@@ -104,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/lib/amqp/client/connection.rb

@@ -3,7 +3,7 @@
 require "socket"
 require "uri"
 require "openssl"
-require_relative "./frames"
+require_relative "./frame_bytes"
 require_relative "./channel"
 require_relative "./errors"
 
@@ -350,7 +350,7 @@ module AMQP
           end
         when 2 # header
           body_size = buf.unpack1("@4 Q>")
-          properties = Properties.decode(buf.byteslice(12, buf.bytesize - 12))
+          properties = Properties.decode(buf, 12)
           @channels[channel_id].header_delivered body_size, properties
         when 3 # body
           @channels[channel_id].body_delivered buf

data/lib/amqp/client/{frames.rb → frame_bytes.rb}

@@ -332,7 +332,7 @@ module AMQP
       end
 
       def self.header(id, body_size, properties)
-        props = Properties.new(**properties).encode
+        props = Properties.encode(properties)
         frame_size = 2 + 2 + 8 + props.bytesize
         [
           2, # type: header

data/lib/amqp/client/properties.rb

@@ -23,56 +23,90 @@ module AMQP
         @app_id = app_id
       end
 
+      # Properties as a Hash
+      # @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
+        }
+      end
+
+      alias to_hash to_h
+
+      # Returns true if two Property objects holds the same information
+      # @return [Boolean]
+      def ==(other)
+        return false unless other.is_a? self.class
+
+        instance_variables.all? { |v| instance_variable_get(v) == other.instance_variable_get(v) }
+      end
+
       # Content type of the message body
       # @return [String, nil]
       attr_accessor :content_type
       # Content encoding of the body
       # @return [String, nil]
       attr_accessor :content_encoding
-      # Custom headers
+      # Headers, for applications and header exchange routing
       # @return [Hash<String, Object>, nil]
       attr_accessor :headers
-      # 2 for persisted message, transient messages for all other values
-      # @return [Integer, nil]
+      # Message persistent level
+      # @note The exchange and queue have to durable as well for the message to be persistent
+      # @return [1] Transient message
+      # @return [2] Persistent message
+      # @return [nil] Not specified (implicitly transient)
       attr_accessor :delivery_mode
       # A priority of the message (between 0 and 255)
       # @return [Integer, nil]
       attr_accessor :priority
-      # A correlation id, most often used used for RPC communication
-      # @return [Integer, nil]
+      # Message correlation id, commonly used to correlate RPC requests and responses
+      # @return [String, nil]
       attr_accessor :correlation_id
       # Queue to reply RPC responses to
       # @return [String, nil]
       attr_accessor :reply_to
       # Number of seconds the message will stay in the queue
-      # @return [Integer]
-      # @return [String]
-      # @return [nil]
+      # @return [String, nil]
       attr_accessor :expiration
+      # Application message identifier
       # @return [String, nil]
       attr_accessor :message_id
-      # User-definable, but often used for the time the message was originally generated
+      # Message timestamp, often indicates when the message was originally generated
       # @return [Date, nil]
       attr_accessor :timestamp
-      # User-definable, but can can indicate what kind of message this is
+      # Message type name
       # @return [String, nil]
       attr_accessor :type
-      # User-definable, but can be used to verify that this is the user that published the message
+      # The user that published the message
       # @return [String, nil]
       attr_accessor :user_id
-      # User-definable, but often indicates which app that generated the message
+      # Name of application that generated the message
       # @return [String, nil]
       attr_accessor :app_id
 
       # Encode properties into a byte array
+      # @param properties [Hash]
       # @return [String] byte array
-      def encode
+      def self.encode(properties)
+        return "\x00\x00" if properties.empty?
+
         flags = 0
         arr = [flags]
-        fmt = StringIO.new(String.new("S>", capacity: 35))
-        fmt.pos = 2
+        fmt = String.new("S>", capacity: 37)
 
-        if content_type
+        if (content_type = properties[:content_type])
           content_type.is_a?(String) || raise(ArgumentError, "content_type must be a string")
 
           flags |= (1 << 15)
@@ -80,7 +114,7 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if content_encoding
+        if (content_encoding = properties[:content_encoding])
           content_encoding.is_a?(String) || raise(ArgumentError, "content_encoding must be a string")
 
           flags |= (1 << 14)
@@ -88,7 +122,7 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if headers
+        if (headers = properties[:headers])
           headers.is_a?(Hash) || raise(ArgumentError, "headers must be a hash")
 
           flags |= (1 << 13)
@@ -97,31 +131,31 @@ module AMQP
           fmt << "L>a*"
         end
 
-        if delivery_mode
+        if (delivery_mode = properties[:delivery_mode])
           delivery_mode.is_a?(Integer) || raise(ArgumentError, "delivery_mode must be an int")
-          delivery_mode.between?(0, 2) || raise(ArgumentError, "delivery_mode must be be between 0 and 2")
 
           flags |= (1 << 12)
           arr << delivery_mode
           fmt << "C"
         end
 
-        if priority
+        if (priority = properties[:priority])
           priority.is_a?(Integer) || raise(ArgumentError, "priority must be an int")
+
           flags |= (1 << 11)
           arr << priority
           fmt << "C"
         end
 
-        if correlation_id
-          priority.is_a?(String) || raise(ArgumentError, "correlation_id must be a string")
+        if (correlation_id = properties[:correlation_id])
+          correlation_id.is_a?(String) || raise(ArgumentError, "correlation_id must be a string")
 
           flags |= (1 << 10)
           arr << correlation_id.bytesize << correlation_id
           fmt << "Ca*"
         end
 
-        if reply_to
+        if (reply_to = properties[:reply_to])
           reply_to.is_a?(String) || raise(ArgumentError, "reply_to must be a string")
 
           flags |= (1 << 9)
@@ -129,8 +163,8 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if expiration
-          self.expiration = expiration.to_s if expiration.is_a?(Integer)
+        if (expiration = properties[:expiration])
+          expiration = expiration.to_s if expiration.is_a?(Integer)
           expiration.is_a?(String) || raise(ArgumentError, "expiration must be a string or integer")
 
           flags |= (1 << 8)
@@ -138,7 +172,7 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if message_id
+        if (message_id = properties[:message_id])
           message_id.is_a?(String) || raise(ArgumentError, "message_id must be a string")
 
           flags |= (1 << 7)
@@ -146,7 +180,7 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if timestamp
+        if (timestamp = properties[:timestamp])
           timestamp.is_a?(Integer) || timestamp.is_a?(Time) || raise(ArgumentError, "timestamp must be an Integer or a Time")
 
           flags |= (1 << 6)
@@ -154,7 +188,7 @@ module AMQP
           fmt << "Q>"
         end
 
-        if type
+        if (type = properties[:type])
           type.is_a?(String) || raise(ArgumentError, "type must be a string")
 
           flags |= (1 << 5)
@@ -162,7 +196,7 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if user_id
+        if (user_id = properties[:user_id])
           user_id.is_a?(String) || raise(ArgumentError, "user_id must be a string")
 
           flags |= (1 << 4)
@@ -170,7 +204,7 @@ module AMQP
           fmt << "Ca*"
         end
 
-        if app_id
+        if (app_id = properties[:app_id])
           app_id.is_a?(String) || raise(ArgumentError, "app_id must be a string")
 
           flags |= (1 << 3)
@@ -179,15 +213,15 @@ module AMQP
         end
 
         arr[0] = flags
-        arr.pack(fmt.string)
+        arr.pack(fmt)
       end
 
       # Decode a byte array
       # @return [Properties]
-      def self.decode(bytes)
+      def self.decode(bytes, pos = 0)
         p = new
-        flags = bytes.unpack1("S>")
-        pos = 2
+        flags = bytes.byteslice(pos, 2).unpack1("S>")
+        pos += 2
         if (flags & 0x8000).positive?
           len = bytes.getbyte(pos)
           pos += 1

data/lib/amqp/client/table.rb

@@ -6,15 +6,20 @@ module AMQP
     # @api private
     module Table
       # Encodes a hash into a byte array
+      # @param hash [Hash]
       # @return [String] Byte array
       def self.encode(hash)
-        tbl = StringIO.new
-        hash.each do |k, v|
+        return "" if hash.empty?
+
+        arr = []
+        fmt = String.new
+        hash.each do |k, value|
           key = k.to_s
-          tbl.write [key.bytesize, key].pack("Ca*")
-          tbl.write encode_field(v)
+          arr.push(key.bytesize, key)
+          fmt << "Ca*"
+          encode_field(value, arr, fmt)
         end
-        tbl.string
+        arr.pack(fmt)
       end
 
       # Decodes an AMQP table into a hash
@@ -27,8 +32,7 @@ module AMQP
           pos += 1
           key = bytes.byteslice(pos, key_len).force_encoding("utf-8")
           pos += key_len
-          rest = bytes.byteslice(pos, bytes.bytesize - pos)
-          len, value = decode_field(rest)
+          len, value = decode_field(bytes, pos)
           pos += len + 1
           hash[key] = value
         end
@@ -36,43 +40,58 @@ module AMQP
       end
 
       # Encoding a single value in a table
+      # @return [nil]
       # @api private
-      def self.encode_field(value)
+      def self.encode_field(value, arr, fmt)
         case value
         when Integer
           if value > 2**31
-            ["l", value].pack("a q>")
+            arr.push("l", value)
+            fmt << "aq>"
           else
-            ["I", value].pack("a l>")
+            arr.push("I", value)
+            fmt << "al>"
           end
         when Float
-          ["d", value].pack("a G")
+          arr.push("d", value)
+          fmt << "aG"
         when String
-          ["S", value.bytesize, value].pack("a L> a*")
+          arr.push("S", value.bytesize, value)
+          fmt << "aL>a*"
         when Time
-          ["T", value.to_i].pack("a Q>")
+          arr.push("T", value.to_i)
+          fmt << "aQ>"
         when Array
-          bytes = value.map { |e| encode_field(e) }.join
-          ["A", bytes.bytesize, bytes].pack("a L> a*")
+          value_arr = []
+          value_fmt = String.new
+          value.each { |e| encode_field(e, value_arr, value_fmt) }
+          bytes = value_arr.pack(value_fmt)
+          arr.push("A", bytes.bytesize, bytes)
+          fmt << "aL>a*"
         when Hash
           bytes = Table.encode(value)
-          ["F", bytes.bytesize, bytes].pack("a L> a*")
+          arr.push("F", bytes.bytesize, bytes)
+          fmt << "aL>a*"
         when true
-          ["t", 1].pack("a C")
+          arr.push("t", 1)
+          fmt << "aC"
         when false
-          ["t", 0].pack("a C")
+          arr.push("t", 0)
+          fmt << "aC"
         when nil
-          ["V"].pack("a")
+          arr << "V"
+          fmt << "a"
         else raise ArgumentError, "unsupported table field type: #{value.class}"
         end
+        nil
       end
 
       # Decodes a single value
-      # @return [Array<Integer, Object>] Bytes read and the parsed object
+      # @return [Array<Integer, Object>] Bytes read and the parsed value
       # @api private
-      def self.decode_field(bytes)
-        type = bytes[0]
-        pos = 1
+      def self.decode_field(bytes, pos)
+        type = bytes[pos]
+        pos += 1
         case type
         when "S"
           len = bytes.byteslice(pos, 4).unpack1("L>")
@@ -84,9 +103,11 @@ module AMQP
           [4 + len, decode(bytes.byteslice(pos, len))]
         when "A"
           len = bytes.byteslice(pos, 4).unpack1("L>")
+          pos += 4
+          array_end = pos + len
           a = []
-          while pos < len
-            length, value = decode_field(bytes.byteslice(pos, -1))
+          while pos < array_end
+            length, value = decode_field(bytes, pos)
             pos += length + 1
             a << value
           end

data/lib/amqp/client/version.rb

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

data/lib/amqp/client.rb

@@ -38,12 +38,18 @@ module AMQP
     # Establishes and returns a new AMQP connection
     # @see Connection#initialize
     # @return [Connection]
+    # @example
+    #   connection = AMQP::Client.new("amqps://server.rmq.cloudamqp.com", connection_name: "My connection").connect
     def connect(read_loop_thread: true)
       Connection.new(@uri, read_loop_thread: read_loop_thread, **@options)
     end
 
     # Opens an AMQP connection using the high level API, will try to reconnect if successfully connected at first
     # @return [self]
+    # @example
+    #   amqp = AMQP::Client.new("amqps://server.rmq.cloudamqp.com")
+    #   amqp.start
+    #   amqp.queue("foobar")
     def start
       @stopped = false
       Thread.new(connect(read_loop_thread: false)) do |conn|
@@ -95,6 +101,10 @@ module AMQP
     #   (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 [Queue]
+    # @example
+    #   amqp = AMQP::Client.new.start
+    #   q = amqp.queue("foobar")
+    #   q.publish("body")
     def queue(name, durable: true, auto_delete: false, arguments: {})
       raise ArgumentError, "Currently only supports named, durable queues" if name.empty?
 
@@ -108,6 +118,10 @@ module AMQP
 
     # Declare an exchange and return a high level Exchange object
     # @return [Exchange]
+    # @example
+    #   amqp = AMQP::Client.new.start
+    #   x = amqp.exchange("my.hash.exchange", "x-consistent-hash")
+    #   x.publish("body", "routing-key")
     def exchange(name, type, durable: true, auto_delete: false, internal: false, arguments: {})
       @exchanges.fetch(name) do
         with_connection do |conn|
@@ -172,9 +186,7 @@ module AMQP
       with_connection do |conn|
         ch = conn.channel
         ch.basic_qos(prefetch)
-        ch.basic_consume(queue, no_ack: no_ack, worker_threads: worker_threads, arguments: arguments) do |msg|
-          blk.call(msg)
-        end
+        ch.basic_consume(queue, no_ack: no_ack, worker_threads: worker_threads, arguments: arguments, &blk)
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amqp-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Carl Hörberg
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-08 00:00:00.000000000 Z
+date: 2021-09-15 00:00:00.000000000 Z
 dependencies: []
 description: Work in progress
 email:
@@ -37,7 +37,7 @@ files:
 - lib/amqp/client/connection.rb
 - lib/amqp/client/errors.rb
 - lib/amqp/client/exchange.rb
-- lib/amqp/client/frames.rb
+- lib/amqp/client/frame_bytes.rb
 - lib/amqp/client/message.rb
 - lib/amqp/client/properties.rb
 - lib/amqp/client/queue.rb