lepus 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf4a273147ed0ac74a06388815e4910e67a37fd686b3a58272f38fe1ecc8cb9e
-  data.tar.gz: 856ae919667b82af10a084f848bcfed8d7035576a2d5b5723b59f8eaa1442f72
+  metadata.gz: 67f07eb800872caf73d2f74330322cfb4682f740cf60734405f399f815368a9f
+  data.tar.gz: 96257edb75021e9154cef73212e26f450f508ad7aa0fb5659756efebb8b3cb5a
 SHA512:
-  metadata.gz: 60c7f8c51fe0005339497a951aa6bce64126b8e7281715501d311a74b0e39bf03f2f26c4d6ebbf59127e050e37449d8f9e5761008d254de63c66c542486114d2
-  data.tar.gz: 70844794237fa832ac5d39cdb9c9f850ca96e848c9c6f571c4398b2a17e486c59d8228b29276c662db7a6ea4ee8a960d12359a56f6112cc5f5bbc0beaa8e82ea
+  metadata.gz: eab85b9d115eade80732103040ca2e0db25e8146e0dc957005e469ec60776f0a0693a59bd5359bc618a1bb69fafd7b8b0ac19502029355703629f1d5a7040e89
+  data.tar.gz: 652b48322bb2372a261c497da6e60d4ea218f90d1ea2ae41da32024da74f6c5d4d288a4249af8279825aba6bf20b385748692190c2db871a63ab35e8e4338d78

data/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.0 - 2026-10-28
+* Added: named producer connections via `config.connection(name, url:, **bunny_options)`; `rabbitmq_url` remains the `:default` connection
+* Added: `connection:` option on `Producer.configure`, `Producer.publish` and `Lepus::Publisher.new`, with one producer connection pool per name
+* Added: `Lepus::InvalidConnectionError` raised for unregistered connection names
+* Added: fake messages in `Lepus::Testing` record their `connection`
+
 ## 0.0.1 - 2024-08-01
 The first release of the gem
 * Added: Initial implementation with support to Sidekiq and Faktory backends

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lepus (0.1.3)
+    lepus (0.2.0)
       base64
       bunny
       concurrent-ruby

data/docs/configuration.md

@@ -28,6 +28,19 @@ end
 | `recovery_attempts` | `10` | Max automatic reconnects; `nil` for infinite |
 | `recover_from_connection_close` | `true` | Auto-recover after a clean close |
 
