cmdx 1.18.0 → 1.20.0

data/lib/cmdx/pipeline.rb

@@ -6,6 +6,14 @@ module CMDx
   # and handling breakpoints that can interrupt execution at specific task statuses.
   class Pipeline
 
+    # @rbs SEQUENTIAL_REGEXP: Regexp
+    SEQUENTIAL_REGEXP = /\Asequential\z/
+    private_constant :SEQUENTIAL_REGEXP
+
+    # @rbs PARALLEL_REGEXP: Regexp
+    PARALLEL_REGEXP = /\Aparallel\z/
+    private_constant :PARALLEL_REGEXP
+
     # Returns the workflow being executed by this pipeline.
     #
     # @return [Workflow] The workflow instance
@@ -54,13 +62,20 @@ module CMDx
     #
     # @rbs () -> void
     def execute
+      default_breakpoints = Utils::Normalize.statuses(
+        workflow.class.settings.breakpoints ||
+        workflow.class.settings.workflow_breakpoints
+      )
+
       workflow.class.pipeline.each do |group|
         next unless Utils::Condition.evaluate(workflow, group.options)
 
-        breakpoints = group.options[:breakpoints] ||
-                      workflow.class.settings[:breakpoints] ||
-                      workflow.class.settings[:workflow_breakpoints]
-        breakpoints = Array(breakpoints).map(&:to_s).uniq
+        breakpoints =
+          if group.options.key?(:breakpoints)
+            Utils::Normalize.statuses(group.options[:breakpoints])
+          else
+            default_breakpoints
+          end
 
         execute_group_tasks(group, breakpoints)
       end
@@ -82,8 +97,8 @@ module CMDx
     # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_group_tasks(group, breakpoints)
       case strategy = group.options[:strategy]
-      when NilClass, /sequential/ then execute_tasks_in_sequence(group, breakpoints)
-      when /parallel/ then execute_tasks_in_parallel(group, breakpoints)
+      when NilClass, SEQUENTIAL_REGEXP then execute_tasks_in_sequence(group, breakpoints)
+      when PARALLEL_REGEXP then execute_tasks_in_parallel(group, breakpoints)
       else raise "unknown execution strategy #{strategy.inspect}"
       end
     end
@@ -111,39 +126,43 @@ module CMDx
       end
     end
 
-    # Executes tasks in parallel using the parallel gem.
+    # Each task receives a snapshot of the workflow context to prevent
+    # unsynchronized concurrent writes to a shared Hash. Snapshots are
+    # merged back into the workflow context after all tasks complete.
     #
     # @param group [CMDx::Group] The task group to execute in parallel
-    # @param breakpoints [Array<Symbol>] Status values that trigger execution breaks
-    # @option group.options [Integer] :in_threads Number of threads to use
-    # @option group.options [Integer] :in_processes Number of processes to use
+    # @param breakpoints [Array<String>] Status values that trigger execution breaks
+    # @option group.options [Integer] :pool_size Number of concurrent threads (defaults to task count)
     #
     # @return [void]
     #
-    # @raise [HaltError] When a task result status matches a breakpoint
+    # @raise [Fault] When a task result status matches a breakpoint
     #
     # @example
     #   execute_tasks_in_parallel(group, ["failed"])
     #
     # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_tasks_in_parallel(group, breakpoints)
-      raise "install the `parallel` gem to use this feature" unless defined?(Parallel)
-
-      parallel_options = group.options.slice(:in_threads, :in_processes)
-      throwable_result = nil
+      contexts = group.tasks.map { Context.new(workflow.context.to_h) }
+      ctx_pairs = group.tasks.zip(contexts)
+      pool_size = group.options.fetch(:pool_size, ctx_pairs.size)
 
-      Parallel.each(group.tasks, **parallel_options) do |task|
+      results = Parallelizer.call(ctx_pairs, pool_size:) do |task, context|
         Chain.current = workflow.chain
