harmoniser 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9feb1146437db2d23bb56ef1a72e47ef0912dbbc02b776c2ef026db44dc687e
-  data.tar.gz: 79dfe110ea228ba5ae58062c575768c8cc5747228a7a4a5432c36a686da7113d
+  metadata.gz: 3a7c3ac5b97ffe50dee2438808e152133893642092fee47a74e49f31e5440686
+  data.tar.gz: 156dbce5e8ba12711085e55d2a2b6f823259946d0df42d6cccd7bd29aeba0139
 SHA512:
-  metadata.gz: 47e94a951a8200b1e2ce2287f4fad5d4dda4ac6d4bf4d4e21a7f0bb03a51c8d95a949f0ef8dccc1f873558741ece21a0de89198d0d4325228869b0ad985d098a
-  data.tar.gz: d7d11b42621ce764702a408a3c1f789326cef84dfa15ad24d6f8c84ba5b2cd28ce4f4ca1496fd38bfc1aedb1a0d89381adf19825c76ef6d310389173782a03bd
+  metadata.gz: 3c14b5e163b0d3863ae1e25db3dc7aaec5ac6debacfe6cb0148066b5154156619b3692a7ea1e72d03d27e407a6366ad93c879476e04e606f864522ba56ffec59
+  data.tar.gz: 546204550ed925fac2e177240ec3266a25d61d81d9034019f76653588af7141c797be2ed42d576000cb7de72699843333b59cfafdb3d50a80a7a31a9596e1172

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.14.0] - 2025-11-25
+
+### Added
+- Introduce Mock functionality for testing without RabbitMQ dependency. Usage:
+
+```ruby
+require "harmoniser/mock"
+Harmoniser::Mock.mock!
+
+# Your Publisher/Subscriber code works the same but without RabbitMQ
+class TestPublisher
+  include Harmoniser::Publisher
+  harmoniser_publisher exchange_name: "my_exchange"
+end
+
+exchange = TestPublisher.publish("message", routing_key: "test")
+published_messages = exchange.published_messages # Access captured messages
+```
+
+- Add examples for mock publishing and topology under `examples/` folder
+- Create Channel wrapper (`Harmoniser::Channel`) to isolate RabbitMQ dependencies
+
+### Changed
+- Remove explicit dependencies to Bunny classes except for Consumer, enabling better RabbitMQ isolation through a single, well-defined interface
+- Use Channel wrapper everywhere except for subscriptions (which still require actual Channel instance for Bunny::Consumer)
+
+
+## [0.13.0] - 2025-05-19
+
+### Added
+- Introduce Harmoniser.configuration#on_error callback to handle errors that occur while running the application, (e.g. when a subscriber raises an error, or when a connection cannot be established to RabbitMQ). This method permits appending as many handlers as needed. Usage:
+
+```ruby
+Harmoniser.configuration do |config|
+  config.on_error do |error, ctx|
+    # error is the exception, i.e. StandardError class raised by the application whereas ctx is the context of the error passed as Hash. The ctx hash contains at least the key `description` which is a string describing the error.
+
+    puts "An error occurred: exception = `#{error.detailed_message}`; description = `#{ctx[:description]}`"
+  end
+end
+```
+
+### Changed
+- Update Bunny to the latest version, i.e., 2.24
+- Delegate into Bunny::Channel to cancel consumers and close channel through
+Channel#cancel_consumers_before_closing!
+- Change severity level from error to warning for errors occurring at channel level
+
+
 ## [0.12.0] - 2024-12-22
 
 ### Changed

data/harmoniser.gemspec

@@ -24,5 +24,5 @@ Gem::Specification.new do |spec|
   spec.executables = ["harmoniser"]
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "bunny", "~> 2.23"
+  spec.add_runtime_dependency "bunny", "~> 2.24"
 end

data/lib/harmoniser/channel.rb

@@ -0,0 +1,66 @@
+require "forwardable"
+
+module Harmoniser
+  class Channel
+    extend Forwardable
+
+    def_delegators :@bunny_channel,
+      :exchange,
+      :queue,
+      :queue_bind
+
+    attr_reader :bunny_channel
+
+    def initialize(bunny_channel)
+      @bunny_channel = bunny_channel
+      after_initialize
+    end
+
+    private
+
+    def after_initialize
+      bunny_channel.cancel_consumers_before_closing!
+      attach_callbacks
+    end
+
+    def attach_callbacks
+      bunny_channel.on_error(&method(:on_error_callback).to_proc)
+      bunny_channel.on_uncaught_exception(&method(:on_uncaught_exception_callback).to_proc)
+    end
+
+    def on_error_callback(channel, amq_method)
+      attributes = {
+        amq_method: amq_method,
+        exchanges: channel.exchanges.keys,
+        queues: channel.consumers.values.map(&:queue)
+      }
+
+      if amq_method.is_a?(AMQ::Protocol::Channel::Close)
+        attributes[:reply_code] = amq_method.reply_code
+        attributes[:reply_text] = amq_method.reply_text
+      end
+
+      stringified_attributes = attributes.map { |k, v| "#{k} = `#{v}`" }.join(", ")
+      Harmoniser.logger.warn("Default on_error handler executed for channel: #{stringified_attributes}")
+      maybe_kill_process(amq_method)
+    end
+
+    def on_uncaught_exception_callback(error, consumer)
+      handle_error(error, {description: "Uncaught exception from consumer", arguments: consumer.arguments, channel_id: consumer.channel.id, consumer_tag: consumer.consumer_tag, exclusive: consumer.exclusive, no_ack: consumer.no_ack, queue: consumer.queue})
+    end
+
+    def maybe_kill_process(amq_method)
+      Process.kill("USR1", Process.pid) if ack_timed_out?(amq_method) && Harmoniser.server?
+    end
+
+    def ack_timed_out?(amq_method)
+      return false unless amq_method.is_a?(AMQ::Protocol::Channel::Close)
+
+      amq_method.reply_text =~ /delivery acknowledgement on channel \d+ timed out/
+    end
+
+    def handle_error(exception, ctx)
+      Harmoniser.configuration.handle_error(exception, ctx)
+    end
+  end
+end

