ruby_reactor 0.5.4 → 0.7.0

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -130,6 +130,56 @@ module RubyReactor
         elements[index]
       end
 
+      # The durable record for a dispatched `async_step`, or nil if the step was
+      # never dispatched (e.g. under `async: false`, where it ran inline and its
+      # value is an ordinary `step_result`). Mirrors `#composed` / `#map` in
+      # reading the reference off `composed_contexts`.
+      #
+      #   subject.async_step(:send_email)          # => the raw record hash
+      #   subject.async_step(:send_email, :status) # => "dispatched" / "completed"
+      def async_step(step_name, key = nil)
+        ensure_executed!
+
+        entry = composed_entry(step_name)
+        return nil unless entry && entry[:type] == :async_step_ref
+
+        record = RubyReactor.configuration.storage_adapter.retrieve_step_result(
+          entry[:context_id] || @reactor_instance.context.context_id,
+          step_name,
+          RubyReactor.reactor_storage_name(@reactor_instance.class)
+        )
+        key && record ? record[key.to_s] : record
+      end
+
+      # The child execution a dispatched `async_reactor` created, as its own
+      # TestSubject — the same drill-down `#composed` gives for an inline child.
+      def async_reactor(step_name)
+        ensure_executed!
+
+        entry = composed_entry(step_name)
+        return nil unless entry && entry[:type] == :async_reactor_ref
+
+        child_class = RubyReactor::Context.resolve_reactor_class(entry[:reactor_class_name])
+        return nil unless child_class
+
+        child_instance = child_class.find(entry[:execution_id])
+        self.class.new(
+          reactor_class: child_instance.class,
+          inputs: child_instance.context.inputs,
+          context: child_instance.context,
+          async: @async,
+          process_jobs: @process_jobs
+        ).tap do |s|
+          s.instance_variable_set(:@executed, true)
+          s.instance_variable_set(:@reactor_instance, child_instance)
+        end
+      end
+
+      def composed_entry(step_name)
+        contexts = @reactor_instance.context.composed_contexts
+        contexts[step_name] || contexts[step_name.to_s] || contexts[step_name.to_sym]
+      end
+
       private
 
       def traverse_composed(step_name)
@@ -191,9 +241,9 @@ module RubyReactor
         end
 
         @run_result = nil
-        if @process_jobs && defined?(Sidekiq::Testing)
-          # Ensure SidekiqAdapter is used to capture jobs in fake mode
-          allow(RubyReactor.configuration).to receive(:async_router).and_return(RubyReactor::SidekiqAdapter)
+        if @process_jobs && AsyncTestHelpers.sidekiq_testing?
+          # Ensure the Sidekiq router is used to capture jobs in fake mode
+          allow(RubyReactor.configuration).to receive(:async_router).and_return(RubyReactor::Adapters::Sidekiq::Router)
 
           # Avoid nesting error which happens in Sidekiq 7+ if a mode is already set
           begin
@@ -203,6 +253,10 @@ module RubyReactor
           rescue Sidekiq::Testing::TestModeAlreadySetError
             @run_result = execution_class.run(@inputs)
           end
+        elsif @process_jobs && AsyncTestHelpers.active_job_testing?
+          # Ensure the ActiveJob router is used to capture jobs in the :test adapter
+          allow(RubyReactor.configuration).to receive(:async_router).and_return(RubyReactor::Adapters::ActiveJob::Router)
+          @run_result = execution_class.run(@inputs)
         else
           @run_result = execution_class.run(@inputs)
         end
@@ -250,7 +304,7 @@ module RubyReactor
           skipped_result(ctx)
         when "running"
           # Try to determine if it is truly running or if we just missed the completion
-          if @process_jobs && defined?(Sidekiq::Testing)
+          if @process_jobs && AsyncTestHelpers.active?
             # Force one more check
             process_pending_jobs
             # Reload status
@@ -357,7 +411,7 @@ module RubyReactor
         @reactor_instance.continue(payload: payload, step_name: step_name)
 
         # Process any pending async jobs
-        process_pending_jobs if @process_jobs && defined?(Sidekiq::Testing)
+        process_pending_jobs if @process_jobs && AsyncTestHelpers.active?
 
         # Reload the reactor instance to get updated state
         @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
