cmdx 1.8.0 → 1.9.1

data/lib/cmdx/configuration.rb

@@ -3,13 +3,112 @@
 module CMDx
 
   # Configuration class that manages global settings for CMDx including middlewares,
-  # callbacks, coercions, validators, breakpoints, and logging.
+  # callbacks, coercions, validators, breakpoints, backtraces, and logging.
   class Configuration
 
+    # @rbs DEFAULT_BREAKPOINTS: Array[String]
     DEFAULT_BREAKPOINTS = %w[failed].freeze
 
-    attr_accessor :middlewares, :callbacks, :coercions, :validators,
-                  :task_breakpoints, :workflow_breakpoints, :logger
+    # Returns the middleware registry for task execution.
+    #
+    # @return [MiddlewareRegistry] The middleware registry
+    #
+    # @example
+    #   config.middlewares.register(CustomMiddleware)
+    #
+    # @rbs @middlewares: MiddlewareRegistry
+    attr_accessor :middlewares
+
+    # Returns the callback registry for task lifecycle hooks.
+    #
+    # @return [CallbackRegistry] The callback registry
+    #
+    # @example
+    #   config.callbacks.register(:before_execution, :log_start)
+    #
+    # @rbs @callbacks: CallbackRegistry
+    attr_accessor :callbacks
+
+    # Returns the coercion registry for type conversions.
+    #
+    # @return [CoercionRegistry] The coercion registry
+    #
+    # @example
+    #   config.coercions.register(:custom, CustomCoercion)
+    #
+    # @rbs @coercions: CoercionRegistry
+    attr_accessor :coercions
+
+    # Returns the validator registry for attribute validation.
+    #
+    # @return [ValidatorRegistry] The validator registry
+    #
+    # @example
+    #   config.validators.register(:email, EmailValidator)
+    #
+    # @rbs @validators: ValidatorRegistry
+    attr_accessor :validators
+
+    # Returns the breakpoint statuses for task execution interruption.
+    #
+    # @return [Array<String>] Array of status names that trigger breakpoints
+    #
+    # @example
+    #   config.task_breakpoints = ["failed", "skipped"]
+    #
+    # @rbs @task_breakpoints: Array[String]
+    attr_accessor :task_breakpoints
+
+    # Returns the breakpoint statuses for workflow execution interruption.
+    #
+    # @return [Array<String>] Array of status names that trigger breakpoints
+    #
+    # @example
+    #   config.workflow_breakpoints = ["failed", "skipped"]
+    #
+    # @rbs @task_breakpoints: Array[String]
+    # @rbs @workflow_breakpoints: Array[String]
+    attr_accessor :workflow_breakpoints
+
+    # Returns the logger instance for CMDx operations.
+    #
+    # @return [Logger] The logger instance
+    #
+    # @example
+    #   config.logger.level = Logger::DEBUG
+    #
+    # @rbs @logger: Logger
+    attr_accessor :logger
+
+    # Returns whether to log backtraces for failed tasks.
+    #
+    # @return [Boolean] true if backtraces should be logged
+    #
+    # @example
+    #   config.backtrace = true
+    #
+    # @rbs @backtrace: bool
+    attr_accessor :backtrace
+
+    # Returns the proc used to clean backtraces before logging.
+    #
+    # @return [Proc, nil] The backtrace cleaner proc, or nil if not set
+    #
+    # @example
+    #   config.backtrace_cleaner = ->(bt) { bt.first(5) }
+    #
+    # @rbs @backtrace_cleaner: (Proc | nil)
+    attr_accessor :backtrace_cleaner
+
+    # Returns the proc called when exceptions occur during execution.
+    #
+    # @return [Proc, nil] The exception handler proc, or nil if not set
+    #
+    # @example
+    #   config.exception_handler = ->(task, error) { Sentry.capture_exception(error) }
+    #
+    # @rbs @exception_handler: (Proc | nil)
+    attr_accessor :exception_handler
 
     # Initializes a new Configuration instance with default values.
     #
@@ -22,6 +121,8 @@ module CMDx
     #   config = Configuration.new
     #   config.middlewares.class # => MiddlewareRegistry
     #   config.task_breakpoints # => ["failed"]
+    #
+    # @rbs () -> void
     def initialize
       @middlewares = MiddlewareRegistry.new
       @callbacks = CallbackRegistry.new
@@ -31,6 +132,10 @@ module CMDx
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
 
