cmdx 1.19.0 → 1.21.0

data/lib/cmdx/parallelizer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Bounded thread pool that processes items concurrently.
+  #
+  # Distributes work across a fixed number of threads using a queue,
+  # collecting results in submission order.
+  class Parallelizer
+
+    # Returns the items to process.
+    #
+    # @return [Array] the items to process
+    #
+    # @example
+    #   parallelizer.items # => [1, 2, 3]
+    #
+    # @rbs @items: Array[untyped]
+    attr_reader :items
+
+    # Returns the number of threads in the pool.
+    #
+    # @return [Integer] the thread pool size
+    #
+    # @example
+    #   parallelizer.pool_size # => 4
+    #
+    # @rbs @pool_size: Integer
+    attr_reader :pool_size
+
+    # Creates a new Parallelizer instance.
+    #
+    # @param items [Array] the items to process concurrently
+    # @param pool_size [Integer] number of threads (defaults to item count)
+    #
+    # @return [Parallelizer] a new parallelizer instance
+    #
+    # @example
+    #   Parallelizer.new([1, 2, 3], pool_size: 2)
+    #
+    # @rbs (Array[untyped] items, ?pool_size: Integer) -> void
+    def initialize(items, pool_size: nil)
+      @items = items
+      @pool_size = Integer(pool_size || items.size)
+    end
+
+    # Processes items concurrently and returns results in submission order.
+    #
+    # @param items [Array] the items to process concurrently
+    # @param pool_size [Integer] number of threads (defaults to item count)
+    #
+    # @yield [item] block called for each item in a worker thread
+    # @yieldparam item [Object] an item from the items array
+    # @yieldreturn [Object] the result for this item
+    #
+    # @return [Array] results in the same order as input items
+    #
+    # @example
+    #   Parallelizer.call([1, 2, 3], pool_size: 2) { |n| n * 10 }
+    #   # => [10, 20, 30]
+    #
+    # @rbs [T, R] (Array[T] items, ?pool_size: Integer) { (T) -> R } -> Array[R]
+    def self.call(items, pool_size: nil, &block)
+      new(items, pool_size:).call(&block)
+    end
+
+    # Distributes items across the thread pool and returns results
+    # in submission order.
+    #
+    # @yield [item] block called for each item in a worker thread
+    # @yieldparam item [Object] an item from the items array
+    # @yieldreturn [Object] the result for this item
+    #
+    # @return [Array] results in the same order as input items
+    #
+    # @example
+    #   Parallelizer.new(%w[a b c]).call { |s| s.upcase }
+    #   # => ["A", "B", "C"]
+    #
+    # @rbs [T, R] () { (T) -> R } -> Array[R]
+    def call(&block)
+      results = Array.new(items.size)
+      queue = Queue.new
+
+      items.each_with_index { |item, i| queue << [item, i] }
+      pool_size.times { queue << nil }
+
+      Array.new(pool_size) do
+        Thread.new do
+          while (entry = queue.pop)
+            item, index = entry
+            results[index] = block.call(item) # rubocop:disable Performance/RedundantBlockCall
+          end
+        end
+      end.each(&:join)
+
+      results
+    end
+
+  end
+end

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.reasons.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
@@ -105,6 +109,18 @@ module CMDx
     # @rbs @retries: Integer
     attr_accessor :retries
 
+    # Returns whether this result is strict.
+    # When false, {CMDx::Executor#halt_execution?} returns false
+    # regardless of the task's breakpoint settings.
+    #
+    # @return [Boolean] Whether the result is strict
+    #
+    # @example
+    #   result.strict? # => true
+    #
+    # @rbs @strict: bool
+    attr_reader :strict
+
     # Returns whether the result has been rolled back.
     #
     # @return [Boolean] Whether the result has been rolled back
@@ -139,6 +155,7 @@ module CMDx
       @reason = nil
       @cause = nil
       @retries = 0
+      @strict = true
       @rolled_back = false
     end
 
@@ -261,13 +278,40 @@ 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
 