data/lib/harmoniser/configuration.rb

@@ -1,5 +1,6 @@
 require "forwardable"
 require "harmoniser/connection"
+require "harmoniser/error_handler"
 require "harmoniser/topology"
 require "harmoniser/options"
 
@@ -7,14 +8,16 @@ module Harmoniser
   class Configuration
     extend Forwardable
 
-    attr_reader :logger, :options
+    attr_reader :error_handler, :logger, :options
     def_delegators :options, :concurrency, :environment, :require, :verbose, :timeout
+    def_delegators :error_handler, :handle_error, :on_error
 
     def initialize
       @logger = Harmoniser.logger
-      @options = Options.new(**default_options)
+      @options = Options.new
       set_logger_severity
       @topology = Topology.new
+      @error_handler = ErrorHandler.default
     end
 
     def connection_opts
@@ -40,16 +43,6 @@ module Harmoniser
 
     private
 
-    def default_options
-      {
-        concurrency: Float::INFINITY,
-        environment: ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "production")),
-        require: ".",
-        timeout: 25,
-        verbose: false
-      }
-    end
-
     def set_logger_severity
       @logger.level = @options.verbose? ? Logger::DEBUG : Logger::INFO
     end

data/lib/harmoniser/connectable.rb

@@ -1,4 +1,5 @@
 require "harmoniser/connection"
+require "harmoniser/channel"
 
 module Harmoniser
   module Connectable
@@ -7,7 +8,7 @@ module Harmoniser
     module ClassMethods
       def connection(configuration = Harmoniser.configuration)
         MUTEX.synchronize do
