ruby_reactor 0.7.1 → 0.8.1

data/lib/ruby_reactor/step/input_contract.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Step
+    # The inputs one unit of work accepts: declared with `input` on a step
+    # class, or inside an inline step's `inputs do ... end` block. Both forms
+    # are enforced by the same `#enforce!`, so they cannot drift apart.
+    class InputContract
+      include RubyReactor::Dsl::ValidationHelpers
+
+      Declaration = Struct.new(:name, :type, :optional, :default, :redact, :predicates, :macro_block, :schema,
+                               :validator, keyword_init: true)
+
+      REDACTED = "[REDACTED]"
+
+      attr_reader :owner, :declarations, :cross_field_validators
+
+      def initialize(owner: nil, declarations: {}, cross_field_validators: [])
+        @owner = owner
+        @declarations = declarations
+        @cross_field_validators = cross_field_validators
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def input(name, type = nil, optional: false, default: nil, redact: false, validate: nil, **predicates, &block)
+        # rubocop:enable Metrics/ParameterLists
+        check_dry_validation_available!
+        unless default.nil? || optional
+          raise Error::ValidationError,
+                "input :#{name} declares `default:` but is required; a default only applies to an " \
+                "optional input, so add `optional: true`."
+        end
+
+        @declarations[name] = Declaration.new(
+          name: name, type: type, optional: optional, default: default, redact: redact,
+          predicates: predicates, macro_block: block, schema: validate,
+          validator: build_declaration_validator(name, type, optional, validate, predicates, &block)
+        )
+      end
+
+      # Cross-field rules over the whole argument hash, applied after the
+      # per-input rules. A block, a dry-schema, or a dry-validation contract.
+      def validate_inputs(schema = nil, &block)
+        @cross_field_validators << create_input_validator(block || Validation::SchemaBuilder.schema_for(schema))
+      end
+
+      def declares?(name)
+        @declarations.key?(name.to_sym)
+      end
+
+      def required_names
+        @declarations.values.reject(&:optional).map(&:name)
+      end
+
+      def optional_names
+        @declarations.values.select(&:optional).map(&:name)
+      end
+
+      def defaults
+        @declarations.values.reject { |d| d.default.nil? }.to_h { |d| [d.name, d.default] }
+      end
+
+      def redacted_names
+        @declarations.values.select(&:redact).map(&:name)
+      end
+
+      def empty?
+        @declarations.empty? && @cross_field_validators.empty?
+      end
+
+      # A child's contract: the parent's declarations plus the child's, where a
+      # same-named child input replaces the parent's. Neither side is mutated.
+      def merge(child)
+        self.class.new(
+          owner: child.owner,
+          declarations: @declarations.merge(child.declarations),
+          cross_field_validators: @cross_field_validators + child.cross_field_validators
+        )
+      end
+
+      def redact(args)
+        names = redacted_names
+        return args if names.empty?
+
+        args.to_h { |key, value| [key, names.include?(key.to_sym) ? REDACTED : value] }
+      end
+
+      # Returns `args` with defaults applied — the resolved values, never the
+      # schema's coerced output — or raises InputValidationError. `step_name`
+      # is left for the caller, which knows it.
+      def enforce!(args)
+        args = apply_defaults(args)
+        errors = {}
+
+        @declarations.each_value do |declaration|
+          next unless declaration.validator
+          next if declaration.optional && !args.key?(declaration.name)
+
+          # `slice`, so an absent key reads "is missing" and nil "must be filled".
+          collect_errors(errors, declaration.validator.call(args.slice(declaration.name)))
+        end
+        @cross_field_validators.each { |validator| collect_errors(errors, validator.call(args)) }
+
+        return args if errors.empty?
+
+        error = Error::InputValidationError.new(errors)
+        error.step_arguments = redact(args)
+        raise error
+      end
+
+      # Applied when the key is absent or the value is nil — never for `false`.
+      # Public so a step's undo/compensate resolve the same `inputs` as `run`
+      # without validating them.
+      def apply_defaults(args)
+        defaults = self.defaults
+        return args if defaults.empty?
+
+        args.merge(defaults) { |_name, supplied, default| supplied.nil? ? default : supplied }
+      end
+
+      private
+
+      def collect_errors(errors, result)
+        errors.merge!(result.error.field_errors) if result.failure?
+      end
+    end
+  end
+end

data/lib/ruby_reactor/step/map_step.rb

@@ -1,31 +1,29 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  module Step
-    class MapStep
-      include RubyReactor::Step
-
-      def self.run(arguments, context)
-        return RubyReactor::Failure("Map source cannot be nil") if arguments[:source].nil?
+  class Step
+    class MapStep < RubyReactor::Step
+      def run
+        return RubyReactor::Failure("Map source cannot be nil") if inputs[:source].nil?
 
         # Initialize map state in context if not present
         context.map_operations ||= {}
 
