ruby_reactor 0.3.0 → 0.3.2

data/lib/ruby_reactor/executor.rb

@@ -34,12 +34,26 @@ module RubyReactor
         }
       )
       @result = nil
+      @acquired_lock = nil
+      @acquired_semaphore = nil
     end
 
     def execute
+      skipped = check_period_gate
+      if skipped
+        @result = skipped
+        update_context_status(@result)
+        save_context
+        return @result
+      end
+
+      check_rate_limit
+      acquire_locks
+
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
 
+      @context.status = :running
       save_context
 
       graph_manager = GraphManager.new(@reactor_class, @dependency_graph, @context)
@@ -48,17 +62,25 @@ module RubyReactor
 
       @result = @step_executor.execute_all_steps
       update_context_status(@result)
+      mark_period_on_success(@result)
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
       @result
+    rescue RubyReactor::Lock::AcquisitionError,
+           RubyReactor::Semaphore::AcquisitionError,
+           RubyReactor::RateLimit::ExceededError => e
+      raise e
     rescue StandardError => e
       @result = @result_handler.handle_execution_error(e)
       update_context_status(@result)
       @result
     ensure
+      release_locks
       save_context
     end
 
     def resume_execution
+      @context.status = :running
+      acquire_locks
       prepare_for_resume
       save_context
 
@@ -69,15 +91,21 @@ module RubyReactor
                 end
 
       update_context_status(@result)
+      mark_period_on_success(@result)
 
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
 
       @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
     end
 
@@ -108,29 +136,127 @@ module RubyReactor
 
     private
 
+    def acquire_locks
+      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
+
+    # 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).
+    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!
+    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).
+    def check_period_gate
+      return nil unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
+
+      config = @reactor_class.period_config
+      key = period_key(config)
+      return nil unless RubyReactor.configuration.storage_adapter.period_seen?(key)
+
+      RubyReactor::Skipped.new(reason: :period, period_key: key)
+    end
+
+    def mark_period_on_success(result)
+      return unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
+      return unless result.is_a?(RubyReactor::Success)
+      return if result.is_a?(RubyReactor::Skipped)
+
+      config = @reactor_class.period_config
+      ttl = RubyReactor::Period.ttl_seconds(config[:every])
+      RubyReactor.configuration.storage_adapter.period_mark(period_key(config), ttl)
+    end
+
+    def period_key(config)
+      base = config[:key_proc].call(@context.inputs)
+      RubyReactor::Period.key(base, config[:every])
+    end
+
+    def acquire_exclusive_lock
+      config = @reactor_class.lock_config
+      key = config[:key_proc].call(@context.inputs)
+
+      # Use root context ID as owner to allow re-entrancy across nested reactors
+      owner = (@context.root_context || @context).context_id
+
+      lock = RubyReactor::Lock.new(
+        key,
+        owner: owner,
+        ttl: config[:ttl],
+        wait: contention_wait(config[:wait]),
+        auto_extend: config.fetch(:auto_extend, true)
+      )
+      lock.acquire
+      @acquired_lock = lock
+    end
+
+    def acquire_semaphore
+      config = @reactor_class.semaphore_config
+      key = config[:key_proc].call(@context.inputs)
+      limit = config[:limit]
+
+      semaphore = RubyReactor::Semaphore.new(key, limit: limit, wait: contention_wait(config[:wait]))
+      semaphore.acquire
+      @acquired_semaphore = semaphore
+    end
+
+    # Inside a Sidekiq worker we'd rather snooze the job via perform_in than
+    # tie up the worker thread on a BLPOP / sleep loop. The non-blocking path
+    # fails fast and the Worker rescue branch reschedules.
+    def contention_wait(configured_wait)
+      return 0 if @context.inline_async_execution
+
+      configured_wait
+    end
+
+    def release_locks
+      release_one("semaphore", @acquired_semaphore) if @acquired_semaphore
+      @acquired_semaphore = nil
+
+      return unless @acquired_lock
+
+      release_one("lock", @acquired_lock)
+      @acquired_lock = nil
+    end
+
+    def release_one(kind, primitive)
+      released = primitive.release
+      return if released
+
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor #{kind} '#{primitive.key}' was not held at release time " \
+        "(likely TTL expired or owner changed)"
+      )
+    rescue StandardError => e
+      # Never let release break the ensure chain — log and move on.
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor failed to release #{kind} '#{primitive.key}': #{e.message}"
+      )
+    end
+
     def update_context_status(result)
       return unless result
 
       case result
       when RubyReactor::AsyncResult
         @context.status = :running
