ruby_reactor 0.5.0 → 0.5.2

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -20,17 +20,23 @@ module RubyReactor
         @conditions = []
         @guards = []
         @dependencies = []
+        @arg_validations = []
+        @validate_args_input = nil
         @args_validator = nil
         @output_validator = nil
         @async = false
         @retry_config = {}
       end
 
-      def argument(name, source, transform: nil)
+      def argument(name, source, type = nil, transform: nil, **predicates)
         @arguments[name] = {
           source: source,
           transform: transform
         }
+
+        return unless type || predicates.any?
+
+        @arg_validations << [name, type, false, predicates]
       end
 
       def run(&block)
@@ -57,20 +63,26 @@ module RubyReactor
         @dependencies.concat(step_names)
       end
 
+      # Cross-field rules over the whole resolved argument hash. Composes with
+      # per-argument inline validations declared via `argument`; the block (or
+      # pre-built schema) is applied last and wins on conflicts.
       def validate_args(schema_or_validator = nil, &block)
-        if block_given?
-          @args_validator = build_input_validator(block)
-        elsif schema_or_validator
-          @args_validator = build_input_validator(schema_or_validator)
-        end
+        @validate_args_input = block || schema_or_validator
       end
 
-      def validate_output(schema_or_validator = nil, &block)
-        if block_given?
-          @output_validator = build_input_validator(block)
-        elsif schema_or_validator
-          @output_validator = build_input_validator(schema_or_validator)
-        end
+      # Scalar-aware output validation.
+      #   validate_output :integer, gteq?: 0   # single value
+      #   validate_output do ... end            # hash output
+      #   validate_output SomeSchema            # pre-built schema
+      def validate_output(type = nil, **predicates, &block)
+        @output_validator =
+          if block
+            create_input_validator(block)
+          elsif type.is_a?(Symbol) || type.is_a?(Module) || predicates.any?
+            build_scalar_validator(type, predicates)
+          elsif type
+            create_input_validator(type)
+          end
       end
 
       def async(async = true)
@@ -96,7 +108,7 @@ module RubyReactor
           conditions: @conditions,
           guards: @guards,
           dependencies: @dependencies,
-          args_validator: @args_validator,
+          args_validator: @args_validator || build_args_validator(@arg_validations, @validate_args_input),
           output_validator: @output_validator,
           async: @async,
           retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
@@ -104,32 +116,6 @@ module RubyReactor
 
         RubyReactor::Dsl::StepConfig.new(step_config)
       end
-
-      private
-
-      def build_input_validator(schema_or_block)
-        check_dry_validation_available!
-
-        schema = case schema_or_block
-                 when Proc
-                   build_validation_schema(&schema_or_block)
-                 else
-                   schema_or_block
-                 end
-
-        RubyReactor::Validation::InputValidator.new(schema)
-      end
-
-      def build_validation_schema(&block)
-        RubyReactor::Validation::SchemaBuilder.build_from_block(&block)
-      end
-
-      def check_dry_validation_available!
-        return if defined?(Dry::Schema)
-
-        raise LoadError,
-              "dry-validation gem is required for validation features. Add 'gem \"dry-validation\"' to your Gemfile."
-      end
     end
 
     class StepConfig

data/lib/ruby_reactor/dsl/validation_helpers.rb

@@ -22,6 +22,40 @@ module RubyReactor
         RubyReactor::Validation::InputValidator.new(schema)
       end
 
+      # Form 1 / 1b — inline scalar or class type for a single named value.
+      def build_inline_validator(name, type, optional, predicates)
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_inline(name, type, optional, predicates)
+        RubyReactor::Validation::InputValidator.new(schema)
+      end
+
+      # Form 2 — block bound to the value's macro (`required`/`optional`).
+      def build_macro_validator(name, optional, &block)
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_macro(name, optional, &block)
+        RubyReactor::Validation::InputValidator.new(schema)
+      end
+
+      # Compose per-argument inline rules with an optional `validate_args`
+      # block / pre-built schema. Returns nil when there is nothing to validate.
+      def build_args_validator(inline_rules, validate_input)
+        return nil if inline_rules.empty? && validate_input.nil?
+
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_args(inline_rules, validate_input)
+        return nil unless schema
+
+        RubyReactor::Validation::InputValidator.new(schema)
+      end
+
+      # Scalar-aware single-value validator (used by `validate_output`). The
+      # value is wrapped under `:value` before validation.
+      def build_scalar_validator(type, predicates)
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_inline(:value, type, false, predicates)
+        RubyReactor::Validation::InputValidator.new(schema, wrap_key: :value)
+      end
+
       private
 
       def check_dry_validation_available!

