cmdx 1.1.2 → 1.5.1

data/lib/cmdx/middlewares/correlate.rb

@@ -2,78 +2,114 @@
 
 module CMDx
   module Middlewares
-    # Middleware that manages correlation IDs for task execution tracing.
-    # Automatically generates or uses provided correlation IDs to track task execution
-    # across complex workflows, enabling better debugging and monitoring.
-    class Correlate < CMDx::Middleware
+    # Middleware for correlating task executions with unique identifiers.
+    #
+    # The Correlate middleware provides thread-safe correlation ID management
+    # for tracking task execution flows across different operations.
+    # It automatically generates correlation IDs when none are provided and
+    # stores them in task result metadata for traceability.
+    module Correlate
 
-      # @return [String, Symbol, Proc, nil] The explicit correlation ID to use, or callable that generates one
-      attr_reader :id
+      extend self
 
-      # @return [Hash] The conditional options for correlation application
-      attr_reader :conditional
+      THREAD_KEY = :cmdx_correlate
 
-      # Initializes the correlation middleware with optional configuration.
+      # Retrieves the current correlation ID from thread-local storage.
       #
-      # @param options [Hash] configuration options for the middleware
-      # @option options [String, Symbol, Proc] :id explicit correlation ID or callable to generate one
-      # @option options [Symbol, Proc] :if condition that must be truthy to apply correlation
-      # @option options [Symbol, Proc] :unless condition that must be falsy to apply correlation
+      # @return [String, nil] The current correlation ID or nil if not set
       #
-      # @return [Correlate] new instance of the middleware
+      # @example Get current correlation ID
+      #   Correlate.id # => "550e8400-e29b-41d4-a716-446655440000"
+      def id
+        Thread.current[THREAD_KEY]
+      end
+
+      # Sets the correlation ID in thread-local storage.
       #
-      # @example Register with a middleware instance
-      #   use :middleware, CMDx::Middlewares::Correlate.new(id: "request-123")
+      # @param id [String] The correlation ID to set
+      # @return [String] The set correlation ID
       #
-      # @example Register with explicit ID
-      #   use :middleware, CMDx::Middlewares::Correlate, id: "request-123"
+      # @example Set correlation ID
+      #   Correlate.id = "abc-123-def"
+      def id=(id)
+        Thread.current[THREAD_KEY] = id
+      end
+
+      # Clears the current correlation ID from thread-local storage.
       #
-      # @example Register with dynamic ID generation
-      #   use :middleware, CMDx::Middlewares::Correlate, id: -> { SecureRandom.uuid }
+      # @return [nil] Always returns nil
       #
-      # @example Register with conditions
-      #   use :middleware, CMDx::Middlewares::Correlate, if: :production?, unless: :testing?
-      def initialize(options = {})
-        @id          = options[:id]
-        @conditional = options.slice(:if, :unless)
+      # @example Clear correlation ID
+      #   Correlate.clear
+      def clear
+        Thread.current[THREAD_KEY] = nil
       end
 
-      # Executes the middleware, wrapping task execution with correlation context.
-      # Evaluates conditions, determines correlation ID, and executes the task within
-      # the correlation context for tracing purposes.
+      # Temporarily uses a new correlation ID for the duration of a block.
+      # Restores the previous ID after the block completes, even if an error occurs.
       #
-      # @param task [CMDx::Task] the task being executed
-      # @param callable [Proc] the callable that executes the task
+      # @param new_id [String] The correlation ID to use temporarily
+      # @yield The block to execute with the new correlation ID
+      # @return [Object] The result of the yielded block
       #
-      # @return [Object] the result of the task execution
+      # @example Use temporary correlation ID
+      #   Correlate.use("temp-id") do
+      #     # Operations here use "temp-id"
+      #     perform_operation
+      #   end
+      #   # Previous ID is restored
+      def use(new_id)
+        old_id = id
+        self.id = new_id
+        yield
+      ensure
+        self.id = old_id
+      end
+
+      # Middleware entry point that applies correlation ID logic to task execution.
       #
-      # @example Task using correlation middleware
-      #   class ProcessOrderTask < CMDx::Task
-      #     use :middleware, CMDx::Middlewares::Correlate, id: "trace-123"
+      # Evaluates the condition from options and applies correlation ID handling
+      # if enabled. Generates or retrieves correlation IDs based on the :id option
+      # and stores them in task result metadata.
       #
