ruby_reactor 0.3.0 → 0.3.2

data/lib/ruby_reactor/configuration.rb

@@ -7,7 +7,8 @@ module RubyReactor
   class Configuration
     include Singleton
 
-    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router
+    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
+                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
@@ -17,12 +18,28 @@ module RubyReactor
       @sidekiq_retry_count ||= 3
     end
 
+    # Base seconds the Sidekiq worker waits before re-checking a contended lock.
+    def lock_snooze_base_delay
+      @lock_snooze_base_delay ||= 5
+    end
+
+    # Extra random seconds added to the base delay to avoid thundering herd.
+    def lock_snooze_jitter
+      @lock_snooze_jitter ||= 5
+    end
+
+    # How many times a single job can snooze on lock contention before it is
+    # marked as failed. Set to :infinity to never escalate.
+    def lock_snooze_max_attempts
+      @lock_snooze_max_attempts ||= 20
+    end
+
     def logger
       @logger ||= Logger.new($stderr)
     end
 
     def async_router
-      @async_router ||= RubyReactor::AsyncRouter
+      @async_router ||= RubyReactor::SidekiqAdapter
     end
 
     def storage

data/lib/ruby_reactor/context.rb

@@ -3,7 +3,7 @@
 module RubyReactor
   class Context
     attr_accessor :inputs, :intermediate_results, :private_data, :current_step, :retry_count, :concurrency_key,
-                  :retry_context, :reactor_class, :execution_trace, :inline_async_execution, :undo_stack, :test_mode,
+                  :retry_context, :reactor_class, :execution_trace, :inline_async_execution, :undo_stack,
                   :parent_context, :root_context, :composed_contexts, :context_id, :map_operations, :map_metadata,
                   :cancelled, :cancellation_reason, :parent_context_id, :status, :failure_reason
 
@@ -23,7 +23,6 @@ module RubyReactor
       @execution_trace = []
       @inline_async_execution = false # Flag to prevent nested async calls
       @undo_stack = [] # Initialize the undo stack
-      @test_mode = false
       @cancelled = false
       @cancellation_reason = nil
       @status = "pending"
@@ -33,6 +32,14 @@ module RubyReactor
       @root_context = nil
     end
 
+    def finished?
+      %w[completed failed cancelled].include?(@status.to_s)
+    end
+
+    def failed?
+      @status.to_s == "failed"
+    end
+
     def get_input(name, path = nil)
       value = @inputs[name.to_sym] || @inputs[name.to_s]
       return nil if value.nil?
@@ -57,6 +64,10 @@ module RubyReactor
     end
     alias result get_result
 
+    def has_result?(step_name)
+      @intermediate_results.key?(step_name.to_sym) || @intermediate_results.key?(step_name.to_s)
+    end
+
     def set_result(step_name, value)
       @intermediate_results[step_name.to_sym] = value
     end
@@ -81,7 +92,6 @@ module RubyReactor
         retry_context: @retry_context,
         reactor_class: @reactor_class,
         execution_trace: @execution_trace,
-        test_mode: @test_mode,
         status: @status,
         failure_reason: @failure_reason
       }
@@ -105,7 +115,6 @@ module RubyReactor
         retry_context: @retry_context.serialize_for_retry,
         execution_trace: ContextSerializer.serialize_value(@execution_trace),
         undo_stack: serialize_undo_stack,
-        test_mode: @test_mode,
         cancelled: @cancelled,
         cancellation_reason: @cancellation_reason,
         status: @status,
@@ -130,7 +139,6 @@ module RubyReactor
       context.retry_context = RetryContext.deserialize_from_retry(data["retry_context"] || {})
       context.execution_trace = ContextSerializer.deserialize_value(data["execution_trace"]) || []
       context.undo_stack = deserialize_undo_stack(data["undo_stack"] || [], context.reactor_class)
-      context.test_mode = data["test_mode"] || false
       context.cancelled = data["cancelled"] || false
       context.cancellation_reason = data["cancellation_reason"]
       context.status = data["status"] || "pending"

data/lib/ruby_reactor/context_serializer.rb

@@ -34,9 +34,25 @@ module RubyReactor
         when RubyReactor::Success
           { "_type" => "Success", "value" => serialize_value(value.value) }
         when RubyReactor::Failure
