ruby_reactor 0.4.0 → 0.5.0

data/lib/ruby_reactor/executor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "English"
 require_relative "executor/input_validator"
 require_relative "executor/graph_manager"
 require_relative "executor/retry_manager"
@@ -8,16 +9,19 @@ require_relative "executor/result_handler"
 require_relative "executor/step_executor"
 
 module RubyReactor
+  # rubocop:disable Metrics/ClassLength
   class Executor
     attr_reader :reactor_class, :context, :dependency_graph, :compensation_manager, :retry_manager, :result_handler,
-                :step_executor, :result
+                :step_executor, :result, :middlewares
 
     def initialize(reactor_class, inputs = {}, context = nil)
       @reactor_class = reactor_class
       @context = context || Context.new(inputs, reactor_class)
+      @middlewares = Executor.middlewares_for(reactor_class)
+      @context.middlewares = @middlewares
       @dependency_graph = DependencyGraph.new
       @compensation_manager = CompensationManager.new(@context)
-      @retry_manager = RetryManager.new(@context)
+      @retry_manager = RetryManager.new(@context, @middlewares)
       @result_handler = ResultHandler.new(
         context: @context,
         compensation_manager: @compensation_manager,
@@ -30,7 +34,8 @@ module RubyReactor
         managers: {
           retry_manager: @retry_manager,
           result_handler: @result_handler,
-          compensation_manager: @compensation_manager
+          compensation_manager: @compensation_manager,
+          middlewares: @middlewares
         }
       )
       @result = nil
@@ -38,17 +43,44 @@ module RubyReactor
       @acquired_semaphore = nil
     end
 
-    def execute
+    def self.resolve_middlewares(reactor_class)
+      global_list = Array(RubyReactor.configuration.middlewares)
+      reactor_list = if reactor_class.respond_to?(:middlewares)
+                       Array(reactor_class.middlewares)
+                     else
+                       []
+                     end
+
+      (global_list + reactor_list).map do |mw|
+        if mw.is_a?(Class)
+          mw.new
+        elsif mw.is_a?(Array) && mw.first.is_a?(Class)
+          klass, opts = mw
+          klass.new(**(opts || {}))
+        else
+          mw
+        end
+      end
+    end
+
+    def self.middlewares_for(reactor_class)
+      RubyReactor::MiddlewareRunner.new(resolve_middlewares(reactor_class))
+    end
+
+    def execute # rubocop:disable Metrics/MethodLength
+      middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
+      completed = false
+
       skipped = check_period_gate
       if skipped
         @result = skipped
         update_context_status(@result)
         save_context
+        completed = true
         return @result
       end
 
-      check_rate_limit
-      acquire_locks
+      acquire_locks_with_telemetry
 
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
@@ -64,6 +96,7 @@ module RubyReactor
       update_context_status(@result)
       mark_period_on_success(@result)
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
+      completed = true
       @result
     rescue RubyReactor::Lock::AcquisitionError,
            RubyReactor::Semaphore::AcquisitionError,
@@ -72,41 +105,60 @@ module RubyReactor
     rescue StandardError => e
       @result = @result_handler.handle_execution_error(e)
       update_context_status(@result)
+      completed = true
       @result
     ensure
       release_locks
-      save_context
+      save_context if persist_context?
+
+      if completed
+        middlewares.on(:complete_reactor, reactor_class.name, @result, @context)
+      else
+        middlewares.on(:failed_reactor, reactor_class.name, $ERROR_INFO, @context)
+      end
     end
 
     def resume_execution
-      @context.status = :running
-      acquire_locks
-      prepare_for_resume
-      save_context
-
-      @result = if @context.current_step
-                  execute_current_step_and_continue
-                else
-                  execute_remaining_steps
-                end
+      middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
+      completed = false
+      begin
+        @context.status = :running
+        acquire_exclusive_lock if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
+        acquire_semaphore if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
+        prepare_for_resume
+        save_context
 
-      update_context_status(@result)
-      mark_period_on_success(@result)
+        @result = if @context.current_step
+                    execute_current_step_and_continue
+                  else
+                    execute_remaining_steps
+                  end
 
-      handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
+        update_context_status(@result)
+        mark_period_on_success(@result)
+
+        handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
+        completed = true
+        @result
+      rescue RubyReactor::Lock::AcquisitionError,
+             RubyReactor::Semaphore::AcquisitionError,
+             RubyReactor::RateLimit::ExceededError
+        raise
+      rescue StandardError => e
+        handle_resume_error(e)
+        update_context_status(@result)
+        completed = true
+        @result
+      ensure
+        release_locks
+        save_context
 