-
-        task_result = task.execute(workflow.context)
-        next unless breakpoints.include?(task_result.status)
-
-        raise Parallel::Break, throwable_result = task_result
+        task.execute(context)
       end
 
-      return if throwable_result.nil?
+      contexts.each { |ctx| workflow.context.merge!(ctx) }
+
+      faulted = results.select { |r| breakpoints.include?(r.status) }
+      return if faulted.empty?
 
-      workflow.throw!(throwable_result)
+      workflow.public_send(
+        :"#{faulted.last.status}!",
+        Locale.t("cmdx.faults.unspecified"),
+        source: :parallel,
+        faults: faulted.map(&:to_h)
+      )
     end
 
   end

data/lib/cmdx/railtie.rb

@@ -24,7 +24,7 @@ module CMDx
     #
     # @rbs (untyped app) -> void
     initializer("cmdx.configure_locales") do |app|
-      Array(app.config.i18n.available_locales).each do |locale|
+      Utils::Wrap.array(app.config.i18n.available_locales).each do |locale|
         path = CMDx.gem_path.join("lib/locales/#{locale}.yml")
         next unless File.file?(path)
 

data/lib/cmdx/result.rb

@@ -28,13 +28,17 @@ module CMDx
 
     # @rbs STRIP_FAILURE: Proc
     STRIP_FAILURE = proc do |hash, result, key|
-      unless result.send(:"#{key}?")
+      unless result.public_send(:"#{key}?")
         # Strip caused/threw failures since its the same info as the log line
-        hash[key] = result.send(key).to_h.except(:caused_failure, :threw_failure)
+        hash[key] = result.public_send(key).to_h.except(:caused_failure, :threw_failure)
       end
     end.freeze
     private_constant :STRIP_FAILURE
 
+    # @rbs FAILURE_KEY_REGEX: Regexp
+    FAILURE_KEY_REGEX = /_failure\z/
+    private_constant :FAILURE_KEY_REGEX
+
     # Returns the task instance associated with this result.
     #
     # @return [CMDx::Task] The task instance
@@ -261,7 +265,7 @@ module CMDx
     def on(*states_or_statuses, &)
       raise ArgumentError, "block required" unless block_given?
 
-      yield(self) if states_or_statuses.any? { |s| send(:"#{s}?") }
+      yield(self) if states_or_statuses.any? { |s| public_send(:"#{s}?") }
       self
     end
 
@@ -338,7 +342,7 @@ module CMDx
       unless frames.empty?
         frames = frames.map(&:to_s)
 
-        if (cleaner = task.class.settings[:backtrace_cleaner])
+        if (cleaner = task.class.settings.backtrace_cleaner)
           cleaner.call(frames)
         end
 
@@ -383,7 +387,7 @@ module CMDx
     def caused_failure
       return unless failed?
 
-      chain.results.reverse.find(&:failed?)
+      chain.results.reverse_each.find(&:failed?)
     end
 
     # @return [Boolean] Whether this result caused the failure
@@ -411,8 +415,17 @@ module CMDx
       return unless failed?
 
       current = index
-      results = chain.results.select(&:failed?)
-      results.find { |r| r.index > current } || results.last
+      last_failed = nil
+
+      chain.results.each do |r|
+        next unless r.failed?
+
+        return r if r.index > current
+
+        last_failed = r
+      end
+
+      last_failed
     end
 
     # @return [Boolean] Whether this result threw the failure
@@ -469,7 +482,7 @@ module CMDx
     #
     # @rbs () -> Integer
     def index
-      chain.index(self)
+      @chain_index || chain.index(self)
     end
 
     # @return [String] The outcome of the task execution
@@ -513,13 +526,16 @@ module CMDx
     #
     # @example
     #   result.to_s # => "task_id=my_task state=complete status=success"
+    # @example With failure
+    #   result.to_s # => "task_id=my_task state=complete status=failed threw_failure=<[1] MyTask: my_task>"
     #
     # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h) do |key, value|
