ears 0.21.1 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ffa13eeabb39addd2d5acb749c6edd32515770b357f7ef6cd3f944cc6aae182
-  data.tar.gz: 4aa87462141bd49cbc616dfff68e7d5b5bf24274b7a6c0430ca02182e15259c5
+  metadata.gz: 8ae7219688923da6df4b3d6939e91449621d143fe835362043a7032aaaff3b40
+  data.tar.gz: 989c76721a48f2a91c8db1944746e598fdde624b47b9c598193de08a47df4798
 SHA512:
-  metadata.gz: 45a3dffcf2f868f753fc985657bc24909c1bba97f1e633eb012ed4185c231d50edc98093f529b336f1e743dabe374a5ff6e662116d72f74ad5c166c0d81146ff
-  data.tar.gz: 020e285268b69f96269a45e70abdb2287f48ff4346eac060a3dd6c4cebc8c27248f49c045a1c0a0139ea5c8bfc6aafb959634a6c62f945328c9fb1056d71e875
+  metadata.gz: 0cd3fac5b725c339d83d2953f7bffab29ed6ac0236d880af665e72308534e7154554dbcf42d74ec5c55db2a95a3fadd4b9283080ae87deb3900c388690b8df5d
+  data.tar.gz: 7ca86de1d5545ea3b701c0d097f7925d27fbaa7e8536f6acfc8a0c5a1de9d51dbeea456ee2ded64768566f171f0a9dc6f5351057083b497c3080b56274f18f98

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.22.1 (2025-09-11)
+
+- Add optional `routing_key_match` parameter to `#published_messages` in `Ears::Testing::TestHelper`
+- Add `#last_published_payload` to `Ears::Testing::TestHelper`
+
+## 0.22.0 (2025-09-11)
+
+- Support publisher confirms in `Ears::Publisher`
+
 ## 0.21.1 (2025-09-09)
 
 - Add testing abstractions: `Ears::Testing::TestHelper`, `Ears::Testing::MessageCapture`, and `Ears::Testing::PublisherMock`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ears (0.21.1)
+    ears (0.22.1)
       bunny (>= 2.22.0)
       connection_pool (~> 2.4)
       multi_json
@@ -113,7 +113,7 @@ CHECKSUMS
   connection_pool (2.5.3) sha256=cfd74a82b9b094d1ce30c4f1a346da23ee19dc8a062a16a85f58eab1ced4305b
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  ears (0.21.1)
+  ears (0.22.1)
   json (2.13.2) sha256=02e1f118d434c6b230a64ffa5c8dee07e3ec96244335c392eaed39e1199dbb68
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87

data/README.md