-      #     def call
-      #       # Task execution is automatically wrapped with correlation
-      #     end
-      #   end
+      # @param task [Task] The task being executed
+      # @param options [Hash] Configuration options for correlation
+      # @option options [Symbol, Proc, Object, nil] :id The correlation ID source
+      # @option options [Symbol, Proc, Object, nil] :if Condition to enable correlation
+      # @option options [Symbol, Proc, Object, nil] :unless Condition to disable correlation
       #
-      # @example Global configuration with conditional tracing
-      #   CMDx.configure do |config|
-      #     config.middlewares.register CMDx::Middlewares::Correlate, if: :should_trace?
-      #   end
-      def call(task, callable)
-        # Check if correlation should be applied based on conditions
-        return callable.call(task) unless task.cmdx_eval(conditional)
+      # @yield The task execution block
+      #
+      # @return [Object] The result of task execution
+      #
+      # @example Basic usage with automatic ID generation
+      #   Correlate.call(task, &block)
+      # @example Use custom correlation ID
+      #   Correlate.call(task, id: "custom-123", &block)
+      # @example Use task method for ID
+      #   Correlate.call(task, id: :correlation_id, &block)
+      # @example Use proc for dynamic ID generation
+      #   Correlate.call(task, id: -> { "dynamic-#{Time.now.to_i}" }, &block)
+      # @example Conditional correlation
+      #   Correlate.call(task, if: :enable_correlation, &block)
+      def call(task, **options, &)
+        return yield unless Utils::Condition.evaluate(task, options)
 
-        # Get correlation ID using yield for dynamic generation
-        correlation_id = task.cmdx_yield(id) ||
-                         CMDx::Correlator.id ||
-                         task.chain.id ||
-                         CMDx::Correlator.generate
+        correlation_id =
+          case callable = options[:id]
+          when Symbol then task.send(callable)
+          when Proc then task.instance_eval(&callable)
+          else
+            if callable.respond_to?(:call)
+              callable.call(task)
+            else
+              callable || id || Identifier.generate
+            end
+          end
 
-        # Execute task with correlation context
-        CMDx::Correlator.use(correlation_id) do
-          callable.call(task)
-        end
+        result = use(correlation_id, &)
+        task.result.metadata[:correlation_id] = correlation_id
+        result
       end
 
     end

data/lib/cmdx/middlewares/runtime.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Middlewares
+    # Middleware for measuring task execution runtime.
+    #
+    # The Runtime middleware provides performance monitoring by measuring
+    # the execution time of tasks using monotonic clock for accuracy.
+    # It stores runtime measurements in task result metadata for analysis.
+    module Runtime
+
+      extend self
+
+      # Middleware entry point that measures task execution runtime.
+      #
+      # Evaluates the condition from options and measures execution time
+      # if enabled. Uses monotonic clock for precise timing measurements
+      # and stores the result in task metadata.
+      #
+      # @param task [Task] The task being executed
+      # @param options [Hash] Configuration options for runtime measurement
+      # @option options [Symbol, Proc, Object, nil] :if Condition to enable runtime measurement
+      # @option options [Symbol, Proc, Object, nil] :unless Condition to disable runtime measurement
+      #
+      # @yield The task execution block
+      #
+      # @return [Object] The result of task execution
+      #
+      # @example Basic usage with automatic runtime measurement
+      #   Runtime.call(task, &block)
+      # @example Conditional runtime measurement
+      #   Runtime.call(task, if: :enable_profiling, &block)
+      # @example Disable runtime measurement
+      #   Runtime.call(task, unless: :skip_profiling, &block)
+      def call(task, **options)
+        return yield unless Utils::Condition.evaluate(task, options)
+
+        now = monotonic_time
+        result = yield
+        task.result.metadata[:runtime] = monotonic_time - now
+        result
+      end
+
+      private
+
+      # Gets the current monotonic time in milliseconds.
+      #
+      # Uses Process.clock_gettime with CLOCK_MONOTONIC for consistent
+      # timing measurements that are not affected by system clock changes.
+      #
+      # @return [Integer] Current monotonic time in milliseconds
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      end
+
+    end
+  end
+end

data/lib/cmdx/middlewares/timeout.rb

@@ -2,89 +2,69 @@
 
 module CMDx
 
