ruby_reactor 0.8.6 → 0.8.8

data/lib/ruby_reactor/rspec/matchers.rb

@@ -207,53 +207,101 @@ module RubyReactor
         end
       end
 
+      # The subject's last `resume` was accepted and handed to a worker (010
+      # FR-009, FR-019): it returned a DispatchResult and the run is `running`.
+      # Use with `resume(..., process_jobs: false)`, before draining.
+      ::RSpec::Matchers.define :be_resume_deferred do
+        match do |subject|
+          subject.ensure_executed!
+          subject.last_resume_result.is_a?(RubyReactor::DispatchResult) &&
+            subject.reactor_instance.context.status.to_s == "running"
+        end
+
+        failure_message do |subject|
+          "expected the last resume to be deferred to a worker (DispatchResult, status running), but it " \
+            "returned #{subject.last_resume_result.class} and the status is " \
+            "#{subject.reactor_instance.context.status}"
+        end
+
+        failure_message_when_negated do |_subject|
+          "expected the last resume not to be deferred, but it was handed to a worker"
+        end
+      end
+
+      # The map rolled its completed elements back with one `undo_all` call
+      # (010 US7); `.with_elements(n)` checks how many results it was given.
+      ::RSpec::Matchers.define :have_run_undo_all do |step_name|
+        chain(:with_elements) { |count| @count = count }
+
+        match do |subject|
+          subject.ensure_executed!
+          @entries = subject.reactor_instance.context.execution_trace.select do |entry|
+            fetch = ->(key) { entry[key] || entry[key.to_s] }
+            fetch.call(:type).to_s == "undo_all" && fetch.call(:step).to_s == step_name.to_s
+          end
+          @entries.any? && (@count.nil? || @entries.any? { |e| (e[:count] || e["count"]).to_i == @count })
+        end
+
+        failure_message do |_subject|
+          counts = @entries.map { |e| e[:count] || e["count"] }
+          if @entries.empty?
+            "expected map :#{step_name} to have run undo_all, but it did not"
+          else
+            "expected map :#{step_name}'s undo_all to get #{@count} elements, but it got #{counts.inspect}"
+          end
+        end
+
+        failure_message_when_negated do |_subject|
+          "expected map :#{step_name} not to have run undo_all, but it did"
+        end
+      end
+
       # Matcher to check if reactor is paused at a specific interrupt step
       # Works with both single and multiple concurrent interrupts
       matcher :be_paused_at do |*step_names|
+        # A step inside a composed child is named by its path, e.g. `[:fulfil, :approve]`.
+        expected = -> { step_names.map { |name| RubyReactor::Reactor.interrupt_key(name).inspect }.join(", ") }
+
         match do |subject|
           subject.ensure_executed!
           return false unless subject.paused?
 
           ready_steps = subject.ready_interrupt_steps
-          step_names.all? { |name| ready_steps.include?(name.to_sym) }
+          step_names.all? { |name| ready_steps.include?(RubyReactor::Reactor.interrupt_key(name)) }
         end
 
         failure_message do |subject|
           if subject.paused?
-            ready_steps = subject.ready_interrupt_steps
-            if step_names.size == 1
-              "expected reactor to be paused at :#{step_names.first}, " \
-                "but ready interrupt steps are: #{ready_steps.inspect}"
-            else
-              "expected reactor to be paused at #{step_names.map { |s| ":#{s}" }.join(", ")}, " \
-                "but ready interrupt steps are: #{ready_steps.inspect}"
-            end
+            "expected reactor to be paused at #{expected.call}, " \
+              "but ready interrupt steps are: #{subject.ready_interrupt_steps.inspect}"
           else
-            "expected reactor to be paused at #{step_names.map { |s| ":#{s}" }.join(", ")}, " \
+            "expected reactor to be paused at #{expected.call}, " \
               "but status was #{subject.reactor_instance.context.status}"
           end
         end
 
         failure_message_when_negated do |_subject|
-          "expected reactor not to be paused at #{step_names.map { |s| ":#{s}" }.join(", ")}, but it is"
+          "expected reactor not to be paused at #{expected.call}, but it is"
         end
       end
 
       # Matcher to check the exact set of ready interrupt steps
       matcher :have_ready_interrupts do |*expected_steps|
+        # A step inside a composed child is named by its path, e.g. `[:fulfil, :approve]`.
+        expected = -> { expected_steps.map { |name| RubyReactor::Reactor.interrupt_key(name) } }
+
         match do |subject|
           subject.ensure_executed!
           return false unless subject.paused?
 
