cmdx 1.19.0 → 1.21.0

data/lib/cmdx/executor.rb

@@ -10,6 +10,14 @@ module CMDx
 
     extend Forwardable
 
+    # @rbs STATE_CALLBACKS: Hash[String, Symbol]
+    STATE_CALLBACKS = Result::STATES.to_h { |s| [s, :"on_#{s}"] }.freeze
+    private_constant :STATE_CALLBACKS
+
+    # @rbs STATUS_CALLBACKS: Hash[String, Symbol]
+    STATUS_CALLBACKS = Result::STATUSES.to_h { |s| [s, :"on_#{s}"] }.freeze
+    private_constant :STATUS_CALLBACKS
+
     # Returns the task being executed.
     #
     # @return [Task] The task instance
@@ -63,23 +71,24 @@ module CMDx
     #
     # @rbs () -> Result
     def execute
-      task.class.settings[:middlewares].call!(task) do
+      task.class.settings.middlewares.call!(task) do
         pre_execution! unless @pre_execution
         execution!
-        verify_returns!
+        verify_context_returns!
       rescue UndefinedMethodError => e
-        raise(e) # No need to clear the Chain since exception is not being re-raised
+        raise_exception(e)
       rescue Fault => e
         result.throw!(e.result, halt: false, cause: e)
       rescue StandardError => e
         retry if retry_execution?(e)
-        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
-        task.class.settings[:exception_handler]&.call(task, e)
+        result.fail!(Utils::Normalize.exception(e), halt: false, cause: e, source: :exception)
+        task.class.settings.exception_handler&.call(task, e)
       ensure
         result.executed!
         post_execution!
       end
 
+      verify_middleware_yield!
       finalize_execution!
     end
 
@@ -95,30 +104,38 @@ module CMDx
     #
     # @rbs () -> Result
     def execute!
-      task.class.settings[:middlewares].call!(task) do
+      task.class.settings.middlewares.call!(task) do
         pre_execution! unless @pre_execution
         execution!
-        verify_returns!
+        verify_context_returns!
       rescue UndefinedMethodError => e
         raise_exception(e)
       rescue Fault => e
         result.throw!(e.result, halt: false, cause: e)
-        halt_execution?(e) ? raise_exception(e) : post_execution!
+
+        if halt_execution?(e)
+          raise_exception(e)
+        else
+          result.executed!
+          post_execution!
+        end
       rescue StandardError => e
         retry if retry_execution?(e)
-        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!(Utils::Normalize.exception(e), halt: false, cause: e, source: :exception)
         raise_exception(e)
       else
         result.executed!
         post_execution!
       end
 
+      verify_middleware_yield!
       finalize_execution!
     end
 
     protected
 
     # Determines if execution should halt based on breakpoint configuration.
+    # Returns false when the result was created with +strict: false+.
     #
     # @param exception [Exception] The exception that occurred
     #
@@ -126,10 +143,14 @@ module CMDx
     #
     # @rbs (Exception exception) -> bool
     def halt_execution?(exception)
-      statuses = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
-      statuses = Array(statuses).map(&:to_s).uniq
+      return false unless exception.result.strict?
 
-      statuses.include?(exception.result.status)
+      @halt_statuses ||= Utils::Normalize.statuses(
+        task.class.settings.breakpoints ||
+        task.class.settings.task_breakpoints
+      ).freeze
+
+      @halt_statuses.include?(exception.result.status)
     end
 
     # Determines if execution should be retried based on retry configuration.
@@ -140,36 +161,22 @@ module CMDx
     #
     # @rbs (Exception exception) -> bool
     def retry_execution?(exception)
-      available_retries = Integer(task.class.settings[:retries] || 0)
-      return false unless available_retries.positive?
-
-      current_retry = result.retries
-      remaining_retries = available_retries - current_retry
-      return false unless remaining_retries.positive?
+      @retry ||= Retry.new(task)
 
