ruby_reactor 0.1.0

data/lib/ruby_reactor/executor.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "executor/input_validator"
+require_relative "executor/graph_manager"
+require_relative "executor/retry_manager"
+require_relative "executor/compensation_manager"
+require_relative "executor/result_handler"
+require_relative "executor/step_executor"
+
+module RubyReactor
+  class Executor
+    attr_reader :reactor_class, :context, :dependency_graph, :compensation_manager, :retry_manager, :result_handler,
+                :step_executor, :result
+
+    def initialize(reactor_class, inputs = {}, context = nil)
+      @reactor_class = reactor_class
+      @context = context || Context.new(inputs, reactor_class)
+      @dependency_graph = DependencyGraph.new
+      @compensation_manager = CompensationManager.new(@context)
+      @retry_manager = RetryManager.new(@context)
+      @result_handler = ResultHandler.new(
+        context: @context,
+        compensation_manager: @compensation_manager,
+        dependency_graph: @dependency_graph
+      )
+      @step_executor = StepExecutor.new(
+        context: @context,
+        dependency_graph: @dependency_graph,
+        reactor_class: @reactor_class,
+        managers: {
+          retry_manager: @retry_manager,
+          result_handler: @result_handler,
+          compensation_manager: @compensation_manager
+        }
+      )
+      @result = nil
+    end
+
+    def execute
+      input_validator = InputValidator.new(@reactor_class, @context)
+      input_validator.validate!
+
+      graph_manager = GraphManager.new(@reactor_class, @dependency_graph, @context)
+      graph_manager.build_and_validate!
+
+      @result = @step_executor.execute_all_steps
+    rescue StandardError => e
+      @result = @result_handler.handle_execution_error(e)
+    end
+
+    def resume_execution
+      prepare_for_resume
+
+      if @context.current_step
+        execute_current_step_and_continue
+      else
+        execute_remaining_steps
+      end
+    rescue StandardError => e
+      handle_resume_error(e)
+    end
+
+    def undo_stack
+      @compensation_manager.undo_stack
+    end
+
+    def undo_trace
+      @compensation_manager.undo_trace
+    end
+
+    def execution_trace
+      @context.execution_trace
+    end
+
+    private
+
+    def prepare_for_resume
+      # Build dependency graph and mark completed steps
+      graph_manager = GraphManager.new(@reactor_class, @dependency_graph, @context)
+      graph_manager.build_and_validate!
+      graph_manager.mark_completed_steps_from_context
+    end
+
+    def execute_current_step_and_continue
+      step_config = @reactor_class.steps[@context.current_step]
+      return RubyReactor::Failure("Step '#{@context.current_step}' not found in reactor") unless step_config
+
+      # Use execute_step (not execute_step_with_retry) so that async steps can be handled properly in inline mode
+      result = @step_executor.execute_step(step_config)
+
+      # execute_step returns nil for inline async, meaning continue execution
+      if result.nil?
+        @result = @step_executor.execute_all_steps
+      else
+        case result
+        when RetryQueuedResult, RubyReactor::Failure, RubyReactor::AsyncResult
+          # Step was requeued, failed, or handed off to async - return the result
+          @result = result
+        when RubyReactor::Success
+          # Step succeeded, continue with remaining steps
+          @result = @step_executor.execute_all_steps
+        end
+      end
+      @result
+    end
+
+    def execute_remaining_steps
+      @result = @step_executor.execute_all_steps
+      @result
+    end
+
+    def handle_resume_error(error)
+      # Only handle errors that haven't already triggered compensation
+      # StepFailureError means compensation already happened, just convert to Failure
+      @result = if error.is_a?(Error::StepFailureError)
+                  RubyReactor.Failure(error.message)
+                else
+                  @result_handler.handle_execution_error(error)
+                end
+      @result
+    end
+  end
+end

