ruby_reactor 0.8.4 → 0.8.5

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -13,7 +13,7 @@ module RubyReactor
         period_config: "with_period", ordered_lock_config: "with_ordered_lock"
       }.freeze
 
-      attr_accessor :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
+      attr_accessor :name, :impl, :arguments, :run_block, :compensate_block, :undo_block,
                     :dependencies, :args_validator, :output_validator
 
       def initialize(name, impl = nil, reactor = nil)
@@ -24,8 +24,6 @@ module RubyReactor
         @run_block = nil
         @compensate_block = nil
         @undo_block = nil
-        @conditions = []
-        @guards = []
         @dependencies = []
         @arg_validations = []
         @validate_args_input = nil
@@ -78,12 +76,15 @@ module RubyReactor
         @undo_block = block
       end
 
-      def where(&predicate)
-        @conditions << predicate
+      # `where`/`guard` were a second, pre-body skip mechanism with failure
+      # rules of their own (008 R-15). A step decides to skip itself from its
+      # body instead, so both stay only to name the replacement.
+      def where(*)
+        raise_removed_condition!(:where)
       end
 
-      def guard(&guard_fn)
-        @guards << guard_fn
+      def guard(*)
+        raise_removed_condition!(:guard)
       end
 
       def wait_for(*step_names)
@@ -148,8 +149,6 @@ module RubyReactor
           run_block: @run_block,
           compensate_block: @compensate_block,
           undo_block: @undo_block,
-          conditions: @conditions,
-          guards: @guards,
           dependencies: @dependencies,
           args_validator: @args_validator || build_args_validator(@arg_validations, @validate_args_input),
           output_validator: @output_validator,
@@ -167,6 +166,15 @@ module RubyReactor
 
       private
 
+      def raise_removed_condition!(keyword)
+        raise RubyReactor::Error::DeprecatedDslError.new(
+          "`#{keyword}` inside a step block has been removed (`where`/`guard` are gone). To skip " \
+          ":#{@name}, return `Skipped(value)` (or call `skip!(value)`) from its `run` body; the " \
+          "reactor continues with that value, exactly as for a Success.",
+          step: @name
+        )
+      end
+
       # The same primitive declared BOTH inline and on the step class is
       # ambiguous — two keys for one slot of the fixed acquisition order, and
       # `StepConfig`'s readers would silently let the inline one win. Refuse it
@@ -237,11 +245,15 @@ module RubyReactor
       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] DEPRECATION: #{location} #{reactor_label} #{message} " \
-             "Removal no earlier than the next MAJOR."
+        warn ["[RubyReactor]", prefix, location, reactor_label, message].compact.join(" ")
       end
 
       def owned_contract
@@ -256,7 +268,7 @@ module RubyReactor
     class StepConfig
       NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }.freeze
 
-      attr_reader :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
+      attr_reader :name, :impl, :arguments, :run_block, :compensate_block, :undo_block,
                   :dependencies, :args_validator, :output_validator, :async_dispatch,
                   :inline_contract
 
@@ -268,8 +280,6 @@ module RubyReactor
         @run_block = config[:run_block]
         @compensate_block = config[:compensate_block]
         @undo_block = config[:undo_block]
-        @conditions = config[:conditions] || []
-        @guards = config[:guards] || []
         @dependencies = config[:dependencies] || []
         @args_validator = config[:args_validator]
         @output_validator = config[:output_validator]
@@ -358,6 +368,51 @@ module RubyReactor
         input_contract ? input_contract.enforce!(args) : args
       end
 
+      # The step's `argument` wiring resolved against `context`: each source,
+      # then its `transform`. The one copy every process uses (StepExecutor,
+      # StepWorker). Any raise becomes an `ArgumentResolutionError`, a
+      # never-started failure attributed to this step (008 R-06) — except a
+      # park signal (a worker waiting on an async result), which is not a failure.
+      def resolve_arguments(context)
+        arguments.to_h do |arg_name, arg_config|
+          value = arg_config[:source].resolve(context)
+          value = arg_config[:transform].call(value) if arg_config[:transform]
+          [arg_name, value]
+        end
+      rescue Error::ExecutionParked
+        raise
+      rescue Error::Rescuable => e
+        raise never_started(Error::ArgumentResolutionError, "could not resolve its arguments", e)
+      end
+
+      # Rollback dispatch, the same wherever the step rolls back
+      # (CompensationManager, StepWorker): the inline block, else the class
+      # step, else Skipped — nothing defined, rollback continues. Coordination,
+      # trace and middleware stay with the caller.
+      def call_compensate(error, arguments, context)
+        catch(StepSignals::TAG) do
+          if compensate_block
+            compensate_block.call(error, wrap_inputs(arguments), context)
+          elsif has_impl?
+            impl.compensate(error, arguments, context)
+          else
+            RubyReactor.Skipped()
+          end
+        end
+      end
+
+      def call_undo(result_value, arguments, context)
+        catch(StepSignals::TAG) do
+          if undo_block
+            undo_block.call(result_value, wrap_inputs(arguments), context)
+          elsif has_impl?
+            impl.undo(result_value, arguments, context)
+          else
+            RubyReactor.Skipped()
+          end
+        end
+      end
+
       # The step's work as a reactor runs it. Coordination is NOT taken here:
       # the caller (StepExecutor / StepWorker) takes this config's effective
       # declarations — inline and class alike — in one fixed order around it.