+      @backtrace = false
+      @backtrace_cleaner = nil
+      @exception_handler = nil
+
       @logger = Logger.new(
         $stdout,
         progname: "cmdx",
@@ -47,6 +152,8 @@ module CMDx
     #   config = Configuration.new
     #   config.to_h
     #   # => { middlewares: #<MiddlewareRegistry>, callbacks: #<CallbackRegistry>, ... }
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
         middlewares: @middlewares,
@@ -55,6 +162,9 @@ module CMDx
         validators: @validators,
         task_breakpoints: @task_breakpoints,
         workflow_breakpoints: @workflow_breakpoints,
+        backtrace: @backtrace,
+        backtrace_cleaner: @backtrace_cleaner,
+        exception_handler: @exception_handler,
         logger: @logger
       }
     end
@@ -70,6 +180,8 @@ module CMDx
   # @example
   #   config = CMDx.configuration
   #   config.middlewares # => #<MiddlewareRegistry>
+  #
+  # @rbs () -> Configuration
   def configuration
     return @configuration if @configuration
 
@@ -91,6 +203,8 @@ module CMDx
   #     config.task_breakpoints = ["failed", "skipped"]
   #     config.logger.level = Logger::DEBUG
   #   end
+  #
+  # @rbs () { (Configuration) -> void } -> Configuration
   def configure
     raise ArgumentError, "block required" unless block_given?
 
@@ -106,6 +220,8 @@ module CMDx
   # @example
   #   CMDx.reset_configuration!
   #   # Configuration is now reset to defaults
+  #
+  # @rbs () -> Configuration
   def reset_configuration!
     @configuration = Configuration.new
   end

data/lib/cmdx/context.rb

@@ -11,6 +11,14 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the internal hash storing context data.
+    #
+    # @return [Hash{Symbol => Object}] The internal hash table
+    #
+    # @example
+    #   context.table # => { name: "John", age: 30 }
+    #
+    # @rbs @table: Hash[Symbol, untyped]
     attr_reader :table
     alias to_h table
 
@@ -28,6 +36,8 @@ module CMDx
     # @example
     #   context = Context.new(name: "John", age: 30)
     #   context[:name] # => "John"
+    #
+    # @rbs (untyped args) -> void
     def initialize(args = {})
       @table =
         if args.respond_to?(:to_hash)
@@ -50,6 +60,8 @@ module CMDx
     #   existing = Context.new(name: "John")
     #   built = Context.build(existing) # reuses existing context
     #   built.object_id == existing.object_id # => true
+    #
+    # @rbs (untyped context) -> Context
     def self.build(context = {})
       if context.is_a?(self) && !context.frozen?
         context
@@ -70,6 +82,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context[:name] # => "John"
     #   context["name"] # => "John" (automatically converted to symbol)
+    #
+    # @rbs ((String | Symbol) key) -> untyped
     def [](key)
       table[key.to_sym]
     end
@@ -85,6 +99,8 @@ module CMDx
     #   context = Context.new
     #   context.store(:name, "John")
     #   context[:name] # => "John"
+    #
+    # @rbs ((String | Symbol) key, untyped value) -> untyped
     def store(key, value)
       table[key.to_sym] = value
     end
@@ -104,6 +120,8 @@ module CMDx
     #   context.fetch(:name) # => "John"
     #   context.fetch(:age, 25) # => 25
     #   context.fetch(:city) { |key| "Unknown #{key}" } # => "Unknown city"
+    #
+    # @rbs ((String | Symbol) key, *untyped) ?{ ((String | Symbol)) -> untyped } -> untyped
     def fetch(key, ...)
       table.fetch(key.to_sym, ...)
     end
@@ -122,6 +140,8 @@ module CMDx
     #   context.fetch_or_store(:name, "Default") # => "John" (existing value)
     #   context.fetch_or_store(:age, 25) # => 25 (stored and returned)
     #   context.fetch_or_store(:city) { |key| "Unknown #{key}" } # => "Unknown city" (stored and returned)
+    #
+    # @rbs ((String | Symbol) key, ?untyped value) ?{ () -> untyped } -> untyped
     def fetch_or_store(key, value = nil)
       table.fetch(key.to_sym) do
         table[key.to_sym] = block_given? ? yield : value
@@ -139,6 +159,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context.merge!(age: 30, city: "NYC")
     #   context.to_h # => {name: "John", age: 30, city: "NYC"}
+    #
+    # @rbs (?untyped args) -> self
     def merge!(args = {})
       args.to_h.each { |key, value| self[key.to_sym] = value }
       self
@@ -156,6 +178,8 @@ module CMDx
     #   context = Context.new(name: "John", age: 30)
     #   context.delete!(:age) # => 30
     #   context.delete!(:city) { |key| "Key #{key} not found" } # => "Key city not found"