@@ -197,6 +197,57 @@ rescue => e
 end
 ```
 
+### Publisher Confirms
+
+#### Basic Usage
+
+For guaranteed message delivery, use `publish_with_confirmation` which waits for broker acknowledgment:
+
+```ruby
+publisher = Ears::Publisher.new('events', :topic)
+
+# Publish with confirmation - blocks until broker acknowledges
+publisher.publish_with_confirmation(
+  { user_id: 123, action: 'payment_processed' },
+  routing_key: 'payment.processed',
+)
+```
+
+#### Configuration
+
+Publisher confirms use a separate channel pool with configurable settings:
+
+```ruby
+Ears.configure do |config|
+  # Confirms-specific channel pool size (default: 32)
+  config.publisher_confirms_pool_size = 32
+
+  # Timeout for waiting for confirms in seconds (default: 5.0)
+  config.publisher_confirms_timeout = 5.0
+
+  # Cleanup timeout after confirmation failure (default: 1.0)
+  config.publisher_confirms_cleanup_timeout = 1.0
+end
+```
+
+#### Error Handling
+
+Publisher confirms raise specific exceptions that are NOT automatically retried:
+
+```ruby
+begin
+  publisher.publish_with_confirmation(data, routing_key: 'important.event')
+rescue Ears::PublishConfirmationTimeout => e
+  # Message may or may not have reached broker
+  logger.error "Confirmation timed out: #{e.message}"
+rescue Ears::PublishNacked => e
+  # Broker explicitly rejected the message
+  logger.error "Message was nacked: #{e.message}"
+end
+```
+
+**Note:** Unlike regular publishing, confirmation errors are not retried to avoid message duplication.
+
 ### Basic consumer usage
 
 First, you should configure `Ears`.

data/lib/ears/configuration.rb

@@ -17,6 +17,9 @@ module Ears
     DEFAULT_PUBLISHER_MAX_RETRIES = 3
     DEFAULT_PUBLISHER_RETRY_BASE_DELAY = 0.1
     DEFAULT_PUBLISHER_RETRY_BACKOFF_FACTOR = 2
+    DEFAULT_PUBLISHER_CONFIRMS_POOL_SIZE = 32
+    DEFAULT_PUBLISHER_CONFIRMS_TIMEOUT = 5.0
+    DEFAULT_PUBLISHER_CONFIRMS_CLEANUP_TIMEOUT = 1.0
 
     # @return [String] the connection string for RabbitMQ.
     attr_accessor :rabbitmq_url
@@ -57,7 +60,16 @@ module Ears
     # @return [Logger] the logger instance for Ears operations
     attr_accessor :logger
 
-    def initialize
+    # @return [Integer] the size of the publisher confirms channel pool
+    attr_accessor :publisher_confirms_pool_size
+
+    # @return [Float] the timeout in seconds for waiting for publisher confirms
+    attr_accessor :publisher_confirms_timeout
+
+    # @return [Float] the timeout in seconds for cleanup operations after confirmation timeout
+    attr_accessor :publisher_confirms_cleanup_timeout
+
+    def initialize # rubocop:disable Metrics/MethodLength
       @rabbitmq_url = DEFAULT_RABBITMQ_URL
       @recovery_attempts = DEFAULT_RECOVERY_ATTEMPTS
       @publisher_pool_size = DEFAULT_PUBLISHER_POOL_SIZE
@@ -69,6 +81,10 @@ module Ears
       @publisher_max_retries = DEFAULT_PUBLISHER_MAX_RETRIES
       @publisher_retry_base_delay = DEFAULT_PUBLISHER_RETRY_BASE_DELAY
       @publisher_retry_backoff_factor = DEFAULT_PUBLISHER_RETRY_BACKOFF_FACTOR
+      @publisher_confirms_pool_size = DEFAULT_PUBLISHER_CONFIRMS_POOL_SIZE
+      @publisher_confirms_timeout = DEFAULT_PUBLISHER_CONFIRMS_TIMEOUT
+      @publisher_confirms_cleanup_timeout =
+        DEFAULT_PUBLISHER_CONFIRMS_CLEANUP_TIMEOUT
       @logger = Logger.new(IO::NULL)
     end
 

data/lib/ears/errors.rb

@@ -2,4 +2,16 @@ module Ears
   # Error that is raised when the Bunny recovery attempts are exhausted.
   class MaxRecoveryAttemptsExhaustedError < StandardError
   end
+
+  # Base error class for publisher-related errors.
+  class PublishError < StandardError
+  end
+
+  # Error raised when a publisher confirmation times out.
+  class PublishConfirmationTimeout < PublishError
+  end
+
+  # Error raised when a message is nacked by the broker.
+  class PublishNacked < PublishError
+  end
 end

data/lib/ears/publisher.rb

@@ -1,6 +1,8 @@
 require 'bunny'
 require 'ears/publisher_channel_pool'
 require 'ears/publisher_retry_handler'
+require 'ears/publisher_confirmation_handler'
+require 'ears/errors'
 
 module Ears
   # Publisher for sending messages to RabbitMQ exchanges.
@@ -51,6 +53,50 @@ module Ears
       end
     end
 
+    # Publishes a message to the configured exchange with confirmation.
+    # Waits for RabbitMQ to confirm the message was received.
+    #
+    # @param [Hash, Array, Object] data The data to serialize as JSON and publish.
+    # @param [String] routing_key The routing key for the message.
+    #
+    # @option opts [String] :routing_key Routing key
+    # @option opts [Boolean] :persistent Should the message be persisted to disk?
+    # @option opts [Boolean] :mandatory Should the message be returned if it cannot be routed to any queue?
+    # @option opts [Integer] :timestamp A timestamp associated with this message
+    # @option opts [Integer] :expiration Expiration time after which the message will be deleted
+    # @option opts [String] :type Message type, e.g. what type of event or command this message represents. Can be any string
+    # @option opts [String] :reply_to Queue name other apps should send the response to
+    # @option opts [String] :content_type Message content type (e.g. application/json)
+    # @option opts [String] :content_encoding Message content encoding (e.g. gzip)
+    # @option opts [String] :correlation_id Message correlated to this one, e.g. what request this message is a reply for
+    # @option opts [Integer] :priority Message priority, 0 to 9. Not used by RabbitMQ, only applications
+    # @option opts [String] :message_id Any message identifier
+    # @option opts [String] :user_id Optional user ID. Verified by RabbitMQ against the actual connection username
+    # @option opts [String] :app_id Optional application ID
+    #
+    # @raise [PublishConfirmationTimeout] if confirmation times out
+    # @raise [PublishNacked] if message is nacked by the broker
+    # @return [void]
+    def publish_with_confirmation(data, routing_key:, **options)
+      publish_options = default_publish_options.merge(options)
+
+      retry_handler.run do
+        validate_connection!
+
+        PublisherChannelPool.with_channel(confirms: true) do |channel|
+          exchange = create_exchange(channel)
+
+          publisher_confirmation_handler.publish_with_confirmation(
+            channel: channel,
+            exchange: exchange,
+            data: data,
+            routing_key: routing_key,
+            options: publish_options,
+          )
+        end
+      end
+    end
+
     # Resets the channel pool, forcing new channels to be created.
     # This can be useful for connection recovery scenarios.
     #
@@ -68,12 +114,9 @@ module Ears
                 :logger
 
     def publish_with_channel(data:, routing_key:, publish_options:)
-      unless Ears.connection.open?
-        raise PublisherRetryHandler::PublishToStaleChannelError,
-              'Connection is not open'
-      end
+      validate_connection!
 
-      PublisherChannelPool.with_channel do |channel|
+      PublisherChannelPool.with_channel(confirms: false) do |channel|
         exchange = create_exchange(channel)
         exchange.publish(
           data,
@@ -82,6 +125,13 @@ module Ears
       end
     end
 
+    def validate_connection!
+      unless Ears.connection.open?
+        raise PublisherRetryHandler::PublishToStaleChannelError,
+              'Connection is not open'
+      end
+    end
+
     def create_exchange(channel)
       Bunny::Exchange.new(
         channel,
@@ -104,5 +154,10 @@ module Ears
     def retry_handler
       @retry_handler ||= PublisherRetryHandler.new(config, logger)
     end
+
+    def publisher_confirmation_handler
+      @publisher_confirmation_handler ||=
+        PublisherConfirmationHandler.new(config: config, logger: logger)
+    end
   end
 end

data/lib/ears/publisher_channel_pool.rb

@@ -3,50 +3,97 @@ require 'connection_pool'
 module Ears
   # Channel pool management for publishers.
   # Provides thread-safe channel pooling separate from consumer channels.
+  # Maintains two separate pools: one for standard publishing and one for confirmed publishing.
   class PublisherChannelPool
     class << self
-      # Executes the given block with a channel from the pool.
+      # Executes the given block with a channel from the appropriate pool.
       #
+      # @param [Boolean] confirms Whether to use a channel with publisher confirms enabled
       # @yieldparam [Bunny::Channel] channel The channel to use for publishing
       # @return [Object] The result of the block
-      def with_channel(&)
-        channel_pool.with(&)
+      def with_channel(confirms: false, &)
+        # CRITICAL: Preserve fork-safety at the entry point
+        reset! if @creator_pid && @creator_pid != Process.pid
+
+        pool = confirms ? confirms_pool : standard_pool
+        pool.with(&)
       end
 
-      # Resets the channel pool, forcing new channels to be created.
+      # Resets both channel pools, forcing new channels to be created.
       # This is useful for connection recovery scenarios.
       #
       # @return [void]
       def reset!
-        pool = @channel_pool
-        @channel_pool = nil
+        std_pool = @standard_pool
+        cnf_pool = @confirms_pool
+        @standard_pool = nil
+        @confirms_pool = nil
         @creator_pid = nil
 
-        pool&.shutdown(&:close)
+        std_pool&.shutdown(&:close)
+        cnf_pool&.shutdown(&:close)
         nil
       end
 
-      private
+      # Resets only the confirms channel pool, forcing new confirmed channels to be created.
+      # This is useful when confirmation failures occur and channels may have contaminated state.
+      #
+      # @return [void]
+      def reset_confirms_pool!
+        cnf_pool = @confirms_pool
+        @confirms_pool = nil
 
-      def channel_pool
-        # Recreate lazily after a fork
-        reset! if @creator_pid && @creator_pid != Process.pid
+        cnf_pool&.shutdown(&:close)
+        nil
+      end
 
-        return @channel_pool if @channel_pool
+      private
+
+      def standard_pool
+        # CRITICAL: Lazy-init must be thread-safe
+        return @standard_pool if @standard_pool
 
         init_mutex.synchronize do
-          @channel_pool ||=
+          # Double-check in case another thread was waiting
+          @standard_pool ||=
             begin
-              @creator_pid = Process.pid
+              @creator_pid ||= Process.pid
+              create_pool(confirms: false)
+            end
+        end
+      end
+
+      def confirms_pool
+        # CRITICAL: Lazy-init must be thread-safe
+        return @confirms_pool if @confirms_pool
 
-              ConnectionPool.new(
-                size: Ears.configuration.publisher_pool_size,
-                timeout: Ears.configuration.publisher_pool_timeout,
-              ) { Ears.connection.create_channel }
+        init_mutex.synchronize do
+          # Double-check in case another thread was waiting
+          @confirms_pool ||=
+            begin
+              @creator_pid ||= Process.pid
+              create_pool(confirms: true)
             end
         end
       end
 
+      def create_pool(confirms:)
+        ConnectionPool.new(
+          size: pool_size_for(confirms),
+          timeout: Ears.configuration.publisher_pool_timeout,
+        ) do
+          channel = Ears.connection.create_channel
+          channel.confirm_select if confirms
+          channel
+        end
+      end
+
+      def pool_size_for(confirms)
+        return Ears.configuration.publisher_confirms_pool_size if confirms
+
+        Ears.configuration.publisher_pool_size
+      end
+
       def init_mutex
         @init_mutex ||= Mutex.new
       end

data/lib/ears/publisher_confirmation_handler.rb

@@ -0,0 +1,91 @@
+require 'ears/errors'
+
+module Ears
+  # Handles publisher confirmations for RabbitMQ messages.
+  #
+  # This class encapsulates the logic for publishing messages with confirmations,
+  # including timeout handling, channel cleanup, and pool coordination.
+  class PublisherConfirmationHandler
+    # Creates a new confirmation handler.
+    #
+    # @param [Ears::Configuration] config The Ears configuration object.
+    # @param [Logger] logger The logger instance for warnings and errors.
+    def initialize(config:, logger:)
+      @config = config
+      @logger = logger
+    end
+
+    # Publishes a message with confirmation.
+    #
+    # @param [Bunny::Channel] channel The channel to use for publishing.
+    # @param [Bunny::Exchange] exchange The exchange to publish to.
+    # @param [Hash, Array, Object] data The data to publish.
+    # @param [String] routing_key The routing key for the message.
+    # @param [Hash] options The publish options.
+    #
+    # @raise [PublishConfirmationTimeout] if confirmation times out
+    # @raise [PublishNacked] if message is nacked by the broker
+    # @return [void]
+    def publish_with_confirmation(
+      channel:,
+      exchange:,
+      data:,
+      routing_key:,
+      options:
+    )
+      exchange.publish(data, { routing_key: routing_key }.merge(options))
+
+      timeout = config.publisher_confirms_timeout
+      unless wait_for_confirms_with_timeout(channel, timeout)
+        handle_confirmation_failure(channel, timeout)
+      end
+    end
+
+    private
+
+    attr_reader :config, :logger
+
+    def wait_for_confirms_with_timeout(channel, timeout)
+      return channel.wait_for_confirms if timeout.nil?
+
+      waiter = Thread.new { channel.wait_for_confirms }
+
+      return waiter.value if waiter.join(timeout)
+
+      begin
+        channel.close if channel.open?
+      rescue StandardError => e
+        warn("Failed closing channel on timeout: #{e.message}")
+      end
+
+      cleanup_timeout = config.publisher_confirms_cleanup_timeout
+      waiter.join(cleanup_timeout) ||
+        warn('Confirm waiter did not stop promptly after close')
+
+      false
+    end
+
+    def handle_confirmation_failure(channel, timeout)
+      begin
+        channel.close if channel&.open?
+      rescue StandardError => e
+        warn("Failed closing channel on failed confirmation: #{e.message}")
+      end
+
+      PublisherChannelPool.reset_confirms_pool!
+
+      if channel.nacked_set&.any?
+        warn('Publisher confirmation failed: message was nacked by broker.')
+        raise PublishNacked, 'Message was nacked by broker'
+      else
+        warn("Publisher confirmation failed: timeout after #{timeout}s.")
+        raise PublishConfirmationTimeout,
+              "Confirmation timeout after #{timeout}s"
+      end
+    end
+
+    def warn(message)
+      logger.warn(message)
+    end
+  end
+end

data/lib/ears/publisher_retry_handler.rb

@@ -19,6 +19,10 @@ module Ears
       Timeout::Error,
     ].freeze
 
+    # Confirmation errors should NOT be retried - they indicate the message
+    # was published but confirmation failed, so retrying could duplicate the message
+    NON_RETRYABLE_ERRORS = [PublishConfirmationTimeout, PublishNacked].freeze
+
     def initialize(config, logger)
       @config = config
       @logger = logger
@@ -28,6 +32,8 @@ module Ears
       attempt = 1
       begin
         block.call
+      rescue *NON_RETRYABLE_ERRORS => e
+        raise e
       rescue *CONNECTION_ERRORS => e
         attempt = handle_connection_error(e, attempt) # rubocop:disable Lint/UselessAssignment
         retry

data/lib/ears/testing/publisher_mock.rb

@@ -41,6 +41,7 @@ module Ears
           setup_exchange_declare(channel)
           setup_register_exchange(channel)
           setup_basic_publish(channel)
+          setup_publisher_confirms(channel)
         end
       end
 
@@ -66,6 +67,14 @@ module Ears
         end
       end
 
+      def setup_publisher_confirms(channel)
+        allow(channel).to receive(:confirm_select)
+        allow(channel).to receive(:wait_for_confirms).and_return(true)
+        allow(channel).to receive(:nacked_set).and_return(Set.new)
+        allow(channel).to receive(:open?).and_return(true)
+        allow(channel).to receive(:close)
+      end
+
       def create_or_get_mock_exchange(name, type, _options)
         mock_exchanges[name] ||= create_mock_exchange(name, type)
       end

data/lib/ears/testing/test_helper.rb

@@ -28,23 +28,38 @@ module Ears
         end
       end
 
-      def published_messages(exchange_name = nil)
+      def published_messages(exchange_name = nil, routing_key_match: nil)
         return [] unless Ears::Testing.message_capture
 
-        if exchange_name
-          return Ears::Testing.message_capture.messages_for(exchange_name)
-        end
+        messages = exchange_name ? messages_for(exchange_name) : all_messages
+        return messages unless routing_key_match
 
-        Ears::Testing.message_capture.all_messages
+        messages.select do |message|
+          message.routing_key.match?(routing_key_match)
+        end
       end
 
       def last_published_message(exchange_name = nil)
         published_messages(exchange_name).last
       end
 
+      def last_published_payload(exchange_name = nil)
+        last_published_message(exchange_name).data
+      end
+
       def clear_published_messages
         Ears::Testing.message_capture&.clear
       end
+
+      private
+
+      def messages_for(exchange_name)
+        Ears::Testing.message_capture.messages_for(exchange_name)
+      end
+
+      def all_messages
+        Ears::Testing.message_capture.all_messages
+      end
     end
   end
 end

data/lib/ears/version.rb

@@ -1,3 +1,3 @@
 module Ears
-  VERSION = '0.21.1'
+  VERSION = '0.22.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ears
 version: !ruby/object:Gem::Version
-  version: 0.21.1
+  version: 0.22.1
 platform: ruby
 authors:
 - InVision AG
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-09 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -89,6 +89,7 @@ files:
 - lib/ears/middlewares/max_retries.rb
 - lib/ears/publisher.rb
 - lib/ears/publisher_channel_pool.rb
+- lib/ears/publisher_confirmation_handler.rb
 - lib/ears/publisher_retry_handler.rb
 - lib/ears/setup.rb
 - lib/ears/testing.rb