data/lib/ruby_reactor/error/input_validation_error.rb

@@ -4,6 +4,10 @@ module RubyReactor
   module Error
     class InputValidationError < Base
       attr_reader :field_errors
+      # Step attribution, set at the raise site when the failure happened at a
+      # step boundary (argument or output validation) rather than at reactor
+      # input validation. Nil for reactor-level input failures.
+      attr_accessor :step_name, :step_arguments
 
       def initialize(field_errors)
         @field_errors = field_errors

data/lib/ruby_reactor/executor/ordered_lock_support.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Executor
+    # Gate check and terminal-advance logic for `with_ordered_lock`. Mixed
+    # into Executor to keep that class under the length limit. All methods
+    # read from `@context.private_data[:ordered_lock]`, which Reactor#run
+    # populates at enqueue time.
+    module OrderedLockSupport
+      # Thread-local stack of ordered-lock keys whose steps are currently
+      # running in this thread. Used to detect a synchronous `Reactor.run`
+      # nested under another ordered-lock reactor on the same key — which
+      # would deadlock since the outer holds the slot and the inner can never
+      # advance.
+      THREAD_LOCAL_ACTIVE_KEYS = :ruby_reactor_active_ordered_locks
+
+      # Minimum interval between liveness heartbeats; protects very small
+      # poison_pill_timeouts (mirrors Lock::MIN_EXTEND_INTERVAL).
+      HEARTBEAT_MIN_INTERVAL = 1.0
+
+      def self.active_keys
+        Thread.current[THREAD_LOCAL_ACTIVE_KEYS] ||= []
+      end
+
+      # Parse the ordered-lock stash from a context's private_data, surviving
+      # the JSON round-trip (symbol or string keys). Module-level so the
+      # Sidekiq worker can advance the nonce on escalation paths that never
+      # construct an Executor.
+      def self.info_from(context)
+        data = context.private_data[:ordered_lock] || context.private_data["ordered_lock"]
+        return nil unless data
+
+        strict_raw = data[:strict]
+        strict_raw = data["strict"] if strict_raw.nil?
+        strict_raw = true if strict_raw.nil?
+
+        {
+          key: data[:key] || data["key"],
+          nonce: (data[:nonce] || data["nonce"]).to_i,
+          epoch: (data[:epoch] || data["epoch"]).to_i,
+          poison_pill_timeout: (data[:poison_pill_timeout] || data["poison_pill_timeout"] ||
+                                OrderedLock::DEFAULT_POISON_PILL_TIMEOUT).to_i,
+          ttl: (data[:ttl] || data["ttl"] || OrderedLock::DEFAULT_TTL).to_i,
+          strict: [true, "true"].include?(strict_raw)
+        }
+      end
+
+      # Strict-ordering gate. Runs BEFORE rate-limit / lock / semaphore so a
+      # waiting nonce never holds any other primitive — preventing
+      # hold-and-wait deadlocks when `with_lock` and `with_ordered_lock`
+      # share inputs. Raises {OrderedLock::WaitError}; the Sidekiq worker
+      # rescues and snoozes.
+      def check_ordered_lock_gate
+        info = ordered_lock_info
+        return :go unless info
+
+        OrderedLock.new(
+          info.fetch(:key),
+          nonce: info.fetch(:nonce),
+          epoch: info.fetch(:epoch),
+          poison_pill_timeout: info.fetch(:poison_pill_timeout),
+          strict: info.fetch(:strict)
+        ).check!
+      end
+
+      # Combined gate-check + thread-local push. Call at the top of
+      # `execute` / `resume_execution`. Pair with `leave_ordered_lock_scope`
+      # in `ensure`.
+      #
+      # The strict-mode chain-skip only fires on a *fresh* start (no step
+      # has run yet on this context). This lets an in-flight run that paused
+      # (Interrupt / AsyncResult) complete on resume regardless of chain
+      # failures that landed while it was parked, while still applying
+      # strict to a fresh Sidekiq job (which enters via `resume_execution`
+      # but has no prior step state).
+      def enter_ordered_lock_scope
+        gate = check_ordered_lock_gate
+        # A stale-batch run never participates regardless of fresh/resume state —
+        # its numbering belongs to a drained generation. Chain-skip stays gated
+        # on a fresh start so an in-flight paused run still completes on resume.
+        @ordered_lock_stale_batch = gate == :stale_batch
+        @ordered_lock_chain_skip = fresh_ordered_lock_start? && gate == :skip_chain_failed
+
+        # Drained-batch gate: the batch GC'd while this caller slept. A genuine
+        # late straggler runs (poison semantics); a Sidekiq redelivery of an
+        # ALREADY-terminal context must not re-execute its steps. Only the
+        # latter — confirmed by a terminal stored status — is short-circuited.
+        @ordered_lock_drained_replay = gate == :drained_go && stored_status_terminal?
+
+        info = ordered_lock_info
+        return unless info
+
+        OrderedLockSupport.active_keys << info[:key]
+
+        # Only a run that will actually execute steps needs a heartbeat. A
+        # short-circuiting run (stale batch / strict chain skip / drained
+        # redelivery) does no work and terminally advances immediately, so
+        # starting a thread for it is pointless churn.
+        return if @ordered_lock_stale_batch || @ordered_lock_chain_skip || @ordered_lock_drained_replay
+
+        start_ordered_lock_heartbeat(info)
+      end
+
+      def fresh_ordered_lock_start?
+        @context.intermediate_results.empty? && @context.current_step.nil?
+      end
+
+      def ordered_lock_chain_skip?
+        @ordered_lock_chain_skip == true
+      end
+
+      def ordered_lock_stale_batch?
+        @ordered_lock_stale_batch == true
+      end
+
+      def ordered_lock_drained_replay?
+        @ordered_lock_drained_replay == true
+      end
+
+      # Terminal Skipped result when the ordered-lock gate short-circuits this
+      # run (stale batch, strict chain failure, or a drained-batch redelivery of
+      # an already-terminal context), or nil to continue. Shared by `execute`
+      # and `resume_execution`.
+      def ordered_lock_short_circuit
+        return RubyReactor::Skipped.new(reason: :ordered_lock_stale_batch) if ordered_lock_stale_batch?
+        return RubyReactor::Skipped.new(reason: :ordered_lock_drained_replay) if ordered_lock_drained_replay?
+        return RubyReactor::Skipped.new(reason: :ordered_lock_chain_failed) if ordered_lock_chain_skip?
+
+        nil
+      end
+
+      # Pre-step short-circuit: ordered-lock gate skip or already-marked
+      # period bucket. Returns a terminal result or nil.
+      def short_circuit_result
+        ordered_lock_short_circuit || check_period_gate
+      end
+
+      def short_circuit!(result)
+        @result = result
+
+        # A stale-batch or drained-batch-redelivery skip means this run's epoch
+        # belongs to a drained generation — typically a slow straggler or a
+        # Sidekiq at-least-once redelivery. If the redelivery is of a job that
+        # ALREADY reached a terminal status, its stored context is the source of
+        # truth; writing :skipped over a :completed/:failed record would silently
+        # corrupt the outcome. Return the skip to the worker (so it stops)
+        # without saving. The `@skip_context_persist` flag also suppresses the
+        # ensure-block save in execute / resume_execution, which would otherwise
+        # clobber the stored terminal record with this run's stale in-memory
+        # status.
+        if redelivery_of_terminal?(result)
+          @skip_context_persist = true
+          return @result
+        end
+
+        update_context_status(@result)
+        save_context
+        @result
+      end
+
+      def skip_context_persist?
+        @skip_context_persist == true
+      end
+
+      # True when the skip is one of the drained-generation reasons (stale batch
+      # or drained-batch replay) AND the stored context already reached a
+      # terminal status — i.e. this is a redelivery of an already-finished run
+      # whose record must not be overwritten. The drained-replay flag is only
+      # set when the status was terminal, but re-checking keeps both paths
+      # uniform and self-guarding.
+      def redelivery_of_terminal?(result)
+        return false unless result.is_a?(RubyReactor::Skipped)
+        return false unless %i[ordered_lock_stale_batch ordered_lock_drained_replay].include?(result.reason)
+
+        stored_status_terminal?
+      end
+
+      def stored_status_terminal?
+        %w[completed failed skipped].include?(stored_context_status)
+      end
+
+      def stored_context_status
+        reactor_class_name = @reactor_class.name || "AnonymousReactor-#{@reactor_class.object_id}"
+        data = RubyReactor.configuration.storage_adapter.retrieve_context(@context.context_id, reactor_class_name)
+        return nil unless data
+
+        (data["status"] || data[:status]).to_s
+      rescue StandardError
+        nil
+      end
+
+      # Combined terminal-advance + thread-local pop. Idempotent: safe to call
+      # in `ensure` even if `enter_ordered_lock_scope` never pushed (gate
+      # raised, or no ordered_lock configured).
+      def leave_ordered_lock_scope
+        # Stop (and join) the heartbeat BEFORE advancing: the advance HDELs this
+        # nonce's assigned_at, and a heartbeat racing that HDEL could restamp it.
+        # The HEARTBEAT_SCRIPT's hexists guard makes a late restamp a harmless
+        # no-op, but joining first keeps the ordering deterministic.
+        stop_ordered_lock_heartbeat
+        advance_ordered_lock_if_terminal
+        info = ordered_lock_info
+        return unless info
+
+        stack = OrderedLockSupport.active_keys
+        idx = stack.rindex(info[:key])
+        stack.delete_at(idx) if idx
+      end
+
+      # Background thread that restamps this nonce's assigned_at every pp/3
+      # seconds (floored at HEARTBEAT_MIN_INTERVAL) while its steps run, so a
+      # legitimately slow blocker is not poison-passed by a successor. Mirrors
+      # the Lock auto-extend thread. The thread sleeps FIRST, so a job that
+      # finishes faster than one interval never touches Redis.
+      def start_ordered_lock_heartbeat(info)
+        return if @ordered_lock_heartbeat_running
+
+        pp = info[:poison_pill_timeout].to_f
+        interval = [pp / 3.0, HEARTBEAT_MIN_INTERVAL].max
+        @ordered_lock_heartbeat_running = true
+        lock = OrderedLock.new(
+          info.fetch(:key), nonce: info.fetch(:nonce), epoch: info.fetch(:epoch)
+        )
+
+        @ordered_lock_heartbeat = Thread.new do
+          while @ordered_lock_heartbeat_running
+            sleep interval
+            break unless @ordered_lock_heartbeat_running
+
+            begin
+              lock.heartbeat!
+            rescue StandardError => e
+              RubyReactor.configuration.logger.warn(
+                "RubyReactor ordered_lock heartbeat failed for '#{info[:key]}' " \
+                "nonce #{info[:nonce]}: #{e.message}"
+              )
+              break
+            end
+          end
+        end
+      end
+
+      def stop_ordered_lock_heartbeat
+        return unless @ordered_lock_heartbeat_running
+
+        @ordered_lock_heartbeat_running = false
+        thread = @ordered_lock_heartbeat
+        @ordered_lock_heartbeat = nil
+        return unless thread
+
+        thread.wakeup if thread.alive?
+        thread.join(0.1)
+      rescue StandardError
+        # Best-effort shutdown; never let heartbeat teardown break the ensure chain.
+      end
+
+      # Advance the cursor when this run reached a *terminal* status.
+      # Retry-queued, interrupted, or async-handed-off results keep the same
+      # nonce owning the slot — a Sidekiq retry must not double-advance. A
+      # terminal `Failure` is also recorded as the chain's poison marker
+      # (only the FIRST such failure sticks).
+      def advance_ordered_lock_if_terminal
+        info = ordered_lock_info
+        return unless info
+        return unless terminal_for_ordered_lock?(@result)
+
+        OrderedLockSupport.advance_with_retry(info, failed: @result.is_a?(RubyReactor::Failure))
+      end
+
+      # A missed advance on a terminal result stalls every successor for up to
+      # poison_pill_timeout with only a warn line as evidence, so one transient
+      # Redis blip is worth absorbing here before giving up.
+      def self.advance_with_retry(info, failed:)
+        attempts = 0
+        begin
+          attempts += 1
+          OrderedLock.new(
+            info.fetch(:key), nonce: info.fetch(:nonce), epoch: info.fetch(:epoch), ttl: info.fetch(:ttl)
+          ).advance!(failed: failed)
+        rescue StandardError => e
+          retry if attempts < 2
+
+          RubyReactor.configuration.logger.warn(
+            "RubyReactor failed to advance ordered_lock '#{info[:key]}' nonce #{info[:nonce]} " \
+            "after #{attempts} attempts: #{e.message} — successors will stall until " \
+            "poison_pill_timeout (#{info[:poison_pill_timeout]}s) expires"
+          )
+        end
+      end
+
+      private
+
+      def ordered_lock_info
+        OrderedLockSupport.info_from(@context)
+      end
+
+      def terminal_for_ordered_lock?(result)
+        case result
+        when RubyReactor::AsyncResult, RubyReactor::InterruptResult, RetryQueuedResult
+          false
+        when RubyReactor::Success, RubyReactor::Failure
+          true
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/result_handler.rb