+      when RubyReactor::Skipped
+        @context.status = :skipped
       when RubyReactor::Success
         @context.status = :completed
       when RubyReactor::Failure
         @context.status = :failed
-        @context.failure_reason = {
-          message: result.error.is_a?(Exception) ? result.error.message : result.error.to_s,
-          step_name: result.step_name,
-          inputs: result.inputs,
-          backtrace: result.backtrace,
-          reactor_name: result.reactor_name,
-          step_arguments: result.step_arguments,
-          exception_class: result.exception_class,
-          file_path: result.file_path,
-          line_number: result.line_number,
-          code_snippet: result.code_snippet,
-          validation_errors: result.validation_errors
-        }
+        @context.failure_reason = result
       when RubyReactor::InterruptResult
         @context.status = :paused
       end
@@ -158,8 +284,15 @@ module RubyReactor
         @result = @step_executor.execute_all_steps
       else
         case result
-        when RetryQueuedResult, RubyReactor::Failure, RubyReactor::AsyncResult, RubyReactor::InterruptResult
-          # Step was requeued, failed, or handed off to async - return the result
+        # Skipped must be listed before Success (Skipped < Success) so the
+        # halt path wins over the "continue with remaining steps" path.
+        when RubyReactor::Skipped,
+             RetryQueuedResult,
+             RubyReactor::Failure,
+             RubyReactor::AsyncResult,
+             RubyReactor::InterruptResult
+          # Terminal: step was skipped, requeued, failed, paused, or handed
+          # off to async. Return the result as-is.
           @result = result
         when RubyReactor::Success
           # Step succeeded, continue with remaining steps

data/lib/ruby_reactor/lock.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Lock
+    class AcquisitionError < StandardError; end
+
+    # Minimum interval between auto-extend pings; protects very small TTLs.
+    MIN_EXTEND_INTERVAL = 1.0
+
+    attr_reader :key, :owner, :ttl, :wait, :auto_extend
+
+    def initialize(key, owner:, ttl: 60, wait: 0, auto_extend: true)
+      @key = "lock:#{key}"
+      @owner = owner
+      @ttl = ttl
+      @wait = wait
+      @auto_extend = auto_extend
+      @extender = nil
+      @extender_running = false
+    end
+
+    def acquire
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      loop do
+        if adapter.lock_acquire(@key, @owner, @ttl)
+          start_extender if @auto_extend
+          return true
+        end
+
+        if @wait.zero? || (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) >= @wait
+          raise AcquisitionError, "Could not acquire lock '#{@key}' for owner '#{@owner}'"
+        end
+
+        sleep 0.1
+      end
+    end
+
+    def release
+      stop_extender
+      adapter.lock_release(@key, @owner)
+    end
+
+    def synchronize
+      acquire
+      yield
+    ensure
+      release
+    end
+
+    private
+
+    def start_extender
+      return if @extender&.alive?
+
+      interval = [@ttl / 3.0, MIN_EXTEND_INTERVAL].max
+      @extender_running = true
+
+      @extender = Thread.new do
+        while @extender_running
+          sleep interval
+          break unless @extender_running
+
+          begin
+            adapter.lock_extend(@key, @owner, @ttl)
+          rescue StandardError => e
+            RubyReactor.configuration.logger.warn(
+              "Lock auto-extend failed for '#{@key}': #{e.message}"
+            )
+            break
+          end
+        end
+      end
+    end
+
+    def stop_extender
+      @extender_running = false
+      thread = @extender
+      @extender = nil
+      return unless thread
+
+      thread.wakeup if thread.alive?
+      thread.join(0.1)
+    rescue StandardError
+      # Best-effort shutdown; never let extender teardown break release.
+    end
+
+    def adapter
+      RubyReactor.configuration.storage_adapter
+    end
+  end
+end

data/lib/ruby_reactor/map/collector.rb

@@ -29,21 +29,9 @@ module RubyReactor
         # Since map_offset tracks dispatching progress and might exceed count due to batching reservation,
         # we must strictly check against the total count of elements.
         # Check for fail_fast failure FIRST