-        if should_run_async?(arguments, context)
-          run_async(arguments, context, context.current_step)
+        if fan_out?
+          run_async(context.current_step)
         else
-          run_inline(arguments, context)
+          run_inline
         end
       end
 
-      def self.compensate(_reason, _arguments, _context)
+      def compensate
         # TODO: Implement compensation for map steps
         RubyReactor.Success()
       end
 
       class << self
         def build_mapped_inputs(mappings, context, element)
-          inputs = {}
+          built = {}
 
           mappings.each do |mapped_input_name, source|
             # Handle serialized template objects (Hashes from Sidekiq)
@@ -39,10 +37,10 @@ module RubyReactor
                     else
                       source.resolve(context)
                     end
-            inputs[mapped_input_name] = value
+            built[mapped_input_name] = value
           end
 
-          inputs
+          built
         end
 
         def resolve_element(template_element, current_element)
@@ -56,242 +54,208 @@ module RubyReactor
 
         private
 
-        def should_run_async?(arguments, context)
-          return false if context.inline_async_execution
-
-          arguments[:async]
+        def extract_path(value, path)
+          if path.is_a?(Symbol) && value.respond_to?(:[])
+            value[path]
+          elsif path.is_a?(String)
+            path.split(".").reduce(value) { |v, key| v&.send(:[], key) }
+          elsif path.is_a?(Array)
+            path.reduce(value) { |v, key| v&.send(:[], key) }
+          elsif value.respond_to?(path)
+            value.send(path)
+          end
         end
+      end
 
-        def run_inline(arguments, context)
-          results = execute_inline_map(arguments, context)
-          return results if results.is_a?(RubyReactor::Failure) || results.is_a?(RubyReactor::Halt)
+      private
 
-          process_results(results, arguments[:collect_block], arguments[:fail_fast])
-        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
+      # (`background`, collector resume, `async_reactor` child) fans out as the
+      # caller would — the collector resumes the reactor in a worker either way.
+      def fan_out?
+        return false if context.map_metadata || context.root_context&.map_metadata
 
-        def execute_inline_map(arguments, context)
-          results = []
-          fail_fast = arguments[:fail_fast].nil? || arguments[:fail_fast]
+        inputs[:fan_out]
+      end
 
-          arguments[:source].each do |element|
-            result = execute_single_element(element, arguments, context)
+      def run_inline
+        results = execute_inline_map
+        return results if results.is_a?(RubyReactor::Failure) || results.is_a?(RubyReactor::Halt)
 
-            # An element-level Halt propagates as a run halt: stop immediately
-            # rather than being collected as a (nil) value.
-            return result if result.is_a?(RubyReactor::Halt)
+        process_results(results, inputs[:collect_block], inputs[:fail_fast])
+      end
 
-            if fail_fast && result.failure?
-              return result # Stop immediately on first failure
-            end
+      def execute_inline_map
+        results = []
+        fail_fast = inputs[:fail_fast].nil? || inputs[:fail_fast]
 
-            # When fail_fast is false, store Result objects; when true, store values
-            results << (fail_fast ? result.value : result)
-          end
+        inputs[:source].each do |element|
+          result = execute_single_element(element)
 
-          results
-        end
+          # An element-level Halt propagates as a run halt: stop immediately
+          # rather than being collected as a (nil) value.
+          return result if result.is_a?(RubyReactor::Halt)
 
-        def execute_single_element(element, arguments, context)
-          mapped_inputs = build_mapped_inputs(arguments[:argument_mappings] || {}, context, element)
-          child_context = RubyReactor::Context.new(mapped_inputs, arguments[:mapped_reactor_class])
-
-          link_contexts(child_context, context)
-
-          map_id = "#{context.context_id}:#{context.current_step}"
-          storage = RubyReactor.configuration.storage_adapter
-          storage.store_map_element_context_id(map_id, child_context.context_id, context.reactor_class.name)
-
-          # Set map metadata for failure handling
-          child_context.map_metadata = {
-            map_id: map_id,
-            parent_reactor_class_name: context.reactor_class.name,
-            index: nil # Inline map execution doesn't track index in metadata currently, but could
-          }
-
-          # Store reference in composed_contexts so the UI knows where to find elements
-          context.composed_contexts[context.current_step] = {
-            name: context.current_step,
-            type: :map_ref,
-            map_id: map_id,
-            element_reactor_class: arguments[:mapped_reactor_class].name
-          }
-
-          executor = RubyReactor::Executor.new(arguments[:mapped_reactor_class], {}, child_context)
-          executor.execute
-          executor.result
-        end
+          if fail_fast && result.failure?
+            return result # Stop immediately on first failure
+          end
 