+    #
+    # @rbs ((String | Symbol) key) ?{ ((String | Symbol)) -> untyped } -> untyped
     def delete!(key, &)
       table.delete(key.to_sym, &)
     end
@@ -170,6 +194,8 @@ module CMDx
     #   context1 = Context.new(name: "John")
     #   context2 = Context.new(name: "John")
     #   context1 == context2 # => true
+    #
+    # @rbs (untyped other) -> bool
     def eql?(other)
       other.is_a?(self.class) && (to_h == other.to_h)
     end
@@ -185,6 +211,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context.key?(:name) # => true
     #   context.key?(:age) # => false
+    #
+    # @rbs ((String | Symbol) key) -> bool
     def key?(key)
       table.key?(key.to_sym)
     end
@@ -200,6 +228,8 @@ module CMDx
     #   context = Context.new(user: {profile: {name: "John"}})
     #   context.dig(:user, :profile, :name) # => "John"
     #   context.dig(:user, :profile, :age) # => nil
+    #
+    # @rbs ((String | Symbol) key, *(String | Symbol) keys) -> untyped
     def dig(key, *keys)
       table.dig(key.to_sym, *keys)
     end
@@ -211,6 +241,8 @@ module CMDx
     # @example
     #   context = Context.new(name: "John", age: 30)
     #   context.to_s # => "name: John, age: 30"
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h)
     end
@@ -227,6 +259,8 @@ module CMDx
     # @yield [Object] optional block
     #
     # @return [Object] the result of the method call
+    #
+    # @rbs (Symbol method_name, *untyped args, **untyped _kwargs) ?{ () -> untyped } -> untyped
     def method_missing(method_name, *args, **_kwargs, &)
       fetch(method_name) do
         store(method_name[0..-2], args.first) if method_name.end_with?("=")
@@ -244,6 +278,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context.respond_to?(:name) # => true
     #   context.respond_to?(:age) # => false
+    #
+    # @rbs (Symbol method_name, ?bool include_private) -> bool
     def respond_to_missing?(method_name, include_private = false)
       key?(method_name) || super
     end

data/lib/cmdx/deprecator.rb

@@ -10,6 +10,7 @@ module CMDx
 
     extend self
 
+    # @rbs EVAL: Proc
     EVAL = proc do |target, callable|
       case callable
       when /raise|log|warn/ then callable
@@ -44,15 +45,17 @@ module CMDx
     #     settings(deprecate: :warn)
     #   end
     #
-    #   MyTask.new # => [MyTask] DEPRECATED: migrate to replacement or discontinue use
+    #   MyTask.new # => [MyTask] DEPRECATED: migrate to a replacement or discontinue use
+    #
+    # @rbs (Task task) -> void
     def restrict(task)
       type = EVAL.call(task, task.class.settings[:deprecate])
 
       case type
       when NilClass, FalseClass # Do nothing
       when TrueClass, /raise/ then raise DeprecationError, "#{task.class.name} usage prohibited"
-      when /log/ then task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
-      when /warn/ then warn("[#{task.class.name}] DEPRECATED: migrate to replacement or discontinue use", category: :deprecated)
+      when /log/ then task.logger.warn { "DEPRECATED: migrate to a replacement or discontinue use" }
+      when /warn/ then warn("[#{task.class.name}] DEPRECATED: migrate to a replacement or discontinue use", category: :deprecated)
       else raise "unknown deprecation type #{type.inspect}"
       end
     end

data/lib/cmdx/errors.rb

@@ -8,11 +8,21 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the internal hash of error messages by attribute.
+    #
+    # @return [Hash{Symbol => Set<String>}] Hash mapping attribute names to error message sets
+    #
+    # @example
+    #   errors.messages # => { email: #<Set: ["must be valid", "is required"]> }
+    #
+    # @rbs @messages: Hash[Symbol, Set[String]]
     attr_reader :messages
 
     def_delegators :messages, :empty?
 
     # Initialize a new error collection.
+    #
+    # @rbs () -> void
     def initialize
       @messages = {}
     end
@@ -26,6 +36,8 @@ module CMDx
     #   errors = CMDx::Errors.new
     #   errors.add(:email, "must be valid format")
     #   errors.add(:email, "cannot be blank")
+    #
+    # @rbs (Symbol attribute, String message) -> void
     def add(attribute, message)
       return if message.empty?
 
@@ -42,6 +54,8 @@ module CMDx
     # @example
     #   errors.for?(:email) # => true
     #   errors.for?(:name)  # => false