-          actual_steps = subject.ready_interrupt_steps.sort
-          expected = expected_steps.map(&:to_sym).sort
-          actual_steps == expected
+          # Symbols and paths (Arrays) do not compare: sort by their inspect.
+          subject.ready_interrupt_steps.sort_by(&:inspect) == expected.call.sort_by(&:inspect)
         end
 
         failure_message do |subject|
           if subject.paused?
             actual_steps = subject.ready_interrupt_steps
-            "expected ready interrupt steps to be #{expected_steps.map { |s| ":#{s}" }}, " \
+            "expected ready interrupt steps to be #{expected.call}, " \
               "but got #{actual_steps.inspect}"
           else
             "expected reactor to be paused with ready interrupt steps, " \
@@ -263,7 +311,7 @@ module RubyReactor
 
         failure_message_when_negated do |subject|
           actual_steps = subject.ready_interrupt_steps
-          "expected ready interrupt steps not to be #{expected_steps.map { |s| ":#{s}" }}, " \
+          "expected ready interrupt steps not to be #{expected.call}, " \
             "but it was #{actual_steps.inspect}"
         end
       end

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -6,7 +6,7 @@ module RubyReactor
     class TestSubject
       include ::RSpec::Mocks::ExampleMethods
 
-      attr_reader :reactor_instance, :run_result
+      attr_reader :reactor_instance, :run_result, :last_resume_result
 
       def initialize(reactor_class:, inputs:, context: {}, async: nil, process_jobs: true)
         @reactor_class = reactor_class
@@ -405,6 +405,12 @@ module RubyReactor
         @reactor_instance.context.status.to_s == "paused"
       end
 
+      # Paused at an interrupt, or running (a resume or background work in
+      # progress): either takes a resume for a ready interrupt (010 FR-017).
+      def resumable?
+        %w[paused running].include?(@reactor_instance.context.status.to_s)
+      end
+
       # Whether the run's rollback handed off at a fan-out map and has not
       # finished (009). Reloads, so it reflects jobs performed since.
       def rolling_back?
@@ -426,48 +432,43 @@ module RubyReactor
       # Get all ready interrupt steps (steps that can be resumed)
       # This is useful when multiple interrupts are waiting concurrently.
       #
-      # @return [Array<Symbol>] list of ready interrupt step names
+      # @return [Array<Symbol, Array<Symbol>>] the reactor's own interrupts by
+      #   name, and one inside a composed child by its step path
+      #   (e.g. `[:fulfil, :approve]`)
       def ready_interrupt_steps
         ensure_executed!
-        return [] unless paused?
-
-        # Build the dependency graph and get ready steps
-        graph = RubyReactor::DependencyGraph.new
-        graph_manager = RubyReactor::Executor::GraphManager.new(
-          @reactor_class, graph, @reactor_instance.context
-        )
-        graph_manager.build_and_validate!
-        graph_manager.mark_completed_steps_from_context
-
-        # Filter to only interrupt steps (using interrupt? predicate method)
-        ready = graph_manager.dependency_graph.ready_steps
-        ready.select { |step_config| step_config.respond_to?(:interrupt?) && step_config.interrupt? }
-             .map { |step_config| step_config.name.to_sym }
+        @reactor_instance.ready_interrupt_steps
       end
 
       # Resume a paused reactor with the given payload
       #
       # @param payload [Hash] The data to provide to the interrupt step
-      # @param step [Symbol, String, nil] The specific interrupt step to resume.
+      # @param step [Symbol, String, Array, nil] The specific interrupt step to resume,
+      #   or the step path of one inside a composed child (e.g. `[:fulfil, :approve]`).
       #   Required when multiple interrupts are ready. If not provided and only
       #   one interrupt is ready, that step will be used.
+      # @param process_jobs [Boolean, nil] false leaves a hand-off pending (to
+      #   assert `be_resume_deferred`); nil keeps the subject's setting
       # @return [TestSubject] self for chaining and introspection
       # @raise [Error::ValidationError] if the reactor is not paused, step is ambiguous, or payload is invalid
-      def resume(payload: {}, step: nil)
+      def resume(payload: {}, step: nil, process_jobs: nil)
         ensure_executed!
 
-        unless paused?
+        # A paused run, or a running one with a ready interrupt, mirroring
+        # `continue` (010 FR-017).
+        unless resumable?
           raise RubyReactor::Error::ValidationError,