data/lib/ruby_reactor/map/collector.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Map
+    class Collector
+      extend Helpers
+
+      # rubocop:disable Metrics/MethodLength
+      def self.perform(arguments)
+        arguments = arguments.transform_keys(&:to_sym)
+        parent_context_id = arguments[:parent_context_id]
+        map_id = arguments[:map_id]
+        parent_reactor_class_name = arguments[:parent_reactor_class_name]
+        step_name = arguments[:step_name]
+        strict_ordering = arguments[:strict_ordering]
+
+        storage = RubyReactor.configuration.storage_adapter
+
+        # Retrieve parent context
+        parent_context = load_parent_context_from_storage(
+          parent_context_id,
+          parent_reactor_class_name,
+          storage
+        )
+
+        # Retrieve results
+        serialized_results = storage.retrieve_map_results(map_id, parent_reactor_class_name,
+                                                          strict_ordering: strict_ordering)
+
+        results = serialized_results.map do |r|
+          if r.is_a?(Hash) && r.key?("_error")
+            RubyReactor::Failure(r["_error"])
+          else
+            RubyReactor::Success(r)
+          end
+        end
+
+        # Get step config to check for collect block and other options
+        parent_class = Object.const_get(parent_reactor_class_name)
+        step_config = parent_class.steps[step_name.to_sym]
+
+        collect_block = step_config.arguments[:collect_block][:source].value
+        # TODO: Check allow_partial_failure option
+
+        final_result = if collect_block
+                         begin
+                           # Pass all results (Success and Failure) to collect block
+                           collected = collect_block.call(results)
+                           RubyReactor::Success(collected)
+                         rescue StandardError => e
+                           RubyReactor::Failure(e)
+                         end
+                       else
+                         # Default behavior: fail if any failure
+                         first_failure = results.find(&:failure?)
+                         first_failure || RubyReactor::Success(results.map(&:value))
+                       end
+
+        # Resume execution
+        resume_parent_execution(parent_context, step_name, final_result, storage)
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/ruby_reactor/map/element_executor.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Map
+    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.map_metadata = arguments
+          reactor_class = context.reactor_class
+        else
+          # Deserialize inputs
+          inputs = ContextSerializer.deserialize_value(serialized_inputs)
+
+          # Resolve reactor class
+          reactor_class = resolve_reactor_class(reactor_class_info)
+
+          # Create context
+          context = Context.new(inputs, reactor_class)
+          context.map_metadata = arguments
+        end
+        storage = RubyReactor.configuration.storage_adapter
+
+        # Execute
+        executor = Executor.new(reactor_class, {}, context)
+
+        if serialized_context
+          executor.resume_execution
+        else
+          executor.execute
+        end
+
+        result = executor.result
+
+        if result.is_a?(RetryQueuedResult)
+          queue_next_batch(arguments) if batch_size
+          return
+        end
+
+        # Store result
+
+        # Store result
+
+        if result.success?
+          storage.store_map_result(map_id, index, result.value, parent_reactor_class_name,
+                                   strict_ordering: strict_ordering)
+        else
+          # Store error
+          storage.store_map_result(map_id, index, { _error: result.error }, parent_reactor_class_name,
+                                   strict_ordering: strict_ordering)
+        end
+
+        # Decrement counter
+        new_count = storage.decrement_map_counter(map_id, parent_reactor_class_name)
+
+        queue_next_batch(arguments) if batch_size
+
+        return unless new_count.zero?
+
+        # Trigger collection
+        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
+        )
+      end
+
+      def self.queue_next_batch(arguments)
+        storage = RubyReactor.configuration.storage_adapter
+        map_id = arguments[:map_id]
+        reactor_class_name = arguments[:parent_reactor_class_name]
+
+        next_index = storage.increment_last_queued_index(map_id, reactor_class_name)
+        total_count = storage.retrieve_map_metadata(map_id, reactor_class_name)["count"]
+
+        return unless next_index < total_count
+
+        parent_context = load_parent_context(arguments, reactor_class_name, storage)
+        element = resolve_next_element(arguments, parent_context, next_index)
+        serialized_inputs = build_serialized_inputs(arguments, parent_context, element)
+
+        queue_element_job(arguments, map_id, next_index, serialized_inputs, reactor_class_name)
+      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
+
+      def self.resolve_next_element(arguments, parent_context, next_index)
+        parent_reactor_class = parent_context.reactor_class
+        step_config = parent_reactor_class.steps[arguments[:step_name].to_sym]
+
+        source_template = step_config.arguments[:source][:source]
+        source = source_template.resolve(parent_context)
+        source[next_index]
+      end
+
+      def self.build_serialized_inputs(arguments, parent_context, element)
+        parent_reactor_class = parent_context.reactor_class
+        step_config = parent_reactor_class.steps[arguments[:step_name].to_sym]
+
+        mappings_template = step_config.arguments[:argument_mappings][:source]
+        mappings = mappings_template.resolve(parent_context) || {}
+
+        mapped_inputs = build_element_inputs(mappings, parent_context, element)
+        ContextSerializer.serialize_value(mapped_inputs)
+      end
+
+      def self.queue_element_job(arguments, map_id, next_index, serialized_inputs, reactor_class_name)
+        RubyReactor.configuration.async_router.perform_map_element_async(
+          map_id: map_id,
+          element_id: "#{map_id}:#{next_index}",
+          index: next_index,
+          serialized_inputs: 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: reactor_class_name,
+          step_name: arguments[:step_name],
+          batch_size: arguments[:batch_size]
+        )
+      end
+      private_class_method :queue_next_batch, :load_parent_context,
+                           :resolve_next_element, :build_serialized_inputs, :queue_element_job
+    end
+  end
+end