@@ -381,6 +436,20 @@ module RubyReactor
         !@async_dispatch.nil?
       end
 
+      # Whether a success of this step is recorded for undo. `async_step` /
+      # `async_reactor` dispatches are independent units of work with their
+      # own compensation flows: the parent rolling back must not "undo" a
+      # dispatch whose unit runs (and may still succeed) elsewhere (008 R-10).
+      def rollback_tracked?
+        !async_dispatch?
+      end
+
+      # Whether a run of this step cut short by an interruption is still
+      # tracked for undo: the construct's own definition decides (008 R-16).
+      def undoes_partial_run?
+        rollback_tracked? && has_impl? && impl.respond_to?(:undoes_partial_run?) && impl.undoes_partial_run?
+      end
+
       def has_impl?
         !@impl.nil?
       end
@@ -403,14 +472,17 @@ module RubyReactor
         (retry_config[:max_attempts] || 0) > 1
       end
 
-      def should_run?(context)
-        @conditions.all? { |condition| condition.call(context) } &&
-          @guards.all? { |guard| guard.call(context) }
-      end
-
       def interrupt?
         false
       end
+
+      private
+
+      def never_started(error_class, what, cause)
+        error = error_class.new("Step '#{name}' #{what}: #{cause.message}", step: name, original_error: cause)
+        error.set_backtrace(cause.backtrace)
+        error
+      end
     end
   end
 end

data/lib/ruby_reactor/error/argument_resolution_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A step's `argument` source, `transform` or result path raised. The step's
+    # body never started, so it is never compensated; completed steps are
+    # undone (008 R-06). The same inputs fail the same way, so never retried.
+    class ArgumentResolutionError < Base
+      attr_reader :exception_class
+
+      def initialize(message, step:, original_error:, context: nil)
+        super(message, step: step, context: context, original_error: original_error)
+        @exception_class = original_error.class.name
+      end
+
+      def retryable? = false
+    end
+  end
+end

data/lib/ruby_reactor/error/rescuable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # `rescue Error::Rescuable` catches every exception reactor code can raise —
+    # standard or not (`NotImplementedError`, `SystemStackError`, a custom
+    # `Exception` subclass) — so it fails its step and rolls back (008 R-16).
+    #
+    # It lets through only interruptions: exceptions raised INTO running code
+    # from outside it. A signal (incl. `Interrupt`, `Sidekiq::Shutdown`), an
+    # exit, running out of memory, and the one an enclosing `Timeout.timeout`
+    # 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.
+    module Rescuable
+      INTERRUPTIONS = [SignalException, SystemExit, NoMemoryError].freeze
+
+      def self.===(exception)
+        exception.is_a?(Exception) && !interruption?(exception)
+      end
+
+      def self.interruption?(exception)
+        INTERRUPTIONS.any? { |klass| exception.is_a?(klass) } ||
+          (defined?(::Timeout::ExitException) && exception.is_a?(::Timeout::ExitException))
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -3,15 +3,17 @@
 module RubyReactor
   class Executor
     class CompensationManager
-      # Raised ONLY by the step's own coordination, before its body: a
-      # coordination error raised from inside a body (a nested direct
+      # Raised ONLY before the step's body: by its own coordination, or while
+      # resolving its arguments (008 R-06).
+      # A coordination error raised from inside a body (a nested direct
       # `Step.run`) arrives as `StepCoordination::NestedCoordinationError`, and
       # a bare `Lock::AcquisitionError` etc. may come from a nested
       # `Reactor.run` — both mean the body ran, so neither is listed here.
       NEVER_STARTED_ERROR_CLASSES = [
         RubyReactor::Executor::StepCoordination::Contended,
         RubyReactor::Executor::StepCoordination::KeyError,
-        RubyReactor::Executor::StepCoordination::DispatchRefused
+        RubyReactor::Executor::StepCoordination::DispatchRefused,
+        RubyReactor::Error::ArgumentResolutionError
       ].freeze
 
       def initialize(context)