-  # Custom exception raised when task execution exceeds the configured timeout limit.
-  # Inherits from Interrupt to provide consistent error handling for timeout scenarios
-  # and allow proper interruption of long-running tasks.
+  # 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 that provides execution timeout protection for tasks.
-    # Automatically interrupts task execution if it exceeds the specified time limit,
-    # preventing runaway processes and ensuring system responsiveness.
-    class Timeout < CMDx::Middleware
+    # Middleware for enforcing execution time limits on tasks.
+    #
+    # The Timeout middleware provides execution time control by wrapping
+    # task execution with Ruby's Timeout module. It automatically fails
+    # tasks that exceed the configured time limit and provides detailed
+    # error information including the exceeded limit.
+    module Timeout
 
-      # @return [Integer, Float, Symbol, Proc] The timeout value in seconds
-      attr_reader :seconds
+      extend self
 
-      # @return [Hash] The conditional options for timeout application
-      attr_reader :conditional
+      # Default timeout limit in seconds when none is specified.
+      DEFAULT_LIMIT = 3
 
-      # Initializes the timeout middleware with optional configuration.
+      # Middleware entry point that enforces execution time limits.
       #
-      # @param options [Hash] configuration options for the middleware
-      # @option options [Integer, Float, Symbol, Proc] :seconds timeout duration in seconds (default: 3)
-      # @option options [Symbol, Proc] :if condition that must be truthy to apply timeout
-      # @option options [Symbol, Proc] :unless condition that must be falsy to apply timeout
+      # Evaluates the condition from options and applies timeout control
+      # if enabled. Supports various timeout limit configurations including
+      # numeric values, task method calls, and dynamic proc evaluation.
       #
-      # @return [Timeout] new instance of the middleware
+      # @param task [Task] The task being executed
+      # @param options [Hash] Configuration options for timeout control
+      # @option options [Numeric, Symbol, Proc, Object] :seconds The timeout limit source
+      # @option options [Symbol, Proc, Object, nil] :if Condition to enable timeout control
+      # @option options [Symbol, Proc, Object, nil] :unless Condition to disable timeout control
       #
-      # @example Register with a middleware instance
-      #   use :middleware, CMDx::Middlewares::Timeout.new(seconds: 30)
+      # @yield The task execution block
       #
-      # @example Register with fixed timeout
-      #   use :middleware, CMDx::Middlewares::Timeout, seconds: 30
+      # @return [Object] The result of task execution
       #
-      # @example Register with dynamic timeout
-      #   use :middleware, CMDx::Middlewares::Timeout, seconds: -> { Rails.env.test? ? 1 : 10 }
+      # @raise [TimeoutError] When execution exceeds the configured limit
       #
-      # @example Register with conditions
-      #   use :middleware, CMDx::Middlewares::Timeout, seconds: 5, if: :long_running?, unless: :skip_timeout?
-      def initialize(options = {})
-        @seconds     = options[:seconds] || 3
-        @conditional = options.slice(:if, :unless)
-      end
-
-      # Executes the middleware, wrapping task execution with timeout protection.
-      # Evaluates conditions, determines timeout duration, and executes the task within
-      # the timeout boundary to prevent runaway execution.
-      #
-      # @param task [CMDx::Task] the task being executed
-      # @param callable [Proc] the callable that executes the task
-      #
-      # @return [Object] the result of the task execution
-      #
-      # @raise [TimeoutError] when task execution exceeds the timeout limit
-      #
-      # @example Task using timeout middleware
-      #   class ProcessFileTask < CMDx::Task
-      #     use :middleware, CMDx::Middlewares::Timeout, seconds: 10
-      #
-      #     def call
-      #       # Task execution is automatically wrapped with timeout protection
-      #     end
-      #   end
-      #
-      # @example Global configuration with conditional timeout
-      #   CMDx.configure do |config|
-      #     config.middlewares.register CMDx::Middlewares::Timeout, seconds: 30, if: :large_dataset?
-      #   end
-      def call(task, callable)
-        # Check if timeout should be applied based on conditions
-        return callable.call(task) unless task.cmdx_eval(conditional)
-
-        # Get seconds using yield for dynamic generation
-        limit = task.cmdx_yield(seconds) || 3
+      # @example Basic usage with default 3 second timeout
+      #   Timeout.call(task, &block)
+      # @example Custom timeout limit in seconds
+      #   Timeout.call(task, seconds: 10, &block)
+      # @example Use task method for timeout limit
+      #   Timeout.call(task, seconds: :timeout_limit, &block)
+      # @example Use proc for dynamic timeout calculation
+      #   Timeout.call(task, seconds: -> { calculate_timeout }, &block)
+      # @example Conditional timeout control
+      #   Timeout.call(task, if: :enable_timeout, &block)
+      def call(task, **options, &)
+        return yield unless Utils::Condition.evaluate(task, options)
 
