senro_usecaser 0.2.0 → 0.4.1

data/lib/senro_usecaser/base.rb

@@ -121,44 +121,13 @@ module SenroUsecaser
   #     organize StepA, StepB
   #   end
   class Base
-    class << self
-      # Declares a dependency to be injected from the container
-      #
-      #: (Symbol, ?Class) -> void
-      def depends_on(name, type = nil)
-        dependencies << name unless dependencies.include?(name)
-        dependency_types[name] = type if type
-
-        define_method(name) do
-          @_dependencies[name]
-        end
-      end
-
-      # Returns the list of declared dependencies
-      #
-      #: () -> Array[Symbol]
-      def dependencies
-        @dependencies ||= []
-      end
-
-      # Returns the dependency type mapping
-      #
-      #: () -> Hash[Symbol, Class]
-      def dependency_types
-        @dependency_types ||= {}
-      end
+    extend DependsOn
 
-      # Sets the namespace for dependency resolution
-      #
-      #: ((Symbol | String)) -> void
-      def namespace(name)
-        @use_case_namespace = name
-      end
-
-      # Returns the declared namespace
+    class << self
+      # Alias for backward compatibility
       #
       #: () -> (Symbol | String)?
-      attr_reader :use_case_namespace
+      alias use_case_namespace declared_namespace
 
       # Declares a sequence of UseCases to execute as a pipeline
       #
@@ -276,17 +245,136 @@ module SenroUsecaser
         @around_hooks ||= []
       end
 
-      # Declares the expected input type for this UseCase
+      # Adds an on_failure hook
       #
-      #: (Class) -> void
-      def input(type)
-        @input_class = type
+      #: () { (untyped, Result[untyped], ?RetryContext?) -> void } -> void
+      def on_failure(&block)
+        on_failure_hooks << block
       end
 
-      # Returns the input class
+      # Returns the list of on_failure hooks
       #