-        case key
-        when /failure/ then "#{key}=<[#{value[:index]}] #{value[:class]}: #{value[:id]}>"
-        else "#{key}=#{value.inspect}"
+        if FAILURE_KEY_REGEX.match?(key)
+          "#{key}=<[#{value[:index]}] #{value[:class]}: #{value[:id]}>"
+        else
+          "#{key}=#{value.inspect}"
         end
       end
     end

data/lib/cmdx/retry.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Manages retry logic and state for task execution.
+  #
+  # The Retry class tracks retry availability, attempt counts, and
+  # remaining retries for a given task. It also resolves exception
+  # matching and computes wait times using configurable jitter strategies.
+  class Retry
+
+    # Returns the task instance associated with this retry.
+    #
+    # @return [Task] the task being retried
+    #
+    # @example
+    #   retry_instance.task # => #<CreateUser ...>
+    #
+    # @rbs @task: Task
+    attr_reader :task
+
+    # Creates a new Retry instance for the given task.
+    #
+    # @param task [Task] the task to manage retries for
+    #
+    # @return [Retry] a new Retry instance
+    #
+    # @example
+    #   retry_instance = Retry.new(task)
+    #
+    # @rbs (Task task) -> void
+    def initialize(task)
+      @task = task
+    end
+
+    # Returns the total number of retries configured for the task.
+    #
+    # @return [Integer] the configured retry count
+    #
+    # @example
+    #   retry_instance.available # => 3
+    #
+    # @rbs () -> Integer
+    def available
+      Integer(task.class.settings.retries || 0)
+    end
+
+    # Checks if the task has any retries configured.
+    #
+    # @return [Boolean] true if retries are configured
+    #
+    # @example
+    #   retry_instance.available? # => true
+    #
+    # @rbs () -> bool
+    def available?
+      available.positive?
+    end
+
+    # Returns the number of retry attempts already made.
+    #
+    # @return [Integer] the current retry attempt count
+    #
+    # @example
+    #   retry_instance.attempts # => 1
+    #
+    # @rbs () -> Integer
+    def attempts
+      Integer(task.result.retries || 0)
+    end
+
+    # Checks if the task has been retried at least once.
+    #
+    # @return [Boolean] true if at least one retry has occurred
+    #
+    # @example
+    #   retry_instance.retried? # => true
+    #
+    # @rbs () -> bool
+    def retried?
+      attempts.positive?
+    end
+
+    # Returns the number of retries still available.
+    #
+    # @return [Integer] the remaining retry count
+    #
+    # @example
+    #   retry_instance.remaining # => 2
+    #
+    # @rbs () -> Integer
+    def remaining
+      available - attempts
+    end
+
+    # Checks if there are retries still available.
+    #
+    # @return [Boolean] true if remaining retries exist
+    #
+    # @example
+    #   retry_instance.remaining? # => true
+    #
+    # @rbs () -> bool
+    def remaining?
+      remaining.positive?
+    end
+
+    # Returns the list of exception classes eligible for retry.
+    #
+    # @return [Array<Class>] exception classes that trigger a retry
+    #
+    # @example
+    #   retry_instance.exceptions # => [StandardError, CMDx::TimeoutError]
+    #
+    # @rbs () -> Array[Class]
+    def exceptions
+      @exceptions ||= Utils::Wrap.array(
+        task.class.settings.retry_on ||
+        [StandardError, CMDx::TimeoutError]
+      )
+    end
+
+    # Checks if the given exception matches any configured retry exception.
+    #
+    # @param exception [Exception] the exception to check
+    #
+    # @return [Boolean] true if the exception qualifies for retry
+    #
+    # @example
+    #   retry_instance.exception?(RuntimeError.new("fail")) # => true
+    #
+    # @rbs (Exception exception) -> bool
+    def exception?(exception)
+      exceptions.any? { |e| exception.class <= e }
+    end
+
+    # Computes the wait time before the next retry attempt.
+    #
+    # Supports multiple jitter strategies: a Symbol calls a task method,
+    # a Proc is evaluated in the task instance context, a callable object
+    # receives the task and attempts, and a Numeric is multiplied by the
+    # attempt count.
+    #
+    # @return [Float] the wait duration in seconds
+    #
+    # @example With numeric jitter (0.5 * attempts)
+    #   retry_instance.wait # => 1.0
+    # @example With symbol jitter referencing a task method
+    #   retry_instance.wait # => 2.5
+    #
+    # @rbs () -> Float
+    def wait
+      jitter = task.class.settings.retry_jitter
+
+      if jitter.is_a?(Symbol)
+        task.send(jitter, attempts)
+      elsif jitter.is_a?(Proc)
+        task.instance_exec(attempts, &jitter)
+      elsif jitter.respond_to?(:call)
+        jitter.call(task, attempts)
+      else
+        jitter.to_f * attempts
+      end.to_f
+    end
+
+  end
+end