+### Named connections
+
+Producers can publish to more than one broker. Register extra brokers by name; `rabbitmq_url` stays the `:default` connection and remains the only one used by consumers, the supervisor, the process registry and the web dashboard.
+
+```ruby
+Lepus.configure do |config|
+  config.rabbitmq_url = ENV.fetch('RABBITMQ_URL')
+  config.connection(:replica, url: ENV.fetch('REPLICA_RABBITMQ_URL'), recovery_attempts: 3)
+end
+```
+
+`url:` is required and must not be blank. Extra keyword arguments are Bunny session options and override the global ones for that connection only; a `connection_name:` given here is used as-is instead of the generated label. The name `:default` is reserved. Publishing through a name that was never registered raises `Lepus::InvalidConnectionError`. See [producers.md](producers.md#named-connections).
+
 ## Application metadata
 
 ```ruby
@@ -72,7 +85,7 @@ Assign consumers to a named worker via their own `configure(process: { name: :hi
 
 ## Producer pool
 
-Producers share a connection pool:
+Producers share a connection pool per named connection (see [Named connections](#named-connections)); every pool uses these settings:
 
 ```ruby
 config.producer do |p|

data/docs/producers.md

@@ -30,7 +30,8 @@ OrdersProducer.publish(
 ```ruby
 configure(
   exchange: { name: 'orders', type: :topic, durable: true },
-  publish:  { persistent: true, mandatory: false }
+  publish:  { persistent: true, mandatory: false },
+  connection: :default
 )
 ```
 
@@ -38,6 +39,7 @@ configure(
 |-----|---------|
 | `exchange` | String (name only) or hash (`name`, `type`, `durable`, `auto_delete`). Auto-declared on first publish. |
 | `publish` | Default publish options merged into every `publish` call: `persistent`, `mandatory`, `content_type`, `expiration`, etc. |
+| `connection` | Named connection to publish through. Defaults to `:default` (`rabbitmq_url`). See [Named connections](#named-connections). |
 
 ## Publishing
 
@@ -119,7 +121,7 @@ OrdersProducer.order_created(order)
 
 ## Connection pooling
 
-Producers share a single connection pool across the process:
+Producers share one connection pool per named connection across the process:
 
 ```ruby
 Lepus.configure do |config|
@@ -130,6 +132,32 @@ Lepus.configure do |config|
 end
 ```
 
+## Named connections
+
+Register extra brokers in the configuration (see [configuration.md](configuration.md#named-connections)):
+
+```ruby
+Lepus.configure do |config|
+  config.connection(:replica, url: ENV.fetch('REPLICA_RABBITMQ_URL'))
+end
+```
+
+Then choose the connection per producer or per call. The per-call value wins, then the one in `configure`, then `:default`:
+
+```ruby
+class AuditProducer < Lepus::Producer
+  configure(exchange: 'audit', connection: :replica)
+end
+
+OrdersProducer.publish(payload, routing_key: 'order.created')                       # :default
+OrdersProducer.publish(payload, routing_key: 'order.created', connection: :replica) # :replica
+AuditProducer.publish(payload)                                                      # :replica
+```
+
+`connection` is never sent to Bunny as a publish option. Each connection gets its own lazily created pool, so a broker that is down only affects the publishes routed to it. An unregistered name raises `Lepus::InvalidConnectionError`.
+
+The low-level publisher takes the same option: `Lepus::Publisher.new('audit', connection: :replica)`.
+
 ## Enable / disable publishing
 
 Useful when you want to disable side effects in tests or a specific environment.

data/docs/testing.md

@@ -89,6 +89,14 @@ end
 
 `producer_messages(ProducerClass)` returns an array of hashes with `:payload`, `:routing_key`, `:delivery_info`, `:metadata`.
 
+Each fake message also records the named connection it was published through:
+
+```ruby
+Lepus::Testing.exchange('orders').find_messages(connection: :replica)
+```
+
+The connection may be given as a symbol or a string. Publishing through a connection that was never registered with `config.connection` raises `Lepus::InvalidConnectionError`, as it does outside of fake mode.
+
 ## RSpec matchers
 
 ```ruby

data/gemfiles/Gemfile.rails-5.2.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    lepus (0.1.3)
+    lepus (0.2.0)
       base64
       bunny
       concurrent-ruby

data/gemfiles/Gemfile.rails-6.1.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    lepus (0.1.3)
+    lepus (0.2.0)
       base64
       bunny
       concurrent-ruby

data/gemfiles/Gemfile.rails-7.2.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    lepus (0.1.3)
+    lepus (0.2.0)
       base64
       bunny
       concurrent-ruby

data/gemfiles/Gemfile.rails-8.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    lepus (0.1.3)
+    lepus (0.2.0)
       base64
       bunny
       concurrent-ruby

data/lib/lepus/configuration.rb

@@ -8,6 +8,7 @@ module Lepus
     DEFAULT_RECOVERY_INTERVAL = 5.0
     DEFAULT_RECOVER_FROM_CONNECTION_CLOSE = true
     DEFAULT_CONSUMERS_DIRECTORY = Pathname.new("app/consumers")
+    DEFAULT_CONNECTION = :default
 
     # @return [String] the connection string for RabbitMQ.
     attr_accessor :rabbitmq_url
@@ -93,17 +94,48 @@ module Lepus
       Web::ManagementAPI.new(base_url: management_api_url)
     end
 
+    # Registers a named RabbitMQ connection that producers can publish through.
+    # The :default connection is reserved and always uses {#rabbitmq_url}.
+    # @param name [Symbol, String] the connection name
+    # @param url [String] the connection string for RabbitMQ
+    # @param options [Hash] Bunny session options overriding the global ones
+    # @return [Hash] the connection settings
+    def connection(name, url:, **options)
+      name = name.to_sym
+      raise ArgumentError, "The #{DEFAULT_CONNECTION.inspect} connection is configured through rabbitmq_url" if name == DEFAULT_CONNECTION
+      raise ArgumentError, "The #{name.inspect} connection requires a url" if url.to_s.strip.empty?
+
+      connections[name] = options.merge(url: url)
+    end
+
+    # @return [Hash{Symbol => Hash}] the named connections registered via {#connection}
+    def connections
+      @connections ||= {}
+    end
+
+    # @param name [Symbol, String, nil] the connection name
+    # @return [Boolean] whether the connection is the default one or a registered named connection
+    def connection?(name)
+      name = (name || DEFAULT_CONNECTION).to_sym
+      name == DEFAULT_CONNECTION || connections.key?(name)
+    end
+
     # @param suffix [String] the suffix to add to the connection name
+    # @param connection [Symbol, String] the named connection to open, :default uses {#rabbitmq_url}
     # @return [Bunny::Session] the connection to RabbitMQ
-    def create_connection(suffix: nil)
-      kwargs = connection_config
-
-      if suffix && connection_name
-        kwargs[:connection_name] = "#{connection_name} #{suffix}"
+    # @raise [Lepus::InvalidConnectionError] when the connection name is not registered
+    def create_connection(suffix: nil, connection: DEFAULT_CONNECTION)
+      name = (connection || DEFAULT_CONNECTION).to_sym
+      url, options = connection_settings(name)
+      kwargs = connection_config.merge(options)
+
+      if connection_name && !options.key?(:connection_name)
+        label = [suffix, (name == DEFAULT_CONNECTION) ? nil : "(#{name})"].compact.join(" ")
+        kwargs[:connection_name] = "#{connection_name} #{label}" unless label.empty?
       end
 
       ::Bunny
-        .new(rabbitmq_url, **kwargs)
+        .new(url, **kwargs)
         .tap { |conn| conn.start }
     end
 
@@ -174,6 +206,15 @@ module Lepus
 
     protected
 
+    def connection_settings(name)
+      return [rabbitmq_url, {}] if name == DEFAULT_CONNECTION
+
+      settings = connections.fetch(name) do
+        raise Lepus::InvalidConnectionError, "Unknown connection #{name.inspect}. Register it with Lepus.config.connection(#{name.inspect}, url: ...)"
+      end
+      [settings[:url], settings.reject { |key, _| key == :url }]
+    end
+
     def connection_config
       {
         connection_name: connection_name,

data/lib/lepus/connection_pool.rb

@@ -9,12 +9,13 @@ module Lepus
     DEFAULT_SIZE = 5
     DEFAULT_TIMEOUT = 5.0
 
-    attr_reader :pool_size, :timeout, :conn_suffix
+    attr_reader :pool_size, :timeout, :conn_suffix, :conn_name
 
-    def initialize(size: DEFAULT_SIZE, timeout: DEFAULT_TIMEOUT, suffix: nil)
+    def initialize(size: DEFAULT_SIZE, timeout: DEFAULT_TIMEOUT, suffix: nil, connection: Lepus::Configuration::DEFAULT_CONNECTION)
       @pool_size = size
       @timeout = timeout
       @conn_suffix = suffix
+      @conn_name = connection
       @available = Concurrent::Array.new
       @in_use = Concurrent::Array.new
       @semaphore = Concurrent::Semaphore.new(pool_size)
@@ -62,7 +63,7 @@ module Lepus
       end
 
       # Create a new connection
-      connection = Lepus.config.create_connection(suffix: @conn_suffix)
+      connection = Lepus.config.create_connection(suffix: @conn_suffix, connection: @conn_name)
       @mutex.with_write_lock do
         @in_use << connection
       end

data/lib/lepus/producer.rb

@@ -35,6 +35,7 @@ module Lepus
       # @param [Hash] opts The options to configure the producer with.
       # @option opts [String, Hash] :exchange The name of the exchange to publish to.
       # @option opts [Hash] :publish Default publish options (persistent, mandatory, immediate).
+      # @option opts [Symbol] :connection The named connection to publish through. Defaults to :default.
       # @yield [definition] Optional block to further configure the producer.
       # @yieldparam [Lepus::Producers::Definition] definition The definition object.
       # @return [Lepus::Producers::Definition] The configured producer definition.
@@ -42,6 +43,7 @@ module Lepus
         raise ArgumentError, "Cannot configure an abstract class" if abstract_class?
 
         @definition = Producers::Definition.new(opts)
+        @publishers = nil
         yield(@definition) if block_given?
         @definition
       end
@@ -54,10 +56,13 @@ module Lepus
         descendants.uniq
       end
 
-      # Creates a publisher instance configured with this producer's settings.
+      # Returns a publisher configured with this producer's settings, memoized per connection.
+      # @param connection [Symbol, String, nil] The named connection. Defaults to the configured one.
       # @return [Lepus::Publisher] A publisher instance ready to send messages.
-      def publisher
-        @publisher ||= Publisher.new(definition.exchange_name, **definition.exchange_options)
+      def publisher(connection = nil)
+        name = (connection || definition.connection).to_sym
+        @publishers ||= {}
+        @publishers[name] ||= Publisher.new(definition.exchange_name, connection: name, **definition.exchange_options)
       end
 
       # Returns the middleware chain for this producer.
@@ -79,9 +84,11 @@ module Lepus
       # Executes the middleware chain (global + per-producer) before publishing.
       #
       # @param payload [String, Hash] The message payload to publish.
+      # @param connection [Symbol, String, nil] The named connection to publish through,
+      #   overriding the one set in {.configure}.
       # @param options [Hash] Additional publish options (routing_key, headers, etc.).
       # @return [void]
-      def publish(payload, **options)
+      def publish(payload, connection: nil, **options)
         if definition.nil?
           raise InvalidProducerConfigError, <<~ERROR
             The #{name} producer is not configured.
@@ -99,7 +106,7 @@ module Lepus
         )
 
         combined_chain.execute(message) do |msg|
-          publisher.publish(msg.payload, **msg.to_publish_options)
+          publisher(connection).publish(msg.payload, **msg.to_publish_options)
         end
       end
 
@@ -142,8 +149,8 @@ module Lepus
 
     attr_reader :definition
 
-    def publisher
-      @publisher ||= Publisher.new(definition.exchange_name, **definition.exchange_options)
+    def publisher(connection = nil)
+      self.class.publisher(connection)
     end
 
     def publish(message, **options)

data/lib/lepus/producers/config.rb

@@ -1,23 +1,27 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module Lepus
   module Producers
     # Configuration class for producer settings
     class Config
-      extend Forwardable
-
       DEFAULT_POOL_SIZE = 1
       DEFAULT_POOL_TIMEOUT = 5.0
 
       attr_accessor :pool_size, :pool_timeout
 
-      def_delegator :connection_pool, :with_connection
-
       def initialize
         @pool_size = DEFAULT_POOL_SIZE
         @pool_timeout = DEFAULT_POOL_TIMEOUT
+        @connection_pools = {}
+        @connection_pools_mutex = Mutex.new
+      end
+
+      # Checks out a connection from the pool of the given named connection.
+      # @param name [Symbol, String] the connection name, :default uses Lepus.config.rabbitmq_url
+      # @yieldparam connection [Bunny::Session]
+      # @raise [Lepus::InvalidConnectionError] when the connection name is not registered
+      def with_connection(name = Lepus::Configuration::DEFAULT_CONNECTION, &block)
+        connection_pool(name).with_connection(&block)
       end
 
       # Assign multiple attributes at once from a hash of options.
@@ -33,13 +37,22 @@ module Lepus
 
       private
 
+      # @param name [Symbol, String] the connection name
       # @return [Lepus::ConnectionPool] a connection pool instance configured for producers
-      def connection_pool
-        @connection_pool ||= Lepus::ConnectionPool.new(
-          size: pool_size,
-          timeout: pool_timeout,
-          suffix: "producer"
-        )
+      def connection_pool(name = Lepus::Configuration::DEFAULT_CONNECTION)
+        name = (name || Lepus::Configuration::DEFAULT_CONNECTION).to_sym
+        unless name == Lepus::Configuration::DEFAULT_CONNECTION || Lepus.config.connection?(name)
+          raise Lepus::InvalidConnectionError, "Unknown connection #{name.inspect}"
+        end
+
+        @connection_pools_mutex.synchronize do
+          @connection_pools[name] ||= Lepus::ConnectionPool.new(
+            size: pool_size,
+            timeout: pool_timeout,
+            suffix: "producer",
+            connection: name
+          )
+        end
       end
     end
   end

data/lib/lepus/producers/definition.rb

@@ -4,7 +4,7 @@ module Lepus
   module Producers
     # Definition class for producer-specific settings
     class Definition
-      attr_reader :publish_options
+      attr_reader :publish_options, :connection
 
       def initialize(options = {})
         opts = Lepus::Primitive::Hash.new(options).deep_symbolize_keys
@@ -16,6 +16,8 @@ module Lepus
         # Handle default publish options
         @publish_options = Lepus::Publisher::DEFAULT_PUBLISH_OPTIONS.merge(opts.delete(:publish) || {})
 
+        @connection = (opts.delete(:connection) || Lepus::Configuration::DEFAULT_CONNECTION).to_sym
+
         # Store any remaining options for future use
         @options = opts
       end

data/lib/lepus/publisher.rb

@@ -15,17 +15,22 @@ module Lepus
     }.freeze
 
     # @param exchange_name [String] The name of the exchange to publish messages to.
+    # @param connection [Symbol, String] The named connection to publish through.
     # @param options [Hash] Additional options for the exchange (type, durable, auto_delete).
     # @return [void]
-    def initialize(exchange_name, **options)
+    def initialize(exchange_name, connection: Lepus::Configuration::DEFAULT_CONNECTION, **options)
       @exchange_name = exchange_name
+      @connection = (connection || Lepus::Configuration::DEFAULT_CONNECTION).to_sym
       @exchange_options = DEFAULT_EXCHANGE_OPTIONS.merge(options)
     end
 
+    # @return [Symbol] the named connection this publisher uses
+    attr_reader :connection
+
     def publish(message, **options)
       return unless Producers.exchange_enabled?(exchange_name)
 
-      Lepus.config.producer_config.with_connection do |connection|
+      Lepus.config.producer_config.with_connection(connection) do |connection|
         connection.with_channel do |channel|
           channel_publish(channel, message, **options)
         end

data/lib/lepus/testing/exchange.rb

@@ -45,6 +45,8 @@ module Lepus
               message[:routing_key] == value
             when :payload
               message[:payload] == value
+            when :connection
+              message[:connection] == value&.to_sym
             when :headers
               message[:headers]&.any? { |k, v| value.any? { |vk, vv| k == vk && v == vv } }
             else

data/lib/lepus/testing.rb

@@ -158,6 +158,10 @@ module Lepus
             return unless Lepus::Producers.exchange_enabled?(exchange_name)
 
             if Lepus::Testing.fake_publisher_enabled?
+              unless Lepus.config.connection?(connection)
+                raise Lepus::InvalidConnectionError, "Unknown connection #{connection.inspect}"
+              end
+
               return fake_publish(message, **options)
             end
 
@@ -186,6 +190,7 @@ module Lepus
 
             fake_message = {
               exchange: exchange_name,
+              connection: connection,
               payload: message, # Store the original message, not the JSON string
               routing_key: opts[:routing_key],
               headers: opts[:headers],

data/lib/lepus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lepus
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/lepus.rb

@@ -56,6 +56,10 @@ module Lepus
   class InvalidProducerConfigError < Error
   end
 
+  # Error that is raised when a named connection is not registered.
+  class InvalidConnectionError < Error
+  end
+
   class ShutdownError < Error
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lepus
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Marcos G. Zimmermann
 autorequire:
 bindir: exec
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64