-      @result
-    rescue RubyReactor::Lock::AcquisitionError,
-           RubyReactor::Semaphore::AcquisitionError,
-           RubyReactor::RateLimit::ExceededError => e
-      raise e
-    rescue StandardError => e
-      handle_resume_error(e)
-      update_context_status(@result)
-      @result
-    ensure
-      release_locks
-      save_context
+        if completed
+          middlewares.on(:complete_reactor, reactor_class.name, @result, @context)
+        else
+          middlewares.on(:failed_reactor, reactor_class.name, $ERROR_INFO, @context)
+        end
+      end
     end
 
     def undo_all
@@ -134,13 +186,24 @@ module RubyReactor
       storage.store_context(@context.context_id, serialized_context, reactor_class_name)
     end
 
+    def persist_context?
+      @context.status.to_s != "pending" ||
+        @context.execution_trace.any? ||
+        @context.intermediate_results.any?
+    end
+
     private
 
     def acquire_locks
+      check_rate_limit
       acquire_exclusive_lock if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
       acquire_semaphore if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
     end
 
+    def acquire_locks_with_telemetry
+      acquire_locks
+    end
+
     # Consume one slot from each configured rate-limit window. Raises
     # `RubyReactor::RateLimit::ExceededError` (carrying a `retry_after_seconds`
     # hint) if any window is full. Only consulted on initial `execute`; resumes
@@ -196,8 +259,14 @@ module RubyReactor
         wait: contention_wait(config[:wait]),
         auto_extend: config.fetch(:auto_extend, true)
       )
-      lock.acquire
-      @acquired_lock = lock
+      begin
+        lock.acquire
+        @acquired_lock = lock
+        middlewares.on(:lock_acquired, key, @context)
+      rescue RubyReactor::Lock::AcquisitionError => e
+        middlewares.on(:lock_failed, key, e, @context)
+        raise
+      end
     end
 
     def acquire_semaphore
@@ -206,8 +275,14 @@ module RubyReactor
       limit = config[:limit]
 
       semaphore = RubyReactor::Semaphore.new(key, limit: limit, wait: contention_wait(config[:wait]))
-      semaphore.acquire
-      @acquired_semaphore = semaphore
+      begin
+        semaphore.acquire
+        @acquired_semaphore = semaphore
+        middlewares.on(:semaphore_acquired, key, limit, @context)
+      rescue RubyReactor::Semaphore::AcquisitionError => e
+        middlewares.on(:semaphore_failed, key, limit, e, @context)
+        raise
+      end
     end
 
     # Inside a Sidekiq worker we'd rather snooze the job via perform_in than
@@ -220,13 +295,19 @@ module RubyReactor
     end
 
     def release_locks
-      release_one("semaphore", @acquired_semaphore) if @acquired_semaphore
+      if @acquired_semaphore
+        key = @acquired_semaphore.key
+        release_one("semaphore", @acquired_semaphore)
+        middlewares.on(:semaphore_released, key, @context)
+      end
       @acquired_semaphore = nil
 
       return unless @acquired_lock
 
+      key = @acquired_lock.key
       release_one("lock", @acquired_lock)
       @acquired_lock = nil
+      middlewares.on(:lock_released, key, @context)
     end
 
     def release_one(kind, primitive)
@@ -326,4 +407,5 @@ module RubyReactor
       )
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/ruby_reactor/map/collector.rb

@@ -59,8 +59,8 @@ module RubyReactor
         # Resume parent execution
         resume_parent_execution(parent_context, step_name, final_result, storage)
       rescue StandardError => e
-        puts "COLLECTOR CRASH: #{e.message}"
-        puts e.backtrace
+        RubyReactor.configuration.logger.error("Map collector crashed: #{e.message}")
+        RubyReactor.configuration.logger.error(e.backtrace.join("\n")) if e.backtrace
         raise e
       end
 
@@ -74,8 +74,8 @@ module RubyReactor
             collected = collect_block.call(results)
             RubyReactor::Success(collected)
           rescue StandardError => e
-            puts "COLLECTOR INNER EXCEPTION: #{e.message}"
-            puts e.backtrace
+            RubyReactor.configuration.logger.error("Map collect block raised: #{e.message}")
+            RubyReactor.configuration.logger.error(e.backtrace.join("\n")) if e.backtrace
             RubyReactor::Failure(e)
           end
         else

