ruby_reactor 0.8.5 → 0.8.7

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -7,6 +7,7 @@ module RubyReactor
       include RubyReactor::Dsl::ValidationHelpers
       include RubyReactor::Dsl::Lockable::ClassMethods
       include RubyReactor::Dsl::Retryable
+      include RubyReactor::Dsl::DefinitionWarnings
 
       COORDINATION_MACROS = {
         lock_config: "with_lock", semaphore_config: "with_semaphore", rate_limit_config: "with_rate_limit",
@@ -34,11 +35,6 @@ module RubyReactor
         @rule_sites = []
       end
 
-      # Deprecation notices print once per declaration site for the process.
-      def self.deprecation_sites
-        @deprecation_sites ||= Set.new
-      end
-
       def argument(name, source, type = nil, transform: nil, **predicates)
         @arguments[name] = {
           source: source,
@@ -244,25 +240,9 @@ module RubyReactor
                                               "the step instead (`validate_inputs` in #{target}).")
       end
 
-      def warn_deprecation(site, message)
-        warn_definition(site, "DEPRECATION:", "#{message} Removal no earlier than the next MAJOR.")
-      end
-
-      # A definition-time warning, printed once per declaration site.
-      def warn_definition(site, prefix, message)
-        location = "#{site.path}:#{site.lineno}"
-        return unless StepBuilder.deprecation_sites.add?(location)
-
-        warn ["[RubyReactor]", prefix, location, reactor_label, message].compact.join(" ")
-      end
-
       def owned_contract
         @inline_contract || (@impl.input_contract if @impl.respond_to?(:declares_inputs?) && @impl.declares_inputs?)
       end
-
-      def reactor_label
-        @reactor&.name || @reactor.inspect
-      end
     end
 
     class StepConfig
@@ -450,6 +430,13 @@ module RubyReactor
         rollback_tracked? && has_impl? && impl.respond_to?(:undoes_partial_run?) && impl.undoes_partial_run?
       end
 
+      # What the undo record keeps of the step's resolved arguments: all of
+      # them, unless the step reads its rollback state elsewhere (a map reads
+      # its declaration and the map records, 009 R-14).
+      def rollback_arguments(resolved)
+        has_impl? && impl.respond_to?(:rollback_arguments) ? impl.rollback_arguments(resolved) : resolved
+      end
+
       def has_impl?
         !@impl.nil?
       end

data/lib/ruby_reactor/error/rescuable.rb

@@ -12,11 +12,16 @@ module RubyReactor
     # raises — rescuing that would stop the caller's timeout from ever firing.
     # Running rollback code during any of them is unsafe; the executor marks
     # the run `aborted` for a manual undo instead.
+    #
+    # Nor does it match `RollbackHandedOff`, a control signal (009 R-04): it
+    # must pass the `rescue Error::Rescuable` sites between `MapStep#undo` and
+    # the executor (`CompensationManager#undo_step`, `StepExecutor`), which
+    # would otherwise record it as an undo failure.
     module Rescuable
       INTERRUPTIONS = [SignalException, SystemExit, NoMemoryError].freeze
 
       def self.===(exception)
-        exception.is_a?(Exception) && !interruption?(exception)
+        exception.is_a?(Exception) && !interruption?(exception) && !exception.is_a?(RollbackHandedOff)
       end
 
       def self.interruption?(exception)

data/lib/ruby_reactor/error/rollback_handed_off.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A control signal, never a failure (009 R-04): a fan-out map started its
+    # distributed rollback and must wait for its element jobs. Raised from
+    # `MapStep#compensate` / `#undo`, it unwinds the rollback without popping
+    # the map's undo entry (the resume cursor), passes every `rescue
+    # Error::Rescuable` (see `Rescuable.===`), and is rescued only by
+    # `Executor` and `Reactor#undo`, which record where the rollback stands,
+    # save, and hand the run off as `rolling_back`.
+    #
+    # `failure` carries the Failure the run will end with, minus its rollback
+    # failures, set by the `ResultHandler` it passes through and consumed by
+    # the executor of that level.
+    class RollbackHandedOff < Base
+      attr_reader :map_id, :reactor_class_name
+      attr_accessor :failure
+
+      def initialize(map_id:, reactor_class_name: nil, message: "rollback handed off at map #{map_id}")
+        super(message)
+        @map_id = map_id
+        @reactor_class_name = reactor_class_name
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -30,11 +30,29 @@ module RubyReactor
       # (005 FR-004). `ResultHandler` attaches it to the final Failure.
       attr_reader :undo_trace, :rollback_failures
 
+      # The step failure being rolled back: `{ step:, error:, compensated:,
+      # compensation_error: }`. A rollback that hands off (009 R-04) records it,
+      # so the resume knows whether that step's own compensate still runs.
+      attr_reader :pending
+
+      # Rollback failures collected before a hand-off, saved serialized on
+      # the context's `rollback` and restored on resume.
+      def restore_rollback_failures(list)
+        @rollback_failures.replace(Array(ContextSerializer.deserialize_value(list)))
+      end
+
+      # A step that paused (a compose whose child hit an interrupt) is already
+      # on top as a partial run; its re-run replaces that entry, so the step is
+      # undone once (010 R-04).
+      # ponytail: assumes the paused step's entry is on top when it re-runs,
+      # which holds because a run stops at a pause and resumes at that step.
       def add_to_undo_stack(step_info)
+        undo_stack.pop if undo_stack.last && undo_stack.last[:step].name == step_info[:step].name
         @context.undo_stack << step_info
       end
 
       def handle_step_failure(step_config, error, arguments)
+        @pending = { step: step_config.name, error: error, compensated: false }
         # A step whose OWN coordination acquisition failed (contention, or a
         # bad key proc) never ran its body — "no step compensates, the
         # contended step's work has not been attempted" (US3-1/T018), which
@@ -44,29 +62,38 @@ module RubyReactor
         # turning a plain contention failure into a confusing
         # CompensationError. Prior steps still roll back normally.
         if step_never_started?(error)
+          @pending[:compensated] = true
           rollback_completed_steps
-          return RubyReactor.Failure("Step '#{step_config.name}' failed: #{error}")
+          return RubyReactor.Failure(step_failure_message(step_config, error))
         end
 
         # Try compensation
         compensation_result = compensate_step(step_config, error, arguments)
+        @pending[:compensated] = true
+        @pending[:compensation_error] = compensation_error_message(step_config, compensation_result)
         case compensation_result
         when RubyReactor::Success
           # Compensation succeeded, continue with rollback
           rollback_completed_steps
-          RubyReactor.Failure("Step '#{step_config.name}' failed: #{error}")
+          RubyReactor.Failure(step_failure_message(step_config, error))
         when RubyReactor::Failure
           # Compensation failed, this is more serious
           rollback_completed_steps
-          raise Error::CompensationError.new(
-            "Compensation for step '#{step_config.name}' failed: #{compensation_result.error}",
-            step: step_config.name,
-            context: @context,
-            original_error: error
-          )
+          raise Error::CompensationError.new(@pending[:compensation_error], step: step_config.name, context: @context,
+                                                                            original_error: error)
         end
       end
 
+      def step_failure_message(step_config, error)
+        "Step '#{step_config.name}' failed: #{error}"
+      end
+
+      def compensation_error_message(step_config, compensation_result)
+        return unless compensation_result.is_a?(RubyReactor::Failure)
+
+        "Compensation for step '#{step_config.name}' failed: #{compensation_result.error}"
+      end
+
       # A unit that compensates itself outside the executor loop (StepWorker's
       # `async_step`): the same coordination re-take, trace, middleware events
       # and `rollback_failures` as a step compensated here.
@@ -77,7 +104,9 @@ module RubyReactor
       # Newest first. Each entry leaves the stack only once its undo returned,
       # so an interruption mid-rollback leaves exactly the entries still to
       # undo — the interrupted one included — for a manual undo (008 R-16).
-      def rollback_completed_steps
+      # `after_pop` runs after each pop: an element rollback job saves there,
+      # so a redelivery resumes after the last undone entry (009 R-07).
+      def rollback_completed_steps(&after_pop)
         until undo_stack.empty?
           step_info = undo_stack.last
           result = @context.with_step(step_info[:step].name) do
@@ -86,6 +115,7 @@ module RubyReactor
           undo_stack.pop
           @undo_trace << { type: :undo, step: step_info[:step].name, result: result,
                            arguments: step_info[:arguments] }
+          after_pop&.call
         end
       end
 

data/lib/ruby_reactor/executor/result_handler.rb

@@ -27,6 +27,8 @@ module RubyReactor
           handle_retries_exhausted(step_config, result, resolved_arguments)
         when RubyReactor::Failure
           handle_failure(step_config, result, resolved_arguments)
+        when RubyReactor::InterruptResult
+          handle_interrupted(step_config, resolved_arguments)
         else
           handle_unknown_result(step_config, result, resolved_arguments)
         end
@@ -35,9 +37,13 @@ module RubyReactor
       # Every reactor-level Failure that follows a rollback is built here, so
       # this is the one place `rollback_failures` is attached (005 R-08).
       def handle_execution_error(error)
-        failure = build_execution_failure(error)
-        failure.rollback_failures.concat(@compensation_manager.rollback_failures) if failure.is_a?(RubyReactor::Failure)
-        failure
+        with_rollback_failures(build_execution_failure(error))
+      end
+
+      # The end of a rollback that handed off (009 R-04): the Failure recorded
+      # at the hand-off, with every rollback failure collected since.
+      def handed_off_failure(failure)
+        with_rollback_failures(failure)
       end
 
       def final_result(reactor_class)
@@ -51,34 +57,62 @@ module RubyReactor
 
       private
 
+      def with_rollback_failures(failure)
+        failure.rollback_failures.concat(@compensation_manager.rollback_failures) if failure.is_a?(RubyReactor::Failure)
+        failure
+      end
+
+      # Every error rolls back the completed steps first (Constitution II), then
+      # becomes the run's Failure.
       def build_execution_failure(error)
+        if error.is_a?(Error::StepFailureError)
+          current_context = error.context || @context
+          current_context.current_step = error.step
+          store_failed_map_context(current_context) if current_context.map_metadata
+        end
+        handing_off_as(error) { @compensation_manager.rollback_completed_steps }
+        failure_for(error)
+      end
+
+      # A rollback that hands off mid-way (009 R-04) carries the Failure this
+      # run will end with, minus its rollback failures, to the executor that
+      # records the hand-off. `error` is what the run fails with once the
+      # rollback is done (a lambda when it is costly or not built yet).
+      def handing_off_as(error)
+        yield
+      rescue Error::RollbackHandedOff => e
+        e.failure ||= failure_for(error.respond_to?(:call) ? error.call : error)
+        raise
+      end
+
+      def failure_for(error)
         case error
         when Error::StepFailureError
-          handle_step_failure_error(error)
+          create_failure_from_error(error, redacted_input_names(error.context))
         when Error::InputValidationError
           # Unified validation failure shape (inputs, step args, step output).
-          # Roll back any completed steps so saga semantics hold for mid-reactor
-          # validation failures (a no-op for input validation at reactor start).
-          @compensation_manager.rollback_completed_steps
           build_validation_failure(error)
         when Error::Base
-          # Other errors need rollback. A `CompensationError` names the step
-          # whose compensation failed.
-          @compensation_manager.rollback_completed_steps
+          # A `CompensationError` names the step whose compensation failed.
           RubyReactor.Failure("Execution error: #{error.message}", exception_class: error.class.name,
                                                                    step_name: error.step || @context.current_step,
                                                                    reactor_name: @context.reactor_class&.name)
         else
           # Any other StandardError after completed work (a checkpoint write,
-          # a hook) still leaves a partial saga: roll it back like any failure
-          # (Constitution II, 008 R-07) and name the step that was executing.
-          @compensation_manager.rollback_completed_steps
+          # a hook) still leaves a partial saga, rolled back like any failure
+          # (Constitution II, 008 R-07); name the step that was executing.
           RubyReactor.Failure("Execution failed: #{error.message}", exception_class: error.class.name,
                                                                     step_name: @context.current_step,
                                                                     reactor_name: @context.reactor_class&.name)
         end
       end
 
+      def redacted_input_names(context)
+        return [] unless context&.reactor_class
+
+        context.reactor_class.inputs.select { |_, config| config[:redact] }.keys
+      end
+
       # Failure for a validation error (reactor inputs, step arguments, or
       # step output), carrying both the structured field errors and the step/
       # reactor attribution stamped at the raise site (nil step_name for
@@ -116,6 +150,20 @@ module RubyReactor
         result
       end
 
+      # A composed child paused at an interrupt (010): the step stays
+      # incomplete, and this run pauses on it. `with_step` cleared
+      # `current_step` on the way out; it is the run's resume cursor. The
+      # child's completed steps are only undone through this step, so it joins
+      # the undo stack as a partial run, as an interrupted compose does (R-04).
+      def handle_interrupted(step_config, resolved_arguments)
+        @context.current_step = step_config.name
+        return unless step_config.undoes_partial_run?
+
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(resolved_arguments),
+                                                  result: RubyReactor.Success(nil) })
+      end
+
       # A step returned `RubyReactor.Skipped(...)`: the run continues exactly as
       # for a Success (value, hand-off, period mark), but the step is NOT pushed
       # for undo — it had nothing to do, so there is nothing to revert (008 R-19).