-        def link_contexts(child_context, parent_context)
-          child_context.parent_context = parent_context
-          child_context.root_context = parent_context.root_context || parent_context
-          child_context.inline_async_execution = parent_context.inline_async_execution
+          # When fail_fast is false, store Result objects; when true, store values
+          results << (fail_fast ? result.value : result)
         end
 
-        def process_results(results, collect_block, _fail_fast = true)
-          if collect_block
-            begin
-              # Collect block receives Result objects when fail_fast is false, values when true
-              return RubyReactor::Success(collect_block.call(results))
-            rescue StandardError => e
-              return RubyReactor::Failure(e)
-            end
-          end
+        results
+      end
 
-          # Simplified: both branches returned Success(results)
-          RubyReactor::Success(results)
-        end
+      def execute_single_element(element)
+        mapped_inputs = self.class.build_mapped_inputs(inputs[:argument_mappings] || {}, context, element)
+        child_context = RubyReactor::Context.new(mapped_inputs, inputs[:mapped_reactor_class])
+
+        link_contexts(child_context, context)
+
+        map_id = "#{context.context_id}:#{context.current_step}"
+        storage = RubyReactor.configuration.storage_adapter
+        storage.store_map_element_context_id(map_id, child_context.context_id, context.reactor_class.name)
+
+        # Set map metadata for failure handling
+        child_context.map_metadata = {
+          map_id: map_id,
+          parent_reactor_class_name: context.reactor_class.name,
+          index: nil # Inline map execution doesn't track index in metadata currently, but could
+        }
+
+        # Store reference in composed_contexts so the UI knows where to find elements
+        context.composed_contexts[context.current_step] = {
+          name: context.current_step,
+          type: :map_ref,
+          map_id: map_id,
+          element_reactor_class: inputs[:mapped_reactor_class].name
+        }
+
+        executor = RubyReactor::Executor.new(inputs[:mapped_reactor_class], {}, child_context)
+        executor.execute
+        executor.result
+      end
 
-        def extract_path(value, path)
-          if path.is_a?(Symbol) && value.respond_to?(:[])
-            value[path]
-          elsif path.is_a?(String)
-            path.split(".").reduce(value) { |v, key| v&.send(:[], key) }
-          elsif path.is_a?(Array)
-            path.reduce(value) { |v, key| v&.send(:[], key) }
-          elsif value.respond_to?(path)
-            value.send(path)
+      def link_contexts(child_context, parent_context)
+        child_context.parent_context = parent_context
+        child_context.root_context = parent_context.root_context || parent_context
+        child_context.inline_async_execution = parent_context.inline_async_execution
+      end
+
+      def process_results(results, collect_block, _fail_fast = true)
+        if collect_block
+          begin
+            # Collect block receives Result objects when fail_fast is false, values when true
+            return RubyReactor::Success(collect_block.call(results))
+          rescue StandardError => e
+            return RubyReactor::Failure(e)
           end
         end
 
-        def run_async(arguments, context, step_name)
-          map_id = "#{context.context_id}:#{step_name}"
-          context.map_operations[step_name.to_s] = map_id
-          prepare_async_execution(context, map_id, arguments[:source].size)
-
-          reactor_class_info = build_reactor_class_info(arguments[:mapped_reactor_class], context, step_name)
+        # Simplified: both branches returned Success(results)
+        RubyReactor::Success(results)
+      end
 
-          initialize_map_metadata(map_id, arguments, context, reactor_class_info)
+      def run_async(step_name)
+        map_id = "#{context.context_id}:#{step_name}"
+        context.map_operations[step_name.to_s] = map_id
+        prepare_async_execution(map_id, inputs[:source].size)
 
-          job_id = dispatch_async_map(map_id, arguments, context, reactor_class_info, step_name)
+        reactor_class_info = build_reactor_class_info(inputs[:mapped_reactor_class], step_name)
 
-          # Store reference in composed_contexts so the UI knows where to find elements
-          context.composed_contexts[step_name.to_s] = {
-            name: step_name.to_s,
-            type: :map_ref,
-            map_id: map_id,
-            element_reactor_class: arguments[:mapped_reactor_class].name
-          }
+        initialize_map_metadata(map_id, reactor_class_info)
 
-          RubyReactor::DispatchResult.new(
-            job_id: job_id,
-            intermediate_results: context.intermediate_results,
-            execution_id: context.context_id
-          )
-        end
+        job_id = dispatch_async_map(map_id, reactor_class_info, step_name)
 