+    #
+    # @rbs (Symbol attribute) -> bool
     def for?(attribute)
       return false unless messages.key?(attribute)
 
@@ -54,6 +68,8 @@ module CMDx
     #
     # @example
     #   errors.full_messages # => { email: ["email must be valid format", "email cannot be blank"] }
+    #
+    # @rbs () -> Hash[Symbol, Array[String]]
     def full_messages
       messages.each_with_object({}) do |(attribute, messages), hash|
         hash[attribute] = messages.map { |message| "#{attribute} #{message}" }
@@ -66,6 +82,8 @@ module CMDx
     #
     # @example
     #   errors.to_h # => { email: ["must be valid format", "cannot be blank"] }
+    #
+    # @rbs () -> Hash[Symbol, Array[String]]
     def to_h
       messages.transform_values(&:to_a)
     end
@@ -78,6 +96,8 @@ module CMDx
     # @example
     #   errors.to_hash # => { email: ["must be valid format", "cannot be blank"] }
     #   errors.to_hash(true) # => { email: ["email must be valid format", "email cannot be blank"] }
+    #
+    # @rbs (?bool full) -> Hash[Symbol, Array[String]]
     def to_hash(full = false)
       full ? full_messages : to_h
     end
@@ -88,6 +108,8 @@ module CMDx
     #
     # @example
     #   errors.to_s # => "email must be valid format. email cannot be blank"
+    #
+    # @rbs () -> String
     def to_s
       full_messages.values.flatten.join(". ")
     end

data/lib/cmdx/executor.rb

@@ -8,6 +8,14 @@ module CMDx
   # and proper error handling for different types of failures.
   class Executor
 
+    # Returns the task being executed.
+    #
+    # @return [Task] The task instance
+    #
+    # @example
+    #   executor.task.id # => "abc123"
+    #
+    # @rbs @task: Task
     attr_reader :task
 
     # @param task [CMDx::Task] The task to execute
@@ -16,6 +24,8 @@ module CMDx
     #
     # @example
     #   executor = CMDx::Executor.new(my_task)
+    #
+    # @rbs (Task task) -> void
     def initialize(task)
       @task = task
     end
@@ -32,6 +42,8 @@ module CMDx
     # @example
     #   CMDx::Executor.execute(my_task)
     #   CMDx::Executor.execute(my_task, raise: true)
+    #
+    # @rbs (Task task, raise: bool) -> Result
     def self.execute(task, raise: false)
       instance = new(task)
       raise ? instance.execute! : instance.execute
@@ -44,16 +56,20 @@ module CMDx
     # @example
     #   executor = CMDx::Executor.new(my_task)
     #   result = executor.execute
+    #
+    # @rbs () -> Result
     def execute
       task.class.settings[:middlewares].call!(task) do
-        pre_execution!
+        pre_execution! unless @pre_execution
         execution!
       rescue UndefinedMethodError => e
         raise(e) # No need to clear the Chain since exception is not being re-raised
       rescue Fault => e
         task.result.throw!(e.result, halt: false, cause: e)
       rescue StandardError => e
+        retry if retry_execution?(e)
         task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        task.class.settings[:exception_handler]&.call(task, e)
       ensure
         task.result.executed!
         post_execution!
@@ -71,9 +87,11 @@ module CMDx
     # @example
     #   executor = CMDx::Executor.new(my_task)
     #   result = executor.execute!
+    #
+    # @rbs () -> Result
     def execute!
       task.class.settings[:middlewares].call!(task) do
-        pre_execution!
+        pre_execution! unless @pre_execution
         execution!
       rescue UndefinedMethodError => e
         raise_exception(e)
@@ -81,6 +99,7 @@ module CMDx
         task.result.throw!(e.result, halt: false, cause: e)
         halt_execution?(e) ? raise_exception(e) : post_execution!
       rescue StandardError => e
+        retry if retry_execution?(e)
         task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         raise_exception(e)
       else
@@ -101,6 +120,8 @@ module CMDx
     #
     # @example
     #   halt_execution?(fault_exception)
+    #
+    # @rbs (Exception exception) -> bool
     def halt_execution?(exception)
       breakpoints = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
       breakpoints = Array(breakpoints).map(&:to_s).uniq
@@ -108,6 +129,40 @@ module CMDx
       breakpoints.include?(exception.result.status)
     end
 
