ears 0.20.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfbd6ab51a763dae5a9e93db48acb059af700fa88eee4b3f854e912b9f6d19be
-  data.tar.gz: aa328f03ba25e0e7afabdc30bfb9a2212b5072ed6a50ba10a1df9396197ada61
+  metadata.gz: 3ffa13eeabb39addd2d5acb749c6edd32515770b357f7ef6cd3f944cc6aae182
+  data.tar.gz: 4aa87462141bd49cbc616dfff68e7d5b5bf24274b7a6c0430ca02182e15259c5
 SHA512:
-  metadata.gz: 140f6f39b0f3099eb0a00a26a0de7bbbff66335a6bad2cd71d3b8e26f1810301ff16de00675e580beb71de959b8a80d80a4a76309556e4f22019dd37effd717f
-  data.tar.gz: 36053b2d7203bb37e2fd527d86c69922f3cc5a4e99c7723f0b73c7f92a24b9df439baf61aaaa72209857b48bab1a17ebfbd5775633ecefaa270bb911757f28c7
+  metadata.gz: 45a3dffcf2f868f753fc985657bc24909c1bba97f1e633eb012ed4185c231d50edc98093f529b336f1e743dabe374a5ff6e662116d72f74ad5c166c0d81146ff
+  data.tar.gz: 020e285268b69f96269a45e70abdb2287f48ff4346eac060a3dd6c4cebc8c27248f49c045a1c0a0139ea5c8bfc6aafb959634a6c62f945328c9fb1056d71e875

data/.tool-versions

@@ -1,2 +1,2 @@
-ruby 3.2.8
-nodejs 24.1.0
+ruby 3.2.9
+nodejs 24.4.1

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.21.1 (2025-09-09)
+
+- Add testing abstractions: `Ears::Testing::TestHelper`, `Ears::Testing::MessageCapture`, and `Ears::Testing::PublisherMock`
+
+## 0.21.0 (2025-09-08)
+
+- Introduce Ears::Publisher with thread-safe channel pooling
+- Introduce configurable logger
+
 ## 0.20.0 (2025-06-02)
 
 - Drop support for Ruby 3.1

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    ears (0.20.0)
+    ears (0.21.1)
       bunny (>= 2.22.0)
+      connection_pool (~> 2.4)
       multi_json
 
 GEM
@@ -13,14 +14,15 @@ GEM
     bunny (2.24.0)
       amq-protocol (~> 2.3)
       sorted_set (~> 1, >= 1.0.2)
+    connection_pool (2.5.3)
     diff-lcs (1.6.2)
     docile (1.4.1)