-        def initialize_map_metadata(map_id, arguments, context, reactor_class_info)
-          storage = RubyReactor.configuration.storage_adapter
-          storage.initialize_map_operation(
-            map_id, arguments[:source].size, context.reactor_class.name,
-            strict_ordering: arguments[:strict_ordering], reactor_class_info: reactor_class_info,
-            **map_recovery_metadata(context, arguments[:step_name] || context.current_step)
-          )
-        end
+        # Store reference in composed_contexts so the UI knows where to find elements
+        context.composed_contexts[step_name.to_s] = {
+          name: step_name.to_s,
+          type: :map_ref,
+          map_id: map_id,
+          element_reactor_class: inputs[:mapped_reactor_class].name
+        }
 
-        # Recovery metadata for the map sweeper. When this map runs inside a map
-        # element (context.map_metadata present), it is a NESTED map: its parent
-        # holds the element's `map_element:` lock, not an `async:` lock (N1).
-        def map_recovery_metadata(context, step_name)
-          outer = context.map_metadata
-          {
-            parent_context_id: context.context_id,
-            step_name: step_name.to_s,
-            parent_is_map_element: !outer.nil?,
-            outer_map_id: outer && (outer[:map_id] || outer["map_id"]),
-            outer_index: outer && (outer[:index] || outer["index"])
-          }
-        end
+        RubyReactor::DispatchResult.new(
+          job_id: job_id,
+          intermediate_results: context.intermediate_results,
+          execution_id: context.context_id
+        )
+      end
 
-        def dispatch_async_map(map_id, arguments, context, _reactor_class_info, step_name)
-          # Every async map runs through the per-element Dispatcher path. When no
-          # batch_size is given we default to the full source size (one fan-out
-          # batch), so there is a single execution path: each element runs in its
-          # own worker, with the map counter/collector tracking completion. This
-          # lets elements with async steps or async retries hand off correctly
-          # instead of being forced to run synchronously in a single worker.
-          batch_size = arguments[:batch_size] || arguments[:source].size
-
-          RubyReactor::Map::Dispatcher.perform(
-            map_id: map_id,
-            parent_context_id: context.context_id,
-            parent_reactor_class_name: context.reactor_class.name,
-            source: arguments[:source],
-            batch_size: batch_size,
-            step_name: step_name,
-            argument_mappings: arguments[:argument_mappings],
-            strict_ordering: arguments[:strict_ordering],
-            mapped_reactor_class: arguments[:mapped_reactor_class],
-            fail_fast: arguments[:fail_fast].nil? || arguments[:fail_fast]
-          )
-          queue_collector(map_id, context, step_name, arguments[:strict_ordering])
-          "map:#{map_id}"
-        end
+      def initialize_map_metadata(map_id, reactor_class_info)
+        storage = RubyReactor.configuration.storage_adapter
+        storage.initialize_map_operation(
+          map_id, inputs[:source].size, context.reactor_class.name,
+          strict_ordering: inputs[:strict_ordering], reactor_class_info: reactor_class_info,
+          **map_recovery_metadata(inputs[:step_name] || context.current_step)
+        )
+      end
 
-        def prepare_async_execution(context, map_id, count)
-          storage = RubyReactor.configuration.storage_adapter
-          middlewares = context.middlewares || Executor.middlewares_for(context.reactor_class)
-          middlewares.on(:before_async_enqueue, context)
-          serialized_context = ContextSerializer.serialize(context)
-          storage.store_context(context.context_id, serialized_context, context.reactor_class.name)
-          storage.set_map_counter(map_id, count, context.reactor_class.name)
-        end
+      # Recovery metadata for the map sweeper. When this map runs inside a map
+      # element (context.map_metadata present), it is a NESTED map: its parent
+      # holds the element's `map_element:` lock, not an `async:` lock (N1).
+      def map_recovery_metadata(step_name)
+        outer = context.map_metadata
+        {
+          parent_context_id: context.context_id,
+          step_name: step_name.to_s,
+          parent_is_map_element: !outer.nil?,
+          outer_map_id: outer && (outer[:map_id] || outer["map_id"]),
+          outer_index: outer && (outer[:index] || outer["index"])
+        }
+      end
 