-      #: () -> Class?
-      attr_reader :input_class
+      #: () -> Array[Proc]
+      def on_failure_hooks
+        @on_failure_hooks ||= []
+      end
+
+      # Configures automatic retry for specific error types
+      #
+      # @example Retry on network errors
+      #   retry_on :network_error, attempts: 3, wait: 1
+      #
+      # @example Retry on exception class
+      #   retry_on Net::OpenTimeout, attempts: 5, wait: 2, backoff: :exponential
+      #
+      # @example Multiple error types with jitter
+      #   retry_on :rate_limited, :timeout, attempts: 3, wait: 1, jitter: 0.1
+      #
+      # rubocop:disable Metrics/ParameterLists
+      #: (*(Symbol | Class), ?attempts: Integer, ?wait: (Float | Integer),
+      #:  ?backoff: Symbol, ?max_wait: (Float | Integer)?, ?jitter: (Float | Integer)) -> void
+      def retry_on(*error_matchers, attempts: 3, wait: 0, backoff: :fixed, max_wait: nil, jitter: 0)
+        retry_configurations << RetryConfiguration.new(
+          matchers: error_matchers.flatten,
+          attempts: attempts,
+          wait: wait,
+          backoff: backoff,
+          max_wait: max_wait,
+          jitter: jitter
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Returns the list of retry configurations
+      #
+      #: () -> Array[RetryConfiguration]
+      def retry_configurations
+        @retry_configurations ||= []
+      end
+
+      # Configures errors that should immediately discard (no retry)
+      #
+      # @example Discard on validation errors
+      #   discard_on :validation_error, :not_found
+      #
+      # @example Discard on exception class
+      #   discard_on ArgumentError
+      #
+      #: (*(Symbol | Class)) -> void
+      def discard_on(*error_matchers)
+        discard_matchers.concat(error_matchers.flatten)
+      end
+
+      # Returns the list of discard matchers
+      #
+      #: () -> Array[(Symbol | Class)]
+      def discard_matchers
+        @discard_matchers ||= []
+      end
+
+      # Adds a before_retry hook
+      #
+      #: () { (untyped, Result[untyped], RetryContext) -> void } -> void
+      def before_retry(&block)
+        before_retry_hooks << block
+      end
+
+      # Returns the list of before_retry hooks
+      #
+      #: () -> Array[Proc]
+      def before_retry_hooks
+        @before_retry_hooks ||= []
+      end
+
+      # Adds an after_retries_exhausted hook
+      #
+      #: () { (untyped, Result[untyped], RetryContext) -> void } -> void
+      def after_retries_exhausted(&block)
+        after_retries_exhausted_hooks << block
+      end
+
+      # Returns the list of after_retries_exhausted hooks
+      #
+      #: () -> Array[Proc]
+      def after_retries_exhausted_hooks
+        @after_retries_exhausted_hooks ||= []
+      end
+
+      # Declares the expected input type(s) for this UseCase
+      # Accepts a Class or one or more Modules that input must include
+      #
+      # @example Single class
+      #   input UserInput
+      #
+      # @example Single module (interface)
+      #   input HasUserId
+      #
+      # @example Multiple modules (interfaces)
+      #   input HasUserId, HasEmail
+      #
+      #: (*Module) -> void
+      def input(*types)
+        @input_types = types
+      end
+
+      # Returns the input types as an array
+      #
+      #: () -> Array[Module]
+      def input_types
+        @input_types || []
+      end
+
+      # Returns the input class (for backwards compatibility)
+      # If a Class is specified, returns it. Otherwise returns the first type.
+      #
+      #: () -> Module?
+      def input_class
+        types = input_types
+        return nil if types.empty?
+
+        # Class があればそれを返す（単一 Class 指定の後方互換）
+        types.find { |t| t.is_a?(Class) } || types.first
+      end
 
       # Declares the expected output type for this UseCase
       #
@@ -335,13 +423,13 @@ module SenroUsecaser
       private
 
       def copy_configuration_to(subclass)
-        subclass.instance_variable_set(:@dependencies, dependencies.dup)
-        subclass.instance_variable_set(:@dependency_types, dependency_types.dup)
-        subclass.instance_variable_set(:@use_case_namespace, @use_case_namespace)
+        copy_depends_on_to(subclass)
         subclass.instance_variable_set(:@organized_steps, @organized_steps&.dup)
         subclass.instance_variable_set(:@on_failure_strategy, @on_failure_strategy)
-        subclass.instance_variable_set(:@input_class, @input_class)
+        subclass.instance_variable_set(:@input_types, @input_types&.dup)
         subclass.instance_variable_set(:@output_schema, @output_schema)
+        subclass.instance_variable_set(:@retry_configurations, retry_configurations.dup)
+        subclass.instance_variable_set(:@discard_matchers, discard_matchers.dup)
       end
 
       def copy_hooks_to(subclass)
@@ -349,6 +437,9 @@ module SenroUsecaser
         subclass.instance_variable_set(:@before_hooks, before_hooks.dup)
         subclass.instance_variable_set(:@after_hooks, after_hooks.dup)
         subclass.instance_variable_set(:@around_hooks, around_hooks.dup)
+        subclass.instance_variable_set(:@on_failure_hooks, on_failure_hooks.dup)
+        subclass.instance_variable_set(:@before_retry_hooks, before_retry_hooks.dup)
+        subclass.instance_variable_set(:@after_retries_exhausted_hooks, after_retries_exhausted_hooks.dup)
       end
     end
 
@@ -372,9 +463,8 @@ module SenroUsecaser
         raise ArgumentError, "#{self.class.name} must define `input` class"
       end
 
-      execute_with_hooks(input) do
-        call(input)
-      end
+      validate_input!(input)
+      execute_with_retry(input)
     end
 
     # Executes the UseCase logic
@@ -386,6 +476,9 @@ module SenroUsecaser
       raise NotImplementedError, "#{self.class.name}#call must be implemented"
     end
 
+    # Represents a record of a step execution in a pipeline
+    StepExecutionRecord = Struct.new(:step, :input, :result, keyword_init: true)
+
     private
 
     # Creates a success Result with the given value
@@ -416,6 +509,48 @@ module SenroUsecaser
       Result.capture(*exception_classes, code: code, &)
     end
 
+    # Validates that input satisfies all declared input types
+    # For Modules: checks if input's class includes the module
+    # For Classes: checks if input is an instance of the class
+    #
+    #: (untyped) -> void
+    def validate_input!(input)
+      types = self.class.input_types
+      return if types.empty?
+
+      types.each do |expected_type|
+        if expected_type.is_a?(Module) && !expected_type.is_a?(Class)
+          # Module の場合: include しているかを検査
+          unless input.class.include?(expected_type)
+            raise ArgumentError,
+                  "Input #{input.class} must include #{expected_type}"
+          end
+        elsif !input.is_a?(expected_type)
+          # Class の場合: インスタンスかを検査
+          raise ArgumentError,
+                "Input must be an instance of #{expected_type}, got #{input.class}"
+        end
+      end
+    end
+
+    # Validates that the result's value satisfies the declared output type
+    # Only validates if result is success and output_schema is a Class
+    #
+    #: (Result[untyped]) -> void
+    def validate_output!(result)
+      return unless result.success?
+
+      expected_type = self.class.output_schema
+      return if expected_type.nil?
+      return unless expected_type.is_a?(Class)
+
+      value = result.value
+      return if value.is_a?(expected_type)
+
+      raise TypeError,
+            "Output must be an instance of #{expected_type}, got #{value.class}"
+    end
+
     # Executes the core logic with before/after/around hooks
     #
     #: (untyped) { () -> Result[untyped] } -> Result[untyped]
@@ -423,10 +558,95 @@ module SenroUsecaser
       execution = build_around_chain(input, core_block)
       run_before_hooks(input)
       result = execution.call
+      validate_output!(result)
       run_after_hooks(input, result)
       result
     end
 
+    # Executes the UseCase with retry support
+    #
+    #: (untyped) -> Result[untyped]
+    def execute_with_retry(input)
+      context = build_retry_context
+      current_input = input
+
+      loop do
+        result = execute_with_hooks(current_input) { call(current_input) }
+
+        return result if result.success?
+        return result if should_discard?(result)
+
+        retry_config = find_matching_retry_config(result)
+        run_on_failure_hooks(current_input, result, context)
+
+        should_retry = context.should_retry? || (retry_config && !context.exhausted?)
+
+        unless should_retry
+          run_after_retries_exhausted_hooks(current_input, result, context) if context.retried?
+          return result
+        end
+
+        wait_time = context.retry_wait || retry_config&.calculate_wait(context.attempt) || 0
+        run_before_retry_hooks(current_input, result, context)
+
+        sleep(wait_time) if wait_time.positive?
+
+        current_input = context.retry_input || current_input
+        context.increment!(last_error: result.errors.first)
+      end
+    end
+
+    # Builds a retry context with max attempts from configurations
+    #
+    #: () -> RetryContext
+    def build_retry_context
+      max_attempts = self.class.retry_configurations.map(&:attempts).max
+      RetryContext.new(max_attempts: max_attempts)
+    end
+
+    # Finds a retry configuration that matches the result
+    #
+    #: (Result[untyped]) -> RetryConfiguration?
+    def find_matching_retry_config(result)
+      self.class.retry_configurations.find { |c| c.matches?(result) }
+    end
+
+    # Checks if the result should be discarded (no retry)
+    #
+    #: (Result[untyped]) -> bool
+    def should_discard?(result)
+      return false unless result.failure?
+
+      result.errors.any? do |error|
+        self.class.discard_matchers.any? do |matcher|
+          case matcher
+          when Symbol
+            error.code == matcher
+          when Class
+            error.cause&.is_a?(matcher)
+          end
+        end
+      end
+    end
+
+    # Runs before_retry hooks
+    #
+    #: (untyped, Result[untyped], RetryContext) -> void
+    def run_before_retry_hooks(input, result, context)
+      self.class.before_retry_hooks.each do |hook|
+        instance_exec(input, result, context, &hook) # steep:ignore BlockTypeMismatch
+      end
+    end
+
+    # Runs after_retries_exhausted hooks
+    #
+    #: (untyped, Result[untyped], RetryContext) -> void
+    def run_after_retries_exhausted_hooks(input, result, context)
+      self.class.after_retries_exhausted_hooks.each do |hook|
+        instance_exec(input, result, context, &hook) # steep:ignore BlockTypeMismatch
+      end
+    end
+
     # Wraps a non-Result value in Result.success
     #
     #: (untyped) -> Result[untyped]
@@ -507,6 +727,44 @@ module SenroUsecaser
       self.class.after_hooks.each { |hook| instance_exec(input, result, &hook) } # steep:ignore BlockTypeMismatch
     end
 
+    # Runs all on_failure hooks when result is a failure
+    #
+    #: (untyped, Result[untyped], ?RetryContext?) -> void
+    def run_on_failure_hooks(input, result, context = nil)
+      return unless result.failure?
+
+      hook_instances.each do |hook_instance|
+        call_on_failure_hook(hook_instance, :on_failure, input, result, context)
+      end
+
+      self.class.extensions.each do |ext|
+        next if hook_class?(ext)
+        next unless ext.respond_to?(:on_failure)
+
+        call_on_failure_hook(ext, :on_failure, input, result, context)
+      end
+
+      self.class.on_failure_hooks.each do |hook|
+        if context && (hook.arity == 3 || hook.arity.negative?)
+          instance_exec(input, result, context, &hook) # steep:ignore BlockTypeMismatch
+        else
+          instance_exec(input, result, &hook) # steep:ignore BlockTypeMismatch
+        end
+      end
+    end
+
+    # Calls an on_failure hook with appropriate arguments
+    #
+    #: (untyped, Symbol, untyped, Result[untyped], RetryContext?) -> void
+    def call_on_failure_hook(target, method_name, input, result, context)
+      method = target.method(method_name)
+      if context && (method.arity == 3 || method.arity.negative?)
+        target.send(method_name, input, result, context)
+      else
+        target.send(method_name, input, result)
+      end
+    end
+
     # Returns instantiated hook objects
     #
     #: () -> Array[Hook]
@@ -540,43 +798,18 @@ module SenroUsecaser
     end
 
     # Resolves a single dependency from the container
+    # Overrides DependsOn::InstanceMethods to accept container as parameter
     #
     #: (Container, Symbol) -> untyped
     def resolve_from_container(container, name)
-      namespace = effective_namespace
-      if namespace
-        container.resolve_in(namespace, name)
+      ns = effective_namespace
+      if ns
+        container.resolve_in(ns, name)
       else
         container.resolve(name)
       end
     end
 
-    # Returns the effective namespace for dependency resolution
-    #
-    #: () -> (Symbol | String)?
-    def effective_namespace
-      return self.class.use_case_namespace if self.class.use_case_namespace
-      return nil unless SenroUsecaser.configuration.infer_namespace_from_module
-
-      infer_namespace_from_class
-    end
-
-    # Infers namespace from the class's module structure
-    #
-    #: () -> String?
-    def infer_namespace_from_class
-      class_name = self.class.name
-      return nil unless class_name
-
-      parts = class_name.split("::")
-      return nil if parts.length <= 1
-
-      module_parts = parts[0...-1] || [] #: Array[String]
-      return nil if module_parts.empty?
-
-      module_parts.map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2').downcase }.join("::")
-    end
-
     # Executes the organized UseCase pipeline
     #
     #: (untyped) -> Result[untyped]
@@ -599,12 +832,18 @@ module SenroUsecaser
     def execute_pipeline_stop(input)
       current_input = input
       result = nil #: Result[untyped]?
+      executed_steps = [] #: Array[StepExecutionRecord]
 
       self.class.organized_steps&.each do |step|
         next unless step.should_execute?(current_input, self)
 
         step_result = execute_step(step, current_input)
-        return step_result if step_result.failure? && step_should_stop?(step)
+        executed_steps << StepExecutionRecord.new(step: step, input: current_input, result: step_result)
+
+        if step_result.failure? && step_should_stop?(step)
+          execute_pipeline_rollback(executed_steps)
+          return step_result
+        end
 
         current_input = step_result.value if step_result.success?
         result = step_result
@@ -619,12 +858,18 @@ module SenroUsecaser
     def execute_pipeline_continue(input)
       current_input = input
       result = nil #: Result[untyped]?
+      executed_steps = [] #: Array[StepExecutionRecord]
 
       self.class.organized_steps&.each do |step|
         next unless step.should_execute?(current_input, self)
 
         step_result = execute_step(step, current_input)
-        return step_result if step_result.failure? && step.on_failure == :stop
+        executed_steps << StepExecutionRecord.new(step: step, input: current_input, result: step_result)
+
+        if step_result.failure? && step.on_failure == :stop
+          execute_pipeline_rollback(executed_steps)
+          return step_result
+        end
 
         current_input = step_result.value if step_result.success?
         result = step_result
@@ -638,16 +883,20 @@ module SenroUsecaser
     #: (untyped) -> Result[untyped]
     def execute_pipeline_collect(input)
       errors = [] #: Array[Error]
+      executed_steps = [] #: Array[StepExecutionRecord]
       state = { input: input, errors: errors, last_success: nil }
 
       self.class.organized_steps&.each do |step|
         next unless step.should_execute?(state[:input], self)
 
         result = execute_step(step, state[:input])
+        executed_steps << StepExecutionRecord.new(step: step, input: state[:input], result: result)
         break if should_stop_collect_pipeline?(result, step, state)
       end
 
-      build_collect_result(state)
+      final_result = build_collect_result(state)
+      execute_pipeline_rollback(executed_steps) if final_result.failure?
+      final_result
     end
 
     # Updates collect state and checks if pipeline should stop
@@ -692,16 +941,68 @@ module SenroUsecaser
     end
 
     # Calls a single UseCase in the pipeline
-    # Requires input_class to be defined for pipeline steps
+    # Requires input type(s) to be defined for pipeline steps
+    # Note: on_failure hooks are not called here - they're called in pipeline rollback
     #
     #: (singleton(Base), untyped) -> Result[untyped]
     def call_use_case(use_case_class, input)
-      unless use_case_class.input_class
-        raise ArgumentError, "#{use_case_class.name} must define `input` class to be used in a pipeline"
+      if use_case_class.input_types.empty?
+        raise ArgumentError, "#{use_case_class.name} must define `input` type(s) to be used in a pipeline"
+      end
+
+      instance = use_case_class.new(container: @_container)
+      instance.send(:perform_as_pipeline_step, input, capture_exceptions: @_capture_exceptions || false)
+    end
+
+    # Performs the UseCase as a pipeline step (without on_failure hooks)
+    # on_failure hooks are handled by the pipeline's rollback mechanism instead
+    #
+    #: (untyped, ?capture_exceptions: bool) -> Result[untyped]
+    def perform_as_pipeline_step(input, capture_exceptions: false)
+      @_capture_exceptions = capture_exceptions
+
+      unless self.class.input_class || self.class.organized_steps
+        raise ArgumentError, "#{self.class.name} must define `input` class"
+      end
+
+      validate_input!(input)
+      execute_with_hooks(input) { call(input) }
+    rescue StandardError => e
+      raise unless capture_exceptions
+
+      Result.from_exception(e)
+    end
+
+    # Executes rollback by calling on_failure hooks on executed steps in reverse order
+    # Unlike run_on_failure_hooks, this method calls hooks regardless of result status
+    # because we want to rollback even successfully completed steps when pipeline fails
+    #
+    #: (Array[StepExecutionRecord]) -> void
+    def execute_pipeline_rollback(executed_steps)
+      executed_steps.reverse_each do |record|
+        step_instance = record.step.use_case_class.new(container: @_container)
+        step_instance.send(:run_rollback_hooks, record.input, record.result)
+      end
+    end
+
+    # Runs on_failure hooks for rollback purposes (regardless of result status)
+    #
+    #: (untyped, Result[untyped]) -> void
+    def run_rollback_hooks(input, result)
+      hook_instances.each do |hook_instance|
+        call_on_failure_hook(hook_instance, :on_failure, input, result, nil)
       end
 
-      call_method = @_capture_exceptions || false ? :call! : :call #: Symbol
-      use_case_class.public_send(call_method, input, container: @_container)
+      self.class.extensions.each do |ext|
+        next if hook_class?(ext)
+        next unless ext.respond_to?(:on_failure)
+
+        call_on_failure_hook(ext, :on_failure, input, result, nil)
+      end
+
+      self.class.on_failure_hooks.each do |hook|
+        instance_exec(input, result, &hook) # steep:ignore BlockTypeMismatch
+      end
     end
   end
 end