ruby_reactor 0.6.0 → 0.7.1

data/lib/ruby_reactor/map/result_enumerator.rb

@@ -96,7 +96,13 @@ module RubyReactor
 
       def wrap_result(result)
         if result.is_a?(Hash) && result.key?("_error")
-          RubyReactor::Failure.new(result["_error"])
+          # `backtrace: []` is load-bearing: without it Failure falls back to
+          # `caller`, so a bare-message element failure would carry the stack of
+          # whoever happened to materialize the enumerator (the JSON encoder, in
+          # the dashboard's case) instead of the stack of the step that failed.
+          RubyReactor::Failure.new(result["_error"], backtrace: [])
+        elsif result.is_a?(Hash) && result.key?("_halt")
+          RubyReactor::Halt.new(reason: result["reason"])
         else
           RubyReactor::Success.new(ContextSerializer.deserialize_value(result))
         end

data/lib/ruby_reactor/map/result_summary.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Map
+    # A map's result set is unbounded, so the API describes it instead of
+    # inlining it. Inlining meant the JSON encoder materialized the lazy
+    # ResultEnumerator itself — one storage read per element — and rendered every
+    # element failure as an opaque blob with no count of how many there were.
+    class ResultSummary
+      # How many failed elements are described in full. The rest are only
+      # counted — a map failing 50k elements must not produce a 50k-entry
+      # response.
+      SAMPLE_LIMIT = 25
+
+      # Sampled failures are a list, not a detail view, and the same summary is
+      # echoed in intermediate_results, the execution trace and the undo stack —
+      # full traces on each would triple a large payload.
+      BACKTRACE_FRAMES = 10
+
+      # ponytail: one windowed read of the whole map; paginate if maps grow past
+      # what fits in a single response.
+      def self.build(enumerator)
+        total = enumerator.count
+        results = RubyReactor.configuration.storage_adapter.retrieve_map_results_batch(
+          enumerator.map_id, enumerator.reactor_class_name, offset: 0, limit: total
+        )
+        # Slots are index-keyed and the window starts at 0, so a full read means
+        # position == element index. A short read means the map is still filling
+        # in and gaps would shift positions — then indices are omitted.
+        failures = collect_failures(results, indexed: results.size == total)
+
+        {
+          "_type" => "map_results",
+          "total" => total,
+          "succeeded" => total - failures[:count],
+          "failed" => failures[:count],
+          "failures" => failures[:sample],
+          "failures_truncated" => failures[:count] > failures[:sample].size
+        }
+      end
+
+      def self.collect_failures(results, indexed:)
+        count = 0
+        sample = []
+
+        results.each_with_index do |raw, position|
+          next unless raw.is_a?(Hash) && raw.key?("_error")
+
+          count += 1
+          next if sample.size >= SAMPLE_LIMIT
+
+          entry = ContextSerializer.simplify_for_api(Failure.new(raw["_error"], backtrace: []))
+          entry["backtrace"] = Array(entry["backtrace"]).first(BACKTRACE_FRAMES)
+          entry["index"] = position if indexed
+          sample << entry
+        end
+
+        { count: count, sample: sample }
+      end
+      private_class_method :collect_failures
+    end
+  end
+end

data/lib/ruby_reactor/map/sweeper.rb

@@ -92,7 +92,7 @@ module RubyReactor
 
         results = data["intermediate_results"] || {}
         status = data["status"].to_s
-        results.key?(meta["step_name"].to_s) || %w[completed failed skipped].include?(status)
+        results.key?(meta["step_name"].to_s) || %w[completed failed halted skipped].include?(status)
       end
 
       def retrigger_collector(meta)

data/lib/ruby_reactor/open_telemetry.rb

@@ -147,7 +147,7 @@ module RubyReactor
       span = @step_spans.delete(step_name)
       return unless span
 
-      if result.is_a?(RubyReactor::AsyncResult)
+      if result.is_a?(RubyReactor::DispatchResult)
         # The step was handed off to a background worker; the run block did not
         # execute here. Rename the span so it is not confused with the real
         # execution span emitted later under the resumed reactor span.
@@ -502,9 +502,9 @@ module RubyReactor
 
       case result
       when RubyReactor::Success
-        if result.skipped?
-          span.set_attribute("reactor.status", "skipped")
-          span.set_attribute("reactor.skipped_reason", result.reason.to_s)
+        if result.halted?
+          span.set_attribute("reactor.status", "halted")
+          span.set_attribute("reactor.halt_reason", result.reason.to_s)
           span.status = ::OpenTelemetry::Trace::Status.ok
         else
           span.set_attribute("reactor.status", "completed")
@@ -578,7 +578,10 @@ module RubyReactor
 
       case result
       when RubyReactor::Success
-        if result.skipped?
+        if result.halted?
+          span.set_attribute("step.status", "halted")
+          span.set_attribute("step.halt_reason", result.reason.to_s)
+        elsif result.skipped?
           span.set_attribute("step.status", "skipped")
           span.set_attribute("step.skipped_reason", result.reason.to_s)
         else