+    # Determines if execution should be retried based on retry configuration.
+    #
+    # @param exception [Exception] The exception that occurred
+    #
+    # @return [Boolean] Whether execution should be retried
+    #
+    # @example
+    #   retry_execution?(standard_error)
+    #
+    # @rbs (Exception exception) -> bool
+    def retry_execution?(exception)
+      available_retries = (task.class.settings[:retries] || 0).to_i
+      return false unless available_retries.positive?
+
+      current_retries = (task.result.metadata[:retries] ||= 0).to_i
+      remaining_retries = available_retries - current_retries
+      return false unless remaining_retries.positive?
+
+      exceptions = Array(task.class.settings[:retry_on] || StandardError)
+      return false unless exceptions.any? { |e| exception.class <= e }
+
+      task.result.metadata[:retries] += 1
+
+      task.logger.warn do
+        reason = "[#{exception.class}] #{exception.message}"
+        task.to_h.merge!(reason:, remaining_retries:)
+      end
+
+      jitter = task.class.settings[:retry_jitter].to_f * current_retries
+      sleep(jitter) if jitter.positive?
+
+      true
+    end
+
     # Raises an exception and clears the chain.
     #
     # @param exception [Exception] The exception to raise
@@ -116,8 +171,11 @@ module CMDx
     #
     # @example
     #   raise_exception(standard_error)
+    #
+    # @rbs (Exception exception) -> void
     def raise_exception(exception)
       Chain.clear
+
       raise(exception)
     end
 
@@ -129,14 +187,27 @@ module CMDx
     #
     # @example
     #   invoke_callbacks(:before_execution)
+    #
+    # @rbs (Symbol type) -> void
     def invoke_callbacks(type)
       task.class.settings[:callbacks].invoke(type, task)
     end
 
     private
 
+    # Lazy loaded repeator instance to handle retries.
+    #
+    # @rbs () -> untyped
+    def repeator
+      @repeator ||= Repeator.new(task)
+    end
+
     # Performs pre-execution tasks including validation and attribute verification.
+    #
+    # @rbs () -> void
     def pre_execution!
+      @pre_execution = true
+
       invoke_callbacks(:before_validation)
 
       task.class.settings[:attributes].define_and_verify(task)
@@ -152,6 +223,8 @@ module CMDx
     end
 
     # Executes the main task logic.
+    #
+    # @rbs () -> void
     def execution!
       invoke_callbacks(:before_execution)
 
@@ -160,6 +233,8 @@ module CMDx
     end
 
     # Performs post-execution tasks including callback invocation.
+    #
+    # @rbs () -> void
     def post_execution!
       invoke_callbacks(:"on_#{task.result.state}")
       invoke_callbacks(:on_executed) if task.result.executed?
@@ -170,14 +245,68 @@ module CMDx
     end
 
     # Finalizes execution by freezing the task and logging results.
+    #
+    # @rbs () -> Result
     def finalize_execution!
-      task.logger.tap do |logger|
-        logger.with_level(:info) do
-          logger.info { task.result.to_h }
-        end
+      log_execution!
+      log_backtrace! if task.class.settings[:backtrace]
+
+      freeze_execution!
+      clear_chain!
+    end
+
+    # Logs the execution result at the configured log level.
+    #
+    # @rbs () -> void
+    def log_execution!
+      task.logger.info { task.result.to_h }
+    end
+
+    # Logs the backtrace of the exception if the task failed.
+    #
+    # @rbs () -> void
+    def log_backtrace!
+      return unless task.result.failed?
+
+      exception = task.result.caused_failure.cause
+      return if exception.is_a?(Fault)
+
+      task.logger.error do
+        "[#{exception.class}] #{exception.message}\n" <<
+          if (cleaner = task.class.settings[:backtrace_cleaner])
+            cleaner.call(exception.backtrace).join("\n\t")
+          else
+            exception.full_message(highlight: false)
+          end
       end
+    end
+
+    # Freezes the task and its associated objects to prevent modifications.
+    #
+    # @rbs () -> void
+    def freeze_execution!
+      # Stubbing on frozen objects is not allowed in most test environments.
+      skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
+      return if Coercions::Boolean.call(skip_freezing)
+
+      task.freeze
+      task.result.freeze
 
-      Freezer.immute(task)
+      # Freezing the context and chain can only be done
+      # once the outer-most task has completed.
+      return unless task.result.index.zero?
+
+      task.context.freeze
+      task.chain.freeze
+    end
+
+    # Clears the chain if the task is the outermost (top-level) task.
+    #
+    # @rbs () -> void
+    def clear_chain!
+      return unless task.result.index.zero?
+
+      Chain.clear
     end
 
   end