-          { "_type" => "Failure", "error" => serialize_value(value.error), "retryable" => value.retryable }
+          {
+            "_type" => "Failure",
+            "error" => serialize_value(value.error),
+            "retryable" => value.retryable,
+            "step_name" => value.step_name,
+            "inputs" => serialize_value(value.inputs),
+            "backtrace" => value.backtrace,
+            "reactor_name" => value.reactor_name,
+            "step_arguments" => serialize_value(value.step_arguments),
+            "exception_class" => value.exception_class,
+            "file_path" => value.file_path,
+            "line_number" => value.line_number,
+            "code_snippet" => serialize_value(value.code_snippet),
+            "validation_errors" => serialize_value(value.validation_errors)
+          }
         when RubyReactor::Context
           { "_type" => "Context", "value" => value.serialize_for_retry }
+        when Symbol
+          { "_type" => "Symbol", "value" => value.to_s }
         when Time
           { "_type" => "Time", "value" => value.iso8601 }
         when BigDecimal
@@ -94,9 +110,24 @@ module RubyReactor
             when "Success"
               RubyReactor::Success(deserialize_value(value["value"]))
             when "Failure"
-              RubyReactor::Failure(deserialize_value(value["error"]), retryable: value["retryable"])
+              RubyReactor::Failure.new(
+                deserialize_value(value["error"]),
+                retryable: value["retryable"],
+                step_name: value["step_name"],
+                inputs: deserialize_value(value["inputs"]),
+                backtrace: value["backtrace"],
+                reactor_name: value["reactor_name"],
+                step_arguments: deserialize_value(value["step_arguments"]),
+                exception_class: value["exception_class"],
+                file_path: value["file_path"],
+                line_number: value["line_number"],
+                code_snippet: deserialize_value(value["code_snippet"]),
+                validation_errors: deserialize_value(value["validation_errors"])
+              )
             when "Context"
               Context.deserialize_from_retry(value["value"])
+            when "Symbol"
+              value["value"].to_sym
             when "Time"
               Time.iso8601(value["value"])
             when "BigDecimal"
@@ -130,11 +161,13 @@ module RubyReactor
                 strict_ordering: value["strict_ordering"],
                 batch_size: value["batch_size"]
               )
+
             else
-              value
+              # Unknown type wrapper, return as is (but deserialize values)
+              value.transform_values { |v| deserialize_value(v) }
             end
           else
-            # Regular hash - symbolize all keys recursively
+            # Regular Hash
             value.transform_keys(&:to_sym).transform_values { |v| deserialize_value(v) }
           end
         when Array
@@ -143,6 +176,24 @@ module RubyReactor
           value
         end
       end
+
+      # Simplifies data for public API usage (removes wrappers, flattens types)
+      def simplify_for_api(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), hash|
+            hash[k.to_s] = simplify_for_api(v)
+          end
+        when Array
+          value.map { |v| simplify_for_api(v) }
+        when Success, Failure, Context
+          simplify_for_api(value.to_h)
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
       private