-      exceptions = Array(task.class.settings[:retry_on] || StandardError)
-      return false unless exceptions.any? { |e| exception.class <= e }
+      return false unless @retry.available? && @retry.remaining?
+      return false unless @retry.exception?(exception)
 
       result.retries += 1
 
       task.logger.warn do
-        reason = "[#{exception.class}] #{exception.message}"
-        task.to_h.merge!(reason:, remaining_retries:)
+        reason = Utils::Normalize.exception(exception)
+        task.to_h.merge!(reason:, remaining_retries: @retry.remaining)
       end
 
-      jitter = task.class.settings[:retry_jitter]
-      jitter =
-        if jitter.is_a?(Symbol)
-          task.send(jitter, current_retry)
-        elsif jitter.is_a?(Proc)
-          task.instance_exec(current_retry, &jitter)
-        elsif jitter.respond_to?(:call)
-          jitter.call(task, current_retry)
-        else
-          jitter.to_f * current_retry
-        end
+      task.errors.clear
 
-      sleep(jitter) if Float(jitter).positive?
+      wait = @retry.wait
+      sleep(wait) if wait.positive?
 
       true
     end
@@ -198,7 +205,7 @@ module CMDx
     #
     # @rbs (Symbol type) -> void
     def invoke_callbacks(type)
-      task.class.settings[:callbacks].invoke(type, task)
+      task.class.settings.callbacks.invoke(type, task)
     end
 
     private
@@ -211,11 +218,12 @@ module CMDx
 
       invoke_callbacks(:before_validation)
 