-        def build_reactor_class_info(mapped_reactor_class, context, step_name)
-          if mapped_reactor_class.respond_to?(:name)
-            { "type" => "class", "name" => mapped_reactor_class.name }
-          else
-            { "type" => "inline", "parent" => context.reactor_class.name, "step" => step_name.to_s }
-          end
-        end
+      def dispatch_async_map(map_id, _reactor_class_info, step_name)
+        # Every async map runs through the per-element Dispatcher path. When no
+        # batch_size is given we default to the full source size (one fan-out
+        # batch), so there is a single execution path: each element runs in its
+        # own worker, with the map counter/collector tracking completion. This
+        # lets elements with async steps or async retries hand off correctly
+        # instead of being forced to run synchronously in a single worker.
+        batch_size = inputs[:batch_size] || inputs[:source].size
+
+        RubyReactor::Map::Dispatcher.perform(
+          map_id: map_id,
+          parent_context_id: context.context_id,
+          parent_reactor_class_name: context.reactor_class.name,
+          source: inputs[:source],
+          batch_size: batch_size,
+          step_name: step_name,
+          argument_mappings: inputs[:argument_mappings],
+          strict_ordering: inputs[:strict_ordering],
+          mapped_reactor_class: inputs[:mapped_reactor_class],
+          fail_fast: inputs[:fail_fast].nil? || inputs[:fail_fast]
+        )
+        queue_collector(map_id, step_name, inputs[:strict_ordering])
+        "map:#{map_id}"
+      end
 
-        # rubocop:disable Metrics/ParameterLists
-        def queue_fan_out(map_id:, arguments:, context:, reactor_class_info:, step_name:, limit: nil)
-          # rubocop:enable Metrics/ParameterLists
-          storage = RubyReactor.configuration.storage_adapter
-          storage.initialize_map_operation(
-            map_id, arguments[:source].size, context.reactor_class.name,
-            strict_ordering: arguments[:strict_ordering], reactor_class_info: reactor_class_info,
-            **map_recovery_metadata(context, step_name)
-          )
-
-          limit ||= arguments[:source].size
-          first_job_id = nil
-          arguments[:source].each_with_index do |element, index|
-            break if index >= limit
-
-            job_id = queue_map_element(
-              map_id: map_id, element: element, index: index, arguments: arguments,
-              context: context, reactor_class_info: reactor_class_info, step_name: step_name
-            )
-            first_job_id ||= job_id
-          end
+      def prepare_async_execution(map_id, count)
+        storage = RubyReactor.configuration.storage_adapter
+        middlewares = context.middlewares || Executor.middlewares_for(context.reactor_class)
+        middlewares.on(:before_async_enqueue, context)
+        serialized_context = ContextSerializer.serialize(context)
+        storage.store_context(context.context_id, serialized_context, context.reactor_class.name)
+        storage.set_map_counter(map_id, count, context.reactor_class.name)
+      end
 
-          queue_collector(map_id, context, step_name, arguments[:strict_ordering])
-          first_job_id
+      def build_reactor_class_info(mapped_reactor_class, step_name)
+        if mapped_reactor_class.respond_to?(:name)
+          { "type" => "class", "name" => mapped_reactor_class.name }
+        else
+          { "type" => "inline", "parent" => context.reactor_class.name, "step" => step_name.to_s }
         end
+      end
 
-        # rubocop:disable Metrics/ParameterLists
-        def queue_map_element(map_id:, element:, index:, arguments:, context:, reactor_class_info:, step_name:)
-          mapped_inputs = build_mapped_inputs(arguments[:argument_mappings] || {}, context, element)
-          serialized_inputs = ContextSerializer.serialize_value(mapped_inputs)
-
-          RubyReactor.configuration.async_router.perform_map_element_async(
-            map_id: map_id, element_id: "#{map_id}:#{index}", index: index,
-            serialized_inputs: serialized_inputs, reactor_class_info: reactor_class_info,
-            strict_ordering: arguments[:strict_ordering], parent_context_id: context.context_id,
-            parent_reactor_class_name: context.reactor_class.name, step_name: step_name.to_s,
-            batch_size: arguments[:batch_size]
-          )
-        end
-        # rubocop:enable Metrics/ParameterLists
-
-        def queue_collector(map_id, context, step_name, strict_ordering)
-          RubyReactor.configuration.async_router.perform_map_collection_async(
-            parent_context_id: context.context_id, map_id: map_id,
-            parent_reactor_class_name: context.reactor_class.name, step_name: step_name.to_s,
-            strict_ordering: strict_ordering, timeout: 3600
-          )
-        end
+      def queue_collector(map_id, step_name, strict_ordering)
+        RubyReactor.configuration.async_router.perform_map_collection_async(
+          parent_context_id: context.context_id, map_id: map_id,
+          parent_reactor_class_name: context.reactor_class.name, step_name: step_name.to_s,
+          strict_ordering: strict_ordering, timeout: 3600
+        )
       end
     end
   end