cmdx 1.0.1 → 1.1.0

data/lib/cmdx/middlewares/correlate.rb

@@ -2,255 +2,70 @@
 
 module CMDx
   module Middlewares
-    ##
-    # Correlation middleware for ensuring consistent correlation ID context during task execution.
-    #
-    # The Correlate middleware establishes and maintains correlation ID context throughout
-    # task execution, enabling seamless request tracking across task boundaries. It ensures
-    # that all tasks within an execution chain share the same correlation identifier for
-    # comprehensive traceability and debugging.
-    #
-    # ## Correlation ID Precedence
-    #
-    # The middleware determines the correlation ID using the following precedence:
-    # 1. **Explicit correlation ID** - Value provided during middleware initialization
-    # 2. **Current thread correlation** - Existing correlation from `CMDx::Correlator.id`
-    # 3. **Chain identifier** - The task's chain ID if no thread correlation exists
-    # 4. **Generated UUID** - New correlation ID if none of the above is available
-    #
-    # ## Conditional Execution
-    #
-    # The middleware supports conditional execution using `:if` and `:unless` options:
-    # - `:if` - Only applies correlation when the condition evaluates to true
-    # - `:unless` - Only applies correlation when the condition evaluates to false
-    # - Conditions can be Procs, method symbols, or boolean values
-    #
-    # ## Thread Safety
-    #
-    # The middleware uses `CMDx::Correlator.use` to establish a correlation context
-    # that is automatically restored after task execution, ensuring thread-local
-    # isolation and proper cleanup even in case of exceptions.
-    #
-    # ## Integration with CMDx Framework
-    #
-    # - **Automatic activation**: Can be applied globally or per-task via `use` directive
-    # - **Chain integration**: Works seamlessly with CMDx::Chain correlation inheritance
-    # - **Nested tasks**: Maintains correlation context across nested task calls
-    # - **Exception safety**: Restores correlation context even when tasks fail
-    #
-    # @example Basic task-specific middleware application
-    #   class ProcessOrderTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate
-    #
-    #     def call
-    #       # Task execution maintains correlation context
-    #       SendEmailTask.call(context)  # Inherits same correlation
-    #     end
-    #   end
-    #
-    # @example Middleware with explicit correlation ID
-    #   class ProcessOrderTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate, id: "order-processing-123"
-    #
-    #     def call
-    #       # Always uses "order-processing-123" as correlation ID
-    #       context.correlation_used = CMDx::Correlator.id
-    #     end
-    #   end
-    #
-    #   result = ProcessOrderTask.call(order_id: 123)
-    #   result.context.correlation_used  # => "order-processing-123"
-    #
-    # @example Middleware with dynamic correlation ID using procs
-    #   class ProcessOrderTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{Time.now.to_i}" }
-    #
-    #     def call
-    #       # Uses dynamically generated correlation ID
-    #       context.correlation_used = CMDx::Correlator.id
-    #     end
-    #   end
-    #
-    #   result = ProcessOrderTask.call(order_id: 456)
-    #   result.context.correlation_used  # => "order-456-1703123456"
-    #
-    # @example Middleware with method-based correlation ID
-    #   class ProcessOrderTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate, id: :generate_order_correlation
-    #
-    #     def call
-    #       # Uses correlation ID from generate_order_correlation method
-    #       context.correlation_used = CMDx::Correlator.id
-    #     end
-    #
-    #     private
-    #
-    #     def generate_order_correlation
-    #       "order-#{order_id}-#{context.request_id}"
-    #     end
-    #   end
-    #
-    # @example Conditional correlation based on environment
-    #   class ProcessOrderTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate, unless: -> { Rails.env.test? }
-    #
-    #     def call
-    #       # Correlation only applied in non-test environments
-    #       context.order = Order.find(order_id)
-    #     end
-    #   end
-    #
-    # @example Conditional correlation based on task state
-    #   class ProcessOrderTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate, if: :correlation_required?
-    #
-    #     def call
-    #       # Correlation applied only when correlation_required? returns true
-    #       context.order = Order.find(order_id)
-    #     end
-    #
-    #     private
-    #
-    #     def correlation_required?
-    #       context.tracking_enabled == true
-    #     end
-    #   end
-    #
-    # @example Nested task correlation propagation
-    #   class ParentTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate
-    #
-    #     def call
-    #       # Correlation established at parent level
-    #       ChildTask.call(context)
-    #     end
-    #   end
-    #
-    #   class ChildTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate
-    #
-    #     def call
-    #       # Inherits parent's correlation ID
-    #       context.child_correlation = CMDx::Correlator.id
-    #     end
-    #   end
-    #
-    # @example Exception handling with correlation restoration
-    #   class RiskyTask < CMDx::Task
-    #     use CMDx::Middlewares::Correlate
-    #
-    #     def call
-    #       raise StandardError, "Task failed"
-    #     end
-    #   end
-    #
-    #   CMDx::Correlator.id = "original-correlation"
-    #
-    #   begin
-    #     RiskyTask.call
-    #   rescue StandardError
-    #     CMDx::Correlator.id  # => "original-correlation" (properly restored)
-    #   end
-    #
-    # @see CMDx::Correlator Thread-safe correlation ID management
-    # @see CMDx::Chain Chain execution context with correlation inheritance
-    # @see CMDx::Middleware Base middleware class
-    # @since 1.0.0
+    # 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
 