-        # Ensure limit is numeric, fallback to default if not
-        limit = 3 unless limit.is_a?(Numeric)
+        limit =
+          case callable = options[:seconds]
+          when Numeric then callable
+          when Symbol then task.send(callable)
+          when Proc then task.instance_eval(&callable)
+          else callable.respond_to?(:call) ? callable.call(task) : DEFAULT_LIMIT
+          end
 
-        # Apply timeout protection
-        ::Timeout.timeout(limit, TimeoutError, "execution exceeded #{limit} seconds") do
-          callable.call(task)
-        end
+        ::Timeout.timeout(limit, TimeoutError, "execution exceeded #{limit} seconds", &)
       rescue TimeoutError => e
-        task.fail!(reason: "[#{e.class}] #{e.message}", original_exception: e, seconds: limit)
-        task.result
+        task.result.tap { |r| r.fail!("[#{e.class}] #{e.message}", cause: e, limit:) }
       end
 
     end

data/lib/cmdx/railtie.rb

@@ -1,32 +1,29 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Rails integration for CMDx framework.
-  #
-  # Provides Rails-specific configuration including internationalization
-  # locale loading and autoload path configuration for CMDx workflows and tasks.
+  # Rails integration class that automatically configures CMDx when the Rails
+  # application initializes. Handles locale configuration and I18n setup.
   class Railtie < Rails::Railtie
 
     railtie_name :cmdx
 
-    # Configure internationalization locales for CMDx.
+    # Configures CMDx locales during Rails application initialization.
     #
-    # Loads available locale files from the CMDx locales directory
-    # and adds them to the I18n load path. Only loads locales that
-    # are configured as available in the Rails application.
+    # Iterates through available locales from the Rails configuration and loads
+    # corresponding CMDx locale files. Reloads the I18n system to ensure
+    # all locales are properly registered.
     #
     # @param app [Rails::Application] the Rails application instance
     #
-    # @return [void]
+    # @raise [LoadError] if locale files cannot be loaded
     #
-    # @raise [StandardError] if I18n reload fails
-    #
-    # @example Configure locales during Rails initialization
-    #   # This initializer runs automatically during Rails boot
-    #   # when CMDx is included in a Rails application
+    # @example
+    #   # This initializer runs automatically when Rails starts
+    #   # It will load locales like en.yml, es.yml, fr.yml if they exist
+    #   # in the CMDx gem's locales directory
     initializer("cmdx.configure_locales") do |app|
       Array(app.config.i18n.available_locales).each do |locale|
-        path = File.expand_path("../../../lib/locales/#{locale}.yml", __FILE__)
+        path = CMDx.gem_path.join("lib/locales/#{locale}.yml")
         next unless File.file?(path)
 
         I18n.load_path << path
@@ -35,35 +32,5 @@ module CMDx
       I18n.reload!
     end
 
-    # Configure Rails autoload paths for CMDx components.
-    #
-    # Adds the app/cmds directory to Rails autoload paths and configures
-    # autoloaders to collapse the workflows and tasks subdirectories.
-    # This enables Rails to automatically load CMDx workflows and tasks
-    # from the conventional directory structure.
-    #
-    # @param app [Rails::Application] the Rails application instance
-    #
-    # @return [void]
-    #
-    # @raise [StandardError] if autoloader configuration fails
-    #
-    # @example Configure autoload paths during Rails initialization
-    #   # This initializer runs automatically during Rails boot
-    #   # Enables loading of:
-    #   # - app/cmds/workflows/my_workflow.rb
-    #   # - app/cmds/tasks/my_task.rb
-    initializer("cmdx.configure_rails_auto_load_paths") do |app|
-      app.config.autoload_paths += %w[app/cmds]
-
-      types = %w[workflows tasks]
-      app.autoloaders.each do |autoloader|
-        types.each do |concept|
-          dir = app.root.join("app/cmds/#{concept}")
-          autoloader.collapse(dir)
-        end
-      end
-    end
-
   end
 end