-    json (2.12.2)
+    json (2.13.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    multi_json (1.15.0)
+    multi_json (1.17.0)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
     prettier_print (1.2.1)
@@ -34,7 +36,7 @@ GEM
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.4)
+    rspec-core (3.13.5)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -43,7 +45,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rubocop (1.79.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -51,10 +53,11 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
+      tsort (>= 0.2.0)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.46.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-rake (0.7.1)
@@ -69,13 +72,14 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
     sorted_set (1.0.3)
       rbtree
       set (~> 1.0)
-    syntax_tree (6.2.0)
+    syntax_tree (6.3.0)
       prettier_print (>= 1.2.0)
+    tsort (0.2.0)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
@@ -106,15 +110,16 @@ CHECKSUMS
   amq-protocol (2.3.4) sha256=98be5b9244e28dc66acc8351a254dbf45d996c5a0b7d49ab3ff8b72b0d2e6308
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   bunny (2.24.0) sha256=072fe4ae98eaa9c95a17e4d166204f710bba8a9a7070b73a8c3b023f439d1682
+  connection_pool (2.5.3) sha256=cfd74a82b9b094d1ce30c4f1a346da23ee19dc8a062a16a85f58eab1ced4305b
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  ears (0.20.0)
-  json (2.12.2) sha256=ba94a48ad265605c8fa9a50a5892f3ba6a02661aa010f638211f3cb36f44abf4
+  ears (0.21.1)
+  json (2.13.2) sha256=02e1f118d434c6b230a64ffa5c8dee07e3ec96244335c392eaed39e1199dbb68
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
-  multi_json (1.15.0) sha256=1fd04138b6e4a90017e8d1b804c039031399866ff3fbabb7822aea367c78615d
+  multi_json (1.17.0) sha256=76581f6c96aebf2e85f8a8b9854829e0988f335e8671cd1a56a1036eb75e4a1b
   parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
-  parser (3.3.8.0) sha256=2476364142b307fa5a1b1ece44f260728be23858a9c71078e956131a75453c45
+  parser (3.3.9.0) sha256=94d6929354b1a6e3e1f89d79d4d302cc8f5aa814431a6c9c7e0623335d7687f2
   prettier_print (1.2.1) sha256=a72838b5f23facff21f90a5423cdcdda19e4271092b41f4ea7f50b83929e6ff9
   prism (1.4.0) sha256=dc0e3e00e93160213dc2a65519d9002a4a1e7b962db57d444cf1a71565bb703e
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
@@ -123,24 +128,25 @@ CHECKSUMS
   rbtree (0.4.6) sha256=14eea4469b24fd2472542e5f3eb105d6344c8ccf36f0b56d55fdcfeb4e0f10fc
   regexp_parser (2.10.0) sha256=cb6f0ddde88772cd64bff1dbbf68df66d376043fe2e66a9ef77fcb1b0c548c61
   rspec (3.13.1) sha256=b9f9a58fa915b8d94a1d6b3195fe6dd28c4c34836a6097015142c4a9ace72140
-  rspec-core (3.13.4) sha256=f9da156b7b775c82610a7b580624df51a55102f8c8e4a103b98f5d7a9fa23958
+  rspec-core (3.13.5) sha256=ab3f682897c6131c67f9a17cfee5022a597f283aebe654d329a565f9937a4fa3
   rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
   rspec-mocks (3.13.5) sha256=e4338a6f285ada9fe56f5893f5457783af8194f5d08884d17a87321d5195ea81
   rspec-support (3.13.4) sha256=184b1814f6a968102b57df631892c7f1990a91c9a3b9e80ef892a0fc2a71a3f7
-  rubocop (1.75.8) sha256=c80ab4286c5dcfc49d7ad1787cdba5569b63b58c96ee7afde4ec47a9c8a85be9
-  rubocop-ast (1.44.1) sha256=e3cc04203b2ef04f6d6cf5f85fe6d643f442b18cc3b23e3ada0ce5b6521b8e92
+  rubocop (1.79.0) sha256=c709e83b16f9fced295d83d190a3a5bbcc46c419d8f9b85f259b99ba6faf5bbe
+  rubocop-ast (1.46.0) sha256=0da7f6ad5b98614f89b74f11873c191059c823eae07d6ffd40a42a3338f2232b
   rubocop-rake (0.7.1) sha256=3797f2b6810c3e9df7376c26d5f44f3475eda59eb1adc38e6f62ecf027cbae4d
   rubocop-rspec (3.6.0) sha256=c0e4205871776727e54dee9cc91af5fd74578001551ba40e1fe1a1ab4b404479
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   set (1.1.2) sha256=ca33a60d202e788041d94a5d4c12315b1639875576f1a266f3a10913646d8ef1
   simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
-  simplecov-html (0.13.1) sha256=5dab0b7ee612e60e9887ad57693832fdf4695b4c0c859eaea5f95c18791ef10b
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
   simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
   sorted_set (1.0.3) sha256=4f2b8bee6e8c59cbd296228c0f1f81679357177a8b6859dcc2a99e86cce6372f
-  syntax_tree (6.2.0) sha256=a50a01c246601af3c258edbb6b12e44373d17966ab3bebd1f7224b3b994a343d
+  syntax_tree (6.3.0) sha256=56e25a9692c798ec94c5442fe94c5e94af76bef91edc8bb02052cbdecf35f13d
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   unicode-display_width (3.1.4) sha256=8caf2af1c0f2f07ec89ef9e18c7d88c2790e217c482bfc78aaa65eadd5415ac1
   unicode-emoji (4.0.4) sha256=2c2c4ef7f353e5809497126285a50b23056cc6e61b64433764a35eff6c36532a
   yard (0.9.37) sha256=a6e910399e78e613f80ba9add9ba7c394b1a935f083cccbef82903a3d2a26992
 
 BUNDLED WITH
-   2.6.9
+   2.7.1

data/README.md

@@ -1,6 +1,6 @@
 # Ears
 
-`Ears` is a small, simple library for writing RabbitMQ consumers.
+`Ears` is a small, simple library for writing RabbitMQ consumers and publishers.
 
 [![CodeQL](https://github.com/ivx/ears/actions/workflows/codeql.yml/badge.svg)](https://github.com/ivx/ears/actions/workflows/codeql.yml)
 
@@ -22,7 +22,182 @@ Or install it yourself as:
 
 ## Usage
 
-### Basic usage
+### Publishing Messages
+
+`Ears` provides a thread-safe publisher for sending messages to RabbitMQ exchanges with automatic retry and connection recovery capabilities.
+
+#### Basic Publisher Usage
+
+To publish messages, create an `Ears::Publisher` instance and call `publish`:
+
+```ruby
+require 'ears'
+
+# Configure Ears (same configuration is shared by consumers and publishers)
+Ears.configure do |config|
+  config.rabbitmq_url = 'amqp://user:password@myrmq:5672'
+  config.connection_name = 'My Publisher'
+end
+
+# Create a publisher for a topic exchange
+publisher = Ears::Publisher.new('my_exchange', :topic, durable: true)
+
+# Publish a message
+data = { user_id: 123, action: 'login', timestamp: Time.now.iso8601 }
+publisher.publish(data, routing_key: 'user.login')
+```
+
+#### Exchange Types and Options
+
+Publishers support all RabbitMQ exchange types:
+
+```ruby
+# Topic exchange (default)
+topic_publisher = Ears::Publisher.new('events', :topic)
+
+# Direct exchange
+direct_publisher = Ears::Publisher.new('commands', :direct)
+
+# Fanout exchange
+fanout_publisher = Ears::Publisher.new('broadcasts', :fanout)
+
+# Headers exchange
+headers_publisher = Ears::Publisher.new('complex_routing', :headers)
+
+# Custom exchange options
+publisher =
+  Ears::Publisher.new(
+    'my_exchange',
+    :topic,
+    durable: true,
+    auto_delete: false,
+    arguments: {
+      'x-message-ttl' => 60_000,
+    },
+  )
+```
+
+#### Message Options
+
+The `publish` method accepts various message options:
+
+```ruby
+publisher.publish(
+  { message: 'Hello World' },
+  routing_key: 'greeting.hello',
+  persistent: true, # Persist message to disk (default: true)
+  headers: {
+    version: '1.0',
+  }, # Custom headers
+  timestamp: Time.now.to_i, # Message timestamp (default: current time)
+  message_id: SecureRandom.uuid, # Unique message identifier
+  correlation_id: 'abc-123', # Correlation ID for request/response patterns
+  reply_to: 'response_queue', # Queue for responses
+  expiration: '60000', # Message TTL in milliseconds
+  priority: 5, # Message priority (0-9)
+  type: 'user_event', # Message type
+  app_id: 'my_application', # Application identifier
+  user_id: 'system', # User identifier (verified by RabbitMQ)
+)
+```
+
+#### Thread-Safe Publishing
+
+Publishers use a connection pool for thread-safe operation, making them suitable for concurrent use:
+
+```ruby
+# Single publisher can be safely used across multiple threads
+publisher = Ears::Publisher.new('events', :topic)
+
+# Example with multiple threads
+threads =
+  10.times.map do |i|
+    Thread.new do
+      100.times do |j|
+        publisher.publish({ thread: i, message: j }, routing_key: "thread.#{i}")
+      end
+    end
+  end
+
+threads.each(&:join)
+```
+
+#### Publisher Configuration
+
+Publisher behavior can be fine-tuned through configuration options:
+
+```ruby
+Ears.configure do |config|
+  # Connection settings
+  config.rabbitmq_url = 'amqp://user:password@myrmq:5672'
+  config.connection_name = 'My Application'
+
+  # Publisher-specific settings
+  config.publisher_pool_size = 32 # Channel pool size (default: 32)
+  config.publisher_pool_timeout = 2 # Pool checkout timeout in seconds (default: 2)
+
+  # Connection retry settings
+  config.publisher_connection_attempts = 30 # Connection retry attempts (default: 30)
+  config.publisher_connection_base_delay = 1 # Base delay between connection attempts (default: 1s)
+  config.publisher_connection_backoff_factor = 1.5 # Connection backoff multiplier (default: 1.5)
+
+  # Publish retry settings
+  config.publisher_max_retries = 3 # Max publish retry attempts (default: 3)
+  config.publisher_retry_base_delay = 0.1 # Base delay between publish retries (default: 0.1s)
+  config.publisher_retry_backoff_factor = 2 # Publish retry backoff multiplier (default: 2)
+end
+```
+
+#### Fault Tolerance and Recovery
+
+Publishers automatically handle connection failures and provide several recovery mechanisms:
+
+##### Automatic Retry with Exponential Backoff
+
+```ruby
+# Publishers automatically retry failed operations
+publisher = Ears::Publisher.new('events', :topic)
+
+# This will automatically retry with exponential backoff if the connection fails
+publisher.publish({ event: 'user_signup' }, routing_key: 'user.signup')
+```
+
+##### Manual Recovery
+
+If you need to manually reset the connection pool (e.g., after detecting connection issues):
+
+```ruby
+publisher = Ears::Publisher.new('events', :topic)
+
+# Reset the channel pool to force new connections
+publisher.reset!
+
+# Subsequent publishes will use fresh channels
+publisher.publish({ event: 'recovery_test' }, routing_key: 'system.recovery')
+```
+
+##### Error Handling
+
+Publishers raise specific exceptions that you can handle:
+
+```ruby
+require 'ears'
+
+publisher = Ears::Publisher.new('events', :topic)
+
+begin
+  publisher.publish({ data: 'test' }, routing_key: 'test.message')
+rescue Ears::PublisherRetryHandler::PublishError => e
+  # Handle publish failures (after all retries exhausted)
+  logger.error "Failed to publish message: #{e.message}"
+  # Consider queuing message for later retry or alerting
+rescue => e
+  # Handle other unexpected errors
+  logger.error "Unexpected error: #{e.message}"
+end
+```
+
+### Basic consumer usage
 
 First, you should configure `Ears`.
 
@@ -34,6 +209,16 @@ Ears.configure do |config|
   config.connection_name = 'My Consumer'
   config.recover_from_connection_close = false # optional configuration, defaults to true if not set
   config.recovery_attempts = 3 # optional configuration, defaults to 10, Bunny::Session would have been nil
+
+  # Publisher configuration (optional)
+  config.publisher_pool_size = 32 # Thread pool size for publishers (default: 32)
+  config.publisher_pool_timeout = 2 # Timeout for pool checkout in seconds (default: 2)
+  config.publisher_connection_attempts = 30 # Connection retry attempts (default: 30)
+  config.publisher_connection_base_delay = 1 # Base delay between connection attempts in seconds (default: 1)
+  config.publisher_connection_backoff_factor = 1.5 # Connection retry backoff multiplier (default: 1.5)
+  config.publisher_max_retries = 3 # Max publish retry attempts (default: 3)
+  config.publisher_retry_base_delay = 0.1 # Base delay between publish retries in seconds (default: 0.1)
+  config.publisher_retry_backoff_factor = 2 # Publish retry backoff multiplier (default: 2)
 end
 ```
 
@@ -285,6 +470,193 @@ Ears.stop!
 
 It will close and reset the current Bunny connection, leading to all consumers being shut down. Also, it will reset the channel.
 
+### Complete Example: Consumer and Publisher
+
+Here's a complete example showing both consumer and publisher usage:
+
+```ruby
+require 'ears'
+
+# Shared configuration
+Ears.configure do |config|
+  config.rabbitmq_url = 'amqp://guest:guest@localhost:5672'
+  config.connection_name = 'Order Processing Service'
+  config.publisher_pool_size = 16
+end
+
+# Consumer that processes orders and publishes events
+class OrderProcessor < Ears::Consumer
+  configure(
+    queue: 'orders',
+    exchange: 'ecommerce',
+    routing_keys: %w[order.created order.updated],
+    retry_queue: true,
+    error_queue: true,
+  )
+
+  def initialize
+    super
+    @event_publisher = Ears::Publisher.new('events', :topic, durable: true)
+  end
+
+  def work(delivery_info, metadata, payload)
+    order = JSON.parse(payload)
+
+    # Process the order
+    process_order(order)
+
+    # Publish success event
+    @event_publisher.publish(
+      {
+        order_id: order['id'],
+        status: 'processed',
+        processed_at: Time.now.iso8601,
+      },
+      routing_key: 'order.processed',
+    )
+
+    ack
+  rescue => error
+    # Publish error event
+    @event_publisher.publish(
+      {
+        order_id: order&.dig('id'),
+        error: error.message,
+        failed_at: Time.now.iso8601,
+      },
+      routing_key: 'order.failed',
+    )
+
+    reject # Send to error queue
+  end
+
+  private
+
+  def process_order(order)
+    # Order processing logic here
+    sleep(0.1) # Simulate processing time
+  end
+end
+
+# Setup and run
+Ears.setup { Ears.setup_consumers(OrderProcessor) }
+
+begin
+  Ears.run!
+ensure
+  # Cleanup code here
+end
+```
+
+## Testing
+
+Ears provides testing helpers to easily test your message publishing without connecting to RabbitMQ.
+
+### Basic Setup
+
+Include the test helper in your RSpec tests and mock the exchanges you want to test:
+
+```ruby
+require 'ears/testing'
+
+RSpec.describe MyService do
+  include Ears::Testing::TestHelper
+
+  before do
+    # Mock exchanges that your code will publish to
+    mock_ears('events', 'notifications')
+  end
+
+  after do
+    # Clean up mocks and captured messages
+    ears_reset!
+  end
+end
+```
+
+### Capturing and Inspecting Messages
+
+Use the helper methods to inspect published messages:
+
+```ruby
+it 'publishes user creation event' do
+  service = UserService.new
+  service.create_user(name: 'John', email: 'john@example.com')
+
+  # Get all messages published to 'events' exchange
+  messages = published_messages('events')
+  expect(messages.size).to eq(1)
+
+  # Inspect the message
+  message = messages.first
+  expect(message.routing_key).to eq('user.created')
+  expect(message.data).to include(name: 'John')
+  expect(message.options[:headers]).to include(version: '1.0')
+end
+```
+
+### Available Helper Methods
+
+- `published_messages(exchange_name = nil)` - Get messages for a specific exchange or all messages
+- `last_published_message(exchange_name = nil)` - Get the most recent message
+- `clear_published_messages` - Clear captured messages during a test
+
+### Message Properties
+
+Each captured message has the following properties:
+
+- `exchange_name` - Name of the exchange
+- `routing_key` - Message routing key
+- `data` - The message payload
+- `options` - Publishing options (headers, persistent, etc.)
+- `timestamp` - When the message was captured
+- `thread_id` - Thread that published the message
+
+### Error Handling
+
+By default, publishing to unmocked exchanges raises an error:
+
+```ruby
+it 'raises error for unmocked exchanges' do
+  publisher = Ears::Publisher.new('unmocked_exchange')
+
+  expect {
+    publisher.publish({ data: 'test' }, routing_key: 'test')
+  }.to raise_error(Ears::Testing::UnmockedExchangeError)
+end
+```
+
+### Complete Example
+
+```ruby
+require 'ears/testing'
+
+RSpec.describe OrderProcessor do
+  include Ears::Testing::TestHelper
+
+  before { mock_ears('events', 'notifications') }
+  after { ears_reset! }
+
+  it 'publishes events when processing order' do
+    processor = OrderProcessor.new
+    order = { id: 123, items: ['item1'], total: 99.99 }
+
+    processor.process(order)
+
+    # Check event was published
+    events = published_messages('events')
+    expect(events.size).to eq(1)
+    expect(events.first.routing_key).to eq('order.processed')
+    expect(events.first.data[:order_id]).to eq(123)
+
+    # Check notification was sent
+    notifications = published_messages('notifications')
+    expect(notifications.size).to eq(1)
+    expect(notifications.first.routing_key).to eq('email.order_confirmation')
+  end
+end
+```
+
 ## Documentation
 
 If you need more in-depth information, look at [our API documentation](https://www.rubydoc.info/gems/ears).

data/ears.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.description = 'A gem for building RabbitMQ consumers.'
   spec.homepage = 'https://github.com/ivx/ears'
   spec.license = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 3.2.8')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.2.9')
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
@@ -33,5 +33,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'bunny', '>= 2.22.0'
+  spec.add_dependency 'connection_pool', '~> 2.4'
   spec.add_dependency 'multi_json'
 end

data/lib/ears/configuration.rb

@@ -1,4 +1,5 @@
 require 'ears/errors'
+require 'logger'
 
 module Ears
   # The class representing the global {Ears} configuration.
@@ -8,6 +9,14 @@ module Ears
 
     DEFAULT_RABBITMQ_URL = 'amqp://guest:guest@localhost:5672'
     DEFAULT_RECOVERY_ATTEMPTS = 10
+    DEFAULT_PUBLISHER_POOL_SIZE = 32
+    DEFAULT_PUBLISHER_POOL_TIMEOUT = 2
+    DEFAULT_PUBLISHER_CONNECTION_ATTEMPTS = 30
+    DEFAULT_PUBLISHER_CONNECTION_BASE_DELAY = 1
+    DEFAULT_PUBLISHER_CONNECTION_BACKOFF_FACTOR = 1.5
+    DEFAULT_PUBLISHER_MAX_RETRIES = 3
+    DEFAULT_PUBLISHER_RETRY_BASE_DELAY = 0.1
+    DEFAULT_PUBLISHER_RETRY_BACKOFF_FACTOR = 2
 
     # @return [String] the connection string for RabbitMQ.
     attr_accessor :rabbitmq_url
@@ -21,9 +30,46 @@ module Ears
     # @return [Integer] max number of recovery attempts, nil means forever
     attr_accessor :recovery_attempts
 
+    # @return [Integer] the size of the publisher channel pool
+    attr_accessor :publisher_pool_size
+
+    # @return [Integer] the timeout in seconds for acquiring a channel from the publisher pool
+    attr_accessor :publisher_pool_timeout
+
+    # @return [Integer] the number of connection attempts for the publisher
+    attr_accessor :publisher_connection_attempts
+
+    # @return [Float] the base delay in seconds between connection attempts
+    attr_accessor :publisher_connection_base_delay
+
+    # @return [Float] the backoff factor for exponential connection delays
+    attr_accessor :publisher_connection_backoff_factor
+
+    # @return [Integer] the maximum number of retries for failed publish attempts
+    attr_accessor :publisher_max_retries
+
+    # @return [Float] the base delay in seconds between retry attempts
+    attr_accessor :publisher_retry_base_delay
+
+    # @return [Float] the backoff factor for exponential retry delays
+    attr_accessor :publisher_retry_backoff_factor
+
+    # @return [Logger] the logger instance for Ears operations
+    attr_accessor :logger
+
     def initialize
       @rabbitmq_url = DEFAULT_RABBITMQ_URL
       @recovery_attempts = DEFAULT_RECOVERY_ATTEMPTS
+      @publisher_pool_size = DEFAULT_PUBLISHER_POOL_SIZE
+      @publisher_pool_timeout = DEFAULT_PUBLISHER_POOL_TIMEOUT
+      @publisher_connection_attempts = DEFAULT_PUBLISHER_CONNECTION_ATTEMPTS
+      @publisher_connection_base_delay = DEFAULT_PUBLISHER_CONNECTION_BASE_DELAY
+      @publisher_connection_backoff_factor =
+        DEFAULT_PUBLISHER_CONNECTION_BACKOFF_FACTOR
+      @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
+      @logger = Logger.new(IO::NULL)
     end
 
     # @return [Proc] that is passed to Bunny’s recovery_attempts_exhausted block. Nil if recovery_attempts is nil.

data/lib/ears/publisher.rb

@@ -0,0 +1,108 @@
+require 'bunny'
+require 'ears/publisher_channel_pool'
+require 'ears/publisher_retry_handler'
+
+module Ears
+  # Publisher for sending messages to RabbitMQ exchanges.
+  #
+  # Uses a connection pool for thread-safe publishing with configurable pool size.
+  # This provides better performance and thread safety compared to using per-thread channels.
+  class Publisher
+    # Creates a new publisher for the specified exchange.
+    #
+    # @param [String] exchange_name The name of the exchange to publish to.
+    # @param [Symbol] exchange_type The type of the exchange (:direct, :fanout, :topic or :headers).
+    # @param [Hash] exchange_options The options for the exchange. These are passed on to +Bunny::Exchange.new+.
+    def initialize(exchange_name, exchange_type = :topic, exchange_options = {})
+      @exchange_name = exchange_name
+      @exchange_type = exchange_type
+      @exchange_options = { durable: true }.merge(exchange_options)
+      @config = Ears.configuration
+      @logger = Ears.configuration.logger
+    end
+
+    # Publishes a JSON message to the configured exchange.
+    #
+    # @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 [PublishError] if publishing fails
+    # @return [void]
+    def publish(data, routing_key:, **options)
+      publish_options = default_publish_options.merge(options)
+
+      retry_handler.run do
+        publish_with_channel(data:, routing_key:, publish_options:)
+      end
+    end
+
+    # Resets the channel pool, forcing new channels to be created.
+    # This can be useful for connection recovery scenarios.
+    #
+    # @return [void]
+    def reset!
+      PublisherChannelPool.reset!
+    end
+
+    private
+
+    attr_reader :exchange_name,
+                :exchange_type,
+                :exchange_options,
+                :config,
+                :logger
+
+    def publish_with_channel(data:, routing_key:, publish_options:)
+      unless Ears.connection.open?
+        raise PublisherRetryHandler::PublishToStaleChannelError,
+              'Connection is not open'
+      end
+
+      PublisherChannelPool.with_channel do |channel|
+        exchange = create_exchange(channel)
+        exchange.publish(
+          data,
+          { routing_key: routing_key }.merge(publish_options),
+        )
+      end
+    end
+
+    def create_exchange(channel)
+      Bunny::Exchange.new(
+        channel,
+        exchange_type,
+        exchange_name,
+        exchange_options,
+      )
+    end
+
+    def default_publish_options
+      {
+        persistent: true,
+        timestamp: Time.now.to_i,
+        headers: {
+        },
+        content_type: 'application/json',
+      }
+    end
+
+    def retry_handler
+      @retry_handler ||= PublisherRetryHandler.new(config, logger)
+    end
+  end
+end

data/lib/ears/publisher_channel_pool.rb

@@ -0,0 +1,55 @@
+require 'connection_pool'
+
+module Ears
+  # Channel pool management for publishers.
+  # Provides thread-safe channel pooling separate from consumer channels.
+  class PublisherChannelPool
+    class << self
+      # Executes the given block with a channel from the pool.
+      #
+      # @yieldparam [Bunny::Channel] channel The channel to use for publishing
+      # @return [Object] The result of the block
+      def with_channel(&)
+        channel_pool.with(&)
+      end
+
+      # Resets the channel pool, forcing new channels to be created.
+      # This is useful for connection recovery scenarios.
+      #
+      # @return [void]
+      def reset!
+        pool = @channel_pool
+        @channel_pool = nil
+        @creator_pid = nil
+
+        pool&.shutdown(&:close)
+        nil
+      end
+
+      private
+
+      def channel_pool
+        # Recreate lazily after a fork
+        reset! if @creator_pid && @creator_pid != Process.pid
+
+        return @channel_pool if @channel_pool
+
+        init_mutex.synchronize do
+          @channel_pool ||=
+            begin
+              @creator_pid = Process.pid
+
+              ConnectionPool.new(
+                size: Ears.configuration.publisher_pool_size,
+                timeout: Ears.configuration.publisher_pool_timeout,
+              ) { Ears.connection.create_channel }
+            end
+        end
+      end
+
+      def init_mutex
+        @init_mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/ears/publisher_retry_handler.rb

@@ -0,0 +1,104 @@
+require 'bunny'
+
+module Ears
+  # A handler for retries and connection recovery when publishing messages.
+  class PublisherRetryHandler
+    # Exception for publishing to a stale/closed channel
+    class PublishToStaleChannelError < StandardError
+    end
+
+    # Connection errors that should trigger retries
+    CONNECTION_ERRORS = [
+      PublishToStaleChannelError,
+      Bunny::ChannelAlreadyClosed,
+      Bunny::ConnectionClosedError,
+      Bunny::ConnectionForced,
+      Bunny::NetworkFailure,
+      Bunny::TCPConnectionFailed,
+      IOError,
+      Timeout::Error,
+    ].freeze
+
+    def initialize(config, logger)
+      @config = config
+      @logger = logger
+    end
+
+    def run(&block)
+      attempt = 1
+      begin
+        block.call
+      rescue *CONNECTION_ERRORS => e
+        attempt = handle_connection_error(e, attempt) # rubocop:disable Lint/UselessAssignment
+        retry
+      rescue StandardError => e
+        attempt = handle_standard_error(e, attempt)
+        retry
+      end
+    end
+
+    private
+
+    attr_reader :config, :logger
+
+    def handle_connection_error(error, attempt)
+      raise(error) unless retry?(error, attempt)
+
+      wait_for_connection(error)
+      logger.info('Resetting channel pool after connection recovery')
+      PublisherChannelPool.reset!
+
+      attempt + 1
+    end
+
+    def handle_standard_error(error, attempt)
+      raise(error) unless retry?(error, attempt)
+
+      sleep(retry_backoff_delay(attempt)) if attempt > 1
+      attempt + 1
+    end
+
+    def retry?(error, attempt)
+      logger.info(
+        "Trying to recover from publish error. Attempt #{attempt}: #{error.class}: #{error.message}",
+      )
+
+      if attempt > config.publisher_max_retries
+        logger.warn(
+          "Connection attempts exhausted, giving up: #{error.class}: #{error.message}",
+        )
+        return false
+      end
+
+      true
+    end
+
+    def wait_for_connection(original_error)
+      connection_attempt = 0
+      logger.info('Trying to reconnect after connection error')
+      while !Ears.connection.open?
+        logger.info(
+          "Connection still closed, attempt #{connection_attempt + 1}",
+        )
+        connection_attempt += 1
+
+        if connection_attempt > config.publisher_connection_attempts
+          logger.error('Connection attempts exhausted, giving up')
+          raise original_error
+        end
+
+        sleep(connection_backoff_delay(connection_attempt))
+      end
+    end
+
+    def retry_backoff_delay(attempt)
+      config.publisher_retry_base_delay *
+        (config.publisher_retry_backoff_factor**(attempt - 1))
+    end
+
+    def connection_backoff_delay(attempt)
+      config.publisher_connection_base_delay *
+        (config.publisher_connection_backoff_factor**(attempt - 1))
+    end
+  end
+end

data/lib/ears/testing/message_capture.rb

@@ -0,0 +1,89 @@
+module Ears
+  module Testing
+    class MessageCapture
+      Message =
+        Struct.new(
+          :exchange_name,
+          :routing_key,
+          :data,
+          :options,
+          :timestamp,
+          :thread_id,
+          keyword_init: true,
+        )
+
+      def initialize
+        @messages = {}
+        @mutex = Mutex.new
+      end
+
+      def add_message(exchange_name, data, routing_key, options = {})
+        @mutex.synchronize do
+          @messages[exchange_name] ||= []
+
+          message =
+            Message.new(
+              exchange_name: exchange_name,
+              routing_key: routing_key,
+              data: data,
+              options: options,
+              timestamp: Time.now,
+              thread_id: Thread.current.object_id.to_s,
+            )
+
+          @messages[exchange_name] << message
+
+          shift_messages(exchange_name)
+
+          message
+        end
+      end
+
+      def messages_for(exchange_name)
+        @mutex.synchronize { (@messages[exchange_name] || []).dup }
+      end
+
+      def all_messages
+        @mutex.synchronize { @messages.values.flatten }
+      end
+
+      def clear
+        @mutex.synchronize { @messages.clear }
+      end
+
+      def count(exchange_name = nil)
+        @mutex.synchronize do
+          return (@messages[exchange_name] || []).size if exchange_name
+
+          @messages.values.sum(&:size)
+        end
+      end
+
+      def empty?
+        @mutex.synchronize do
+          @messages.empty? || @messages.values.all?(&:empty?)
+        end
+      end
+
+      def find_messages(exchange_name: nil, routing_key: nil, data: nil)
+        messages = exchange_name ? messages_for(exchange_name) : all_messages
+
+        messages.select do |msg|
+          next false if routing_key && msg.routing_key != routing_key
+          next false if data && msg.data != data
+
+          true
+        end
+      end
+
+      private
+
+      def shift_messages(exchange_name)
+        max_messages = Ears::Testing.configuration.max_captured_messages
+        if @messages[exchange_name].size > max_messages
+          @messages[exchange_name].shift
+        end
+      end
+    end
+  end
+end

data/lib/ears/testing/publisher_mock.rb

@@ -0,0 +1,102 @@
+require 'rspec/mocks'
+
+module Ears
+  module Testing
+    class UnmockedExchangeError < StandardError
+    end
+
+    class PublisherMock
+      include RSpec::Mocks::ExampleMethods
+
+      def initialize(exchange_names, message_capture)
+        @exchange_names = Array(exchange_names)
+        @message_capture = message_capture
+        @mock_exchanges = {}
+      end
+
+      def setup_mocks
+        setup_connection
+        setup_channel_pool
+      end
+
+      private
+
+      attr_reader :exchange_names, :message_capture, :mock_exchanges
+
+      def setup_connection
+        mock_connection = instance_double(Bunny::Session, open?: true)
+        Ears.instance_variable_set(:@connection, mock_connection)
+      end
+
+      def setup_channel_pool
+        mock_channel = create_mock_channel
+        allow(Ears::PublisherChannelPool).to receive(:with_channel).and_yield(
+          mock_channel,
+        )
+        mock_channel
+      end
+
+      def create_mock_channel
+        instance_double(Bunny::Channel).tap do |channel|
+          setup_exchange_declare(channel)
+          setup_register_exchange(channel)
+          setup_basic_publish(channel)
+        end
+      end
+
+      def setup_exchange_declare(channel)
+        allow(channel).to receive(:exchange_declare) do |name, type, options|
+          create_or_get_mock_exchange(name, type, options)
+        end
+      end
+
+      def setup_register_exchange(channel)
+        allow(channel).to receive(:register_exchange)
+      end
+
+      def setup_basic_publish(channel)
+        allow(channel).to receive(
+          :basic_publish,
+        ) do |data, exchange, routing_key, options|
+          if exchange_names.include?(exchange)
+            capture_message(exchange, data, routing_key, options)
+          elsif strict_mocking?
+            raise_unmocked_exchange_error(exchange)
+          end
+        end
+      end
+
+      def create_or_get_mock_exchange(name, type, _options)
+        mock_exchanges[name] ||= create_mock_exchange(name, type)
+      end
+
+      def create_mock_exchange(name, type)
+        exchange = instance_double(Bunny::Exchange, name: name, type: type)
+
+        setup_exchange_publish(exchange, name)
+
+        exchange
+      end
+
+      def setup_exchange_publish(exchange, name)
+        allow(exchange).to receive(:publish) do |data, routing_options|
+          routing_key = routing_options[:routing_key]
+          capture_message(name, data, routing_key, routing_options)
+        end
+      end
+
+      def capture_message(exchange_name, data, routing_key, options)
+        message_capture.add_message(exchange_name, data, routing_key, options)
+      end
+
+      def strict_mocking?
+        Ears::Testing.configuration.strict_exchange_mocking
+      end
+
+      def raise_unmocked_exchange_error(exchange)
+        raise UnmockedExchangeError,
+              "Exchange '#{exchange}' has not been mocked. Add mock_ears('#{exchange}') to your test setup."
+      end
+    end
+  end
+end

data/lib/ears/testing/test_helper.rb

@@ -0,0 +1,50 @@
+require 'rspec/mocks'
+
+module Ears
+  module Testing
+    module TestHelper
+      include RSpec::Mocks::ExampleMethods
+
+      def mock_ears(*exchange_names)
+        Ears::Testing.message_capture ||= MessageCapture.new
+
+        @original_connection = Ears.instance_variable_get(:@connection)
+
+        publisher_mock =
+          PublisherMock.new(exchange_names, Ears::Testing.message_capture)
+        publisher_mock.setup_mocks
+      end
+
+      def ears_reset!
+        Ears::Testing.message_capture = nil
+
+        if instance_variable_defined?(:@original_connection)
+          Ears.instance_variable_set(:@connection, @original_connection)
+          remove_instance_variable(:@original_connection)
+        end
+
+        if defined?(Ears::PublisherChannelPool)
+          Ears::PublisherChannelPool.reset!
+        end
+      end
+
+      def published_messages(exchange_name = nil)
+        return [] unless Ears::Testing.message_capture
+
+        if exchange_name
+          return Ears::Testing.message_capture.messages_for(exchange_name)
+        end
+
+        Ears::Testing.message_capture.all_messages
+      end
+
+      def last_published_message(exchange_name = nil)
+        published_messages(exchange_name).last
+      end
+
+      def clear_published_messages
+        Ears::Testing.message_capture&.clear
+      end
+    end
+  end
+end

data/lib/ears/testing.rb

@@ -0,0 +1,37 @@
+require 'ears'
+require 'ears/testing/test_helper'
+require 'ears/testing/message_capture'
+require 'ears/testing/publisher_mock'
+
+module Ears
+  module Testing
+    class << self
+      attr_accessor :message_capture
+
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def reset!
+        @message_capture = nil
+        @configuration = nil
+      end
+    end
+
+    class Configuration
+      attr_accessor :max_captured_messages,
+                    :auto_cleanup,
+                    :strict_exchange_mocking
+
+      def initialize
+        @max_captured_messages = 1000
+        @auto_cleanup = true
+        @strict_exchange_mocking = true
+      end
+    end
+  end
+end

data/lib/ears/version.rb

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

data/lib/ears.rb

@@ -2,6 +2,8 @@ require 'bunny'
 require 'ears/configuration'
 require 'ears/consumer'
 require 'ears/middleware'
+require 'ears/publisher'
+require 'ears/publisher_channel_pool'
 require 'ears/setup'
 require 'ears/version'
 

data/package-lock.json

@@ -8,7 +8,7 @@
       "devDependencies": {
         "@invisionag/prettier-config": "^2.1.3",
         "@prettier/plugin-ruby": "^4.0.4",
-        "prettier": "^3.5.3"
+        "prettier": "^3.6.2"
       }
     },
     "node_modules/@invisionag/prettier-config": {
@@ -30,9 +30,9 @@
       }
     },
     "node_modules/prettier": {
-      "version": "3.5.3",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.5.3.tgz",
-      "integrity": "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw==",
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
       "bin": {
@@ -62,9 +62,9 @@
       "requires": {}
     },
     "prettier": {
-      "version": "3.5.3",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.5.3.tgz",
-      "integrity": "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw==",
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true
     }
   }

data/package.json

@@ -9,7 +9,7 @@
   "devDependencies": {
     "@invisionag/prettier-config": "^2.1.3",
     "@prettier/plugin-ruby": "^4.0.4",
-    "prettier": "^3.5.3"
+    "prettier": "^3.6.2"
   },
   "prettier": "@invisionag/prettier-config/ruby"
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ears
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.1
 platform: ruby
 authors:
 - InVision AG
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-02 00:00:00.000000000 Z
+date: 2025-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.22.0
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -73,7 +87,14 @@ files:
 - lib/ears/middlewares/appsignal.rb
 - lib/ears/middlewares/json.rb
 - lib/ears/middlewares/max_retries.rb
+- lib/ears/publisher.rb
+- lib/ears/publisher_channel_pool.rb
+- lib/ears/publisher_retry_handler.rb
 - lib/ears/setup.rb
+- lib/ears/testing.rb
+- lib/ears/testing/message_capture.rb
+- lib/ears/testing/publisher_mock.rb
+- lib/ears/testing/test_helper.rb
 - lib/ears/version.rb
 - package-lock.json
 - package.json
@@ -94,7 +115,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.8
+      version: 3.2.9
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="