-      # @return [String, nil] The explicit correlation ID to use
+      # @return [String, Symbol, Proc, nil] The explicit correlation ID to use, or callable that generates one
+      attr_reader :id
+
       # @return [Hash] The conditional options for correlation application
-      attr_reader :id, :conditional
+      attr_reader :conditional
 
-      ##
-      # Initializes the Correlate middleware with optional configuration.
+      # Initializes the correlation middleware with optional configuration.
       #
       # @param options [Hash] configuration options for the middleware
-      # @option options [String, Symbol, Proc] :id explicit correlation ID to use (takes precedence over all other sources)
-      # @option options [Proc, Symbol, Boolean] :if condition that must be true for middleware to execute
-      # @option options [Proc, Symbol, Boolean] :unless condition that must be false for middleware to execute
+      # @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 [Correlate] new instance of the middleware
+      #
+      # @example Register with a middleware instance
+      #   use :middleware, CMDx::Middlewares::Correlate.new(id: "request-123")
       #
-      # @example Basic initialization
-      #   middleware = CMDx::Middlewares::Correlate.new
+      # @example Register with explicit ID
+      #   use :middleware, CMDx::Middlewares::Correlate, id: "request-123"
       #
-      # @example With explicit correlation ID
-      #   middleware = CMDx::Middlewares::Correlate.new(id: "api-request-123")
+      # @example Register with dynamic ID generation
+      #   use :middleware, CMDx::Middlewares::Correlate, id: -> { SecureRandom.uuid }
       #
-      # @example With conditional execution
-      #   middleware = CMDx::Middlewares::Correlate.new(unless: -> { Rails.env.test? })
-      #   middleware = CMDx::Middlewares::Correlate.new(if: :correlation_enabled?)
+      # @example Register with conditions
+      #   use :middleware, CMDx::Middlewares::Correlate, if: :production?, unless: :testing?
       def initialize(options = {})
         @id          = options[:id]
         @conditional = options.slice(:if, :unless)
       end
 
