ruby_reactor 0.4.1 → 0.5.1

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,21 +43,56 @@ module RubyReactor
       @acquired_semaphore = nil
     end
 
-    def execute
-      skipped = check_period_gate
-      if skipped
-        @result = skipped
-        update_context_status(@result)
-        save_context
-        return @result
+    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
 
-      check_rate_limit
-      acquire_locks
+    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
 
+      if (skipped = check_period_gate)
+        completed = true
+        return finalize_skipped(skipped)
+      end
+
+      # Validate inputs BEFORE consuming a rate-limit slot or grabbing a
+      # lock/semaphore: a run that can never start must not burn quota or
+      # briefly block other callers.
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
 
+      acquire_locks_with_telemetry
+
+      # Re-check the period gate now that we hold the lock. The pre-lock check
+      # is a fast path; this one closes the race where two callers both passed
+      # it and then serialized on the lock — without it the second caller would
+      # re-run work the first already marked. (No-op when no lock is configured.)
+      if (skipped = check_period_gate)
+        completed = true
+        return finalize_skipped(skipped)
+      end
+
       @context.status = :running
       save_context
 
@@ -64,49 +104,91 @@ 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,
-           RubyReactor::RateLimit::ExceededError => e
+           RubyReactor::RateLimit::ExceededError,
+           RubyReactor::RateLimitRegistry::UnknownLimitError => e
       raise e
     rescue StandardError => e
       @result = @result_handler.handle_execution_error(e)
       update_context_status(@result)
+      completed = true
       @result
     ensure
       release_locks
       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
+    def resume_execution # rubocop:disable Metrics/MethodLength
+      middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
+      completed = false
+      # A fresh async reactor run reaches the worker through resume_execution
+      # (it never calls execute), so the period and rate-limit gates that live
+      # in execute must be applied here too. Genuine resumes (a step already ran
+      # or we paused mid-flight, so current_step is set) must NOT re-gate: a
+      # paused reactor must not throttle or skip itself on the way back in.
+      first_run = first_execution?
+      begin
+        @context.status = :running
 
-      @result = if @context.current_step
-                  execute_current_step_and_continue
-                else
-                  execute_remaining_steps
-                end
+        if first_run && (skipped = check_period_gate)
+          completed = true
+          return finalize_skipped(skipped)
+        end
+        check_rate_limit if first_run
 
-      update_context_status(@result)
-      mark_period_on_success(@result)
+        acquire_concurrency_primitives
 
-      handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
+        # Post-lock re-check (see execute) — closes the period race for the
+        # first run of a locked async reactor.
+        if first_run && (skipped = check_period_gate)
+          completed = true
+          return finalize_skipped(skipped)
+        end
 
-      @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
+        prepare_for_resume
+        save_context
+
+        @result = if @context.current_step
+                    execute_current_step_and_continue
+                  else
+                    execute_remaining_steps
+                  end
+
+        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,
+             RubyReactor::RateLimitRegistry::UnknownLimitError
+        raise
+      rescue StandardError => e
+        handle_resume_error(e)
+        update_context_status(@result)
+        completed = true
+        @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
@@ -143,26 +225,64 @@ module RubyReactor
     private
 
     def acquire_locks
+      check_rate_limit
+      acquire_concurrency_primitives
+    end
+
+    def acquire_concurrency_primitives
       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
-    # never re-check (a paused reactor must not block itself on resume).
+    # hint) if any window is full. Consulted on the first execution only —
+    # `execute` for sync reactors, the first `resume_execution` pass for async
+    # reactors. Genuine resumes never re-check (a paused reactor must not block
+    # itself on resume).
     def check_rate_limit
       return unless @reactor_class.respond_to?(:rate_limit_config) && @reactor_class.rate_limit_config
 
       config = @reactor_class.rate_limit_config
-      key_base = config[:key_proc].call(@context.inputs)
 
-      RubyReactor::RateLimit.new(key_base, limits: config[:limits]).check_and_increment!
+      if config[:name]
+        # Named global limit: the name is the shared key base and the windows
+        # come from the registry (resolved lazily so config order doesn't matter).
+        key_base = config[:name].to_s
+        limits = RubyReactor.configuration.rate_limits.fetch(config[:name])
+      else
+        key_base = config[:key_proc].call(@context.inputs)
+        limits = config[:limits]
+      end
+
+      RubyReactor::RateLimit.new(key_base, limits: limits).check_and_increment!
+    end
+
+    # True when nothing has run yet for this context — the very first execution
+    # of the reactor, including an async reactor's first worker pass. A genuine
+    # resume (paused, async-handed-off, or retried step) always records a
+    # `current_step` before serializing, so it is never mistaken for a first run.
+    def first_execution?
+      @context.current_step.nil? && @context.intermediate_results.empty?
+    end
+
+    # Record and persist a Skipped result, then return it. Shared by the
+    # pre-lock and post-lock period gates in both execute and resume.
+    def finalize_skipped(skipped)
+      @result = skipped
+      update_context_status(@result)
+      save_context
+      @result
     end
 
     # Returns a Skipped result if the period bucket is already marked, else nil.
-    # Only consulted on initial `execute`; resumes never re-check (a paused run
-    # must not skip itself when its own marker eventually appears).
+    # Consulted before AND after lock acquisition on a first execution; genuine
+    # resumes never re-check (a paused run must not skip itself when its own
+    # marker eventually appears).
     def check_period_gate
       return nil unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
 
@@ -202,8 +322,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
@@ -212,8 +338,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
@@ -226,13 +358,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)
@@ -332,4 +470,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