harmoniser 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9feb1146437db2d23bb56ef1a72e47ef0912dbbc02b776c2ef026db44dc687e
-  data.tar.gz: 79dfe110ea228ba5ae58062c575768c8cc5747228a7a4a5432c36a686da7113d
+  metadata.gz: 71c030f6ce0d93a7e9bb55a88c3d3cad300f4ab05809944e08442d2bca43cafb
+  data.tar.gz: da8f3f99f2a9846b35b10a8e986f28e53087a81d2a1a6fd149778e3d82222de1
 SHA512:
-  metadata.gz: 47e94a951a8200b1e2ce2287f4fad5d4dda4ac6d4bf4d4e21a7f0bb03a51c8d95a949f0ef8dccc1f873558741ece21a0de89198d0d4325228869b0ad985d098a
-  data.tar.gz: d7d11b42621ce764702a408a3c1f789326cef84dfa15ad24d6f8c84ba5b2cd28ce4f4ca1496fd38bfc1aedb1a0d89381adf19825c76ef6d310389173782a03bd
+  metadata.gz: 0774eab4d7682a72e880e764acdb55e05e6e9d10048bbdb3e74ed010293d6dc8c416d9de9d73c3a6752e3c9d1ace45d70dc212a3cc01fb2a33b77d4a494d56d2
+  data.tar.gz: 2eebe48b9779d08b0e516d13daa9f94b358f851de3999d4ca0ee600cab89ae48396bdd351ff583bc9be566e44f113f2fe14c0ef59ce3378d5fe1f35d88802c83

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [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/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

@@ -7,7 +7,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
@@ -21,6 +21,7 @@ module Harmoniser
         connection
           .create_channel(nil, consumer_pool_size, false, consumer_pool_shutdown_timeout)
           .tap do |channel|
+            channel.cancel_consumers_before_closing!
             attach_callbacks(channel)
           end
       end
@@ -45,12 +46,12 @@ module Harmoniser
         end
 
         stringified_attributes = attributes.map { |k, v| "#{k} = `#{v}`" }.join(", ")
-        Harmoniser.logger.error("Default on_error handler executed for channel: #{stringified_attributes}")
+        Harmoniser.logger.warn("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}`")
+        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)
@@ -62,6 +63,10 @@ module Harmoniser
 
         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
 
     class << self

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/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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harmoniser
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Jose Lloret
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-22 00:00:00.000000000 Z
+date: 2025-05-19 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:
@@ -48,6 +48,7 @@ files:
 - 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
@@ -68,7 +69,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 +85,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: []