@@ -65,15 +67,26 @@ module RubyReactor
         end
       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.
+      def compensate(step_config, error, arguments)
+        compensate_step(step_config, error, arguments)
+      end
+
+      # 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
-        undo_stack.reverse_each do |step_info|
+        until undo_stack.empty?
+          step_info = undo_stack.last
           result = @context.with_step(step_info[:step].name) do
             undo_step(step_info[:step], step_info[:result], step_info[:arguments])
           end
+          undo_stack.pop
           @undo_trace << { type: :undo, step: step_info[:step].name, result: result,
                            arguments: step_info[:arguments] }
         end
-        undo_stack.clear
       end
 
       private
@@ -117,19 +130,18 @@ module RubyReactor
         ).around_rollback(&block)
       end
 
+      # Under `with_step`, as `rollback_completed_steps` runs each undo: a
+      # construct (compose, map) reads `context.current_step` to find its own
+      # state during either rollback moment.
       def compensate_step(step_config, error, arguments)
+        @context.with_step(step_config.name) { compensate_step_body(step_config, error, arguments) }
+      end
+
+      def compensate_step_body(step_config, error, arguments)
         middlewares.on(:start_compensation, step_config.name, error, arguments, @context)
         begin
           compensate_result = coordinated_rollback(step_config, arguments) do
