cmdx 1.7.5 → 1.9.0

data/examples/paper_trail_whatdunnit.md

@@ -0,0 +1,39 @@
+# Paper Trail Whatdunnit
+
+Tag paper trail version records with which service made a change with a custom `whatdunnit` attribute.
+
+<https://github.com/paper-trail-gem/paper_trail?tab=readme-ov-file#4c-storing-metadata>
+
+### Setup
+
+```ruby
+# lib/cmdx_paper_trail_middleware.rb
+class CmdxPaperTrailMiddleware
+  def self.call(task, **options, &)
+    # This makes sure to reset the whatdunnit value to the previous
+    # value for nested task calls
+
+    begin
+      PaperTrail.request.controller_info ||= {}
+      old_whatdunnit = PaperTrail.request.controller_info[:whatdunnit]
+      PaperTrail.request.controller_info[:whatdunnit] = task.class.name
+      yield
+    ensure
+      PaperTrail.request.controller_info[:whatdunnit] = old_whatdunnit
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxPaperTrailMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/lib/cmdx/attribute.rb

@@ -66,7 +66,7 @@ module CMDx
         if names.none?
           raise ArgumentError, "no attributes given"
         elsif (names.size > 1) && options.key?(:as)
-          raise ArgumentError, ":as option only supports one attribute per definition"
+          raise ArgumentError, "the :as option only supports one attribute per definition"
         end
 
         names.filter_map { |name| new(name, **options, &) }
@@ -212,7 +212,14 @@ module CMDx
     #
     # @raise [RuntimeError] When the method name is already defined on the task
     def define_and_verify
-      raise "#{task.class.name}##{method_name} already defined" if task.respond_to?(method_name, true)
+      if task.respond_to?(method_name, true)
+        raise <<~MESSAGE
+          The method #{method_name.inspect} is already defined on the #{task.class.name} task.
+          This may be due conflicts with one of the task's user defined or internal methods/attributes.
+
+          Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
+        MESSAGE
+      end
 
       attribute_value = AttributeValue.new(self)
       attribute_value.generate

data/lib/cmdx/attribute_value.rb

@@ -51,9 +51,10 @@ module CMDx
       return if errors.for?(method_name)
 
       coerced_value = coerce_value(derived_value)
+      transformed_value = transform_value(coerced_value)
       return if errors.for?(method_name)
 
-      attributes[method_name] = coerced_value
+      attributes[method_name] = transformed_value
     end
 
     # Validates the current attribute value against configured validators.
@@ -113,7 +114,7 @@ module CMDx
     #
     # @example
     #   # Default can be symbol, proc, or direct value
-    #   default_value # => "default_value"
+    #   -> { rand(100) } # => 23
     def default_value
       default = options[:default]
 
@@ -138,7 +139,7 @@ module CMDx
     #
     # @example
     #   # Derives from hash key, method call, or proc execution
-    #   derive_value({user_id: 42}) # => 42
+    #   context.user_id # => 42
     def derive_value(source_value)
       derived_value =
         case source_value
@@ -154,9 +155,29 @@ module CMDx
       nil
     end
 
+    # Transforms the derived value using the transform option.
+    #
+    # @param derived_value [Object] The value to transform
+    #
+    # @return [Object, nil] The transformed value or nil if transformation failed
+    #
+    # @example
+    #   :downcase # => "hello"
+    def transform_value(derived_value)
+      transform = options[:transform]
+
+      if transform.is_a?(Symbol) && derived_value.respond_to?(transform, true)
+        derived_value.send(transform)
+      elsif transform.respond_to?(:call)
+        transform.call(derived_value)
+      else
+        derived_value
+      end
+    end
+
     # Coerces the derived value to the expected type(s) using the coercion registry.
     #
-    # @param derived_value [Object] The value to coerce
+    # @param transformed_value [Object] The value to coerce
     #
     # @return [Object, nil] The coerced value or nil if coercion failed
     #
@@ -165,14 +186,14 @@ module CMDx
     # @example
     #   # Coerces "42" to Integer, "true" to Boolean, etc.
     #   coerce_value("42") # => 42
-    def coerce_value(derived_value)
-      return derived_value if attribute.types.empty?
+    def coerce_value(transformed_value)
+      return transformed_value if types.empty?
 
       registry = task.class.settings[:coercions]
-      last_idx = attribute.types.size - 1
+      last_idx = types.size - 1
 
-      attribute.types.find.with_index do |type, i|
-        break registry.coerce(type, task, derived_value, options)
+      types.find.with_index do |type, i|
+        break registry.coerce(type, task, transformed_value, options)
       rescue CoercionError => e
         next if i != last_idx
 
@@ -180,7 +201,7 @@ module CMDx
           if last_idx.zero?
             e.message
           else
-            tl = attribute.types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
+            tl = types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
             Locale.t("cmdx.coercions.into_any", types: tl)
           end
 

data/lib/cmdx/callback_registry.rb

@@ -95,9 +95,19 @@ module CMDx
       raise TypeError, "unknown callback type #{type.inspect}" unless TYPES.include?(type)
 
       Array(registry[type]).each do |callables, options|
-        next unless Utils::Condition.evaluate(task, options, task)
+        next unless Utils::Condition.evaluate(task, options)
 
-        Array(callables).each { |callable| Utils::Call.invoke(task, callable, task) }
+        Array(callables).each do |callable|
+          if callable.is_a?(Symbol)
+            task.send(callable)
+          elsif callable.is_a?(Proc)
+            task.instance_exec(&callable)
+          elsif callable.respond_to?(:call)
+            callable.call(task)
+          else
+            raise "cannot invoke #{callable}"
+          end
+        end
       end
     end
 

data/lib/cmdx/coercions/hash.rb

@@ -5,6 +5,7 @@ module CMDx
     # Coerces various input types into Hash objects
     #
     # Supports conversion from:
+    # - Nil values (converted to empty Hash)
     # - Hash objects (returned as-is)
     # - Array objects (converted using Hash[*array])
     # - JSON strings starting with "{" (parsed into Hash)
@@ -30,12 +31,16 @@ module CMDx
       # @example Coerce from JSON string
       #   Hash.call('{"key": "value"}') # => {"key" => "value"}
       def call(value, options = {})
-        if value.is_a?(::Hash)
+        if value.nil?
+          {}
+        elsif value.is_a?(::Hash)
           value
         elsif value.is_a?(::Array)
           ::Hash[*value]
         elsif value.is_a?(::String) && value.start_with?("{")
           JSON.parse(value)
+        elsif value.respond_to?(:to_h)
+          value.to_h
         else
           raise_coercion_error!
         end

data/lib/cmdx/configuration.rb

@@ -3,13 +3,14 @@
 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
 
     DEFAULT_BREAKPOINTS = %w[failed].freeze
 
     attr_accessor :middlewares, :callbacks, :coercions, :validators,
-                  :task_breakpoints, :workflow_breakpoints, :logger
+                  :task_breakpoints, :workflow_breakpoints, :logger,
+                  :backtrace, :backtrace_cleaner, :exception_handler
 
     # Initializes a new Configuration instance with default values.
     #
@@ -31,6 +32,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",
@@ -55,6 +60,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

data/lib/cmdx/deprecator.rb

@@ -44,15 +44,15 @@ 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
     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

@@ -48,7 +48,7 @@ module CMDx
       !messages[attribute].empty?
     end
 
-    # Convert errors to a hash format with arrays of fullmessages.
+    # Convert errors to a hash format with arrays of full messages.
     #
     # @return [Hash{Symbol => Array<String>}] Hash with attribute keys and message arrays
     #

data/lib/cmdx/executor.rb

@@ -46,14 +46,16 @@ module CMDx
     #   result = executor.execute
     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!
@@ -73,7 +75,7 @@ module CMDx
     #   result = executor.execute!
     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 +83,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
@@ -108,6 +111,38 @@ 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)
+    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
@@ -118,6 +153,7 @@ module CMDx
     #   raise_exception(standard_error)
     def raise_exception(exception)
       Chain.clear
+
       raise(exception)
     end
 
@@ -135,8 +171,15 @@ module CMDx
 
     private
 
+    # Lazy loaded repeator instance to handle retries.
+    def repeator
+      @repeator ||= Repeator.new(task)
+    end
+
     # Performs pre-execution tasks including validation and attribute verification.
     def pre_execution!
+      @pre_execution = true
+
       invoke_callbacks(:before_validation)
 
       task.class.settings[:attributes].define_and_verify(task)
@@ -144,8 +187,10 @@ module CMDx
 
       task.result.fail!(
         Locale.t("cmdx.faults.invalid"),
-        full_message: task.errors.to_s,
-        messages: task.errors.to_h
+        errors: {
+          full_message: task.errors.to_s,
+          messages: task.errors.to_h
+        }
       )
     end
 
@@ -169,13 +214,56 @@ module CMDx
 
     # Finalizes execution by freezing the task and logging results.
     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.
+    def log_execution!
+      task.logger.info { task.result.to_h }
+    end
+
+    # Logs the backtrace of the exception if the task failed.
+    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.
+    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
+
+      # Freezing the context and chain can only be done
+      # once the outer-most task has completed.
+      return unless task.result.index.zero?
 
-      Freezer.immute(task)
+      task.context.freeze
+      task.chain.freeze
+    end
+
+    def clear_chain!
+      return unless task.result.index.zero?
+
+      Chain.clear
     end
 
   end

data/lib/cmdx/log_formatters/logstash.rb

@@ -21,15 +21,15 @@ module CMDx
       #
       # @example Basic usage
       #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
-      #   # => '{"@version":"1","@timestamp":"2024-01-15T10:30:45.123456Z","severity":"INFO","progname":"MyApp","pid":12345,"message":"User logged in"}\n'
+      #   # => '{"severity":"INFO","progname":"MyApp","pid":12345,"message":"User logged in","@version":"1","@timestamp":"2024-01-15T10:30:45.123456Z"}\n'
       def call(severity, time, progname, message)
         hash = {
-          "@version" => "1",
-          "@timestamp" => time.utc.iso8601(6),
           severity:,
           progname:,
           pid: Process.pid,
-          message: Utils::Format.to_log(message)
+          message: Utils::Format.to_log(message),
+          "@version" => "1",
+          "@timestamp" => time.utc.iso8601(6)
         }
 
         ::JSON.dump(hash) << "\n"

data/lib/cmdx/pipeline.rb

@@ -42,7 +42,7 @@ module CMDx
     #   pipeline.execute
     def execute
       workflow.class.pipeline.each do |group|
-        next unless Utils::Condition.evaluate(workflow, group.options, workflow)
+        next unless Utils::Condition.evaluate(workflow, group.options)
 
         breakpoints = group.options[:breakpoints] ||
                       workflow.class.settings[:breakpoints] ||
@@ -108,18 +108,18 @@ module CMDx
     # @example
     #   execute_tasks_in_parallel(group, ["failed"])
     def execute_tasks_in_parallel(group, breakpoints)
-      raise "install the `parallel` gem to use this feature" unless defined?(::Parallel)
+      raise "install the `parallel` gem to use this feature" unless defined?(Parallel)
 
       parallel_options = group.options.slice(:in_threads, :in_processes)
       throwable_result = nil
 
-      ::Parallel.each(group.tasks, **parallel_options) do |task|
+      Parallel.each(group.tasks, **parallel_options) do |task|
         Chain.current = workflow.chain
 
         task_result = task.execute(workflow.context)
         next unless breakpoints.include?(task_result.status)
 
-        raise ::Parallel::Break, throwable_result = task_result
+        raise Parallel::Break, throwable_result = task_result
       end
 
       return if throwable_result.nil?

data/lib/cmdx/railtie.rb

@@ -32,5 +32,14 @@ module CMDx
       ::I18n.reload!
     end
 
+    # Configures the backtrace cleaner for CMDx in a Rails environment.
+    #
+    # Sets the backtrace cleaner to the Rails backtrace cleaner.
+    initializer("cmdx.backtrace_cleaner") do
+      CMDx.configuration.backtrace_cleaner = lambda do |backtrace|
+        Rails.backtrace_cleaner.clean(backtrace)
+      end
+    end
+
   end
 end

data/lib/cmdx/result.rb

@@ -291,7 +291,16 @@ module CMDx
 
       # Strip the first two frames (this method and the delegator)
       frames = caller_locations(3..-1)
-      fault.set_backtrace(frames.map(&:to_s)) unless frames.empty?
+
+      unless frames.empty?
+        frames = frames.map(&:to_s)
+
+        if (cleaner = task.class.settings[:backtrace_cleaner])
+          cleaner.call(frames)
+        end
+
+        fault.set_backtrace(frames)
+      end
 
       raise(fault)
     end

data/lib/cmdx/task.rb

@@ -40,9 +40,6 @@ module CMDx
     class << self
 
       # @param options [Hash] Configuration options to merge with existing settings
-      # @option options [AttributeRegistry] :attributes Registry for task attributes
-      # @option options [Boolean] :deprecate Whether the task is deprecated
-      # @option options [Array<Symbol>] :tags Tags associated with the task
       #
       # @return [Hash] The merged settings hash
       #
@@ -54,13 +51,21 @@ module CMDx
         @settings ||= begin
           hash =
             if superclass.respond_to?(:settings)
-              superclass.settings
+              parent = superclass.settings
+              parent
+                .except(:backtrace_cleaner, :exception_handler, :logger, :deprecate)
+                .transform_values!(&:dup)
+                .merge!(
+                  backtrace_cleaner: parent[:backtrace_cleaner] || CMDx.configuration.backtrace_cleaner,
+                  exception_handler: parent[:exception_handler] || CMDx.configuration.exception_handler,
+                  logger: parent[:logger] || CMDx.configuration.logger,
+                  deprecate: parent[:deprecate]
+                )
             else
-              CMDx.configuration.to_h.except(:logger)
-            end.transform_values(&:dup)
+              CMDx.configuration.to_h
+            end
 
           hash[:attributes] ||= AttributeRegistry.new
-          hash[:deprecate] ||= false
           hash[:tags] ||= []
 
           hash.merge!(options)

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.7.5"
+  VERSION = "1.9.0"
 
 end

data/lib/cmdx.rb

@@ -5,6 +5,7 @@ require "date"
 require "forwardable"
 require "json"
 require "logger"
+require "pathname"
 require "securerandom"
 require "set"
 require "time"

data/lib/generators/cmdx/templates/install.rb

@@ -32,6 +32,15 @@ CMDx.configure do |config|
     level: Logger::INFO
   )
 
+  # Backtrace configuration - controls whether to log backtraces on faults and exceptions
+  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#backtraces
+  # config.backtrace = false
+  # config.backtrace_cleaner = nil
+
+  # Exception handler configuration - called when non-fault exceptions are raised
+  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#exception-handler
+  # config.exception_handler = nil
+
   # Additional global configurations - automatically applied to all tasks
   #
   # Middlewares - https://github.com/drexed/cmdx/blob/main/docs/middlewares.md

data/lib/locales/af.yml

@@ -9,8 +9,8 @@ af:
       into_any: "kon nie na een van: %{types} omskep word nie"
       unknown: "onbekende %{type} omskep tipe"
     faults:
-      invalid: "Ongeldige insette"
-      unspecified: "Geen rede gegee nie"
+      invalid: "Ongeldig"
+      unspecified: "Ongespesifiseer"
     types:
       array: "skikking"
       big_decimal: "groot desimale"

data/lib/locales/ar.yml

@@ -9,8 +9,8 @@ ar:
       into_any: "لا يمكن تحويله إلى واحد من: %{types}"
       unknown: "نوع تحويل %{type} غير معروف"
     faults:
-      invalid: "مدخلات غير صالحة"
-      unspecified: "لم يتم تقديم سبب"
+      invalid: "غير صالح"
+      unspecified: "غير محدد"
     types:
       array: "مصفوفة"
       big_decimal: "عدد عشري كبير"

data/lib/locales/az.yml

@@ -9,8 +9,8 @@ az:
       into_any: "aşağıdakılardan birinə çevrilə bilmədi: %{types}"
       unknown: "naməlum %{type} çevrilmə tipi"
     faults:
-      invalid: "Etibarsız girişlər"
-      unspecified: "Səbəb göstərilməyib"
+      invalid: "Etibarsız"
+      unspecified: "Göstərilməyib"
     types:
       array: "massiv"
       big_decimal: "böyük onluq"

data/lib/locales/be.yml

@@ -9,8 +9,8 @@ be:
       into_any: "не ўдалося пераўтварыць у адзін з: %{types}"
       unknown: "невядомы тып пераўтварэння %{type}"
     faults:
-      invalid: "Няправільныя ўваходныя даныя"
-      unspecified: "Прычына не паказана"
+      invalid: "Няправільныя"
+      unspecified: "Не паказана"
     types:
       array: "масіў"
       big_decimal: "вялікае дзесятковае лік"

data/lib/locales/bg.yml

@@ -9,8 +9,8 @@ bg:
       into_any: "не може да бъде преобразуван в един от: %{types}"
       unknown: "неизвестен тип преобразуване %{type}"
     faults:
-      invalid: "Невалидни входни данни"
-      unspecified: "Не е посочена причина"
+      invalid: "Невалидни"
+      unspecified: "Не е посочена"
     types:
       array: "масив"
       big_decimal: "голямо десетично число"

data/lib/locales/bn.yml

@@ -9,8 +9,8 @@ bn:
       into_any: "নিম্নলিখিতগুলির মধ্যে একটিতে রূপান্তর করা যায়নি: %{types}"
       unknown: "অজানা %{type} রূপান্তর প্রকার"
     faults:
-      invalid: "অবৈধ ইনপুট"
-      unspecified: "কোন কারণ দেওয়া হয়নি"
+      invalid: "অবৈধ"
+      unspecified: "অনির্দিষ্ট"
     types:
       array: "অ্যারে"
       big_decimal: "বড় দশমিক"