data/lib/ruby_reactor/dsl/lockable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    module Lockable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config
+
+        # Propagate lock/semaphore/period/rate-limit config to subclasses;
+        # without this a subclass of a configured reactor would silently lose
+        # those settings.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@lock_config, @lock_config) if @lock_config
+          subclass.instance_variable_set(:@semaphore_config, @semaphore_config) if @semaphore_config
+          subclass.instance_variable_set(:@period_config, @period_config) if @period_config
+          subclass.instance_variable_set(:@rate_limit_config, @rate_limit_config) if @rate_limit_config
+        end
+
+        # Configure locking for this reactor
+        # @param ttl [Integer] Time to live in seconds (default: 60)
+        # @param wait [Integer] Time to wait for lock in seconds (default: 0)
+        # @param auto_extend [Boolean] When true (default), a background thread
+        #   refreshes the lock TTL every ttl/3 seconds while the reactor runs,
+        #   protecting steps that may legitimately outlast `ttl`. Pass `false`
+        #   to disable and rely solely on `ttl` for expiry.
+        # @yield [inputs] Block that returns the lock key string
+        def with_lock(ttl: 60, wait: 0, auto_extend: true, &block)
+          @lock_config = {
+            ttl: ttl,
+            wait: wait,
+            auto_extend: auto_extend,
+            key_proc: block
+          }
+        end
+
+        # Configure semaphore for this reactor
+        # @param limit [Integer] Maximum concurrent executions
+        # @param wait [Integer] Time to wait for a token in seconds (default: 0)
+        # @yield [inputs] Block that returns the semaphore key string
+        def with_semaphore(limit:, wait: 0, &block)
+          @semaphore_config = {
+            limit: limit,
+            wait: wait,
+            key_proc: block
+          }
+        end
+
+        # Configure a calendar-aligned dedup window for this reactor. The
+        # reactor will run at most once per bucket per key; subsequent calls
+        # in the same bucket return `RubyReactor::Skipped` without executing
+        # any steps.
+        #
+        # Note: `with_period` is *dedup*, not *concurrency*. Two concurrent
+        # racers can both see no marker and both run. Pair with `with_lock`
+        # for true at-most-one semantics within the bucket.
+        #
+        # @param every [Symbol, Integer] :minute / :hour / :day / :week /
+        #   :month / :year, or an integer number of seconds for a sliding
+        #   bucket (index = `time.to_i / every`).
+        # @yield [inputs] Block that returns the period key base. The final
+        #   Redis marker key is `period:<base>:<bucket_id>`.
+        def with_period(every:, &block)
+          # Validate eagerly so misconfiguration surfaces at class load time.
+          RubyReactor::Period.period_seconds(every)
+
+          @period_config = {
+            every: every,
+            key_proc: block
+          }
+        end
+
+        # Configure rate limiting for this reactor (fixed-window counter).
+        # Pass either a single window via `limit:` + `period:`, or a hash of
+        # windows via `limits:` for layered API quotas.
+        #
+        # @example Single window
+        #   with_rate_limit(limit: 3, period: :second) { |i| "stripe:#{i[:account_id]}" }
+        #
+        # @example Multi-window (3/sec AND 100/min AND 5000/hr)
+        #   with_rate_limit(
+        #     limits: { second: 3, minute: 100, hour: 5000 }
+        #   ) { |i| "stripe:#{i[:account_id]}" }
+        #
+        # @param limit [Integer] requests per period (single-window form)
+        # @param period [Symbol, Integer] :second / :minute / :hour / :day /
+        #   :week / :month / :year, or integer seconds (single-window form)
+        # @param limits [Hash{Symbol,Integer => Integer}] mapping of period
+        #   unit to limit (multi-window form)
+        # @yield [inputs] Block returning the rate-limit key base.
+        def with_rate_limit(limit: nil, period: nil, limits: nil, &block)
+          normalized = normalize_rate_limit_args(limit, period, limits)
+
+          @rate_limit_config = {
+            limits: normalized,
+            key_proc: block
+          }
+        end
+
+        private
+
+        def normalize_rate_limit_args(limit, period, limits)
+          if limits
+            raise ArgumentError, "with_rate_limit: use either :limits, or :limit + :period, not both" if limit || period
+
+            limits.map do |period_key, limit_val|
+              {
+                period_seconds: RubyReactor::Period.period_seconds(period_key),
+                limit: Integer(limit_val),
+                name: period_key.to_s
+              }
+            end
+          elsif limit && period
+            [{
+              period_seconds: RubyReactor::Period.period_seconds(period),
+              limit: Integer(limit),
+              name: period.to_s
+            }]
+          else
+            raise ArgumentError, "with_rate_limit requires :limit + :period, or :limits"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/dsl/reactor.rb

@@ -118,8 +118,9 @@ module RubyReactor
           step_config
         end
 
-        def returns(step_name)
-          @return_step = step_name
+        def returns(step_name = nil)
+          @return_step = step_name if step_name
+          @return_step
         end
 
         def middleware(middleware_class)

data/lib/ruby_reactor/error/step_failure_error.rb

@@ -3,11 +3,14 @@
 module RubyReactor
   module Error
     class StepFailureError < Base
-      attr_reader :step_arguments
+      attr_reader :step_arguments, :exception_class
 
-      def initialize(message, step: nil, context: nil, original_error: nil, step_arguments: {})
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(message, step: nil, context: nil, original_error: nil, step_arguments: {}, exception_class: nil)
+        # rubocop:enable Metrics/ParameterLists
         super(message, step: step, context: context, original_error: original_error)
         @step_arguments = step_arguments
+        @exception_class = exception_class
       end
 
       def retryable?

data/lib/ruby_reactor/executor/result_handler.rb

@@ -14,6 +14,9 @@ module RubyReactor
 
       def handle_step_result(step_config, result, resolved_arguments)
         case result
+        when RubyReactor::Skipped
+          # Important: must come before the Success branch — Skipped < Success.
+          handle_skipped(step_config, result)
         when RubyReactor::Success
           handle_success(step_config, result, resolved_arguments)
         when RubyReactor::MaxRetriesExhaustedFailure
@@ -31,7 +34,7 @@ module RubyReactor
           handle_step_failure_error(error)
         when Error::InputValidationError
           # Preserve validation errors as-is for proper error handling