-                "Cannot resume: reactor is not paused (status: #{@reactor_instance.context.status})"
+                "Cannot resume: reactor is not paused or running (status: #{@reactor_instance.context.status})"
         end
 
         step_name = determine_resume_step(step)
 
         # Use the reactor's continue method
-        @reactor_instance.continue(payload: payload, step_name: step_name)
+        @last_resume_result = @reactor_instance.continue(payload: payload, step_name: step_name)
 
         # Process any pending async jobs
-        process_pending_jobs if @process_jobs && AsyncTestHelpers.active?
+        drain = process_jobs.nil? ? @process_jobs : process_jobs
+        process_pending_jobs if drain && AsyncTestHelpers.active?
 
         # Reload the reactor instance to get updated state
         @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
@@ -483,10 +484,10 @@ module RubyReactor
 
         if step
           # User explicitly specified a step
-          step_sym = step.to_sym
+          step_sym = RubyReactor::Reactor.interrupt_key(step)
           unless ready_steps.include?(step_sym)
             raise RubyReactor::Error::ValidationError,
-                  "Cannot resume: step :#{step} is not ready. Ready steps: #{ready_steps.inspect}"
+                  "Cannot resume: step #{step_sym.inspect} is not ready. Ready steps: #{ready_steps.inspect}"
           end
           step_sym
         elsif ready_steps.size == 1

data/lib/ruby_reactor/step/compose_step.rb

@@ -74,6 +74,8 @@ module RubyReactor
         unless child_context
           composed_inputs = build_composed_inputs(inputs.argument_mappings || {})
           child_context = RubyReactor::Context.new(composed_inputs, inputs.composed_reactor_class)
+          # Resumed only through this run, never on its own (010 R-07).
+          child_context.private_data[:composed] = true
         end
 
         link_contexts(child_context, context)
@@ -120,6 +122,14 @@ module RubyReactor
         # the metadata the direct and async paths do propagate.
         return result if result.is_a?(RubyReactor::Failure)
 
+        # The child paused at an interrupt: so does this run. Each compose
+        # level re-stamps its own id, so the top-level result names the root.
+        if result.is_a?(RubyReactor::InterruptResult)
+          return RubyReactor::InterruptResult.new(execution_id: context.context_id,
+                                                  correlation_id: result.correlation_id,
+                                                  intermediate_results: context.intermediate_results)
+        end
+
         result.success? ? RubyReactor.Success(result.value) : RubyReactor.Failure(result.error)
       end
     end

data/lib/ruby_reactor/step/map_step.rb

@@ -19,6 +19,7 @@ module RubyReactor
       input :collect_block, optional: true
       input :atomic, optional: true
       input :fan_out, optional: true
+      input :undo_all_block, optional: true
 
       def run
         # Initialize map state in context if not present
@@ -46,9 +47,14 @@ module RubyReactor
       # A map rolls back where it ran (009 R-01): a fan-out map one job per
       # started element, `batch_size` per throw, handing the run off until
       # they all report; an inline map in process, 100 elements per read.
+      #
+      # A map declaring `undo_all` rolls its completed elements back with one
+      # call to that block instead (010 R-13).
       def compensate
         step_name = context.current_step
         map_id = "#{context.context_id}:#{step_name}"
+        return bulk_rollback(map_id, step_name, undo_all_block) if undo_all_block
+
         dispatched_map_id(step_name) ? distributed_rollback(map_id, step_name) : inline_rollback(map_id, step_name)
       end
 
@@ -115,6 +121,12 @@ module RubyReactor
         context.reactor_class.steps[context.current_step].arguments[:mapped_reactor_class][:source].value
       end
 
+      # The `undo_all` block, from the same static declaration (009 R-14): the
+      # undo record carries no arguments.
+      def undo_all_block
+        context.reactor_class.steps[context.current_step].arguments[:undo_all_block]&.dig(:source)&.value
+      end
+
       # Fans out anywhere except inside a map element: an element's result and
       # the map's completion counter are tracked by its own ElementExecutor job,
       # so a nested hand-off there would escape that tracking. A reactor worker

data/lib/ruby_reactor/storage/adapter.rb

@@ -112,6 +112,23 @@ module RubyReactor
         raise NotImplementedError
       end
 