-        failed_context_id = storage.retrieve_map_failed_context_id(map_id, parent_reactor_class_name)
-        if failed_context_id
-          # Resolve the class of the mapped reactor to retrieve its context
-          reactor_class = resolve_reactor_class(metadata["reactor_class_info"])
-
-          failed_context_data = storage.retrieve_context(failed_context_id, reactor_class.name)
-
-          if failed_context_data
-            failed_context = RubyReactor::Context.deserialize_from_retry(failed_context_data)
-
-            # Resume parent execution (which marks step as failed)
-            resume_parent_execution(parent_context, step_name, RubyReactor::Failure(failed_context.failure_reason),
-                                    storage)
-            return
-          end
+        if (failed_context_id = storage.retrieve_map_failed_context_id(map_id, parent_reactor_class_name))
+          handle_failure(failed_context_id, metadata, storage, parent_context, step_name)
+          return
         end
 
         return if results_count < total_count
@@ -96,6 +84,19 @@ module RubyReactor
           RubyReactor::Success(results)
         end
       end
+
+      def self.handle_failure(failed_context_id, metadata, storage, parent_context, step_name)
+        # Resolve the class of the mapped reactor to retrieve its context
+        reactor_class = resolve_reactor_class(metadata["reactor_class_info"])
+        failed_context_data = storage.retrieve_context(failed_context_id, reactor_class.name)
+
+        return unless failed_context_data
+
+        failed_context = RubyReactor::Context.deserialize_from_retry(failed_context_data)
+        reason = failed_context.failure_reason
+        result = reason.is_a?(RubyReactor::Failure) ? reason : RubyReactor::Failure(reason)
+        resume_parent_execution(parent_context, step_name, result, storage)
+      end
     end
   end
 end

data/lib/ruby_reactor/map/element_executor.rb

@@ -5,151 +5,137 @@ module RubyReactor
     class ElementExecutor
       extend Helpers
 
-      # rubocop:disable Metrics/MethodLength
       def self.perform(arguments)
         arguments = arguments.transform_keys(&:to_sym)
-        map_id = arguments[:map_id]
-        _element_id = arguments[:element_id]
-        index = arguments[:index]
-        serialized_inputs = arguments[:serialized_inputs]
-        reactor_class_info = arguments[:reactor_class_info]
-        strict_ordering = arguments[:strict_ordering]
-        parent_context_id = arguments[:parent_context_id]
-        parent_reactor_class_name = arguments[:parent_reactor_class_name]
-        step_name = arguments[:step_name]
-        batch_size = arguments[:batch_size]
-        # rubocop:enable Metrics/MethodLength
-        serialized_context = arguments[:serialized_context]
 
-        if serialized_context
-          context = ContextSerializer.deserialize(serialized_context)
+        context = hydrate_or_create_context(arguments)
+        storage = RubyReactor.configuration.storage_adapter
+        storage.store_map_element_context_id(arguments[:map_id], context.context_id,
+                                             arguments[:parent_reactor_class_name])
+
+        return if check_fail_fast?(arguments, storage)
+
+        executor = Executor.new(context.reactor_class, {}, context)
+        arguments[:serialized_context] ? executor.resume_execution : executor.execute
+
+        handle_result(executor.result, arguments, context, storage, executor)
+        finalize_execution(arguments, storage)
+      end
+
+      def self.load_parent_context(arguments, reactor_class_name, storage)
+        parent_context_data = storage.retrieve_context(arguments[:parent_context_id], reactor_class_name)
+        parent_reactor_class = Object.const_get(reactor_class_name)
+        parent_context = Context.new(
+          ContextSerializer.deserialize_value(parent_context_data["inputs"]),
+          parent_reactor_class
+        )
+        parent_context.context_id = arguments[:parent_context_id]
+        parent_context
+      end
+
+      # Legacy helpers resolved_next_element, build_serialized_inputs, queue_element_job
+      # are REMOVED as they are no longer used for self-queuing.
+
+      # Basic helper to build inputs for the CURRENT element (still needed for perform)
+      # Wait, perform uses `serialized_inputs` passed to it.
+      # We don't need `build_element_inputs` here?
+      # `perform` uses `params[:serialized_inputs]`.
+      # So we can remove input building helpers too?
+      # Let's check if they are used elsewhere.
+      # `resolve_reactor_class` is used in `perform`.
+      # `build_element_inputs` is likely in Helpers or mixed in?
+
+      # rubocop:disable Style/IdenticalConditionalBranches
+      def self.hydrate_or_create_context(arguments)
+        if arguments[:serialized_context]
+          context = ContextSerializer.deserialize(arguments[:serialized_context])
           context.map_metadata = arguments