@@ -33,8 +33,11 @@ module RubyReactor
         when Error::StepFailureError
           handle_step_failure_error(error)
         when Error::InputValidationError
-          # Preserve validation errors as-is for proper error handling
-          RubyReactor.Failure(error, validation_errors: error.field_errors)
+          # 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
           @compensation_manager.rollback_completed_steps
@@ -56,6 +59,25 @@ module RubyReactor
 
       private
 
+      # 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
+      # reactor-level input failures).
+      def build_validation_failure(error)
+        redact_inputs = []
+        redact_inputs = @context.reactor_class.inputs.select { |_, c| c[:redact] }.keys if @context.reactor_class
+
+        RubyReactor.Failure(
+          error,
+          validation_errors: error.field_errors,
+          step_name: error.step_name,
+          step_arguments: error.step_arguments || {},
+          inputs: @context.inputs,
+          redact_inputs: redact_inputs,
+          reactor_name: @context.reactor_class&.name
+        )
+      end
+
       # A step returned `RubyReactor.Skipped(...)`. Halt cleanly: record the
       # event in the trace, do NOT push to the undo stack (so existing
       # completed steps stay as-is — no compensation), and stamp the step
@@ -180,12 +202,17 @@ module RubyReactor
         output_validation_result = step_config.output_validator.call(value)
         return if output_validation_result.success?
 