data/lib/ruby_reactor/map/execution.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Map
+    class Execution
+      extend Helpers
+
+      def self.perform(arguments)
+        arguments = arguments.transform_keys(&:to_sym)
+        storage = RubyReactor.configuration.storage_adapter
+
+        parent_context = load_parent_context_from_storage(
+          arguments[:parent_context_id], arguments[:parent_reactor_class_name], storage
+        )
+        reactor_class = resolve_reactor_class(arguments[:reactor_class_info])
+        inputs = ContextSerializer.deserialize_value(arguments[:serialized_inputs])
+
+        results = execute_all_elements(
+          source: inputs[:source], mappings: inputs[:mappings],
+          reactor_class: reactor_class, parent_context: parent_context,
+          storage_options: {
+            map_id: arguments[:map_id], storage: storage,
+            parent_reactor_class_name: arguments[:parent_reactor_class_name],
+            strict_ordering: arguments[:strict_ordering]
+          }
+        )
+
+        finalize_execution(results, parent_context, arguments[:step_name], arguments[:parent_reactor_class_name],
+                           storage)
+      end
+
+      def self.execute_all_elements(source:, mappings:, reactor_class:, parent_context:, storage_options:)
+        source.map.with_index do |element, index|
+          element_inputs = build_element_inputs(mappings, parent_context, element)
+          result = reactor_class.run(element_inputs)
+
+          store_result(result, index, storage_options)
+
+          result
+        end
+      end
+
+      def self.store_result(result, index, options)
+        value = result.success? ? result.value : { _error: result.error }
+        options[:storage].store_map_result(
+          options[:map_id], index, value, options[:parent_reactor_class_name],
+          strict_ordering: options[:strict_ordering]
+        )
+      end
+
+      def self.finalize_execution(results, parent_context, step_name, parent_reactor_class_name, storage)
+        step_config = Object.const_get(parent_reactor_class_name).steps[step_name.to_sym]
+        final_result = apply_collect_block(results, step_config)
+        resume_parent_execution(parent_context, step_name, final_result, storage)
+      end
+
+      private_class_method :execute_all_elements, :store_result, :finalize_execution
+    end
+  end
+end