-          RubyReactor.Failure(error)
+          RubyReactor.Failure(error, validation_errors: error.field_errors)
         when Error::Base
           # Other errors need rollback
           @compensation_manager.rollback_completed_steps
@@ -53,6 +56,22 @@ module RubyReactor
 
       private
 
+      # A step returned `RubyReactor.Skipped(...)`. Halt cleanly: record the
+      # event in the trace, do NOT push to the undo stack (so existing
+      # completed steps stay as-is — no compensation), and stamp the step
+      # name on the result so the caller can see who halted.
+      def handle_skipped(step_config, result)
+        @step_results[step_config.name] = result
+        result.instance_variable_set(:@step_name, step_config.name) if result.step_name.nil?
+        @context.execution_trace << {
+          type: :skipped,
+          step: step_config.name,
+          timestamp: Time.now,
+          reason: result.reason
+        }
+        result
+      end
+
       def handle_success(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
@@ -129,7 +148,7 @@ module RubyReactor
 
       def create_failure_from_error(error, redact_inputs)
         original_error = error.original_error
-        exception_class = original_error&.class&.name
+        exception_class = resolve_exception_class(original_error, error)
         backtrace = original_error&.backtrace || error.backtrace
         file_path, line_number = extract_location(backtrace)
         code_snippet = RubyReactor::Utils::CodeExtractor.extract(file_path, line_number) if file_path
@@ -149,6 +168,12 @@ module RubyReactor
         )
       end
 
+      def resolve_exception_class(original_error, error)
+        return original_error.class.name if original_error
+
+        error.respond_to?(:exception_class) ? error.exception_class : nil
+      end
+
       def validate_step_output(step_config, value, resolved_arguments = {})
         return unless step_config.output_validator
 

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -116,7 +116,8 @@ module RubyReactor
                    @context.root_context&.reactor_class&.async? ||
                    @context.inline_async_execution
 
-        if is_async && !@context.test_mode
+        # Always try async retry if configured
+        if is_async
           handle_async_retry(step_config, reactor_class, result)
         else
           handle_sync_retry(step_config, reactor_class, result)
@@ -124,12 +125,19 @@ module RubyReactor
       end
 
       def handle_async_retry(step_config, reactor_class, result)
-        requeue_job_for_step_retry(step_config, result.error, reactor_class)
-        RetryQueuedResult.new(
-          step_config.name,
-          @context.retry_context.attempts_for_step(step_config.name),
-          @context.retry_context.next_retry_at
-        )
+        requeue_result = requeue_job_for_step_retry(step_config, result.error, reactor_class)
+
+        # If it returned an AsyncResult, we are truly async.
+        # Otherwise, it ran inline and we should return the result of that execution.
+        if requeue_result.is_a?(RubyReactor::AsyncResult)
+          RetryQueuedResult.new(
+            step_config.name,
+            @context.retry_context.attempts_for_step(step_config.name),
+            @context.retry_context.next_retry_at
+          )
+        else
+          requeue_result
+        end
       end
 
       def handle_sync_retry(step_config, reactor_class, result)

data/lib/ruby_reactor/executor/step_executor.rb

@@ -13,7 +13,7 @@ module RubyReactor
       end
 
       def execute_all_steps
-        until @dependency_graph.all_completed?
+        until @dependency_graph.all_completed? || @context.finished?
           ready_steps = @dependency_graph.ready_steps
 
           if ready_steps.empty?
@@ -33,6 +33,11 @@ module RubyReactor
             # If a step returns RetryQueuedResult, we need to stop and return it
             return result if result.is_a?(RetryQueuedResult)
 
+            # If a step returns Skipped, halt the reactor cleanly (no
+            # compensation). Must be checked BEFORE Failure / Success because
+            # Skipped is a Success subclass.
+            return result if result.is_a?(RubyReactor::Skipped)
+
             # If a step returns Failure, we need to stop execution and return it
             return result if result.is_a?(RubyReactor::Failure)
 
@@ -65,53 +70,29 @@ module RubyReactor
         end
       end
 