@@ -430,14 +484,15 @@ module RubyReactor
       private
 
       def process_pending_jobs
-        return unless defined?(Sidekiq::Testing)
+        return unless AsyncTestHelpers.active?
 
-        SidekiqHelpers.drain_async_jobs
+        AsyncTestHelpers.drain_async_jobs
         @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
       end
 
       def prepare_execution_class
-        # Even if no interceptors, we might need to subclass to override async steps
+        # Even if no interceptors, we might need to subclass to force the whole
+        # reactor to run in-process.
         return @reactor_class if @interceptors.empty? && @async != false
 
         interceptors = @interceptors
@@ -450,7 +505,7 @@ module RubyReactor
           @input_validations = superclass.input_validations.dup
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
-          @async = superclass.async?
+          @background_handoff = superclass.background_handoff
           @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
 
           # 2. Add Name Handling with Unique Registry Entry
@@ -460,15 +515,16 @@ module RubyReactor
           define_singleton_method(:name) { unique_name }
           RubyReactor::Registry.register(unique_name, self)
 
-          # 3. Apply Force Sync (Disable async on all steps)
+          # 3. `async: false` / `run_async(false)` means "run this reactor's full
+          # logic here, in one process". Under the new DSL that is three things:
+          # suppress the `background` hand-off, and run `async_step` /
+          # `async_reactor` units inline instead of dispatching them.
           if force_sync
+            @background_handoff = nil
             @steps.each do |name, config|
-              next unless config.async?
+              next unless config.respond_to?(:async_dispatch?) && config.async_dispatch?
 
-              # Clone and modify
-              new_config = config.clone
-              new_config.instance_variable_set(:@async, false)
-              @steps[name] = new_config
+              @steps[name] = config.clone.tap { |c| c.instance_variable_set(:@async_dispatch, nil) }
             end
           end
         end
@@ -499,7 +555,8 @@ module RubyReactor
 
           if nested_interceptors.any?
             apply_nested_interceptors(step_config, nested_interceptors)
-            step_config.instance_variable_set(:@async, false)
+            # A mocked inner step only takes effect if the child runs here.
+            step_config.instance_variable_set(:@async_dispatch, nil)
           end
 
           # Apply direct interceptors (mocks/failures on this step)
@@ -547,7 +604,7 @@ module RubyReactor
           @input_validations = superclass.input_validations.dup
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
-          @async = superclass.async?
+          @background_handoff = superclass.background_handoff
           @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
         end
 
@@ -602,7 +659,9 @@ module RubyReactor
         end
 
         step_config.instance_variable_set(:@run_block, wrapper_impl)
-        step_config.instance_variable_set(:@async, false)
+        # The mock replaces the step's body, so it must run where the spec can
+        # observe it rather than being dispatched to a worker.
+        step_config.instance_variable_set(:@async_dispatch, nil)
       end
     end
     # rubocop:enable Metrics/ClassLength

data/lib/ruby_reactor/rspec.rb

@@ -3,6 +3,8 @@
 require_relative "rspec/helpers"
 require_relative "rspec/matchers"
 require_relative "rspec/sidekiq_helpers"
+require_relative "rspec/active_job_helpers"
+require_relative "rspec/async_test_helpers"
 require_relative "rspec/storage_reset"
 require_relative "rspec/test_subject"
 
@@ -44,6 +46,8 @@ module RubyReactor
         ::Sidekiq::Worker.clear_all
       end
 
+      ::ActiveJob::Base.queue_adapter.enqueued_jobs.clear if AsyncTestHelpers.active_job_testing?
+
       adapter = ::RubyReactor.configuration.storage_adapter
       adapter.reset! if adapter.respond_to?(:reset!)
 

data/lib/ruby_reactor/semaphore.rb

@@ -40,6 +40,16 @@ module RubyReactor
       release
     end
 
+    # Park support: re-adopt a token that stayed checked out across a parked
+    # gap. Verifies the token is still in the held set — a reset/expiry in
+    # between means the slot was lost and the caller must acquire fresh.
+    def reattach(token) # rubocop:disable Naming/PredicateMethod
+      return false unless token && adapter.semaphore_held?(@key, token)
+
+      @token = token
+      true
+    end
+
     private
 
     def ensure_initialized