-      ##
-      # Executes the task within a managed correlation context.
-      #
-      # First evaluates any conditional execution rules (`:if` or `:unless` options).
-      # If conditions allow execution, establishes a correlation ID using the
-      # precedence hierarchy and executes the task within that correlation context.
-      # The correlation ID is automatically restored after task completion, ensuring
-      # proper cleanup and thread isolation.
-      #
-      # The correlation ID determination follows this precedence:
-      # 1. Explicit correlation ID (provided during middleware initialization)
-      #    - String/Symbol: Used as-is or called as method if task responds to it
-      #    - Proc/Lambda: Executed in task context for dynamic generation
-      # 2. Current thread correlation (CMDx::Correlator.id)
-      # 3. Task's chain ID (task.chain.id)
-      # 4. Generated UUID (CMDx::Correlator.generate)
-      #
-      # @param task [CMDx::Task] the task instance to execute
-      # @param callable [#call] the callable that executes the task
-      # @return [CMDx::Result] the task execution result
-      #
-      # @example Basic middleware execution
-      #   middleware = CMDx::Middlewares::Correlate.new
-      #   task = ProcessOrderTask.new(order_id: 123)
-      #   callable = -> { task.call }
-      #
-      #   result = middleware.call(task, callable)
-      #   # Task executed within correlation context
-      #
-      # @example Correlation ID precedence in action
-      #   # Scenario 1: Explicit string correlation ID takes precedence
-      #   middleware = CMDx::Middlewares::Correlate.new(id: "explicit-123")
-      #   middleware.call(task, callable)  # Uses "explicit-123"
-      #
-      #   # Scenario 2: Dynamic correlation ID using proc
-      #   middleware = CMDx::Middlewares::Correlate.new(id: -> { "dynamic-#{order_id}" })
-      #   middleware.call(task, callable)  # Uses result of proc execution
+      # 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.
       #
-      #   # Scenario 3: Method-based correlation ID
-      #   middleware = CMDx::Middlewares::Correlate.new(id: :correlation_method)
-      #   middleware.call(task, callable)  # Uses task.correlation_method if it exists
+      # @param task [CMDx::Task] the task being executed
+      # @param callable [Proc] the callable that executes the task
       #
-      #   # Scenario 4: Thread correlation when no explicit ID
-      #   CMDx::Correlator.id = "thread-correlation"
-      #   middleware = CMDx::Middlewares::Correlate.new
-      #   middleware.call(task, callable)  # Uses "thread-correlation"
+      # @return [Object] the result of the task execution
       #
-      #   # Scenario 5: Chain ID when no explicit or thread correlation
-      #   CMDx::Correlator.clear
-      #   middleware.call(task, callable)  # Uses task.chain.id
+      # @example Task using correlation middleware
+      #   class ProcessOrderTask < CMDx::Task
+      #     use :middleware, CMDx::Middlewares::Correlate, id: "trace-123"
       #
-      #   # Scenario 6: Generated UUID when no other correlation exists
-      #   CMDx::Correlator.clear
-      #   # Assuming task.chain.id is nil
-      #   middleware.call(task, callable)  # Uses generated UUID
+      #     def call
+      #       # Task execution is automatically wrapped with correlation
+      #     end
+      #   end
       #
-      # @example Conditional execution
-      #   # Middleware only executes in production
-      #   middleware = CMDx::Middlewares::Correlate.new(if: -> { Rails.env.production? })
-      #   result = middleware.call(task, callable)
-      #   # Correlation applied only in production environment
+      # @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)
+        return callable.call(task) unless task.cmdx_eval(conditional)
 
         # Get correlation ID using yield for dynamic generation
-        correlation_id = task.__cmdx_yield(id) ||
+        correlation_id = task.cmdx_yield(id) ||
                          CMDx::Correlator.id ||
                          task.chain.id ||
                          CMDx::Correlator.generate

data/lib/cmdx/middlewares/timeout.rb

@@ -2,220 +2,81 @@
 
 module CMDx
 