-      def merge_executor_state(other_executor)
-        # Merge the state from the async-executed executor back into ours
-        # We need to update our context IN PLACE, not replace the reference,
-        # because the Executor also holds a reference to the same context object
-
-        # Update intermediate results
-        other_executor.context.intermediate_results.each do |step_name, value|
-          @context.set_result(step_name, value)
-        end
-
-        # Append execution trace from the async execution
-        # The Worker's execution will have ALL steps including ones we already executed,
-        # but we only want to add the NEW entries (from current_step onwards)
-        current_trace_length = @context.execution_trace.length
-        new_trace_entries = other_executor.context.execution_trace[current_trace_length..] || []
-
-        @context.execution_trace.concat(new_trace_entries)
-
-        # Update retry context
-        @context.retry_context = other_executor.context.retry_context
-
-        # Update current_step:
-        # If the other executor has a current_step, it means it paused/interrupted there. We should adopt it.
-        # If it's nil, it means it completed successfully, so we clear our current_step (which was the async step).
-        @context.current_step = other_executor.context.current_step
-
-        # Update our dependency graph to reflect completed steps
-        other_executor.context.intermediate_results.each_key do |step_name|
-          @dependency_graph.complete_step(step_name)
-        end
-
-        # Also mark the current_step as completed if it exists (for failed steps that don't have results)
-        @dependency_graph.complete_step(other_executor.context.current_step) if other_executor.context.current_step
-
-        # Merge any undo stack items
-        other_executor.undo_stack.each do |item|
-          # Avoid duplicates by checking if this step is already in the undo stack
-          # Use string comparison for step names to avoid symbol/string mismatch issues
-          unless @compensation_manager.undo_stack.any? { |existing| existing[:step].name.to_s == item[:step].name.to_s }
-            @compensation_manager.add_to_undo_stack(item)
-          end
-        end
+      private
 
-        # Merge undo trace from the other executor
-        other_executor.undo_trace.each do |trace_entry|
-          @compensation_manager.undo_trace << trace_entry
-        end
+      def reconstruct_failure(data)
+        return data if data.is_a?(RubyReactor::Failure)
+        return nil unless data.is_a?(Hash)
+
+        # Helper for hash access with string/symbol keys
+        get = ->(key) { data[key] || data[key.to_s] }
+
+        RubyReactor::Failure.new(
+          get.call(:message),
+          step_name: get.call(:step_name),
+          inputs: get.call(:inputs),
+          redact_inputs: get.call(:redact_inputs) || [],
+          backtrace: get.call(:backtrace),
+          reactor_name: get.call(:reactor_name),
+          step_arguments: get.call(:step_arguments),
+          exception_class: get.call(:exception_class),
+          file_path: get.call(:file_path),
+          line_number: get.call(:line_number),
+          code_snippet: get.call(:code_snippet),
+          validation_errors: get.call(:validation_errors)
+        )
       end
 
       def execute_step_with_retry(step_config)
@@ -190,8 +171,6 @@ module RubyReactor
         end
       end
 
-      private
-
       def handle_async_step(step_config)
         # Step-level async: hand off execution to worker
 
@@ -204,60 +183,11 @@ module RubyReactor
 
         serialized_context = ContextSerializer.serialize(context_to_serialize)
 
-        result = configuration.async_router.perform_async(
+        configuration.async_router.perform_async(
           serialized_context,
           reactor_class_name,
           intermediate_results: @context.intermediate_results
         )
-
-        # Handle different result types from async router
-        case result
-        when RubyReactor::AsyncResult
-          # Production behavior: return async result to caller
-
-          result
-        when Executor
-          handle_inline_executor_result(result)
-        else
-          # Unexpected result type, treat as error
-          raise Error::ValidationError.new(
-            "Unexpected result type from async router: #{result.class}",
-            context: @context
-          )
-        end
-      end
-
-      def handle_inline_executor_result(result)
-        # Worker executed inline and returned an executor.
-        # This happens when running in test mode or when perform_async returns an executor.
-        # We need to merge the state back into our current executor.
-        #
-        # If we are a child reactor, the worker executed the root reactor, so the result
-        # will be a Root executor. We handle this mismatch below by finding our
-        # corresponding child context within the root result.
-        if @context.root_context && (result.context.reactor_class != @reactor_class)
-          # We are a child, and result is root.
-          # We need to find ourselves in the root result using context_id.
-          matching_context = find_context_by_id(result.context, @context.context_id)
-
-          if matching_context
-            # Replace the result's context with the matching child context
-            # so merge_executor_state works correctly
-            result.instance_variable_set(:@context, matching_context)
-          else
-            # Fallback: if we can't find it (shouldn't happen), we might be in trouble.
-            # But let's try to proceed, maybe it's not nested?
-            # For now, raise an error to be explicit
-            raise Error::ValidationError.new(
-              "Could not find child context with ID #{@context.context_id} in root result",
-              context: @context
-            )
-          end
-        end
-
-        merge_executor_state(result)
-
-        result.result
       end
 
       def handle_interrupt_step(step_config)