data/lib/ruby_reactor/ordered_lock.rb

@@ -62,11 +62,11 @@ module RubyReactor
     #   via the stored context status.
     # - `:skip_chain_failed` — only in strict mode: an earlier nonce in this
     #   sequence terminated with a Failure, so this run is short-circuited
-    #   with `Skipped(reason: :ordered_lock_chain_failed)` without executing.
+    #   with `Halt(reason: :ordered_lock_chain_failed)` without executing.
     # - `:stale_batch` — this run's epoch no longer matches the key's current
     #   generation: its batch fully drained and the numbering was reused by a
     #   newer batch. The run is short-circuited with
-    #   `Skipped(reason: :ordered_lock_stale_batch)` and must not participate.
+    #   `Halt(reason: :ordered_lock_stale_batch)` and must not participate.
     # - `:poison_advance` is collapsed to `:go` from the caller's perspective.
     def check!
       raise ArgumentError, "OrderedLock#check! requires a nonce" unless @nonce
@@ -111,7 +111,7 @@ module RubyReactor
     #
     # `failed:` records this nonce as the chain-failure marker (only the FIRST
     # failure sticks). In strict mode the marker causes subsequent nonces to
-    # short-circuit with Skipped.
+    # short-circuit with Halt.
     def advance!(failed: false)
       raise ArgumentError, "OrderedLock#advance! requires a nonce" unless @nonce
 

data/lib/ruby_reactor/reactor.rb

@@ -118,7 +118,7 @@ module RubyReactor
                                                            RubyReactor.reactor_storage_name(self.class),
                                                            intermediate_results: @context.intermediate_results)
 
-        # Even if it's an AsyncResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
+        # Even if it's an DispatchResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
         # Check storage to see if it's already finished or paused (interrupted).
         begin
           reloaded = self.class.find(@context.context_id)
@@ -167,6 +167,14 @@ module RubyReactor
       target_step = step_name
       @context.set_result(target_step, payload)
 
+      # `interrupt :x, resume: :background` — payload is validated and stored
+      # (above, in this process); the remaining work goes to a worker instead
+      # of running inline in the delivering process.
+      step_config = self.class.steps[step_name.to_sym]
+      if step_config.respond_to?(:background_resume?) && step_config.background_resume?
+        return @result = enqueue_background_resume
+      end
+
       # Resume execution
       executor = Executor.new(self.class, {}, @context)
       @result = executor.resume_execution
@@ -311,6 +319,21 @@ module RubyReactor
       save_context
     end
 
+    # Mirror of perform_async_run for the interrupt-resume path: persist the
+    # context (now carrying the validated payload) BEFORE enqueue — the job
+    # payload is identity-only (F2) — then hand the remainder to a worker.
+    def enqueue_background_resume
+      @context.status = :running
+      Executor.middlewares_for(self.class).on(:before_async_enqueue, @context)
+      save_context
+
+      @result = configuration.async_router.perform_async(@context.context_id,
+                                                         RubyReactor.reactor_storage_name(self.class),
+                                                         intermediate_results: @context.intermediate_results)
+
+      check_for_inline_completion || @result
+    end
+
     def perform_async_run
       @context.status = :running
       # Persist BEFORE enqueue — the job payload is identity-only (F2).
@@ -324,7 +347,7 @@ module RubyReactor
     end
 
     def check_for_inline_completion
-      # Even if it's an AsyncResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
+      # Even if it's an DispatchResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
       # Check storage to see if it's already finished or paused (interrupted).
       reloaded = self.class.find(@context.context_id)
       if reloaded.finished? || reloaded.context.status.to_s == "paused"

data/lib/ruby_reactor/rspec/matchers.rb

@@ -264,18 +264,18 @@ module RubyReactor
         RubyReactor.configuration.storage_adapter
       end
 
-      # Distinguishes `RubyReactor::Skipped` from a plain `Success`. Works on
-      # any object with a `skipped?` predicate.
+      # Distinguishes `RubyReactor::Halt` (a clean halt) from a plain
+      # `Success`. Works on any object with a `halted?` predicate.
       #
       # Examples:
-      #   expect(result).to be_skipped
-      #   expect(result).to be_skipped.because(:period)
-      #   expect(result).to be_skipped.at_step(:second)
-      ::RSpec::Matchers.define :be_skipped do
+      #   expect(result).to be_halted
+      #   expect(result).to be_halted.because(:period)
+      #   expect(result).to be_halted.at_step(:second)
+      ::RSpec::Matchers.define :be_halted do
         match do |subject|
           subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           actual = subject.respond_to?(:result) ? subject.result : subject
-          next false unless actual.respond_to?(:skipped?) && actual.skipped?
+          next false unless actual.respond_to?(:halted?) && actual.halted?
           next false if @expected_reason && actual.reason != @expected_reason
           next false if @expected_step && actual.step_name != @expected_step
 
@@ -292,12 +292,62 @@ module RubyReactor
 
         failure_message do |subject|
           actual = subject.respond_to?(:result) ? subject.result : subject