data/lib/ruby_reactor/map/element_executor.rb

@@ -9,6 +9,12 @@ module RubyReactor
         arguments = arguments.transform_keys(&:to_sym)
 
         context = hydrate_or_create_context(arguments)
+        # The element already runs inside its own background worker, so any async
+        # steps (and async retries) must execute inline here rather than handing
+        # off to a detached Worker that would escape map result/counter tracking.
+        # This mirrors SidekiqWorkers::Worker, which sets the same flag.
+        context.inline_async_execution = true
+
         storage = RubyReactor.configuration.storage_adapter
         storage.store_map_element_context_id(arguments[:map_id], context.context_id,
                                              arguments[:parent_reactor_class_name])
@@ -18,7 +24,15 @@ module RubyReactor
         executor = Executor.new(context.reactor_class, {}, context)
         arguments[:serialized_context] ? executor.resume_execution : executor.execute
 
-        handle_result(executor.result, arguments, context, storage, executor)
+        result = executor.result
+
+        # An async retry requeued this element as a fresh MapElementWorker job, so
+        # it is not finished yet. Do not store a result, decrement the completion
+        # counter, or trigger the next batch — the requeued job will do that when
+        # the element ultimately succeeds or exhausts its retries.
+        return if result.is_a?(RetryQueuedResult)
+
+        handle_result(result, arguments, context, storage, executor)
         finalize_execution(arguments, storage)
       end
 

data/lib/ruby_reactor/map/helpers.rb

@@ -52,7 +52,7 @@ module RubyReactor
       end
 
       # Resumes parent reactor execution after map completion
-      def resume_parent_execution(parent_context, step_name, final_result, storage)
+      def resume_parent_execution(parent_context, step_name, final_result, storage) # rubocop:disable Metrics/MethodLength
         executor = RubyReactor::Executor.new(parent_context.reactor_class, {}, parent_context)
         step_name_sym = step_name.to_sym
 
@@ -74,9 +74,22 @@ module RubyReactor
             error.set_backtrace(final_result.error.backtrace)
           end
 
-          failure_response = executor.result_handler.handle_execution_error(error)
-          # Manually update context status since we're not running executor loop
-          executor.send(:update_context_status, failure_response)
+          # Bracket the rollback with reactor lifecycle events so that
+          # compensation/undo spans nest under a reactor span (and stay attached
+          # to the originating trace), mirroring the success path's
+          # resume_execution. Without this, rollback runs in the collector worker
+          # with no active reactor span and the undo/compensation spans orphan.
+          executor.middlewares.on(:start_reactor, parent_context.reactor_class.name, parent_context.inputs,
+                                  parent_context)
+          failure_response = nil
+          begin
+            failure_response = executor.result_handler.handle_execution_error(error)
+            # Manually update context status since we're not running executor loop
+            executor.send(:update_context_status, failure_response)
+          ensure
+            executor.middlewares.on(:failed_reactor, parent_context.reactor_class.name, failure_response,
+                                    parent_context)
+          end
         else
           parent_context.set_result(step_name_sym, final_result.value)
 

data/lib/ruby_reactor/middleware.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Base class for all middlewares in RubyReactor.
+  # Middlewares allow hooking into the execution lifecycle of reactors and steps.
+  class Middleware
+    attr_reader :options
+
+    def initialize(**options)
+      @options = options
+    end
+  end
+end

data/lib/ruby_reactor/middleware_runner.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # MiddlewareRunner executes event hooks on a collection of configured middlewares.
+  class MiddlewareRunner
+    def initialize(middlewares)
+      @middlewares = middlewares || []
+    end
+
+    # Dispatches the given lifecycle event to all configured middlewares.
+    # Invokes the specific event hook method if defined, e.g., `on_start_reactor`.
+    # Fallback to the generic `on` method if implemented on the middleware.
+    # StandardErrors are swallowed and logged to prevent middleware failure from halting execution.
+    def on(event, *args)
+      @middlewares.each do |middleware|
+        method_name = "on_#{event}"
+        if middleware.respond_to?(method_name)
+          middleware.send(method_name, *args)
+        elsif middleware.respond_to?(:on)
+          middleware.on(event, *args)
+        end
+      rescue StandardError => e
+        RubyReactor.configuration.logger.warn(
+          "RubyReactor middleware error in #{middleware.class} during #{event}: #{e.message}"
+        )
+      end
+    end
+  end
+end