data/lib/cmdx/settings.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Value object encapsulating all per-task configuration. Registries are
+  # deep-duped on inheritance; scalar settings delegate to a parent Settings
+  # or to the global Configuration rather than eagerly copying values.
+  class Settings
+
+    class << self
+
+      private
+
+      # Defines a reader that delegates to the parent Settings chain,
+      # falling through to Configuration when no parent exists.
+      #
+      # @param names [Array<Symbol>] Setting names to define
+      #
+      # @rbs (*Symbol names) -> void
+      def delegate_to_configuration(*names)
+        names.each do |name|
+          ivar = :"@#{name}"
+
+          attr_writer(name)
+
+          define_method(name) do
+            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+            value = @parent ? @parent.public_send(name) : CMDx.configuration.public_send(name)
+            instance_variable_set(ivar, value)
+
+            value
+          end
+        end
+      end
+
+      # Defines a reader that delegates to the parent Settings only.
+      # Returns nil when the chain is exhausted.
+      #
+      # @param names [Array<Symbol>] Setting names to define
+      # @param with_fallback [Boolean] Whether to fall back to Configuration
+      #
+      # @rbs (*Symbol names, with_fallback: bool) -> void
+      def delegate_to_parent(*names, with_fallback: false)
+        names.each do |name|
+          ivar = :"@#{name}"
+
+          attr_writer(name)
+
+          define_method(name) do
+            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+            value = @parent&.public_send(name)
+            value ||= CMDx.configuration.public_send(name) if with_fallback
+            instance_variable_set(ivar, value)
+
+            value
+          end
+        end
+      end
+
+    end
+
+    # Returns the attribute registry for task parameters.
+    #
+    # @return [AttributeRegistry] The attribute registry
+    #
+    # @rbs @attributes: AttributeRegistry
+    attr_accessor :attributes
+
+    # Returns the callback registry for task lifecycle hooks.
+    #
+    # @return [CallbackRegistry] The callback registry
+    #
+    # @rbs @callbacks: CallbackRegistry
+    attr_accessor :callbacks
+
+    # Returns the coercion registry for type conversions.
+    #
+    # @return [CoercionRegistry] The coercion registry
+    #
+    # @rbs @coercions: CoercionRegistry
+    attr_accessor :coercions
+
+    # Returns the middleware registry for task execution.
+    #
+    # @return [MiddlewareRegistry] The middleware registry
+    #
+    # @rbs @middlewares: MiddlewareRegistry
+    attr_accessor :middlewares
+
+    # Returns the validator registry for attribute validation.
+    #
+    # @return [ValidatorRegistry] The validator registry
+    #
+    # @rbs @validators: ValidatorRegistry
+    attr_accessor :validators
+
+    # Returns the expected return keys after execution.
+    #
+    # @return [Array<Symbol>] Expected return keys after execution
+    #
+    # @rbs @returns: Array[Symbol]
+    attr_accessor :returns
+
+    # Returns the tags for task categorization.
+    #
+    # @return [Array<Symbol>] Tags for categorization
+    #
+    # @rbs @tags: Array[Symbol]
+    attr_accessor :tags
+
+    # @!attribute [rw] backtrace
+    #   @return [Boolean] true if backtraces should be logged
+    delegate_to_configuration :backtrace
+
+    # @!attribute [rw] rollback_on
+    #   @return [Array<String>] Statuses that trigger rollback
+    delegate_to_configuration :rollback_on
+
+    # @!attribute [rw] task_breakpoints
+    #   @return [Array<String>] Default task breakpoint statuses
+    delegate_to_configuration :task_breakpoints
+
+    # @!attribute [rw] workflow_breakpoints
+    #   @return [Array<String>] Default workflow breakpoint statuses
+    delegate_to_configuration :workflow_breakpoints
+
+    # @!attribute [rw] backtrace_cleaner
+    #   @return [Proc, nil] The backtrace cleaner proc
+    delegate_to_parent :backtrace_cleaner, with_fallback: true
+
+    # @!attribute [rw] breakpoints
+    #   @return [Array<String>, nil] Per-task breakpoints override
+    delegate_to_parent :breakpoints
+
+    # @!attribute [rw] deprecate
+    #   @return [Symbol, Proc, Boolean, nil] Deprecation behavior
+    delegate_to_parent :deprecate
+
+    # @!attribute [rw] exception_handler
+    #   @return [Proc, nil] The exception handler proc
+    delegate_to_parent :exception_handler, with_fallback: true
+
+    # @!attribute [rw] logger
+    #   @return [Logger] The logger instance
+    delegate_to_parent :logger, with_fallback: true
+
+    # @!attribute [rw] log_formatter
+    #   @return [Proc, nil] Per-task log formatter override
+    delegate_to_parent :log_formatter
+
+    # @!attribute [rw] log_level
+    #   @return [Integer, nil] Per-task log level override
+    delegate_to_parent :log_level
+
+    # @!attribute [rw] retries
+    #   @return [Integer, nil] Number of retries on failure
+    delegate_to_parent :retries
+
+    # @!attribute [rw] retry_jitter
+    #   @return [Numeric, Symbol, Proc, nil] Jitter between retries
+    delegate_to_parent :retry_jitter
+
+    # @!attribute [rw] retry_on
+    #   @return [Array<Class>, Class, nil] Exception classes to retry on
+    delegate_to_parent :retry_on
+
+    # Creates a new Settings instance, inheriting registries from a parent
+    # Settings or the global Configuration. Scalar settings are resolved
+    # lazily via delegation rather than eagerly copied.
+    #
+    # @param parent [Settings, nil] Parent settings to inherit from
+    # @param overrides [Hash] Field values to override after inheritance
+    #
+    # @example
+    #   Settings.new(parent: ParentTask.settings, deprecate: true)
+    #
+    # @rbs (?parent: Settings?, **untyped overrides) -> void
+    def initialize(parent: nil, **overrides)
+      @parent = parent
+
+      init_registries
+      init_collections
+
+      overrides.each { |key, value| public_send(:"#{key}=", value) }
+    end
+
+    private
+
+    # Dups registries from the parent Settings or global Configuration
+    # so each task class gets its own mutable copy.
+    #
+    # @rbs () -> void
+    def init_registries
+      if @parent
+        @middlewares = @parent.middlewares.dup
+        @callbacks = @parent.callbacks.dup
+        @coercions = @parent.coercions.dup
+        @validators = @parent.validators.dup
+        @attributes = @parent.attributes.dup
+      else
+        config = CMDx.configuration
+
+        @middlewares = config.middlewares.dup
+        @callbacks = config.callbacks.dup
+        @coercions = config.coercions.dup
+        @validators = config.validators.dup
+        @attributes = AttributeRegistry.new
+      end
+    end
+
+    # Initializes array-valued settings that need their own copy
+    # to avoid cross-class mutation.
+    #
+    # @rbs () -> void
+    def init_collections
+      @returns = @parent&.returns&.dup || EMPTY_ARRAY
+      @tags = @parent&.tags&.dup || EMPTY_ARRAY
+    end
+
+  end
+end