-            catch(StepSignals::TAG) do
-              if step_config.compensate_block
-                step_config.compensate_block.call(error, step_config.wrap_inputs(arguments), @context)
-              elsif step_config.has_impl?
-                step_config.impl.compensate(error, arguments, @context)
-              else
-                RubyReactor.Skipped() # Default: nothing defined, rollback continues
-              end
-            end
+            step_config.call_compensate(error, arguments, @context)
           end
 
           @context.append_execution_trace(
@@ -152,7 +164,7 @@ module RubyReactor
           end
 
           compensate_result
-        rescue StandardError => e
+        rescue Error::Rescuable => e
           record_rollback_failure(step_config.name, :compensate, e)
           middlewares.on(:failed_compensation, step_config.name, e, @context)
           # A raise is a compensation failure like a returned Failure: the
@@ -162,19 +174,11 @@ module RubyReactor
         end
       end
 
-      def undo_step(step_config, result, arguments) # rubocop:disable Metrics/MethodLength
+      def undo_step(step_config, result, arguments)
         middlewares.on(:start_undo, step_config.name, result, arguments, @context)
         begin
           undo_result = coordinated_rollback(step_config, arguments) do
-            catch(StepSignals::TAG) do
-              if step_config.undo_block
-                step_config.undo_block.call(result.value, step_config.wrap_inputs(arguments), @context)
-              elsif step_config.has_impl?
-                step_config.impl.undo(result.value, arguments, @context)
-              else
-                RubyReactor.Skipped() # Default: nothing defined, rollback continues
-              end
-            end
+            step_config.call_undo(result.value, arguments, @context)
           end
 
           @context.append_execution_trace(
@@ -196,7 +200,7 @@ module RubyReactor
           end
 
           undo_result
-        rescue StandardError => e
+        rescue Error::Rescuable => e
           record_rollback_failure(step_config.name, :undo, e)
           middlewares.on(:failed_undo, step_config.name, e, @context)
           # Log undo failure but don't halt the rollback process

data/lib/ruby_reactor/executor/result_handler.rb

@@ -62,12 +62,20 @@ module RubyReactor
           @compensation_manager.rollback_completed_steps
           build_validation_failure(error)
         when Error::Base
-          # Other errors need rollback
+          # Other errors need rollback. A `CompensationError` names the step
+          # whose compensation failed.
           @compensation_manager.rollback_completed_steps
-          RubyReactor.Failure("Execution error: #{error.message}", exception_class: error.class.name)
+          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
-          # Unknown errors - don't rollback as they may not be reactor-related
-          RubyReactor.Failure("Execution failed: #{error.message}", exception_class: error.class.name)
+          # 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
+          RubyReactor.Failure("Execution failed: #{error.message}", exception_class: error.class.name,
+                                                                    step_name: @context.current_step,
+                                                                    reactor_name: @context.reactor_class&.name)
         end
       end
 
@@ -108,9 +116,9 @@ module RubyReactor
         result
       end
 
-      # A step returned `RubyReactor.Skipped(...)`. The reactor continues:
-      # validate and record the value exactly like a Success, but do NOT push
-      # to the undo stack (nothing happened, so there is nothing to undo).
+      # 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).
       def handle_skipped(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
@@ -130,11 +138,7 @@ module RubyReactor
       def handle_success(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
-        # `async_step` / `async_reactor` dispatches are independent units of
-        # work with their own compensation flows — the parent rolling back must
-        # not "undo" a dispatch whose unit runs (and may still succeed)
-        # elsewhere. They never enter the parent's undo stack.
-        unless async_unit?(step_config)
+        if step_config.rollback_tracked?
           @compensation_manager.add_to_undo_stack({ step: step_config, arguments: resolved_arguments,
                                                     result: result })
         end
@@ -142,10 +146,6 @@ module RubyReactor
         @dependency_graph.complete_step(step_config.name)
       end
 
-      def async_unit?(step_config)
-        step_config.respond_to?(:async_dispatch?) && step_config.async_dispatch?
-      end
-
       # A composed child's Failure carries the child's own rollback failures;
       # fold them in BEFORE this level rolls back, so they come first.
       def adopt_rollback_failures(result)
@@ -254,6 +254,8 @@ module RubyReactor
       def resolve_exception_class(original_error, error)
         # A step's own contention is reported by its cause (Lock::AcquisitionError, ...).
         original_error = original_error.original if original_error.is_a?(StepCoordination::Contended)
+        # Argument failures report their cause's class (008 R-06).
+        return original_error.exception_class if original_error.is_a?(Error::ArgumentResolutionError)
         return original_error.class.name if original_error
 
         error.respond_to?(:exception_class) ? error.exception_class : nil

data/lib/ruby_reactor/executor/step_coordination.rb

@@ -99,7 +99,7 @@ module RubyReactor
         key
       rescue KeyError
         raise
-      rescue StandardError => e
+      rescue RubyReactor::Error::Rescuable => e
         raise KeyError.new(
           "#{step_name}: coordination key proc raised #{e.class}: #{e.message}",
           step: step_name, original_error: e
@@ -188,7 +188,7 @@ module RubyReactor
       # counter and marker must survive the park.
       rescue Contended, Error::ExecutionParked
         raise
-      rescue StandardError
+      rescue Error::Rescuable
         clear_contention_state
         raise
       end
@@ -498,7 +498,7 @@ module RubyReactor
         rescue Error::ExecutionParked
           outcome = :parked
           raise
-        rescue StandardError
+        rescue Error::Rescuable
           outcome = :failed
           raise
         ensure
@@ -513,8 +513,8 @@ module RubyReactor
       #   step again and must keep its place: the stash survives, so the next
       #   attempt re-reads the SAME nonce. The heartbeat is stopped across the
       #   gap; `poison_pill_timeout` bounds it.
-      # - :abandoned — an exit that is not a `StandardError` (`Sidekiq::Shutdown`,
-      #   `NoMemoryError`, ...). Not advanced: `Sidekiq::Shutdown` pushes the
+      # - :abandoned — an interruption (`Sidekiq::Shutdown`, `NoMemoryError`,
+      #   ...; `Error::Rescuable`, 008 R-16). Not advanced: `Sidekiq::Shutdown` pushes the
       #   job back to run again, which must keep this place, and `failed: true`
       #   would poison successors for work that may yet complete. With the
       #   heartbeat stopped, the poison pill releases the position within
@@ -644,7 +644,7 @@ module RubyReactor
         return skipped_for_period if storage_adapter.period_seen?(key)
 
         result = yield
-        if plain_success?(result) && !chain_failed?(result)
+        if continuing_success?(result) && !chain_failed?(result)
           storage_adapter.period_mark(key, RubyReactor::Period.ttl_seconds(config[:every]))
         end
         result
@@ -654,8 +654,11 @@ module RubyReactor
         RubyReactor.Skipped(nil, reason: :period, step_name: step_name)
       end
 
-      def plain_success?(result)
-        result.is_a?(RubyReactor::Success) && !result.is_a?(RubyReactor::Halt) && !result.is_a?(RubyReactor::Skipped)
+      # A body's `Skipped` marks the bucket like a Success: it is only an
+      # instrumentation mark. The library's own skips (period, ordered lock)
+      # are returned by the gates around this one, never through it.
+      def continuing_success?(result)
+        result.is_a?(RubyReactor::Success) && !result.is_a?(RubyReactor::Halt)
       end
 
       def period_key(config)