data/lib/ruby_reactor/step/async_reactor_step.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Step
+    # The dispatching half of `async_reactor`: everything that happens in the
+    # PARENT's process. The child then runs as an ordinary independently
+    # dispatched reactor execution — no new enqueue primitive, no new storage
+    # primitive, and no entry in the parent's compensation graph.
+    #
+    # Dispatch reuses the full pre-enqueue sequence of a top-level async run
+    # rather than a raw `perform_async`, because `Reactor#run` does
+    # three load-bearing things a naive `Context.new` + enqueue would silently
+    # skip: validate the child's inputs (the worker's resume path never
+    # validates, so skipping here starts a child on garbage), assign the
+    # ordered-lock nonce at ENQUEUE time (so ordering matches caller order), and
+    # persist before enqueueing (F2).
+    class AsyncReactorStep
+      include RubyReactor::Step
+
+      class << self
+        def run(arguments, context)
+          child_class = arguments[:async_reactor_class]
+          child_inputs = build_child_inputs(arguments[:argument_mappings] || {}, context)
+
+          # A dispatch-time failure fails the DISPATCHING step, i.e. normal saga
+          # handling in the parent. That is deliberately outside the
+          # no-auto-compensation rule, which governs the child's own execution.
+          validation = validate_child_inputs(child_class, child_inputs)
+          return validation if validation
+
+          deadlock = detect_lock_deadlock(child_class, child_inputs, context)
+          return deadlock if deadlock
+
+          return run_inline(child_class, child_inputs, context) if run_inline?(context)
+
+          dispatch(child_class, child_inputs, context)
+        end
+
+        private
+
+        def build_child_inputs(mappings, context)
+          mappings.transform_values { |source| source.resolve(context) }
+        end
+
+        def validate_child_inputs(child_class, child_inputs)
+          return nil unless child_class.respond_to?(:validate_inputs)
+
+          result = child_class.validate_inputs(child_inputs)
+          return nil unless result.failure?
+
+          RubyReactor.Failure(
+            "async_reactor child #{child_class.name} rejected its inputs: #{result.error.message}",
+            validation_errors: (result.error.field_errors if result.error.respond_to?(:field_errors))
+          )
+        end
+
+        # Lock ownership is NOT shared across the async boundary: parent
+        # and child run concurrently, so giving the child the parent's owner
+        # would put both inside the critical section at once — mutual exclusion
+        # silently broken, which is worse than a stall. Instead the one
+        # GUARANTEED deadlock (the parent holds a key its child will wait on,
+        # while the parent may go on to wait for that child) is caught here,
+        # loudly, at dispatch. Ordinary cross-execution contention on the same
+        # key is unaffected and still snoozes normally.
+        def detect_lock_deadlock(child_class, child_inputs, context)
+          held = held_lock_keys(context)
+          return nil if held.empty?
+
+          collision = child_lock_keys(child_class, child_inputs).find { |key| held.include?(key) }
+          return nil unless collision
+
+          RubyReactor.Failure(deadlock_message(collision, child_class, context))
+        end
+
+        def child_lock_keys(child_class, child_inputs)
+          keys = []
+          if child_class.respond_to?(:lock_config) && child_class.lock_config
+            keys << child_class.lock_config[:key_proc].call(child_inputs)
+          end
+
+          # A semaphore with a single slot has the identical circular-wait
+          # shape. Higher limits are contention, not guaranteed deadlock.
+          semaphore = child_class.respond_to?(:semaphore_config) ? child_class.semaphore_config : nil
+          keys << semaphore[:key_proc].call(child_inputs) if semaphore && semaphore[:limit] == 1
+
+          keys.compact
+        end
+
+        def held_lock_keys(context)
+          root = context.root_context || context
+          Array(root.private_data[:held_lock_keys] || root.private_data["held_lock_keys"])
+        end
+
+        def deadlock_message(key, child_class, context)
+          parent = context.reactor_class&.name || "the dispatching reactor"
+          <<~MSG.strip
+            async_reactor dispatch of #{child_class.name || "<anonymous>"} would deadlock: it declares the \
+            lock key '#{key}', which #{parent} currently holds and will not release until it finishes.
+            The child would snooze forever, and if #{parent} later reads this child's result it would wait \
+            for work that can never start. Lock ownership is never shared across the async boundary — the \
+            two run concurrently, so sharing it would break mutual exclusion outright.
+            Fix, in order of preference:
+              1. Use `compose` instead of `async_reactor` if the child belongs inside #{parent}'s critical \
+            section and its result is needed — waiting for it means the work is sequential anyway.
+              2. Narrow the lock keys, if parent and child actually protect different resources.
+              3. Restructure so the locked reactor never reads the child's result — fire-and-forget, and \
+            verify in the child itself or in a successor reactor outside the lock window.
+          MSG
+        end
+
+        # `RSpec::TestSubject`'s `async: false` clears the dispatch marker to run
+        # the whole reactor in one process.
+        def run_inline?(context)
+          config = context.reactor_class&.steps&.[](context.current_step)
+          config.respond_to?(:async_dispatch?) && !config.async_dispatch?
+        end
+
+        def run_inline(child_class, child_inputs, context)
+          result = child_class.run(child_inputs)
+          store_reference(context, execution_id: (result.execution_id if result.respond_to?(:execution_id)),
+                                   child_class: child_class)
+          # Success(nil) for the same reason dispatch returns it: `result(:name)`
+          # must route through the reference (which now points at an already
+          # terminal child) rather than through a recorded value.
+          RubyReactor.Success(nil)
+        end
+
+        def dispatch(child_class, child_inputs, context)
+          child_context = build_child_context(child_class, child_inputs, context)
+          assign_ordered_lock_nonce!(child_class, child_context)
+
+          # Persist BEFORE enqueue (F2) — the payload is identity-only.
+          child_context.status = :running
+          # Marks the child as owned by a job of its own, which is what makes it
+          # sweepable: a compose child carries the same parent_context_id but runs
+          # inline in the parent, so re-enqueueing one would double-run it.
+          child_context.private_data[:async_dispatched] = true
+          save(child_context, child_class)
+
+          # The reference is written synchronously, by the process that is about
+          # to keep running other steps, so there is no cross-process race on it
+          # (unlike the child's eventual result, which the child itself writes).
+          store_reference(context, execution_id: child_context.context_id, child_class: child_class)
+          log_dispatch(context, child_class, child_context)
+
+          RubyReactor.configuration.async_router.perform_async(
+            child_context.context_id, RubyReactor.reactor_storage_name(child_class)
+          )
+
+          RubyReactor.Success(nil)
+        end
+
+        def build_child_context(child_class, child_inputs, context)
+          child_context = RubyReactor::Context.new(child_inputs, child_class)
+          # Linked for traceability only — the child is NOT nested inside the
+          # parent's context tree, because it must survive the parent finishing.
+          child_context.parent_context_id = context.context_id
+          child_context
+        end
+
+        def assign_ordered_lock_nonce!(child_class, child_context)
+          return unless child_class.respond_to?(:ordered_lock_config) && child_class.ordered_lock_config
+
+          config = child_class.ordered_lock_config
+          key = config[:key_proc].call(child_context.inputs)
+          nonce, epoch = RubyReactor::OrderedLock.assign(key, ttl: config[:ttl])
+
+          child_context.private_data[:ordered_lock] = {
+            key: key, nonce: nonce, epoch: epoch,
+            poison_pill_timeout: config[:poison_pill_timeout],
+            ttl: config[:ttl], strict: config.fetch(:strict, true)
+          }
+        end
+
+        def store_reference(context, execution_id:, child_class:)
+          context.composed_contexts[context.current_step] = {
+            name: context.current_step,
+            type: :async_reactor_ref,
+            execution_id: execution_id,
+            reactor_class_name: RubyReactor.reactor_storage_name(child_class),
+            dispatched_at: Time.now
+          }
+        end
+
+        def save(child_context, child_class)
+          RubyReactor.configuration.storage_adapter.store_context(
+            child_context.context_id,
+            RubyReactor::ContextSerializer.serialize(child_context),
+            RubyReactor.reactor_storage_name(child_class)
+          )
+        end
+
+        # The link between parent and child, machine-parseable. Matters
+        # most here — a fire-and-forget child's failure may have no other surface
+        # in the parent at all.
+        def log_dispatch(context, child_class, child_context)
+          RubyReactor.configuration.logger.info(
+            "event=\"ruby_reactor.async_reactor.dispatched\" " \
+            "reactor=#{context.reactor_class&.name.inspect} step=#{context.current_step.inspect} " \
+            "execution_id=#{context.context_id.inspect} child_reactor=#{child_class.name.inspect} " \
+            "child_execution_id=#{child_context.context_id.inspect}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/step/compose_step.rb

@@ -108,7 +108,7 @@ module RubyReactor
         end
 
         def handle_execution_result(result)
-          return result if result.is_a?(RubyReactor::AsyncResult) || result.is_a?(RubyReactor::RetryQueuedResult)
+          return result if result.is_a?(RubyReactor::DispatchResult) || result.is_a?(RubyReactor::RetryQueuedResult)
 
           if result.success?
             RubyReactor.Success(result.value)

data/lib/ruby_reactor/step/map_step.rb

@@ -168,7 +168,7 @@ module RubyReactor
             element_reactor_class: arguments[:mapped_reactor_class].name
           }
 