data/lib/ruby_reactor/map/helpers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Map
+    # Shared helper methods for Map executors
+    module Helpers
+      # Resolves the reactor class from reactor_class_info
+      def resolve_reactor_class(info)
+        if info["type"] == "class"
+          Object.const_get(info["name"])
+        elsif info["type"] == "inline"
+          parent_class = Object.const_get(info["parent"])
+          step_config = parent_class.steps[info["step"].to_sym]
+          step_config.arguments[:mapped_reactor_class][:source].value
+        else
+          raise "Unknown reactor class info: #{info}"
+        end
+      end
+
+      # Loads parent context from storage
+      def load_parent_context_from_storage(parent_context_id, reactor_class_name, storage)
+        parent_context_data = storage.retrieve_context(parent_context_id, reactor_class_name)
+        RubyReactor::Context.deserialize_from_retry(parent_context_data)
+      end
+
+      # Builds mapped inputs for a single element
+      def build_element_inputs(mappings, parent_context, element)
+        RubyReactor::Step::MapStep.build_mapped_inputs(mappings, parent_context, element)
+      end
+
+      # Applies collect block to results
+      def apply_collect_block(results, step_config)
+        collect_block = step_config.arguments[:collect_block][:source].value
+
+        if collect_block
+          # Pass all results (Success and Failure) to collect block
+          begin
+            collected = collect_block.call(results)
+            RubyReactor::Success(collected)
+          rescue StandardError => e
+            RubyReactor::Failure(e)
+          end
+        else
+          # Default behavior: fail if any failure
+          first_failure = results.find(&:failure?)
+          first_failure || RubyReactor::Success(results.map(&:value))
+        end
+      end
+
+      # Resumes parent reactor execution after map completion
+      def resume_parent_execution(parent_context, step_name, final_result, storage)
+        value = final_result.success? ? final_result.value : final_result
+        parent_context.set_result(step_name.to_sym, value)
+        parent_context.current_step = nil
+
+        executor = RubyReactor::Executor.new(parent_context.reactor_class, {}, parent_context)
+        executor.resume_execution
+
+        storage.store_context(
+          parent_context.context_id,
+          ContextSerializer.serialize(parent_context),
+          parent_context.reactor_class.name
+        )
+      end
+    end
+  end
+end

data/lib/ruby_reactor/max_retries_exhausted_failure.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class MaxRetriesExhaustedFailure < Failure
+    attr_reader :attempts, :original_error
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(message, step:, attempts:, original_error: nil,
+                   inputs: {}, backtrace: nil, redact_inputs: [],
+                   reactor_name: nil, step_arguments: {})
+      # rubocop:enable Metrics/ParameterLists
+      super(message,
+            step_name: step, inputs: inputs, backtrace: backtrace,
+            redact_inputs: redact_inputs, reactor_name: reactor_name, step_arguments: step_arguments)
+      @attempts = attempts
+      @original_error = original_error
+    end
+  end
+end

data/lib/ruby_reactor/reactor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Reactor
+    include RubyReactor::Dsl::Reactor
+
+    attr_reader :context, :result, :undo_trace, :execution_trace
+
+    def initialize(context = {})
+      @context = context
+      @result = :unexecuted
+      @undo_trace = []
+      @execution_trace = []
+    end
+
+    def run(inputs = {})
+      if self.class.async?
+        # For async reactors, enqueue the job and return immediately
+        context = Context.new(inputs, self.class)
+        serialized_context = ContextSerializer.serialize(context)
+        configuration.async_router.perform_async(serialized_context)
+      else
+        # For sync reactors (potentially with async steps), execute normally
+        executor = Executor.new(self.class, inputs)
+        @result = executor.execute
+
+        @context = executor.context
+
+        @undo_trace = executor.undo_trace
+        @execution_trace = executor.execution_trace
+
+        # If execution returned an AsyncResult (from step-level async), return it
+        return @result if @result.is_a?(RubyReactor::AsyncResult)
+
+        @result
+      end
+    end
+
+    def validate!
+      # Validate reactor configuration
+      validate_steps!
+      validate_return_step!
+      validate_dependencies!
+    end
+
+    private
+
+    def configuration
+      RubyReactor::Configuration.instance
+    end
+
+    def validate_steps!
+      return unless self.class.steps.empty?
+
+      raise Error::ValidationError, "Reactor must have at least one step"
+    end
+
+    def validate_return_step!
+      return unless self.class.return_step
+
+      return if self.class.steps.key?(self.class.return_step)
+
+      raise Error::ValidationError, "Return step '#{self.class.return_step}' is not defined"
+    end
+
+    def validate_dependencies!
+      graph = DependencyGraph.new
+      self.class.steps.each_value { |config| graph.add_step(config) }
+
+      return unless graph.has_cycles?
+
+      raise Error::DependencyError, "Dependency graph contains cycles"
+    end
+  end
+end