-          @connection ||= Connection.new(configuration.connection_opts)
+          @connection ||= Connection.new(configuration.connection_opts, error_handler: configuration.error_handler)
           @connection.start unless @connection.open? || @connection.recovering_from_network_failure?
           @connection
         end
@@ -20,47 +21,7 @@ module Harmoniser
       def create_channel(consumer_pool_size: 1, consumer_pool_shutdown_timeout: 60)
         connection
           .create_channel(nil, consumer_pool_size, false, consumer_pool_shutdown_timeout)
-          .tap do |channel|
-            attach_callbacks(channel)
-          end
-      end
-
-      private
-
-      def attach_callbacks(channel)
-        channel.on_error(&method(:on_error).to_proc)
-        channel.on_uncaught_exception(&method(:on_uncaught_exception).to_proc)
-      end
-
-      def on_error(channel, amq_method)
-        attributes = {
-          amq_method: amq_method,
-          exchanges: channel.exchanges.keys,
-          queues: channel.consumers.values.map(&:queue)
-        }
-
-        if amq_method.is_a?(AMQ::Protocol::Channel::Close)
-          attributes[:reply_code] = amq_method.reply_code
-          attributes[:reply_text] = amq_method.reply_text
-        end
-
-        stringified_attributes = attributes.map { |k, v| "#{k} = `#{v}`" }.join(", ")
-        Harmoniser.logger.error("Default on_error handler executed for channel: #{stringified_attributes}")
-        maybe_kill_process(amq_method)
-      end
-
-      def on_uncaught_exception(error, consumer)
-        Harmoniser.logger.error("Default on_uncaught_exception handler executed for channel: error_class = `#{error.class}`, error_message = `#{error.message}`, error_backtrace = `#{error.backtrace&.first(5)}, queue = `#{consumer.queue}`")
-      end
-
-      def maybe_kill_process(amq_method)
-        Process.kill("USR1", Process.pid) if ack_timed_out?(amq_method) && Harmoniser.server?
-      end
-
-      def ack_timed_out?(amq_method)
-        return false unless amq_method.is_a?(AMQ::Protocol::Channel::Close)
-
-        amq_method.reply_text =~ /delivery acknowledgement on channel \d+ timed out/
+          .yield_self { |bunny_channel| Channel.new(bunny_channel) }
       end
     end
 

data/lib/harmoniser/connection.rb

@@ -1,5 +1,6 @@
 require "forwardable"
 require "bunny"
+require "harmoniser/error_handler"
 
 module Harmoniser
   class Connection
@@ -21,7 +22,8 @@ module Harmoniser
 
     def_delegators :@bunny, :create_channel, :open?, :recovering_from_network_failure?
 
-    def initialize(opts, logger: Harmoniser.logger)
+    def initialize(opts, error_handler: ErrorHandler.default, logger: Harmoniser.logger)
+      @error_handler = error_handler
       @logger = logger
       @bunny = Bunny.new(maybe_dynamic_opts(opts)).tap do |bunny|
         attach_callbacks(bunny)
@@ -43,7 +45,7 @@ module Harmoniser
       begin
         @bunny.start
       rescue => e
-        @logger.error("Connection attempt failed: retries = `#{retries}`, error_class = `#{e.class}`, error_message = `#{e.message}`")
+        handle_error(e, {description: "Connection attempt failed", retries: retries})
         sleep(1)
         retries += 1
         retry
@@ -56,7 +58,7 @@ module Harmoniser
         @logger.info("Connection closed: connection = `#{self}`")
       end
     rescue => e
-      @logger.error("Connection#close failed: error_class = `#{e.class}`, error_message = `#{e.message}`")
+      handle_error(e, {description: "Connection close failed"})
       false
     end
 
@@ -102,5 +104,9 @@ module Harmoniser
     def vhost
       @bunny.vhost
     end
+
+    def handle_error(exception, ctx)
+      @error_handler.handle_error(exception, ctx)
+    end
   end
 end

data/lib/harmoniser/error_handler.rb