-  ##
-  # Timeout middleware that enforces execution time limits on tasks.
-  #
-  # This middleware wraps task execution with timeout protection, automatically
-  # failing tasks that exceed their configured timeout duration. The timeout
-  # value can be static, dynamic, or method-based. If no timeout is specified,
-  # it defaults to 3 seconds. Optionally supports conditional timeout application
-  # based on task or context state.
-  #
-  # ## Timeout Value Types
-  #
-  # The middleware supports multiple ways to specify timeout values:
-  # - **Static values** (Integer/Float): Fixed timeout duration
-  # - **Method symbols**: Calls the specified method on the task for dynamic calculation
-  # - **Procs/Lambdas**: Executed in task context for runtime timeout determination
-  #
-  # ## Conditional Execution
-  #
-  # The middleware supports conditional timeout application using `:if` and `:unless` options:
-  # - `:if` - Only applies timeout when the condition evaluates to true
-  # - `:unless` - Only applies timeout when the condition evaluates to false
-  # - Conditions can be Procs, method symbols, or boolean values
-  #
-  # @example Static timeout configuration
-  #   class ProcessOrderTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout, seconds: 30 # 30 seconds
-  #
-  #     def call
-  #       # Task logic that might take too long
-  #     end
-  #   end
-  #
-  # @example Dynamic timeout using proc
-  #   class ProcessOrderTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout, seconds: -> { complex_order? ? 60 : 30 }
-  #
-  #     def call
-  #       # Task logic with dynamic timeout based on order complexity
-  #     end
-  #
-  #     private
-  #
-  #     def complex_order?
-  #       context.order_items.count > 10
-  #     end
-  #   end
-  #
-  # @example Method-based timeout
-  #   class ProcessOrderTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout, seconds: :calculate_timeout
-  #
-  #     def call
-  #       # Task logic with method-calculated timeout
-  #     end
-  #
-  #     private
-  #
-  #     def calculate_timeout
-  #       base_timeout = 30
-  #       base_timeout += (context.order_items.count * 2)
-  #       base_timeout
-  #     end
-  #   end
-  #
-  # @example Using default timeout (3 seconds)
-  #   class QuickTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout # 3 seconds default
-  #
-  #     def call
-  #       # Task logic with default timeout
-  #     end
-  #   end
-  #
-  # @example Conditional timeout based on task context
-  #   class ProcessOrderTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout,
-  #         seconds: 30,
-  #         if: proc { context.enable_timeout? }
-  #
-  #     def call
-  #       # Task logic with conditional timeout
-  #     end
-  #   end
-  #
-  # @example Conditional timeout with method reference
-  #   class ProcessOrderTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout,
-  #         seconds: 60,
-  #         unless: :skip_timeout?
-  #
-  #     def call
-  #       # Task logic
-  #     end
-  #
-  #     private
-  #
-  #     def skip_timeout?
-  #       Rails.env.development?
-  #     end
-  #   end
-  #
-  # @example Global timeout middleware
-  #   class ApplicationTask < CMDx::Task
-  #     use CMDx::Middlewares::Timeout, seconds: 60 # Default 60 seconds
-  #   end
-  #
-  # @see CMDx::Middleware Base middleware class
-  # @see CMDx::Task Task settings configuration
-  # @see CMDx::Workflow Workflow execution context
-
-  ##
-  # Custom timeout error class that inherits from Interrupt.
-  #
-  # This error is raised when task execution exceeds the configured timeout
-  # duration. It provides a clean way to distinguish timeout errors from
-  # other types of interruptions or exceptions.
-  #
-  # @example Catching timeout errors
-  #   begin
-  #     task.call
-  #   rescue CMDx::TimeoutError => e
-  #     puts "Task timed out: #{e.message}"
-  #   end
-  #
-  # @see CMDx::Middlewares::Timeout The middleware that raises this error
+  # 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.
   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
 
       # @return [Integer, Float, Symbol, Proc] The timeout value in seconds
+      attr_reader :seconds
+
       # @return [Hash] The conditional options for timeout application
-      attr_reader :seconds, :conditional
+      attr_reader :conditional
 
-      ##
-      # Initializes the timeout middleware.
+      # Initializes the timeout middleware with optional configuration.
       #
-      # @param options [Hash] Configuration options for the timeout middleware
-      # @option options [Integer, Float, Symbol, Proc] :seconds Timeout value in seconds.
-      #   - Integer/Float: Used as-is for static timeout
-      #   - Symbol: Called as method on task if it exists, otherwise used as numeric value
-      #   - Proc/Lambda: Executed in task context for dynamic timeout calculation
-      #   Defaults to 3 seconds if not provided.
-      # @option options [Symbol, Proc] :if Condition that must be truthy for timeout to be applied
-      # @option options [Symbol, Proc] :unless Condition that must be falsy for timeout to be applied
+      # @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
       #
-      # @example Static timeout configuration
-      #   CMDx::Middlewares::Timeout.new(seconds: 30)
+      # @return [Timeout] new instance of the middleware
       #