@@ -139,7 +187,8 @@ module RubyReactor
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
         if step_config.rollback_tracked?
-          @compensation_manager.add_to_undo_stack({ step: step_config, arguments: resolved_arguments,
+          @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                    arguments: step_config.rollback_arguments(resolved_arguments),
                                                     result: result })
         end
         @context.set_result(step_config.name, result.value)
@@ -156,36 +205,38 @@ module RubyReactor
 
       def handle_retries_exhausted(step_config, result, resolved_arguments)
         adopt_rollback_failures(result)
-        @compensation_manager.handle_step_failure(step_config, result.original_error, resolved_arguments)
-        orig_err = result.original_error.is_a?(Exception) ? result.original_error : nil
-        error = Error::StepFailureError.new(result.error, step: step_config.name, context: @context,
-                                                          original_error: orig_err,
-                                                          step_arguments: resolved_arguments,
-                                                          validation_errors: result.validation_errors)
-        if result.respond_to?(:backtrace) && result.backtrace
-          error.set_backtrace(result.backtrace)
-        elsif orig_err
-          error.set_backtrace(orig_err.backtrace)
+        error = step_failure_error(step_config, result.error, result, resolved_arguments, cause: result.original_error)
+        handing_off_as(error) do
+          @compensation_manager.handle_step_failure(step_config, result.original_error, resolved_arguments)
         end
         raise error
       end
 
       def handle_failure(step_config, result, resolved_arguments)
         adopt_rollback_failures(result)