@@ -0,0 +1,51 @@
+module Harmoniser
+  class ErrorHandler
+    TIMEOUT = 25
+    DEFAULT_ERROR_HANDLER = ->(exception, ctx) do
+      Harmoniser.logger.error("Error handler called: exception = `#{exception.detailed_message}`, context = `#{ctx}`")
+    end
+
+    class << self
+      def default
+        @default ||= new([DEFAULT_ERROR_HANDLER])
+      end
+    end
+
+    def initialize(handlers = [])
+      @handlers = handlers
+    end
+
+    def on_error(handler = nil, &block)
+      h = handler || block
+      raise ArgumentError, "Please, provide a handler or a block" if h.nil?
+      raise TypeError, "Handler must respond to call" unless h.respond_to?(:call)
+
+      @handlers << h
+      self
+    end
+
+    def handle_error(exception, ctx = {})
+      coordinator = Thread::Queue.new
+
+      Thread.new do
+        handlers
+          .each { |handler| trigger_handler(handler, exception, ctx) }
+          .tap { coordinator.push(true) }
+      end.tap do |thread|
+        thread.report_on_exception = true
+      end
+
+      !!coordinator.pop(timeout: TIMEOUT)
+    end
+
+    private
+
+    attr_reader :handlers
+
+    def trigger_handler(handler, exception, ctx)
+      handler.call(exception, ctx)
+    rescue => e
+      warn "An error occurred while handling a previous error: #{e.detailed_message}"
+    end
+  end
+end

data/lib/harmoniser/launcher/base.rb

@@ -61,15 +61,13 @@ module Harmoniser
       def maybe_close_subscriber
         return unless Subscriber.connection?
 
-        maybe_cancel_subscribers
+        report_subscribers_to_cancel
         report_work_pool
         Subscriber.connection.close
       end
 
-      def maybe_cancel_subscribers
+      def report_subscribers_to_cancel
         @logger.info("Subscribers will be cancelled from queues: klasses = `#{@subscribers}`")
-        @subscribers.each(&:harmoniser_subscriber_stop)
-        @logger.info("Subscribers cancelled: klasses = `#{@subscribers}`")
       end
 
       def report_work_pool

data/lib/harmoniser/launcher/bounded.rb

@@ -12,7 +12,7 @@ module Harmoniser
       end
 
       def channel
-        @channel ||= Subscriber.create_channel(consumer_pool_size: @configuration.concurrency, consumer_pool_shutdown_timeout: @configuration.timeout)
+        @channel ||= Subscriber.create_channel(consumer_pool_size: @configuration.concurrency, consumer_pool_shutdown_timeout: @configuration.timeout).bunny_channel
       end
     end
   end

data/lib/harmoniser/mock/channel.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Harmoniser
+  module Mock
+    class Channel
+      class MockExchange
+        attr_reader :name, :type, :opts
+
+        def initialize(name, opts = {})
+          @name = name
+          @type = opts[:type]
+          @opts = opts.except(:type)
+          @published_messages = []
+          @return_handler = nil
+        end
+
+        def publish(payload, opts = {})
+          @published_messages << {payload: payload, opts: opts}
+          true
+        end
+
+        def on_return(&block)
+          @return_handler = block
+          self
+        end
+
+        def published_messages
+          @published_messages.dup
+        end
+
+        def reset!
+          @published_messages.clear
+          @return_handler = nil
+        end
+      end
+
+      class MockQueue
+        attr_reader :name, :opts
+
+        def initialize(name, opts = {})
+          @name = name
+          @opts = opts
+        end
+      end
+
+      def initialize
+        @exchanges = {}
+        @queues = {}
+        @bindings = []
+      end
+
+      def exchange(name, opts = {})
+        @exchanges[name] ||= MockExchange.new(name, opts)
+      end
+
+      def queue(name, opts = {})
+        @queues[name] ||= MockQueue.new(name, opts)
+      end
+
+      def queue_bind(destination_name, exchange_name, opts = {})
+        @bindings << {
+          destination_name: destination_name,
+          exchange_name: exchange_name,
+          opts: opts
+        }
+        true
+      end
+
+      def exchanges
+        @exchanges.dup
+      end
+
+      def queues
+        @queues.dup
+      end
+
+      def bindings
+        @bindings.dup
+      end
+
+      def reset!
+        @exchanges.clear
+        @queues.clear
+        @bindings.clear
+      end
+
+      def bunny_channel
+        raise "Cannot access bunny_channel in mock mode. Mock mode is intended for testing only and cannot be used when running Harmoniser as a server process."
+      end
+    end
+  end
+end