-      # @example Dynamic timeout with proc
-      #   CMDx::Middlewares::Timeout.new(seconds: -> { heavy_operation? ? 120 : 30 })
+      # @example Register with a middleware instance
+      #   use :middleware, CMDx::Middlewares::Timeout.new(seconds: 30)
       #
-      # @example Method-based timeout
-      #   CMDx::Middlewares::Timeout.new(seconds: :calculate_timeout_limit)
+      # @example Register with fixed timeout
+      #   use :middleware, CMDx::Middlewares::Timeout, seconds: 30
       #
-      # @example Using default timeout (3 seconds)
-      #   CMDx::Middlewares::Timeout.new
+      # @example Register with dynamic timeout
+      #   use :middleware, CMDx::Middlewares::Timeout, seconds: -> { Rails.env.test? ? 1 : 10 }
       #
-      # @example Conditional timeout
-      #   CMDx::Middlewares::Timeout.new(seconds: 30, if: :production_mode?)
-      #   CMDx::Middlewares::Timeout.new(seconds: 60, unless: proc { Rails.env.test? })
+      # @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 task with conditional timeout protection.
-      #
-      # Evaluates the conditional options to determine if timeout should be applied.
-      # If conditions are met, resolves the timeout value using and wraps the task
-      # execution with a timeout mechanism that will interrupt execution if it exceeds
-      # the configured time limit. If conditions are not met, executes the task
-      # without timeout protection.
+      # 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.
       #
-      # The timeout value determination follows this precedence:
-      # 1. Explicit timeout value (provided during middleware initialization)
-      #    - Integer/Float: Used as-is for static timeout
-      #    - Symbol: Called as method on task if it exists, otherwise used as numeric value
-      #    - Proc/Lambda: Executed in task context for dynamic timeout calculation
-      # 2. Default value of 3 seconds if no timeout is specified
+      # @param task [CMDx::Task] the task being executed
+      # @param callable [Proc] the callable that executes the task
       #
-      # @param task [CMDx::Task] The task instance to execute
-      # @param callable [#call] The next middleware or task execution callable
-      # @return [CMDx::Result] The task execution result
-      # @raise [TimeoutError] If execution exceeds the configured timeout and conditions are met
+      # @return [Object] the result of the task execution
       #
-      # @example Static timeout - successful execution
-      #   # Task completes in 5 seconds, timeout is 30 seconds, condition is true
-      #   result = task.call  # => success
+      # @raise [TimeoutError] when task execution exceeds the timeout limit
       #
-      # @example Static timeout - timeout exceeded
-      #   # Task would take 60 seconds, timeout is 30 seconds, condition is true
-      #   result = task.call  # => failed with timeout error
+      # @example Task using timeout middleware
+      #   class ProcessFileTask < CMDx::Task
+      #     use :middleware, CMDx::Middlewares::Timeout, seconds: 10
       #
-      # @example Dynamic timeout with proc
-      #   # Task uses proc to calculate 120 seconds for complex operation
-      #   # Task completes in 90 seconds
-      #   result = task.call  # => success
+      #     def call
+      #       # Task execution is automatically wrapped with timeout protection
+      #     end
+      #   end
       #
-      # @example Method-based timeout
-      #   # Task calls :timeout_limit method which returns 45 seconds
-      #   # Task completes in 30 seconds
-      #   result = task.call  # => success
-      #
-      # @example Condition not met
-      #   # Task takes 60 seconds, timeout is 30 seconds, but condition is false
-      #   result = task.call  # => success (no timeout applied)
+      # @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)
+        return callable.call(task) unless task.cmdx_eval(conditional)
 
         # Get seconds using yield for dynamic generation
-        limit = task.__cmdx_yield(seconds) || 3
+        limit = task.cmdx_yield(seconds) || 3
+
+        # Ensure limit is numeric, fallback to default if not
+        limit = 3 unless limit.is_a?(Numeric)
 
         # Apply timeout protection
         ::Timeout.timeout(limit, TimeoutError, "execution exceeded #{limit} seconds") do