+      def retrieve_map_result_slots(map_id, reactor_class_name, indexes)
+        raise NotImplementedError
+      end
+
+      # Interrupt resume claims and attempt counts (010 DM §2, §3).
+      def claim_interrupt_resume(context_id, reactor_class_name, step_name, serialized_payload)
+        raise NotImplementedError
+      end
+
+      def retrieve_interrupt_resumes(context_id, reactor_class_name, step_names)
+        raise NotImplementedError
+      end
+
+      def increment_interrupt_attempts(context_id, reactor_class_name, step_name)
+        raise NotImplementedError
+      end
+
       # Map rollback records (009 DM §5); see RedisMapRollback.
       %i[count_map_element_context_ids retrieve_map_element_context_ids_from_tail start_map_rollback
          retrieve_map_rollback_metadata claim_map_rollback_positions retrieve_map_rollback_offset

data/lib/ruby_reactor/storage/redis_adapter.rb

@@ -286,6 +286,44 @@ module RubyReactor
         @redis.hlen(key)
       end
 
+      # Result slots at `indexes`, aligned with them: nil where a slot is
+      # missing (expired), else the stored value, JSON-parsed (010 R-13).
+      def retrieve_map_result_slots(map_id, reactor_class_name, indexes)
+        return [] if indexes.empty?
+
+        @redis.hmget(map_results_key(map_id, reactor_class_name), *indexes.map(&:to_s)).map do |raw|
+          raw && JSON.parse(raw)
+        end
+      end
+
+      # A resume's claim on one interrupt (010 DM §2): the first `SET NX` wins,
+      # and the value holds the payload until the run's lock owner applies it.
+      # Never deleted; it expires with the run and stays the dedupe marker.
+      def claim_interrupt_resume(context_id, reactor_class_name, step_name, serialized_payload) # rubocop:disable Naming/PredicateMethod
+        !!@redis.set(interrupt_resume_key(context_id, reactor_class_name, step_name), serialized_payload,
+                     nx: true, ex: durability_ttl)
+      end
+
+      # `{ "step" => serialized_payload }` for the claimed ones among `step_names`.
+      def retrieve_interrupt_resumes(context_id, reactor_class_name, step_names)
+        names = Array(step_names).map(&:to_s)
+        return {} if names.empty?
+
+        values = @redis.mget(*names.map { |name| interrupt_resume_key(context_id, reactor_class_name, name) })
+        names.zip(values).to_h.compact
+      end
+
+      # Invalid resume payloads counted per interrupt (010 DM §3), kept out of
+      # the context blob so counting never writes the run.
+      def increment_interrupt_attempts(context_id, reactor_class_name, step_name)
+        key = "#{context_key(context_id, reactor_class_name)}:resume_attempts:#{step_name}"
+        count, = @redis.multi do |tx|
+          tx.incr(key)
+          tx.expire(key, durability_ttl)
+        end
+        count
+      end
+
       private
 
       # Single source of truth for the retention window of all durability-bearing
@@ -297,6 +335,10 @@ module RubyReactor
         RubyReactor.configuration.context_ttl
       end
 
+      def interrupt_resume_key(context_id, reactor_class_name, step_name)
+        "#{context_key(context_id, reactor_class_name)}:resume:#{step_name}"
+      end
+
       def context_key(context_id, reactor_class_name)
         "reactor:#{reactor_class_name}:context:#{context_id}"
       end

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.8.6"
+  VERSION = "0.8.8"
 end

data/lib/ruby_reactor/web/api.rb

@@ -81,6 +81,8 @@ module RubyReactor
                 ),
                 error: data[:failure_reason]
               }
+              pending = self.class.pending_compensation(api_status, data[:rollback])
+              response_data[:pending_compensation] = pending if pending
 
               ContextSerializer.simplify_for_api(response_data)
             end
@@ -152,6 +154,9 @@ module RubyReactor
                 if result.is_a?(RubyReactor::Failure)
                   response.status = 422
                   { error: result.error }
+                elsif result.is_a?(RubyReactor::DispatchResult)
+                  # Accepted and handed to a worker (010 FR-009, FR-019).
+                  { success: true, message: "Resume accepted" }
                 else
                   { success: true, message: "Reactor resumed" }
                 end
@@ -164,6 +169,18 @@ module RubyReactor
         end
       end
 
+      # An aborted run whose failing step's `compensate` an interruption cut
+      # off (010 R-11): a manual undo runs it again first.
+      def self.pending_compensation(status, rollback)
+        return unless status == "aborted" && rollback.is_a?(Hash)
+
+        fetch = ->(key) { Utils::FetchIndifferent.call(rollback, key) }
+        return unless rollback.key?("arguments") || rollback.key?(:arguments)
+        return unless fetch.call(:compensated) == false
+
+        { step: fetch.call(:step).to_s }
+      end
+
       def self.scan_limit(raw)
         limit = raw.to_i
         return 50 unless limit.positive?