-        failure_result = @compensation_manager.handle_step_failure(step_config, result.error, resolved_arguments)
-        orig_err = result.error.is_a?(Exception) ? result.error : nil
-        # A step that propagates another unit's validation failure (an
-        # async_step reader) keeps its field errors on the reactor's failure.
-        error = Error::StepFailureError.new(failure_result.error, step: step_config.name, context: @context,
-                                                                  original_error: orig_err,
-                                                                  step_arguments: resolved_arguments,
-                                                                  validation_errors: result.validation_errors)
+        message = @compensation_manager.step_failure_message(step_config, result.error)
+        failure_result = handing_off_as(-> { step_failure_error(step_config, message, result, resolved_arguments) }) do
+          @compensation_manager.handle_step_failure(step_config, result.error, resolved_arguments)
+        end
+        raise step_failure_error(step_config, failure_result.error, result, resolved_arguments)
+      end
+
+      # A step that propagates another unit's failure (an async_step reader, a
+      # map adopting a fan-out element's Failure) keeps its field errors and
+      # exception class on the reactor's failure.
+      def step_failure_error(step_config, message, result, resolved_arguments, cause: result.error)
+        orig_err = cause.is_a?(Exception) ? cause : nil
+        error = Error::StepFailureError.new(message, step: step_config.name, context: @context,
+                                                     original_error: orig_err,
+                                                     step_arguments: resolved_arguments,
+                                                     exception_class: (result.exception_class unless orig_err),
+                                                     validation_errors: result.validation_errors)
         if result.respond_to?(:backtrace) && result.backtrace
           error.set_backtrace(result.backtrace)
         elsif orig_err
           error.set_backtrace(orig_err.backtrace)
         end