+    # Sets a reason and optional metadata on a successful result without
+    # changing its state or status. Useful for annotating why a task succeeded.
+    # When halt is true, uses throw/catch to exit the work method early.
+    #
+    # @param reason [String, nil] Reason or note for the success
+    # @param halt [Boolean] Whether to halt execution after success
+    # @param metadata [Hash] Additional metadata about the success
+    # @option metadata [Object] :* Any key-value pairs for additional metadata
+    #
+    # @raise [RuntimeError] When status is not success
+    #
+    # @example
+    #   result.success!("Created 42 records")
+    #   result.success!("Imported", halt: false, rows: 100)
+    #
+    # @rbs (?String? reason, halt: bool, **untyped metadata) -> void
+    def success!(reason = nil, halt: true, **metadata)
+      raise "can only be used while #{SUCCESS}" unless success?
+
+      @reason = reason
+      @metadata = metadata
+
+      throw(:cmdx_halt) if halt
+    end
+
     # @param reason [String, nil] Reason for skipping the task
     # @param halt [Boolean] Whether to halt execution after skipping
     # @param cause [Exception, nil] Exception that caused the skip
+    # @param strict [Boolean] Whether this skip is strict (default: true).
+    #   When false, {CMDx::Executor#halt_execution?} returns false regardless of task settings.
     # @param metadata [Hash] Additional metadata about the skip
     # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
@@ -276,17 +320,19 @@ module CMDx
     # @example
     #   result.skip!("Dependencies not met", cause: dependency_error)
     #   result.skip!("Already processed", halt: false)
+    #   result.skip!("Optional step", strict: false)
     #
-    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
-    def skip!(reason = nil, halt: true, cause: nil, **metadata)
+    # @rbs (?String? reason, halt: bool, cause: Exception?, strict: bool, **untyped metadata) -> void
+    def skip!(reason = nil, halt: true, cause: nil, strict: true, **metadata)
       return if skipped?
 
       raise "can only transition to #{SKIPPED} from #{SUCCESS}" unless success?
 
       @state = INTERRUPTED
       @status = SKIPPED
-      @reason = reason || Locale.t("cmdx.faults.unspecified")
+      @reason = reason || Locale.t("cmdx.reasons.unspecified")
       @cause = cause
+      @strict = strict
       @metadata = metadata
 
       halt! if halt
@@ -295,6 +341,8 @@ module CMDx
     # @param reason [String, nil] Reason for task failure
     # @param halt [Boolean] Whether to halt execution after failure
     # @param cause [Exception, nil] Exception that caused the failure
+    # @param strict [Boolean] Whether this failure is strict (default: true).
+    #   When false, {CMDx::Executor#halt_execution?} returns false regardless of task settings.
     # @param metadata [Hash] Additional metadata about the failure
     # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
@@ -303,17 +351,19 @@ module CMDx
     # @example
     #   result.fail!("Validation failed", cause: validation_error)
     #   result.fail!("Network timeout", halt: false, timeout: 30)
+    #   result.fail!("Soft failure", strict: false)
     #
-    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
-    def fail!(reason = nil, halt: true, cause: nil, **metadata)
+    # @rbs (?String? reason, halt: bool, cause: Exception?, strict: bool, **untyped metadata) -> void
+    def fail!(reason = nil, halt: true, cause: nil, strict: true, **metadata)
       return if failed?
 
       raise "can only transition to #{FAILED} from #{SUCCESS}" unless success?
 
       @state = INTERRUPTED
       @status = FAILED
-      @reason = reason || Locale.t("cmdx.faults.unspecified")
+      @reason = reason || Locale.t("cmdx.reasons.unspecified")
       @cause = cause
+      @strict = strict
       @metadata = metadata
 
       halt! if halt
@@ -338,7 +388,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 +433,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 +461,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
@@ -451,6 +510,16 @@ module CMDx
       retries.positive?
     end
 
+    # @return [Boolean] Whether the result is strict
+    #
+    # @example
+    #   result.strict? # => true
+    #
+    # @rbs () -> bool
+    def strict?
+      !!@strict
+    end
+
     # @return [Boolean] Whether the result has been rolled back
     #
     # @example
@@ -469,7 +538,7 @@ module CMDx
     #
     # @rbs () -> Integer
     def index
-      chain.index(self)
+      @chain_index || chain.index(self)
     end
 
     # @return [String] The outcome of the task execution
@@ -486,7 +555,7 @@ module CMDx
     #
     # @example
     #   result.to_h
-    #   # => {state: "complete", status: "success", outcome: "success", metadata: {}}
+    #   # => {state: "complete", status: "success", outcome: "success", reason: "Unspecified", metadata: {}}
     #
     # @rbs () -> Hash[Symbol, untyped]
     def to_h
@@ -494,10 +563,10 @@ module CMDx
         state:,
         status:,
         outcome:,
+        reason:,
         metadata:
       ).tap do |hash|
         if interrupted?
-          hash[:reason] = reason
           hash[:cause] = cause
           hash[:rolled_back] = rolled_back?
         end
@@ -513,13 +582,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