amq-protocol 2.3.4 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90852fae30dd15d9f1f6ee5f9c0d98e856c3efcbd4c11e7e824caf63a01360f7
-  data.tar.gz: a000c7b2f435fc08f2d9c90a765f81e0414ca1c3038fcab1915ff7bcd4bdb929
+  metadata.gz: e3f43ce885cd75341d0b5b784857aada66eab3990174d7b145b572a04286f41f
+  data.tar.gz: 7ec8798e7d34ec8d4218b209e67d75fc45fe254e80997d761f8c7c2cf0521366
 SHA512:
-  metadata.gz: 718a613e5a2355791ef4d07bd38676b005cb00cd54969183a31eeba96cc3439ba223a8d9636050aa9aaf2ac5ca63150d3e3c53ce3e4638b53191097183b47ba3
-  data.tar.gz: 598de750f0c0ba6c838f4d1f34b4fb24f05b0a580c6b8beb7804d4edae437c628c18ac56d8ef87afc78ad56876ca4baafcf051f90f1eea9bb0cf3d48e993ea66
+  metadata.gz: 378697156e2adf582c060b1be25c374f68cf7764008cebf926a07a3c1f02f7669680e2d934a4cec94a18f3e779889a45b4998113a076844d4298e230914683c6
+  data.tar.gz: 8ff53d0b35d42dbfa6a515391b26593340446ceb985740bd1ec6d5e0cb043beef4d46e7c262ee918ac753a4a96db746e1dceaba4fc8b479228340045080650ee

data/AGENTS.md