-        raise error
+        error
       end
 
       # Wrapped first, so a returned `Step::Inputs` is validated and stored as its Hash.
@@ -193,31 +244,16 @@ module RubyReactor
         success_result = RubyReactor.Success(result)
         validate_step_output(step_config, success_result.value, resolved_arguments)
         @step_results[step_config.name] = success_result
-        @compensation_manager.add_to_undo_stack({ step: step_config, arguments: resolved_arguments,
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(resolved_arguments),
                                                   result: success_result })
         @context.set_result(step_config.name, success_result.value)
         @dependency_graph.complete_step(step_config.name)
       end
 
-      def handle_step_failure_error(error)
-        current_context = error.context || @context
-        current_context.current_step = error.step
-
-        store_failed_map_context(current_context) if current_context.map_metadata
-
-        @compensation_manager.rollback_completed_steps
-
-        redact_inputs = []
-        if error.context&.reactor_class
-          redact_inputs = error.context.reactor_class.inputs.select { |_, config| config[:redact] }.keys
-        end
-
-        create_failure_from_error(error, redact_inputs)
-      end
-
       def store_failed_map_context(context)
         return unless context.map_metadata && context.map_metadata[:map_id]
-        return unless context.map_metadata[:fail_fast]
+        return unless Map::Helpers.normalize_arguments(context.map_metadata)[:atomic]
 
         storage = RubyReactor.configuration.storage_adapter
         storage.store_map_failed_context_id(
@@ -276,7 +312,7 @@ module RubyReactor
         # compensation and roll back prior steps, so the side effect is not
         # orphaned. Then surface the structured validation error (the later
         # rollback in handle_execution_error is a no-op — stack already clear).
-        @compensation_manager.handle_step_failure(step_config, error, resolved_arguments)
+        handing_off_as(error) { @compensation_manager.handle_step_failure(step_config, error, resolved_arguments) }
         raise error
       end
 

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -61,7 +61,7 @@ module RubyReactor
         serialized_context = ContextSerializer.serialize(context_to_serialize)
 
         if @context.map_metadata
-          map_args = @context.map_metadata.transform_keys(&:to_sym)
+          map_args = Map::Helpers.normalize_arguments(@context.map_metadata)
           configuration.async_router.perform_map_element_in(
             delay,
             map_id: map_args[:map_id],
@@ -75,7 +75,7 @@ module RubyReactor
             step_name: map_args[:step_name],
             batch_size: map_args[:batch_size],
             serialized_context: serialized_context,
-            fail_fast: map_args[:fail_fast]
+            atomic: map_args[:atomic]
           )
         else
           # Persist BEFORE enqueue — the job payload is identity-only (F2). The
@@ -108,8 +108,8 @@ module RubyReactor
           result
         when RubyReactor::Failure
           handle_failure_result(step_config, reactor_class, result)
-        when RetryQueuedResult, RubyReactor::DispatchResult
-          # Pass through async results
+        when RetryQueuedResult, RubyReactor::DispatchResult, RubyReactor::InterruptResult
+          # Pass through async results, and a composed child's pause
           result
         else
           clear_retry_state
@@ -193,7 +193,8 @@ module RubyReactor
           reactor_name: reactor_class.name,
           step_arguments: result.respond_to?(:step_arguments) ? result.step_arguments : {},
           validation_errors: result.validation_errors,
-          rollback_failures: result.rollback_failures
+          rollback_failures: result.rollback_failures,
+          exception_class: result.exception_class
         )
       end
 