-          RubyReactor::AsyncResult.new(
+          RubyReactor::DispatchResult.new(
             job_id: job_id,
             intermediate_results: context.intermediate_results,
             execution_id: context.context_id

data/lib/ruby_reactor/step_sweeper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Re-dispatches `async_step` units whose job was lost.
+  #
+  # An `async_step` is the one dispatched unit with no context of its own, so
+  # neither Sweeper (top-level contexts) nor Map::Sweeper (map elements) can see
+  # it. All it leaves behind is a Step Result Record stuck at `dispatched`, and
+  # because that record is also the re-attach marker, `already_dispatched?`
+  # actively refuses to dispatch again — so without this sweep a lost unit strands
+  # its parent forever, re-parking on every recovery of the parent itself.
+  #
+  # Liveness is the `async_step:` lock StepWorker holds for the life of the unit,
+  # mirroring how Sweeper reads `async:` and Map::Sweeper reads `map_element:`. A
+  # duplicate that races a live worker loses that lock and drops itself, so a
+  # mis-judged unit re-runs its body at most once.
+  class StepSweeper
+    DEFAULT_LIMIT = 1000
+
+    # The re-dispatch arguments, which the record carries verbatim because its
+    # key names the reactor that owns the step rather than the root the worker
+    # must load. Records written before recovery existed lack them and are skipped.
+    DISPATCH_KEYS = %w[root_context_id reactor_class_name step_context_id step_name].freeze
+
+    def self.run_once(limit: DEFAULT_LIMIT)
+      new.run_once(limit: limit)
+    end
+
+    def initialize(storage: nil, async_router: nil, logger: nil)
+      @storage = storage || RubyReactor.configuration.storage_adapter
+      @async_router = async_router || RubyReactor.configuration.async_router
+      @logger = logger || RubyReactor.configuration.logger
+    end
+
+    # Scans stored Step Result Records and re-dispatches the dispatched-but-dead
+    # ones. Returns the number re-dispatched.
+    def run_once(limit: DEFAULT_LIMIT)
+      redispatched = 0
+
+      @storage.scan_step_results(count: limit).each do |record|
+        next unless record["status"] == "dispatched"
+
+        arguments = dispatch_arguments(record)
+        next unless arguments
+        next if live?(arguments)
+
+        @async_router.perform_step_async(**arguments)
+        redispatched += 1
+      rescue StandardError => e
+        # One bad record must not abort the whole sweep.
+        @logger.warn("RubyReactor::StepSweeper failed to re-dispatch #{record["step_name"]}: #{e.class}: #{e.message}")
+      end
+
+      redispatched
+    end
+
+    private
+
+    def dispatch_arguments(record)
+      values = record.values_at(*DISPATCH_KEYS)
+      return nil if values.any?(&:nil?)
+
+      DISPATCH_KEYS.map(&:to_sym).zip(values).to_h
+    end
+
+    def live?(arguments)
+      @storage.lock_held?(
+        RubyReactor.async_step_lock_key(arguments[:step_context_id], arguments[:step_name])
+      )
+    end
+  end
+end