@@ -0,0 +1,23 @@
+# Instructions for AI Agents
+
+## Overview
+
+This is a pure Ruby implementation of a AMQP 0-9-1 protocol parser
+(more specifically% serialization, deserialization, framing) used by
+[Bunny](https://github.com/ruby-amqp/bunny), a Ruby AMQP 0-9-1 client for RabbitMQ.
+
+## Target Ruby Version
+
+This library targets Ruby 3.0 and later versions.
+
+## Comments
+
+ * Only add very important comments, both in tests and in the implementation
+
+## Git Instructions
+
+ * Never add yourself to the list of commit co-authors
+
+## Style Guide
+
+ * Never add full stops to Markdown list items

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/ChangeLog.md

@@ -1,8 +1,35 @@
-## Changes between 2.3.4 and 2.3.5 (in development)
+## Changes between 2.5.0 and 2.6.0 (in development)
 
 No changes yet.
 
 
+## Changes between 2.4.0 and 2.5.0 (Dec 31, 2025)
+
+### Additional Consumer Hot Path Optimizations
+
+A few more decode method optimizations for consumer delivery code paths.
+
+
+## Changes between 2.3.4 and 2.4.0 (Dec 30, 2025)
+
+### Performance Improvements
+
+Optimized encoding and decoding hot paths:
+
+ * Built-in `Q>`/`q>` packing/unpacking directives are 6-7x faster than the original implementation (that originally targeted Ruby 1.8.x)
+ * Switched to `unpack1` instead of `unpack().first` throughout
+ * Use `byteslice` instead of `slice` for binary string operations
+ * Use `getbyte` for single byte access (4x faster than alternatives)
+ * Adopted `frozen_string_literal` pragma
+
+The improvements on Ruby 3.4 are very meaningful:
+
+ * `AMQ::Pack.pack_uint64_big_endian`: about 6.6x faster
+ * `AMQ::Pack.unpack_uint64_big_endian`: about 7.2x faster
+ * `Basic.Deliver.decode`: about 1.7x faster
+ * `Basic.Ack/Nack/Reject.encode`: about 2.5x faster
+
+
 ## Changes between 2.3.3 and 2.3.4 (May 12, 2025)
 
 ### (Forward) Compatibility with Ruby 3.5
@@ -16,13 +43,13 @@ GitHub issue: [#80](https://github.com/ruby-amqp/amq-protocol/pull/80)
 
 ### Improved Compatibility with Ruby 3.4
 
-Contribiuted by @BenTalagan.
+Contributed by @BenTalagan.
 
 GitHub issue: [#79](https://github.com/ruby-amqp/amq-protocol/pull/79)
 
 ### Support Binary-Encoded Frozen Strings for Payloads
 
-Contribiuted by @djrodgerspryor.
+Contributed by @djrodgerspryor.
 
 GitHub issue: [#78](https://github.com/ruby-amqp/amq-protocol/pull/78)
 

data/GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md

data/Gemfile

@@ -10,6 +10,11 @@ group :development do
   gem "rake"
 end
 
+group :benchmark do
+  gem "benchmark-ips", "~> 2.12"
+  gem "benchmark-memory", "~> 0.2"
+end
+
 group :test do
   gem "rspec", ">= 3.8.0"
   gem "rspec-its"

data/README.md

@@ -9,6 +9,8 @@ needs for you, including RabbitMQ extensions to AMQP 0.9.1.
 
 ## Supported Ruby Versions
 
+ * amq-protocol `2.3.4` has fixes for Ruby 3.5 compatibility
+ * amq-protocol `2.3.3` has fixes for Ruby 3.4 compatibility
  * amq-protocol `2.3.0` only supports Ruby 2.2+.
  * amq-protocol `2.0.0` through `2.2.0` and later supports Ruby 2.0+.
  * amq-protocol `1.9.2` was the last version to support Ruby 1.8 and 1.9.
@@ -45,21 +47,14 @@ To run tests, use
 amq-protocol is maintained by [Michael Klishin](https://github.com/michaelklishin).
 
 
-## CI Status
-
-[![Build Status](https://secure.travis-ci.org/ruby-amqp/amq-protocol.svg)](https://travis-ci.org/ruby-amqp/amq-protocol)
-
-
 ## Issues
 
 Please report any issues you may find to our [Issue tracker](http://github.com/ruby-amqp/amq-protocol/issues) on GitHub.
 
-
 ## Mailing List
 
 Any questions you may have should be sent to the [Ruby AMQP mailing list](http://groups.google.com/group/ruby-amqp).
 
-
 ## License
 
 MIT (see LICENSE in the repository root).

data/benchmarks/frame_encoding.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: true
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require "amq/protocol/client"
+require "benchmark/ips"
+
+puts
+puts "-" * 80
+puts "Frame Encoding Benchmarks on #{RUBY_DESCRIPTION}"
+puts "-" * 80
+
+# Test data
+SMALL_PAYLOAD = "x" * 100
+MEDIUM_PAYLOAD = "x" * 1024
+LARGE_PAYLOAD = "x" * 16384
+
+CHANNEL = 1
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("Frame.encode(:method, small)") do
+    AMQ::Protocol::Frame.encode(:method, SMALL_PAYLOAD, CHANNEL)
+  end
+
+  x.report("Frame.encode(:method, medium)") do
+    AMQ::Protocol::Frame.encode(:method, MEDIUM_PAYLOAD, CHANNEL)
+  end
+
+  x.report("Frame.encode(:body, large)") do
+    AMQ::Protocol::Frame.encode(:body, LARGE_PAYLOAD, CHANNEL)
+  end
+
+  x.report("MethodFrame.new + encode") do
+    frame = AMQ::Protocol::MethodFrame.new(SMALL_PAYLOAD, CHANNEL)
+    frame.encode
+  end
+
+  x.report("BodyFrame.new + encode") do
+    frame = AMQ::Protocol::BodyFrame.new(MEDIUM_PAYLOAD, CHANNEL)
+    frame.encode
+  end
+
+  x.report("HeartbeatFrame.encode") do
+    AMQ::Protocol::HeartbeatFrame.encode
+  end
+
+  x.compare!
+end
+
+puts
+puts "-" * 80
+puts "Frame Header Decoding"
+puts "-" * 80
+
+# Encoded frame headers
+METHOD_HEADER = [1, 0, 1, 0, 0, 0, 100].pack("CnN")  # type=1, channel=1, size=100
+BODY_HEADER = [3, 0, 5, 0, 0, 16, 0].pack("CnN")     # type=3, channel=5, size=4096
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("Frame.decode_header (method)") do
+    AMQ::Protocol::Frame.decode_header(METHOD_HEADER)
+  end
+
+  x.report("Frame.decode_header (body)") do
+    AMQ::Protocol::Frame.decode_header(BODY_HEADER)
+  end
+
+  x.compare!
+end

data/benchmarks/method_encoding.rb

@@ -0,0 +1,198 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: true
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require "amq/protocol/client"
+require "benchmark/ips"
+
+puts
+puts "-" * 80
+puts "AMQP Method Encoding/Decoding Benchmarks on #{RUBY_DESCRIPTION}"
+puts "-" * 80
+
+FRAME_SIZE = 131072  # 128KB, typical default
+
+# Common message properties
+BASIC_PROPERTIES = {
+  content_type: "application/json",
+  delivery_mode: 2,
+  priority: 0,
+  headers: { "x-custom" => "value" }
+}.freeze
+
+MINIMAL_PROPERTIES = {
+  delivery_mode: 2
+}.freeze
+
+# Payloads
+SMALL_BODY = '{"id":1}'.freeze
+MEDIUM_BODY = ('x' * 1024).freeze
+LARGE_BODY = ('x' * 65536).freeze
+
+puts "=== Basic.Publish (Full Message Encoding) ==="
+puts "This is the critical hot path for publishing messages"
+puts
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("Publish small (8B) + minimal props") do
+    AMQ::Protocol::Basic::Publish.encode(
+      1,              # channel
+      SMALL_BODY,     # payload
+      MINIMAL_PROPERTIES,
+      "",             # exchange
+      "test.queue",   # routing_key
+      false,          # mandatory
+      false,          # immediate
+      FRAME_SIZE
+    )
+  end
+
+  x.report("Publish small (8B) + full props") do
+    AMQ::Protocol::Basic::Publish.encode(
+      1,
+      SMALL_BODY,
+      BASIC_PROPERTIES,
+      "",
+      "test.queue",
+      false,
+      false,
+      FRAME_SIZE
+    )
+  end
+
+  x.report("Publish medium (1KB) + full props") do
+    AMQ::Protocol::Basic::Publish.encode(
+      1,
+      MEDIUM_BODY,
+      BASIC_PROPERTIES,
+      "",
+      "test.queue",
+      false,
+      false,
+      FRAME_SIZE
+    )
+  end
+
+  x.report("Publish large (64KB) + full props") do
+    AMQ::Protocol::Basic::Publish.encode(
+      1,
+      LARGE_BODY,
+      BASIC_PROPERTIES,
+      "",
+      "test.queue",
+      false,
+      false,
+      FRAME_SIZE
+    )
+  end
+
+  x.compare!
+end
+
+# Create sample encoded methods for decoding benchmarks
+puts
+puts "=== Method Decoding ==="
+
+# Simulate encoded Basic.Deliver frame payload (after class/method ID)
+# Basic.Deliver: consumer_tag(shortstr), delivery_tag(longlong), redelivered(bit), exchange(shortstr), routing_key(shortstr)
+def make_deliver_payload(consumer_tag, delivery_tag, exchange, routing_key)
+  buffer = String.new(encoding: 'BINARY')
+  buffer << consumer_tag.bytesize.chr
+  buffer << consumer_tag
+  buffer << AMQ::Pack.pack_uint64_big_endian(delivery_tag)
+  buffer << "\x00"  # redelivered = false
+  buffer << exchange.bytesize.chr
+  buffer << exchange
+  buffer << routing_key.bytesize.chr
+  buffer << routing_key
+  buffer
+end
+
+DELIVER_PAYLOAD_SHORT = make_deliver_payload("ctag", 1, "", "q")
+DELIVER_PAYLOAD_TYPICAL = make_deliver_payload("bunny-consumer-12345", 999999, "amq.topic", "events.user.created")
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("Basic.Deliver.decode (short)") do
+    AMQ::Protocol::Basic::Deliver.decode(DELIVER_PAYLOAD_SHORT)
+  end
+
+  x.report("Basic.Deliver.decode (typical)") do
+    AMQ::Protocol::Basic::Deliver.decode(DELIVER_PAYLOAD_TYPICAL)
+  end
+
+  x.compare!
+end
+
+puts
+puts "=== Properties Encoding/Decoding ==="
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("encode_properties (minimal)") do
+    AMQ::Protocol::Basic.encode_properties(100, MINIMAL_PROPERTIES)
+  end
+
+  x.report("encode_properties (full)") do
+    AMQ::Protocol::Basic.encode_properties(1024, BASIC_PROPERTIES)
+  end
+
+  x.compare!
+end
+
+# Create encoded properties for decode benchmark
+ENCODED_MINIMAL_PROPS = AMQ::Protocol::Basic.encode_properties(100, MINIMAL_PROPERTIES)
+ENCODED_FULL_PROPS = AMQ::Protocol::Basic.encode_properties(1024, BASIC_PROPERTIES)
+
+# Skip the first 12 bytes (class_id, weight, body_size)
+PROPS_DATA_MINIMAL = ENCODED_MINIMAL_PROPS[12..-1]
+PROPS_DATA_FULL = ENCODED_FULL_PROPS[12..-1]
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("decode_properties (minimal)") do
+    AMQ::Protocol::Basic.decode_properties(PROPS_DATA_MINIMAL)
+  end
+
+  x.report("decode_properties (full)") do
+    AMQ::Protocol::Basic.decode_properties(PROPS_DATA_FULL)
+  end
+
+  x.compare!
+end
+
+puts
+puts "=== Other Common Methods ==="
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("Basic.Ack.encode") do
+    AMQ::Protocol::Basic::Ack.encode(1, 12345, false)
+  end
+
+  x.report("Basic.Nack.encode") do
+    AMQ::Protocol::Basic::Nack.encode(1, 12345, false, true)
+  end
+
+  x.report("Basic.Reject.encode") do
+    AMQ::Protocol::Basic::Reject.encode(1, 12345, true)
+  end
+
+  x.report("Queue.Declare.encode") do
+    AMQ::Protocol::Queue::Declare.encode(1, "test.queue", false, true, false, false, false, {})
+  end
+
+  x.report("Exchange.Declare.encode") do
+    AMQ::Protocol::Exchange::Declare.encode(1, "test.exchange", "topic", false, true, false, false, false, {})
+  end
+
+  x.compare!
+end

data/benchmarks/pack_unpack.rb

@@ -0,0 +1,158 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: true
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require "amq/protocol/client"
+require "benchmark/ips"
+
+puts
+puts "-" * 80
+puts "Pack/Unpack Micro-benchmarks on #{RUBY_DESCRIPTION}"
+puts "-" * 80
+
+# Test data
+UINT64_VALUE = 0x123456789ABCDEF0
+UINT32_VALUE = 0x12345678
+UINT16_VALUE = 0x1234
+
+PACKED_UINT64_BE = (+"\x12\x34\x56\x78\x9A\xBC\xDE\xF0").force_encoding('BINARY').freeze
+PACKED_UINT32_BE = (+"\x12\x34\x56\x78").force_encoding('BINARY').freeze
+PACKED_UINT16_BE = (+"\x12\x34").force_encoding('BINARY').freeze
+
+puts "=== Pack Operations ==="
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("AMQ::Pack.pack_uint64_big_endian") do
+    AMQ::Pack.pack_uint64_big_endian(UINT64_VALUE)
+  end
+
+  # Alternative: direct pack with 'Q>' directive (Ruby 1.9.3+)
+  x.report("[val].pack('Q>')") do
+    [UINT64_VALUE].pack('Q>')
+  end
+
+  x.report("[val].pack('N') uint32") do
+    [UINT32_VALUE].pack('N')
+  end
+
+  x.report("[val].pack('n') uint16") do
+    [UINT16_VALUE].pack('n')
+  end
+
+  x.compare!
+end
+
+puts
+puts "=== Unpack Operations ==="
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("AMQ::Pack.unpack_uint64_big_endian") do
+    AMQ::Pack.unpack_uint64_big_endian(PACKED_UINT64_BE)
+  end
+
+  # Alternative: direct unpack with 'Q>' directive
+  x.report("data.unpack('Q>')") do
+    PACKED_UINT64_BE.unpack('Q>')
+  end
+
+  x.report("data.unpack1('Q>')") do
+    PACKED_UINT64_BE.unpack1('Q>')
+  end
+
+  x.report("data.unpack('N').first") do
+    PACKED_UINT32_BE.unpack('N').first
+  end
+
+  x.report("data.unpack1('N')") do
+    PACKED_UINT32_BE.unpack1('N')
+  end
+
+  x.compare!
+end
+
+puts
+puts "=== String Slicing ==="
+
+DATA = ("x" * 1000).force_encoding('BINARY').freeze
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("data[offset, length]") do
+    DATA[100, 50]
+  end
+
+  x.report("data.byteslice(offset, length)") do
+    DATA.byteslice(100, 50)
+  end
+
+  x.report("data.slice(offset, length)") do
+    DATA.slice(100, 50)
+  end
+
+  x.compare!
+end
+
+puts
+puts "=== Single Byte Access ==="
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("data[0, 1].unpack('C').first") do
+    DATA[0, 1].unpack('C').first
+  end
+
+  x.report("data.getbyte(0)") do
+    DATA.getbyte(0)
+  end
+
+  x.report("data[0].ord") do
+    DATA[0].ord
+  end
+
+  x.report("data.unpack1('C')") do
+    DATA.unpack1('C')
+  end
+
+  x.compare!
+end
+
+puts
+puts "=== Buffer Building ==="
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("String.new + <<") do
+    buf = String.new
+    buf << "hello"
+    buf << "world"
+    buf << [1234].pack('N')
+    buf
+  end
+
+  x.report("+'' + <<") do
+    buf = +''
+    buf << "hello"
+    buf << "world"
+    buf << [1234].pack('N')
+    buf
+  end
+
+  x.report("Array#join") do
+    parts = []
+    parts << "hello"
+    parts << "world"
+    parts << [1234].pack('N')
+    parts.join
+  end
+
+  x.compare!
+end

data/benchmarks/run_all.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# frozen_string_literal: true
+
+# Master benchmark runner
+# Usage: ruby benchmarks/run_all.rb
+
+require 'fileutils'
+
+BENCHMARK_DIR = File.dirname(__FILE__)
+RESULTS_DIR = File.join(BENCHMARK_DIR, "results")
+
+FileUtils.mkdir_p(RESULTS_DIR)
+
+benchmarks = %w[
+  pack_unpack.rb
+  frame_encoding.rb
+  table_encoding.rb
+  method_encoding.rb
+]
+
+timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+ruby_version = RUBY_VERSION.gsub('.', '_')
+results_file = File.join(RESULTS_DIR, "benchmark_#{ruby_version}_#{timestamp}.txt")
+
+puts "=" * 80
+puts "AMQ-Protocol Benchmark Suite"
+puts "=" * 80
+puts "Ruby: #{RUBY_DESCRIPTION}"
+puts "Time: #{Time.now}"
+puts "Results will be saved to: #{results_file}"
+puts "=" * 80
+puts
+
+File.open(results_file, 'w') do |f|
+  f.puts "AMQ-Protocol Benchmark Results"
+  f.puts "Ruby: #{RUBY_DESCRIPTION}"
+  f.puts "Time: #{Time.now}"
+  f.puts "=" * 80
+  f.puts
+
+  benchmarks.each do |benchmark|
+    benchmark_path = File.join(BENCHMARK_DIR, benchmark)
+
+    if File.exist?(benchmark_path)
+      puts "\n>>> Running #{benchmark}..."
+      puts
+
+      output = `ruby #{benchmark_path} 2>&1`
+      puts output
+
+      f.puts ">>> #{benchmark}"
+      f.puts output
+      f.puts
+    else
+      puts "Warning: #{benchmark_path} not found, skipping..."
+    end
+  end
+end
+
+puts
+puts "=" * 80
+puts "Benchmark complete! Results saved to: #{results_file}"
+puts "=" * 80