data/lib/ruby_reactor/executor/step_executor.rb

@@ -133,9 +133,11 @@ module RubyReactor
       # the stack. A worker run is redelivered instead, and re-runs the step.
       def track_interrupted_construct(step_config, arguments, error)
         return if @context.inline_async_execution || Error::Rescuable === error # rubocop:disable Style/CaseEquality
+        return if error.is_a?(Error::RollbackHandedOff) # a rollback signal, not an interruption
         return unless step_config.undoes_partial_run?
 
-        @compensation_manager.add_to_undo_stack({ step: step_config, arguments: arguments,
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(arguments),
                                                   result: RubyReactor.Success(nil) })
       end
 
@@ -429,6 +431,15 @@ module RubyReactor
           return RubyReactor.Success(result)
         end
 
+        # A map element cannot pause: nothing would resume it. The step fails
+        # like any other, rolling back what the element completed (010 R-08).
+        if inside_map_element?
+          failure = RubyReactor::Failure("interrupt :#{step_config.name} is not supported inside a map element",
+                                         step_name: step_config.name, reactor_name: @reactor_class.name,
+                                         retryable: false)
+          return @result_handler.handle_step_result(step_config, failure, {})
+        end
+
         # We are pausing
         correlation_id = nil
         correlation_id = step_config.correlation_id_block.call(@context) if step_config.correlation_id_block
@@ -443,6 +454,17 @@ module RubyReactor
         )
       end
 
+      # This run, or one it is composed into, is a map element.
+      def inside_map_element?
+        context = @context
+        while context
+          return true if context.map_metadata
+
+          context = context.parent_context
+        end
+        false
+      end
+
       def configuration
         RubyReactor::Configuration.instance
       end