data/lib/harmoniser/mock/connection.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "harmoniser/mock/channel"
+
+module Harmoniser
+  module Mock
+    class Connection
+      def initialize(opts = {}, error_handler: nil, logger: nil)
+        @opts = opts
+        @error_handler = error_handler
+        @logger = logger
+        @open = false
+      end
+
+      def create_channel(id = nil, consumer_pool_size = 1, consumer_pool_ack = false, consumer_pool_shutdown_timeout = 60)
+        Channel.new
+      end
+
+      def open?
+        @open
+      end
+
+      def recovering_from_network_failure?
+        false
+      end
+
+      def start
+        @open = true
+        self
+      end
+
+      def close
+        @open = false
+        true
+      end
+    end
+  end
+end

data/lib/harmoniser/mock.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "harmoniser/mock/connection"
+require "harmoniser/mock/channel"
+require "harmoniser/connectable"
+
+module Harmoniser
+  module Mock
+    @mocked = false
+    @prepended = false
+
+    class << self
+      def mock!
+        unless @prepended
+          @prepended = true
+          Harmoniser::Connectable::ClassMethods.prepend(MockConnectableMethods)
+        end
+        @mocked = true
+      end
+
+      def disable!
+        @mocked = false
+      end
+
+      def mocked?
+        @mocked
+      end
+
+      def disabled?
+        !@mocked
+      end
+    end
+
+    module MockConnectableMethods
+      def connection(configuration = Harmoniser.configuration)
+        return super unless Harmoniser::Mock.mocked?
+
+        Harmoniser::Connectable::MUTEX.synchronize do
+          @mock_connection ||= Harmoniser::Mock::Connection.new(configuration.connection_opts, error_handler: configuration.error_handler)
+          @mock_connection.start unless @mock_connection.open? || @mock_connection.recovering_from_network_failure?
+          @mock_connection
+        end
+      end
+
+      def connection?
+        return super unless Harmoniser::Mock.mocked?
+        !!defined?(@mock_connection)
+      end
+
+      def create_channel(consumer_pool_size: 1, consumer_pool_shutdown_timeout: 60)
+        return super unless Harmoniser::Mock.mocked?
+        connection.create_channel(nil, consumer_pool_size, false, consumer_pool_shutdown_timeout)
+      end
+    end
+  end
+end

data/lib/harmoniser/options.rb

@@ -1,5 +1,21 @@
 module Harmoniser
-  Options = Data.define(:concurrency, :environment, :require, :verbose, :timeout) do
+  class Options < Data.define(:concurrency, :environment, :require, :verbose, :timeout)
+    DEFAULT = {
+      concurrency: -> { Float::INFINITY },
+      environment: -> { ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "production")) },
+      require: -> { "." },
+      timeout: -> { 25 },
+      verbose: -> { false }
+    }.freeze
+
+    def initialize(**kwargs)
+      options = DEFAULT
+        .map { |k, v| [k, v.call] }
+        .to_h
+        .merge(kwargs)
+      super(**options)
+    end
+
     def production?
       environment == "production"
     end

data/lib/harmoniser/publisher.rb

@@ -33,12 +33,12 @@ module Harmoniser
       end
 
       def create_exchange