-          reactor_class = context.reactor_class
 
-          # Ensure inputs are present (fallback to serialized_inputs if missing from context)
-          if context.inputs.empty? && serialized_inputs
-            context.inputs = ContextSerializer.deserialize_value(serialized_inputs)
+          if context.inputs.empty? && arguments[:serialized_inputs]
+            context.inputs = ContextSerializer.deserialize_value(arguments[:serialized_inputs])
           end
+          context
         else
-          # Deserialize inputs
-          inputs = ContextSerializer.deserialize_value(serialized_inputs)
-
-          # Resolve reactor class
-          reactor_class = resolve_reactor_class(reactor_class_info)
+          inputs = ContextSerializer.deserialize_value(arguments[:serialized_inputs])
+          reactor_class = resolve_reactor_class(arguments[:reactor_class_info])
 
-          # Create context
           context = Context.new(inputs, reactor_class)
-          context.parent_context_id = parent_context_id
+          context.parent_context_id = arguments[:parent_context_id]
           context.map_metadata = arguments
+          context
         end
+      end
+      # rubocop:enable Style/IdenticalConditionalBranches
 
-        storage = RubyReactor.configuration.storage_adapter
-        storage.store_map_element_context_id(map_id, context.context_id, parent_reactor_class_name)
-
-        # Fail Fast Check
-        if arguments[:fail_fast]
-          failed_context_id = storage.retrieve_map_failed_context_id(map_id, parent_reactor_class_name)
-          if failed_context_id
-            # Decrement counter as we are skipping execution
-            new_count = storage.decrement_map_counter(map_id, parent_reactor_class_name)
-            return unless new_count.zero?
+      def self.check_fail_fast?(arguments, storage)
+        return false unless arguments[:fail_fast]
 
-            # Trigger collection if we are the last one (skipped or otherwise)
-            RubyReactor.configuration.async_router.perform_map_collection_async(
-              parent_context_id: parent_context_id,
-              map_id: map_id,
-              parent_reactor_class_name: parent_reactor_class_name,
-              step_name: step_name,
-              strict_ordering: strict_ordering,
-              timeout: 3600
-            )
-            return
-          end
-        end
-
-        # Execute
-        executor = Executor.new(reactor_class, {}, context)
+        map_id = arguments[:map_id]
+        parent_reactor_class_name = arguments[:parent_reactor_class_name]
 
-        if serialized_context
-          executor.resume_execution
-        else
-          executor.execute
-        end
+        failed_context_id = storage.retrieve_map_failed_context_id(map_id, parent_reactor_class_name)
+        return false unless failed_context_id
 
-        result = executor.result
+        # Skip execution
+        finalize_execution(arguments, storage)
+        true
+      end
 
-        if result.is_a?(RetryQueuedResult)
-          trigger_next_batch_if_needed(arguments, index, batch_size)
-          return
-        end
+      def self.handle_result(result, arguments, context, storage, executor)
+        return if result.is_a?(RetryQueuedResult)
 
-        # Store result
+        map_id = arguments[:map_id]
+        index = arguments[:index]
+        parent_class = arguments[:parent_reactor_class_name] # Using short name for variable
 
         if result.success?
-          storage.store_map_result(map_id, index,
-                                   ContextSerializer.serialize_value(result.value),
-                                   parent_reactor_class_name,
-                                   strict_ordering: strict_ordering)
+          storage.store_map_result(map_id, index, ContextSerializer.serialize_value(result.value),
+                                   parent_class, strict_ordering: arguments[:strict_ordering])
         else
-          # Trigger Compensation Logic
           executor.undo_all
-
-          # Store error
-          storage.store_map_result(map_id, index, { _error: result.error }, parent_reactor_class_name,
-                                   strict_ordering: strict_ordering)
+          storage.store_map_result(map_id, index, { _error: result.error }, parent_class,
+                                   strict_ordering: arguments[:strict_ordering])
 
           if arguments[:fail_fast]
-            storage.store_map_failed_context_id(map_id, context.context_id, parent_reactor_class_name)
+            storage.store_map_failed_context_id(map_id, context.context_id, parent_class)
+            # FAST FAIL: Trigger Collector immediately to cancel/fail the map execution
+            RubyReactor.configuration.async_router.perform_map_collection_async(
+              parent_context_id: arguments[:parent_context_id],
+              map_id: map_id,
+              parent_reactor_class_name: parent_class,
+              step_name: arguments[:step_name],
+              strict_ordering: arguments[:strict_ordering],
+              timeout: 3600
+            )
           end
         end