data/lib/ruby_reactor/retry_context.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Tracks retry attempts and state for steps in async execution
+  class RetryContext
+    attr_accessor :step_attempts, :current_step, :failure_reason, :next_retry_at
+
+    def initialize
+      @step_attempts = {}
+      @current_step = nil
+      @failure_reason = nil
+      @next_retry_at = nil
+    end
+
+    def increment_attempt_for_step(step_name)
+      step_name = step_name.to_s
+      @step_attempts[step_name] ||= 0
+      @step_attempts[step_name] += 1
+    end
+
+    def attempts_for_step(step_name)
+      step_name = step_name.to_s
+      @step_attempts[step_name] || 0
+    end
+
+    def can_retry_step?(step_name, max_attempts)
+      attempts = attempts_for_step(step_name)
+      attempts < max_attempts
+    end
+
+    def reset
+      @step_attempts = {}
+      @current_step = nil
+      @failure_reason = nil
+      @next_retry_at = nil
+    end
+
+    def serialize_for_retry
+      {
+        step_attempts: @step_attempts,
+        current_step: @current_step,
+        failure_reason: serialize_error(@failure_reason),
+        next_retry_at: @next_retry_at&.iso8601
+      }
+    end
+
+    def self.deserialize_from_retry(data)
+      context = new
+      context.step_attempts = data["step_attempts"] || {}
+      context.current_step = data["current_step"]
+      context.failure_reason = deserialize_error(data["failure_reason"])
+      context.next_retry_at = data["next_retry_at"] ? Time.iso8601(data["next_retry_at"]) : nil
+      context
+    end
+
+    def self.calculate_backoff_delay(attempt_number, backoff_strategy, base_delay)
+      case backoff_strategy
+      when :exponential
+        base_delay * (2**(attempt_number - 1))
+      when :linear
+        base_delay * attempt_number
+      when :fixed
+        base_delay
+      else
+        raise ArgumentError, "Unknown backoff strategy: #{backoff_strategy}"
+      end
+    end
+
+    private
+
+    def serialize_error(error)
+      return nil unless error
+
+      {
+        class: error.class.name,
+        message: error.message,
+        backtrace: error.backtrace
+      }
+    end
+
+    def self.deserialize_error(data)
+      return nil unless data
+
+      error_class = data["class"] ? Object.const_get(data["class"]) : StandardError
+      error = error_class.new(data["message"])
+      error.set_backtrace(data["backtrace"]) if data["backtrace"]
+      error
+    end
+
+    private_class_method :deserialize_error
+  end
+end

data/lib/ruby_reactor/retry_queued_result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Result returned when a step retry has been queued for async execution
+  class RetryQueuedResult
+    attr_reader :step_name, :attempt_number, :next_retry_at
+
+    def initialize(step_name, attempt_number, next_retry_at)
+      @step_name = step_name
+      @attempt_number = attempt_number
+      @next_retry_at = next_retry_at
+    end
+
+    def retry_queued?
+      true
+    end
+
+    def success?
+      false
+    end
+
+    def failure?
+      false
+    end
+  end
+end

data/lib/ruby_reactor/sidekiq_workers/map_collector_worker.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module SidekiqWorkers
+    class MapCollectorWorker
+      include ::Sidekiq::Worker
+
+      def perform(arguments)
+        RubyReactor::Map::Collector.perform(arguments)
+      end
+    end
+  end
+end