-        exchange = Bunny::Exchange.new(
-          Publisher.create_channel,
-          @harmoniser_exchange_definition.type,
-          @harmoniser_exchange_definition.name,
-          @harmoniser_exchange_definition.opts
-        )
+        exchange = Publisher
+          .create_channel
+          .exchange(
+            @harmoniser_exchange_definition.name,
+            {type: @harmoniser_exchange_definition.type}.merge(@harmoniser_exchange_definition.opts)
+          )
         handle_return(exchange)
         exchange
       end

data/lib/harmoniser/subscriber.rb

@@ -41,7 +41,7 @@ module Harmoniser
       def create_consumer(channel)
         raise_missing_consumer_definition unless @harmoniser_consumer_definition
 
-        ch = channel || Subscriber.create_channel
+        ch = channel || Subscriber.create_channel.bunny_channel
         consumer = Bunny::Consumer.new(
           ch,
           @harmoniser_consumer_definition.queue_name,

data/lib/harmoniser/topology.rb

@@ -5,7 +5,7 @@ module Harmoniser
   class Topology
     include Connectable
 
-    attr_reader :bindings, :exchanges, :queues
+    attr_reader :bindings, :exchanges, :queues, :declared_channel
 
     def initialize
       @bindings = Set.new
@@ -41,25 +41,26 @@ module Harmoniser
     end
 
     def declare
-      self.class.create_channel.tap do |ch|
+      @declared_channel = self.class.create_channel.tap do |ch|
         declare_exchanges(ch)
         declare_queues(ch)
         declare_bindings(ch)
-        ch.connection.close
       end
+      self.class.connection.close
+      self
     end
 
     private
 
     def declare_exchanges(channel)
       exchanges.each do |exchange|
-        Bunny::Exchange.new(channel, exchange.type, exchange.name, exchange.opts)
+        channel.exchange(exchange.name, {type: exchange.type}.merge(exchange.opts))
       end
     end
 
     def declare_queues(channel)
       queues.each do |queue|
-        Bunny::Queue.new(channel, queue.name, queue.opts)
+        channel.queue(queue.name, queue.opts)
       end
     end
 

data/lib/harmoniser/version.rb

@@ -1,3 +1,3 @@
 module Harmoniser
-  VERSION = "0.12.0"
+  VERSION = "0.14.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harmoniser
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Jose Lloret
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-22 00:00:00.000000000 Z
+date: 2025-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.23'
+        version: '2.24'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.23'
+        version: '2.24'
 description: A declarative approach to communication with RabbitMQ that simplifies
   the integration of publishing and consuming messages.
 email:
@@ -42,17 +42,22 @@ files:
 - bin/setup
 - harmoniser.gemspec
 - lib/harmoniser.rb
+- lib/harmoniser/channel.rb
 - lib/harmoniser/cli.rb
 - lib/harmoniser/configurable.rb
 - lib/harmoniser/configuration.rb
 - lib/harmoniser/connectable.rb
 - lib/harmoniser/connection.rb
 - lib/harmoniser/definition.rb
+- lib/harmoniser/error_handler.rb
 - lib/harmoniser/launcher.rb
 - lib/harmoniser/launcher/base.rb
 - lib/harmoniser/launcher/bounded.rb
 - lib/harmoniser/launcher/unbounded.rb
 - lib/harmoniser/loggable.rb
+- lib/harmoniser/mock.rb
+- lib/harmoniser/mock/channel.rb
+- lib/harmoniser/mock/connection.rb
 - lib/harmoniser/options.rb
 - lib/harmoniser/parser.rb
 - lib/harmoniser/publisher.rb
@@ -68,7 +73,7 @@ metadata:
   homepage_uri: https://github.com/jollopre/harmoniser
   source_code_uri: https://github.com/jollopre/harmoniser
   changelog_uri: https://github.com/jollopre/harmoniser/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -84,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.4.10
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A minimalistic approach to interact with RabbitMQ
 test_files: []