+      end
 
-        # Decrement counter
-        new_count = storage.decrement_map_counter(map_id, parent_reactor_class_name)
+      def self.finalize_execution(arguments, storage)
+        map_id = arguments[:map_id]
+        parent_class = arguments[:parent_reactor_class_name]
 
-        # Trigger next batch if it's the last element of the current batch
-        trigger_next_batch_if_needed(arguments, index, batch_size)
+        new_count = storage.decrement_map_counter(map_id, parent_class)
+        trigger_next_batch_if_needed(arguments, arguments[:index], arguments[:batch_size])
 
         return unless new_count.zero?
 
-        # Trigger collection
         RubyReactor.configuration.async_router.perform_map_collection_async(
-          parent_context_id: parent_context_id,
+          parent_context_id: arguments[:parent_context_id],
           map_id: map_id,
-          parent_reactor_class_name: parent_reactor_class_name,
-          step_name: step_name,
-          strict_ordering: strict_ordering,
+          parent_reactor_class_name: parent_class,
+          step_name: arguments[:step_name],
+          strict_ordering: arguments[:strict_ordering],
           timeout: 3600
         )
       end
 
-      def self.load_parent_context(arguments, reactor_class_name, storage)
-        parent_context_data = storage.retrieve_context(arguments[:parent_context_id], reactor_class_name)
-        parent_reactor_class = Object.const_get(reactor_class_name)
-        parent_context = Context.new(
-          ContextSerializer.deserialize_value(parent_context_data["inputs"]),
-          parent_reactor_class
-        )
-        parent_context.context_id = arguments[:parent_context_id]
-        parent_context
-      end
-
-      # Legacy helpers resolved_next_element, build_serialized_inputs, queue_element_job
-      # are REMOVED as they are no longer used for self-queuing.
-
-      # Basic helper to build inputs for the CURRENT element (still needed for perform)
-      # Wait, perform uses `serialized_inputs` passed to it.
-      # We don't need `build_element_inputs` here?
-      # `perform` uses `params[:serialized_inputs]`.
-      # So we can remove input building helpers too?
-      # Let's check if they are used elsewhere.
-      # `resolve_reactor_class` is used in `perform`.
-      # `build_element_inputs` is likely in Helpers or mixed in?
-
       def self.trigger_next_batch_if_needed(arguments, index, batch_size)
         return unless batch_size && ((index + 1) % batch_size).zero?
 
         # Trigger Dispatcher for next batch
         next_batch_args = arguments.dup
+        # Ensure we don't carry over temporary execution flags if any
         next_batch_args[:continuation] = true
         RubyReactor::Map::Dispatcher.perform(next_batch_args)
       end

data/lib/ruby_reactor/map/execution.rb

@@ -31,6 +31,7 @@ module RubyReactor
       end
 
       def self.execute_all_elements(source:, mappings:, reactor_class:, parent_context:, storage_options:)
+        # rubocop:disable Metrics/BlockLength
         source.map.with_index do |element, index|
           if storage_options[:fail_fast]
             failed_context_id = storage_options[:storage].retrieve_map_failed_context_id(
@@ -71,12 +72,12 @@ module RubyReactor
 
           result
         end.compact
+        # rubocop:enable Metrics/BlockLength
       end
 
       def self.link_contexts(child_context, parent_context)
         child_context.parent_context = parent_context
         child_context.root_context = parent_context.root_context || parent_context
-        child_context.test_mode = parent_context.test_mode
         child_context.inline_async_execution = parent_context.inline_async_execution
       end
 

data/lib/ruby_reactor/map/helpers.rb

@@ -63,7 +63,8 @@ module RubyReactor
             final_result.error,
             step: step_name_sym,
             context: parent_context,
-            original_error: final_result.error.is_a?(Exception) ? final_result.error : nil
+            original_error: final_result.error.is_a?(Exception) ? final_result.error : nil,
+            exception_class: final_result.respond_to?(:exception_class) ? final_result.exception_class : nil
           )
 
           # Pass backtrace if available

data/lib/ruby_reactor/map/result_enumerator.rb

@@ -60,7 +60,7 @@ module RubyReactor
       end
 
       def [](index)
-        return nil if index < 0 || index >= count
+        return nil if index.negative? || index >= count
 
         results = @storage.retrieve_map_results_batch(
           @map_id,