-        raise Error::StepFailureError.new(
-          "Step '#{step_config.name}' output validation failed: #{output_validation_result.error.message}",
-          step: step_config.name,
-          context: @context,
-          step_arguments: resolved_arguments
-        )
+        error = output_validation_result.error
+        error.step_name = step_config.name
+        error.step_arguments = resolved_arguments
+
+        # The step DID run — its side effect exists even though its output is
+        # invalid. Treat it like a step failure: run the step's own
+        # 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)
+        raise error
       end
 
       def extract_location(backtrace)

data/lib/ruby_reactor/executor/step_executor.rb

@@ -128,6 +128,10 @@ module RubyReactor
       def safe_execute_step_sync(step_config, resolved_arguments = nil)
         resolved_arguments ||= resolve_arguments(step_config)
         execute_step_sync_without_result_handling(step_config, resolved_arguments)
+      rescue Error::InputValidationError
+        # Validation failures are not retryable and must surface as a structured
+        # InputValidationError (with field_errors), so let them propagate.
+        raise
       rescue StandardError => e
         # Identify redacted inputs
         redact_inputs = @reactor_class.inputs.select { |_, config| config[:redact] }.keys
@@ -240,11 +244,12 @@ module RubyReactor
         validation_result = step_config.args_validator.call(resolved_arguments)
         return if validation_result.success?
 
-        raise Error::StepFailureError.new(
-          "Step '#{step_config.name}' argument validation failed: #{validation_result.error.message}",
-          step: step_config.name,
-          context: @context
-        )
+        # Stamp step attribution so the resulting Failure can say WHERE the
+        # validation failed, not just what was invalid.
+        error = validation_result.error
+        error.step_name = step_config.name
+        error.step_arguments = resolved_arguments
+        raise error
       end
 
       def resolve_arguments(step_config)