-          if !actual.respond_to?(:skipped?) || !actual.skipped?
-            "expected result to be Skipped, got #{actual.class}"
+          if !actual.respond_to?(:halted?) || !actual.halted?
+            "expected result to be Halt, got #{actual.class}"
           elsif @expected_reason && actual.reason != @expected_reason
-            "expected Skipped reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
+            "expected Halt reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
           else
-            "expected Skipped at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+            "expected Halt at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+          end
+        end
+
+        failure_message_when_negated do
+          "expected result not to be Halt"
+        end
+      end
+
+      # Asserts that a STEP was skipped — either the subject itself is a
+      # `RubyReactor::Skipped` result, or the execution trace records a
+      # `:skipped` entry (optionally for a specific step via `.at_step`). A
+      # halted run never satisfies this — halting and skipping are distinct.
+      #
+      # Examples:
+      #   expect(result).to be_skipped
+      #   expect(subject).to be_skipped.at_step(:maybe_sync)
+      ::RSpec::Matchers.define :be_skipped do
+        match do |subject|
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          next false if actual.respond_to?(:halted?) && actual.halted?
+
+          entries = skipped_trace_entries(subject)
+          next entries.any? { |e| e[:step].to_s == @expected_step.to_s } if @expected_step
+          next true if entries.any?
+
+          actual.respond_to?(:skipped?) && actual.skipped?
+        end
+
+        chain :at_step do |step|
+          @expected_step = step
+        end
+
+        def skipped_trace_entries(subject)
+          trace = if subject.respond_to?(:reactor_instance)
+                    subject.reactor_instance.context.execution_trace
+                  elsif subject.respond_to?(:execution_trace)
+                    subject.execution_trace
+                  else
+                    []
+                  end
+          trace.select { |e| e[:type].to_s == "skipped" }
+        end
+
+        failure_message do |subject|
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          if @expected_step
+            "expected a skipped step named #{@expected_step.inspect}, found none in the execution trace"
+          else
+            "expected result to be Skipped, got #{actual.class}"
           end
         end
 

data/lib/ruby_reactor/rspec/sidekiq_helpers.rb

@@ -38,7 +38,8 @@ module RubyReactor
         @worker_classes ||= [
           RubyReactor::Adapters::Sidekiq::Worker,
           RubyReactor::Adapters::Sidekiq::MapElementWorker,
-          RubyReactor::Adapters::Sidekiq::MapCollectorWorker
+          RubyReactor::Adapters::Sidekiq::MapCollectorWorker,
+          RubyReactor::Adapters::Sidekiq::StepWorker
         ]
       end
 

data/lib/ruby_reactor/rspec/step_executor_patch.rb

@@ -14,7 +14,7 @@ module RubyReactor
         result = super
 
         # 2. Add test-specific logic for inline async execution
-        # Only interfere if we got an AsyncResult and we are in a testing environment that supports inline execution
+        # Only interfere if we got an DispatchResult and we are in a testing environment that supports inline execution
         if should_check_inline_completion?(result)
           # Check if it finished or paused inline (e.g. Sidekiq::Testing.inline!)
           refresh_context_from_storage
@@ -75,7 +75,7 @@ module RubyReactor
       end
 
       def should_check_inline_completion?(result)
-        return false unless result.is_a?(RubyReactor::AsyncResult) || result.is_a?(RubyReactor::RetryQueuedResult)
+        return false unless result.is_a?(RubyReactor::DispatchResult) || result.is_a?(RubyReactor::RetryQueuedResult)
         return true if defined?(Sidekiq::Testing) && Sidekiq::Testing.inline?
 
         false

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)
@@ -250,8 +300,8 @@ module RubyReactor
                   end
                 end
           RubyReactor::Success.new(val)
-        when "skipped"
-          skipped_result(ctx)
+        when "halted", "skipped" # "skipped" is the legacy name for a halt
+          halted_result(ctx)
         when "running"
           # Try to determine if it is truly running or if we just missed the completion
           if @process_jobs && AsyncTestHelpers.active?
@@ -276,14 +326,14 @@ module RubyReactor
       end
 
       # A clean halt: either a `with_period` gate or a step returning
-      # `RubyReactor.Skipped(...)`. The sync run already produced the exact
-      # Skipped (reason/step intact) — surface it. For async runs the worker
+      # `RubyReactor.Halt(...)`. The sync run already produced the exact
+      # Halt (reason/step intact) — surface it. For async runs the worker
       # swallows the return value, so rebuild from the trace.
-      def skipped_result(ctx)
-        return @run_result if @run_result.is_a?(RubyReactor::Skipped)
+      def halted_result(ctx)
+        return @run_result if @run_result.is_a?(RubyReactor::Halt)
 
-        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "skipped" }
-        RubyReactor::Skipped.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
+        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "halt" }
+        RubyReactor::Halt.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
       end
 
       def success?
@@ -441,7 +491,8 @@ module RubyReactor
       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
@@ -454,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
@@ -464,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
@@ -503,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)
@@ -551,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
 
@@ -606,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/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