-      task.class.settings[:attributes].define_and_verify(task)
+      task.class.settings.attributes.define_and_verify(task)
       return if task.errors.empty?
 
       result.fail!(
         Locale.t("cmdx.faults.invalid"),
+        source: :validation,
         errors: {
           full_message: task.errors.to_s,
           messages: task.errors.to_h
@@ -224,22 +232,23 @@ module CMDx
     end
 
     # Executes the main task logic.
+    # Wraps task.work in catch(:cmdx_halt) so that success! can halt early.
     #
     # @rbs () -> void
     def execution!
       invoke_callbacks(:before_execution)
 
       result.executing!
-      task.work
+      catch(:cmdx_halt) { task.work }
     end
 
     # Verifies that all declared returns are present in the context after execution.
     #
     # @rbs () -> void
-    def verify_returns!
+    def verify_context_returns!
       return unless result.success?
 
-      returns = Array(task.class.settings[:returns])
+      returns = Utils::Wrap.array(task.class.settings.returns)
       missing = returns.reject { |name| task.context.key?(name) }
       return if missing.empty?
 
@@ -247,6 +256,7 @@ module CMDx
 
       result.fail!(
         Locale.t("cmdx.faults.invalid"),
+        source: :context,
         errors: {
           full_message: task.errors.to_s,
           messages: task.errors.to_h
@@ -258,20 +268,37 @@ module CMDx
     #
     # @rbs () -> void
     def post_execution!
-      invoke_callbacks(:"on_#{result.state}")
+      return if task.class.settings.callbacks.empty?
+
+      invoke_callbacks(STATE_CALLBACKS[result.state])
       invoke_callbacks(:on_executed) if result.executed?
 
-      invoke_callbacks(:"on_#{result.status}")
+      invoke_callbacks(STATUS_CALLBACKS[result.status])
       invoke_callbacks(:on_good) if result.good?
       invoke_callbacks(:on_bad) if result.bad?
     end
 
+    # Detects if middleware swallowed the block without yielding.
+    # When this happens the result is still in the initialized state.
+    #
+    # @rbs () -> void
+    def verify_middleware_yield!
+      return unless result.initialized?
+
+      result.fail!(
+        Locale.t("cmdx.faults.invalid"),
+        halt: false,
+        source: :middleware
+      )
+      result.executed!
+    end
+
     # Finalizes execution by freezing the task, logging results, and rolling back work.
     #
-    # @rbs () -> Result
+    # @rbs () -> void
     def finalize_execution!
       log_execution!
-      log_backtrace! if task.class.settings[:backtrace]
+      log_backtrace! if task.class.settings.backtrace
 
       rollback_execution!
       freeze_execution!
@@ -295,8 +322,8 @@ module CMDx
       return if exception.nil? || exception.is_a?(Fault)
 
       task.logger.error do
-        "[#{exception.class}] #{exception.message}\n" <<
-          if (cleaner = task.class.settings[:backtrace_cleaner])
+        Utils::Normalize.exception(exception) << "\n" <<
+          if (cleaner = task.class.settings.backtrace_cleaner)
             cleaner.call(exception.backtrace).join("\n\t")
           else
             exception.full_message(highlight: false)
@@ -309,25 +336,26 @@ module CMDx
     # @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)
+      return unless CMDx.configuration.freeze_results
 
       task.freeze
       result.freeze
 
-      # Freezing the context and chain can only be done
-      # once the outer-most task has completed.
+      # Freezing the context and chain can only be done once the outer-most
+      # task has completed.
       return unless result.index.zero?
 
       task.context.freeze
       task.chain.freeze
     end
 
-    # Clears the chain if the task is the outermost (top-level) task.
+    # Clears the chain if the task is the outermost (top-level) task
+    # and the current thread's chain is the same instance this task belongs to.
     #
     # @rbs () -> void
     def clear_chain!
       return unless result.index.zero?
+      return unless Chain.current.equal?(task.chain)
 
       Chain.clear
     end
@@ -339,9 +367,8 @@ module CMDx
       return if result.rolled_back?
       return unless task.respond_to?(:rollback)
 
-      statuses = task.class.settings[:rollback_on]
-      statuses = Array(statuses).map(&:to_s).uniq
-      return unless statuses.include?(result.status)
+      @rollback_statuses ||= Utils::Normalize.statuses(task.class.settings.rollback_on).freeze
+      return unless @rollback_statuses.include?(result.status)
 
       result.rolled_back = true
       task.rollback

data/lib/cmdx/identifier.rb

@@ -20,12 +20,10 @@ module CMDx
     #   # => "01890b2c-1234-5678-9abc-def123456789"
     #
     # @rbs () -> String
-    def generate
-      if SecureRandom.respond_to?(:uuid_v7)
-        SecureRandom.uuid_v7
-      else
-        SecureRandom.uuid
-      end
+    if SecureRandom.respond_to?(:uuid_v7)
+      def generate = SecureRandom.uuid_v7
+    else
+      def generate = SecureRandom.uuid
     end
 
   end

data/lib/cmdx/locale.rb

@@ -2,18 +2,15 @@
 
 module CMDx
   # Provides internationalization and localization support for CMDx.
-  # Handles translation lookups with fallback to default English messages
-  # when I18n gem is not available.
+  # Handles translation lookups with fallback to the configured locale's
+  # default messages when I18n gem is not available.
   module Locale
 
     extend self
 
-    # @rbs EN: Hash[String, untyped]
-    EN = YAML.load_file(CMDx.gem_path.join("lib/locales/en.yml")).freeze
-    private_constant :EN
-
     # Translates a key to the current locale with optional interpolation.
-    # Falls back to English translations if I18n gem is unavailable.
+    # Falls back to the configured locale's YAML file translations if
+    # I18n gem is unavailable.
     #
     # @param key [String, Symbol] The translation key (supports dot notation)
     # @param options [Hash] Translation options
@@ -38,12 +35,12 @@ module CMDx
     #
     # @rbs ((String | Symbol) key, **untyped options) -> String
     def translate(key, **options)
-      options[:default] ||= EN.dig("en", *key.to_s.split("."))
+      options[:default] ||= translation_default(key)
       return ::I18n.t(key, **options) if defined?(::I18n)
 
       case message = options.delete(:default)
-      when NilClass then "Translation missing: #{key}"
       when String then message % options
+      when NilClass then "Translation missing: #{key}"
       else message
       end
     end
@@ -51,5 +48,31 @@ module CMDx
     # @see #translate
     alias t translate
 
+    private
+
+    # Resolves and caches the default translation for a key by digging
+    # into the configured locale's YAML translations.
+    #
+    # @param key [String, Symbol] The translation key
+    #
+    # @return [String, nil] The resolved translation or nil
+    #
+    # @rbs ((String | Symbol) key) -> String?
+    def translation_default(key)
+      tkey = "#{CMDx.configuration.default_locale}.#{key}"
+
+      @translation_defaults ||= {}
+      return @translation_defaults[tkey] if @translation_defaults.key?(tkey)
+
+      @default_translations ||= begin
+        path = CMDx.gem_path.join("lib/locales/#{CMDx.configuration.default_locale}.yml")
+        raise ArgumentError, "locale file not found: #{path}" unless path.exist?
+
+        YAML.load_file(path).freeze
+      end
+
+      @translation_defaults[tkey] = @default_translations.dig(*tkey.split("."))
+    end
+
   end
 end

data/lib/cmdx/middleware_registry.rb

@@ -7,43 +7,48 @@ module CMDx
   # that can be inserted, removed, and executed in sequence. Each middleware
   # can be configured with specific options and is executed in the order
   # they were registered.
+  #
+  # Supports copy-on-write semantics: a duped registry shares the parent's
+  # data until a write operation triggers materialization.
   class MiddlewareRegistry
 
-    # Returns the ordered collection of middleware entries.
-    #
-    # @return [Array<Array>] Array of middleware-options pairs
-    #
-    # @example
-    #   registry.registry # => [[LoggingMiddleware, {level: :debug}], [AuthMiddleware, {}]]
-    #
-    # @rbs @registry: Array[Array[untyped]]
-    attr_reader :registry
-    alias to_a registry
-
     # Initialize a new middleware registry.
     #
-    # @param registry [Array] Initial array of middleware entries
+    # @param registry [Array, nil] Initial array of middleware entries
     #
     # @example
     #   registry = MiddlewareRegistry.new
     #   registry = MiddlewareRegistry.new([[MyMiddleware, {option: 'value'}]])
     #
-    # @rbs (?Array[Array[untyped]] registry) -> void
-    def initialize(registry = [])
-      @registry = registry
+    # @rbs (?Array[Array[untyped]]? registry) -> void
+    def initialize(registry = nil)
+      @registry = registry || []
+    end
+
+    # Sets up copy-on-write state when duplicated via dup.
+    #
+    # @param source [MiddlewareRegistry] The registry being duplicated
+    #
+    # @rbs (MiddlewareRegistry source) -> void
+    def initialize_dup(source)
+      @parent = source
+      @registry = nil
+      super
     end
 
-    # Create a duplicate of the registry with duplicated middleware entries.
+    # Returns the ordered collection of middleware entries.
+    # Delegates to the parent registry when not yet materialized.
     #
-    # @return [MiddlewareRegistry] A new registry instance with duplicated entries
+    # @return [Array<Array>] Array of middleware-options pairs
     #
     # @example
-    #   new_registry = registry.dup
+    #   registry.registry # => [[LoggingMiddleware, {level: :debug}], [AuthMiddleware, {}]]
     #
-    # @rbs () -> MiddlewareRegistry
-    def dup
-      self.class.new(registry.map(&:dup))
+    # @rbs () -> Array[Array[untyped]]
+    def registry
+      @registry || @parent.registry
     end
+    alias to_a registry
 
     # Register a middleware component in the registry.
     #
@@ -61,7 +66,9 @@ module CMDx
     #
     # @rbs (untyped middleware, ?at: Integer, **untyped options) -> self
     def register(middleware, at: -1, **options)
-      registry.insert(at, [middleware, options])
+      materialize!
+
+      @registry.insert(at, [middleware, options])
       self
     end
 
@@ -76,7 +83,9 @@ module CMDx
     #
     # @rbs (untyped middleware) -> self
     def deregister(middleware)
-      registry.reject! { |mw, _opts| mw == middleware }
+      materialize!
+
+      @registry.reject! { |mw, _opts| mw == middleware }
       self
     end
 
@@ -105,6 +114,17 @@ module CMDx
 
     private
 
+    # Copies the parent's registry data into this instance,
+    # severing the copy-on-write link.
+    #
+    # @rbs () -> void
+    def materialize!
+      return if @registry
+
+      @registry = @parent.registry.map(&:dup)
+      @parent = nil
+    end
+
     # Recursively execute middleware in the chain.
     #
     # @param index [Integer] Current middleware index in the chain

data/lib/cmdx/middlewares/correlate.rb

@@ -129,8 +129,10 @@ module CMDx
       # @return [Hash] The thread or fiber storage
       #
       # @rbs () -> Hash
-      def thread_or_fiber
-        Fiber.respond_to?(:storage) ? Fiber.storage : Thread.current
+      if Fiber.respond_to?(:storage)
+        def thread_or_fiber = Fiber.storage
+      else
+        def thread_or_fiber = Thread.current
       end
 
     end

data/lib/cmdx/middlewares/runtime.rb

@@ -11,7 +11,8 @@ module CMDx
 
       extend self
 
-      # Middleware entry point that measures task execution runtime.
+      # Middleware entry point that measures task execution runtime and
+      # task execution start and end times.
       #
       # Evaluates the condition from options and measures execution time
       # if enabled. Uses monotonic clock for precise timing measurements
@@ -35,11 +36,16 @@ module CMDx
       #
       # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
       def call(task, **options)
+        unow = utc_time
+        mnow = monotonic_time
         return yield unless Utils::Condition.evaluate(task, options)
 
-        now = monotonic_time
         result = yield
-        task.result.metadata[:runtime] = monotonic_time - now
+        task.result.metadata.merge!(
+          runtime: monotonic_time - mnow,
+          ended_at: utc_time,
+          started_at: unow
+        )
         result
       end
 
@@ -57,6 +63,15 @@ module CMDx
         Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
       end
 
+      # Gets the current UTC time in ISO 8601 format.
+      #
+      # @return [String] Current UTC time in ISO 8601 format
+      #
+      # @rbs () -> String
+      def utc_time
+        Time.now.utc.iso8601
+      end
+
     end
   end
 end

data/lib/cmdx/middlewares/timeout.rb

@@ -1,14 +1,6 @@
 # frozen_string_literal: true
 
 module CMDx
-
-  # Error raised when task execution exceeds the configured timeout limit.
-  #
-  # This error occurs when a task takes longer to execute than the specified
-  # time limit. Timeout errors are raised by Ruby's Timeout module and are
-  # caught by the middleware to properly fail the task with timeout information.
-  TimeoutError = Class.new(Interrupt)
-
   module Middlewares
     # Middleware for enforcing execution time limits on tasks.
     #
@@ -66,12 +58,21 @@ module CMDx
           else callable.respond_to?(:call) ? callable.call(task) : DEFAULT_LIMIT
           end
 
+        limit = Float(limit)
+        return yield unless limit.positive?
+
         ::Timeout.timeout(limit, TimeoutError, "execution exceeded #{limit} seconds", &)
       rescue TimeoutError => e
-        task.result.tap { |r| r.fail!("[#{e.class}] #{e.message}", cause: e, limit:) }
+        task.result.tap do |r|
+          r.fail!(
+            Utils::Normalize.exception(e),
+            cause: e,
+            source: :timeout,
+            limit:
+          )
+        end
       end
 
     end
   end
-
 end