cmdx 0.5.0 → 1.0.0

data/lib/cmdx/logger_ansi.rb

@@ -1,22 +1,108 @@
 # frozen_string_literal: true
 
 module CMDx
+  # ANSI color formatting module for logger severity levels.
+  #
+  # The LoggerAnsi module provides ANSI color formatting for log severity levels
+  # to enhance readability in terminal output. Each severity level is assigned
+  # a specific color and bold formatting to make log messages more visually
+  # distinguishable.
+  #
+  # @example Basic severity colorization
+  #   LoggerAnsi.call("DEBUG message")    # => Blue bold text
+  #   LoggerAnsi.call("INFO message")     # => Green bold text
+  #   LoggerAnsi.call("WARN message")     # => Yellow bold text
+  #   LoggerAnsi.call("ERROR message")    # => Red bold text
+  #   LoggerAnsi.call("FATAL message")    # => Magenta bold text
+  #
+  # @example Usage in log formatters
+  #   class CustomFormatter
+  #     def call(severity, time, progname, msg)
+  #       colored_severity = LoggerAnsi.call(severity)
+  #       "#{colored_severity} #{msg}"
+  #     end
+  #   end
+  #
+  # @example Integration with pretty formatters
+  #   # Used internally by PrettyLine, PrettyJson, PrettyKeyValue formatters
+  #   formatted_severity = LoggerAnsi.call("ERROR")  # => Red bold "ERROR"
+  #
+  # @see CMDx::Utils::AnsiColor ANSI color utility functions
+  # @see CMDx::LogFormatters::PrettyLine Pretty line formatter with colors
+  # @see CMDx::LogFormatters::PrettyJson Pretty JSON formatter with colors
   module LoggerAnsi
 
+    # Mapping of log severity levels to ANSI colors.
+    #
+    # Maps the first character of severity levels to their corresponding
+    # color codes for consistent visual representation across log output.
     SEVERITY_COLORS = {
-      "D" => :blue,
-      "I" => :green,
-      "W" => :yellow,
-      "E" => :red,
-      "F" => :magenta
+      "D" => :blue,      # DEBUG
+      "I" => :green,     # INFO
+      "W" => :yellow,    # WARN
+      "E" => :red,       # ERROR
+      "F" => :magenta    # FATAL
     }.freeze
 
     module_function
 
+    # Applies ANSI color formatting to a severity string.
+    #
+    # Formats the input string with appropriate ANSI color codes based on
+    # the first character of the string, which typically represents the
+    # log severity level. All formatted text is rendered in bold.
+    #
+    # @param s [String] The severity string to colorize
+    # @return [String] The string with ANSI color codes applied
+    #
+    # @example Colorizing different severity levels
+    #   LoggerAnsi.call("DEBUG")  # => "\e[1;34mDEBUG\e[0m" (blue bold)
+    #   LoggerAnsi.call("INFO")   # => "\e[1;32mINFO\e[0m" (green bold)
+    #   LoggerAnsi.call("WARN")   # => "\e[1;33mWARN\e[0m" (yellow bold)
+    #   LoggerAnsi.call("ERROR")  # => "\e[1;31mERROR\e[0m" (red bold)
+    #   LoggerAnsi.call("FATAL")  # => "\e[1;35mFATAL\e[0m" (magenta bold)
+    #
+    # @example Unknown severity level
+    #   LoggerAnsi.call("CUSTOM") # => "\e[1;39mCUSTOM\e[0m" (default color bold)
+    #
+    # @example Full log message formatting
+    #   severity = "ERROR"
+    #   message = "Task failed with validation errors"
+    #   colored_severity = LoggerAnsi.call(severity)
+    #   log_line = "#{colored_severity}: #{message}"
+    #   # => "\e[1;31mERROR\e[0m: Task failed with validation errors"
     def call(s)
-      color = SEVERITY_COLORS[s[0]] || :default
+      Utils::AnsiColor.call(s, color: color(s), mode: :bold)
+    end
 
-      Utils::AnsiColor.call(s, color:, mode: :bold)
+    # Determines the appropriate color for a severity string.
+    #
+    # Extracts the first character from the severity string and maps it to
+    # the corresponding color symbol using the SEVERITY_COLORS hash. If no
+    # mapping is found for the first character, returns the default color.
+    #
+    # @param s [String] The severity string to determine color for
+    # @return [Symbol] The color symbol for the severity level
+    #
+    # @example Mapping severity levels to colors
+    #   color("DEBUG")    # => :blue
+    #   color("INFO")     # => :green
+    #   color("WARN")     # => :yellow
+    #   color("ERROR")    # => :red
+    #   color("FATAL")    # => :magenta
+    #
+    # @example Unknown severity level
+    #   color("CUSTOM")   # => :default
+    #   color("TRACE")    # => :default
+    #
+    # @example Case sensitivity
+    #   color("debug")    # => :default (lowercase 'd' not mapped)
+    #   color("Debug")    # => :blue (uppercase 'D' is mapped)
+    #
+    # @note This method only considers the first character of the input string
+    # @see SEVERITY_COLORS The mapping hash used for color determination
+    def color(s)
+      SEVERITY_COLORS[s[0]] || :default
     end
 
   end

data/lib/cmdx/logger_serializer.rb

@@ -1,14 +1,130 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Logger message serialization module for structured log output.
+  #
+  # The LoggerSerializer module provides functionality to serialize log messages
+  # into structured hash format suitable for various log formatters. It handles
+  # different message types including Result objects and plain messages, with
+  # optional ANSI colorization for terminal output.
+  #
+  # @example Basic message serialization
+  #   task = ProcessOrderTask.new
+  #   message = "Processing order 123"
+  #
+  #   LoggerSerializer.call(:info, Time.now, task, message)
+  #   # => {
+  #   #   origin: "CMDx",
+  #   #   index: 0,
+  #   #   chain_id: "...",
+  #   #   type: "Task",
+  #   #   class: "ProcessOrderTask",
+  #   #   id: "...",
+  #   #   tags: [],
+  #   #   message: "Processing order 123"
+  #   # }
+  #
+  # @example Result object serialization
+  #   result = task.result  # CMDx::Result instance
+  #
+  #   LoggerSerializer.call(:info, Time.now, task, result)
+  #   # => {
+  #   #   origin: "CMDx",
+  #   #   state: "complete",
+  #   #   status: "success",
+  #   #   outcome: "success",
+  #   #   metadata: {},
+  #   #   runtime: 0.5,
+  #   #   index: 0,
+  #   #   chain_id: "...",
+  #   #   # ... other result data
+  #   # }
+  #
+  # @example Colorized result serialization
+  #   LoggerSerializer.call(:info, Time.now, task, result, ansi_colorize: true)
+  #   # => Same as above but with ANSI color codes in state/status/outcome values
+  #
+  # @see CMDx::Result Result object structure and data
+  # @see CMDx::TaskSerializer Task serialization functionality
+  # @see CMDx::ResultAnsi Result ANSI colorization
   module LoggerSerializer
 
+    # Keys that should be colorized when ANSI colorization is enabled.
+    #
+    # These keys represent result state information that benefits from
+    # color coding in terminal output for better visual distinction.
     COLORED_KEYS = %i[
       state status outcome
     ].freeze
 
     module_function
 
+    # Serializes a log message into a structured hash format.
+    #
+    # Converts log messages into hash format suitable for structured logging.
+    # Handles both Result objects and plain messages differently, with optional
+    # ANSI colorization for terminal-friendly output.
+    #
+    # @param _severity [Symbol] Log severity level (not used in current implementation)
+    # @param _time [Time] Log timestamp (not used in current implementation)
+    # @param task [CMDx::Task] The task instance generating the log message
+    # @param message [Object] The message to serialize (Result object or other)
+    # @param options [Hash] Serialization options
+    # @option options [Boolean] :ansi_colorize (false) Whether to apply ANSI colors
+    # @return [Hash] Structured hash representation of the log message
+    #
+    # @example Plain message serialization
+    #   LoggerSerializer.call(:info, Time.now, task, "Task started")
+    #   # => {
+    #   #   origin: "CMDx",
+    #   #   index: 0,
+    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   type: "Task",
+    #   #   class: "MyTask",
+    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   tags: [],
+    #   #   message: "Task started"
+    #   # }
+    #
+    # @example Result object serialization
+    #   result = CMDx::Result.new(task)
+    #   result.complete!
+    #
+    #   LoggerSerializer.call(:info, Time.now, task, result)
+    #   # => {
+    #   #   origin: "CMDx",
+    #   #   state: "complete",
+    #   #   status: "success",
+    #   #   outcome: "success",
+    #   #   metadata: {},
+    #   #   runtime: 0.001,
+    #   #   index: 0,
+    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   type: "Task",
+    #   #   class: "MyTask",
+    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   tags: []
+    #   # }
+    #
+    # @example Colorized result serialization
+    #   LoggerSerializer.call(:info, Time.now, task, result, ansi_colorize: true)
+    #   # => Same as above but state/status/outcome values contain ANSI color codes
+    #   # => { state: "\e[32mcomplete\e[0m", status: "\e[32msuccess\e[0m", ... }
+    #
+    # @example Hash-like message object
+    #   custom_message = OpenStruct.new(action: "process", item_id: 123)
+    #   LoggerSerializer.call(:debug, Time.now, task, custom_message)
+    #   # => {
+    #   #   origin: "CMDx",
+    #   #   action: "process",
+    #   #   item_id: 123,
+    #   #   index: 0,
+    #   #   chain_id: "...",
+    #   #   type: "Task",
+    #   #   class: "MyTask",
+    #   #   id: "...",
+    #   #   tags: []
+    #   # }
     def call(_severity, _time, task, message, **options)
       m = message.respond_to?(:to_h) ? message.to_h : {}
 

data/lib/cmdx/middleware.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module CMDx
+  ##
+  # Base class for CMDx middleware that follows Rack-style interface.
+  #
+  # Middleware components can wrap task execution to provide cross-cutting
+  # concerns like logging, authentication, caching, or error handling.
+  # Each middleware must implement the `call` method which receives the
+  # task instance and a callable that represents the next middleware
+  # in the chain.
+  #
+  # @example Basic middleware implementation
+  #   class LoggingMiddleware < CMDx::Middleware
+  #     def call(task, callable)
+  #       puts "Before executing #{task.class.name}"
+  #       result = callable.call(task)
+  #       puts "After executing #{task.class.name}"
+  #       result
+  #     end
+  #   end
+  #
+  # @example Middleware with initialization parameters
+  #   class AuthenticationMiddleware < CMDx::Middleware
+  #     def initialize(required_role)
+  #       @required_role = required_role
+  #     end
+  #
+  #     def call(task, callable)
+  #       unless task.context.user&.has_role?(@required_role)
+  #         task.fail!(reason: "Insufficient permissions")
+  #         return task.result
+  #       end
+  #       callable.call(task)
+  #     end
+  #   end
+  #
+  # @example Short-circuiting middleware
+  #   class CachingMiddleware < CMDx::Middleware
+  #     def call(task, callable)
+  #       cache_key = "#{task.class.name}:#{task.context.to_h.hash}"
+  #
+  #       if cached_result = Rails.cache.read(cache_key)
+  #         task.result.merge!(cached_result)
+  #         return task.result
+  #       end
+  #
+  #       result = callable.call(task)
+  #       Rails.cache.write(cache_key, result.to_h) if result.success?
+  #       result
+  #     end
+  #   end
+  #
+  # @see MiddlewareRegistry management
+  # @see Task middleware integration
+  class Middleware
+
+    ##
+    # Executes the middleware logic.
+    #
+    # This method must be implemented by subclasses to define the middleware
+    # behavior. The method receives the task instance and a callable that
+    # represents the next middleware in the chain or the final task execution.
+    #
+    # @param task [Task] the task instance being executed
+    # @param callable [#call] the next middleware or task execution callable
+    # @return [Result] the task execution result
+    # @abstract Subclasses must implement this method
+    def call(_task, _callable)
+      raise UndefinedCallError, "call method not defined in #{self.class.name}"
+    end
+
+  end
+end

data/lib/cmdx/middleware_registry.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module CMDx
+  ##
+  # The MiddlewareRegistry collection provides a Rack-style middleware chain that wraps
+  # task execution with cross-cutting concerns like logging, authentication,
+  # caching, and more. Middleware can short-circuit execution by returning
+  # early without calling the next middleware in the chain.
+  #
+  # The MiddlewareRegistry collection extends Array to provide specialized functionality for
+  # managing collections of middleware definitions within CMDx tasks. It handles
+  # middleware execution coordination, chaining, and inspection.
+  #
+  # @example Basic middleware usage
+  #   middleware_registry = MiddlewareRegistry.new
+  #   middleware_registry.use(LoggingMiddleware)
+  #   middleware_registry.use(AuthenticationMiddleware, required_role: :admin)
+  #   middleware_registry.use(CachingMiddleware, ttl: 300)
+  #
+  #   result = middleware_registry.call(task) do |t|
+  #     t.call
+  #     t.result
+  #   end
+  #
+  # @example Array-like operations
+  #   middleware_registry << [LoggingMiddleware, [], nil]
+  #   middleware_registry.size  # => 1
+  #   middleware_registry.empty?  # => false
+  #   middleware_registry.each { |middleware| puts middleware.inspect }
+  #
+  # @example Using proc middleware
+  #   middleware_registry.use(proc do |task, callable|
+  #     puts "Before task execution"
+  #     result = callable.call(task)
+  #     puts "After task execution"
+  #     result
+  #   end)
+  #
+  # @see Middleware Base middleware class
+  # @since 1.0.0
+  class MiddlewareRegistry < Array
+
+    # Adds middleware to the registry.
+    #
+    # @param middleware [Class, Object, Proc] The middleware to add
+    # @param args [Array] Arguments to pass to middleware constructor
+    # @param block [Proc] Block to pass to middleware constructor
+    # @return [MiddlewareRegistry] self for method chaining
+    #
+    # @example Add middleware class
+    #   registry.use(LoggingMiddleware, log_level: :info)
+    #
+    # @example Add middleware instance
+    #   registry.use(LoggingMiddleware.new(log_level: :info))
+    #
+    # @example Add proc middleware
+    #   registry.use(proc { |task, callable| callable.call(task) })
+    def use(middleware, *args, &block)
+      self << [middleware, args, block]
+      self
+    end
+
+    # Executes the middleware chain around the given block.
+    #
+    # @param task [Task] The task instance to pass through middleware
+    # @yield [Task] The task instance for final execution
+    # @yieldreturn [Object] The result of task execution
+    # @return [Object] The result from the middleware chain
+    #
+    # @example Execute with middleware
+    #   result = registry.call(task) do |t|
+    #     t.call
+    #     t.result
+    #   end
+    def call(task, &)
+      return yield(task) if empty?
+
+      build_chain(&).call(task)
+    end
+
+    private
+
+    # Builds the middleware call chain.
+    #
+    # Creates a nested chain of callables where each middleware wraps the next,
+    # with the provided block as the innermost callable.
+    #
+    # @param block [Proc] The final block to execute
+    # @return [Proc] The middleware chain as a callable
+    def build_chain(&block)
+      reverse.reduce(block) do |next_callable, (middleware, args, middleware_block)|
+        proc do |task|
+          if middleware.respond_to?(:call) && !middleware.respond_to?(:new)
+            # Proc middleware
+            middleware.call(task, next_callable)
+          else
+            # Class or instance middleware
+            instance = middleware.respond_to?(:new) ? middleware.new(*args, &middleware_block) : middleware
+            instance.call(task, next_callable)
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/cmdx/middlewares/correlate.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+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
+    class Correlate < CMDx::Middleware
+
+      # @return [String, nil] The explicit correlation ID to use
+      # @return [Hash] The conditional options for correlation application
+      attr_reader :id, :conditional
+
+      ##
+      # Initializes the Correlate 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
+      #
+      # @example Basic initialization
+      #   middleware = CMDx::Middlewares::Correlate.new
+      #
+      # @example With explicit correlation ID
+      #   middleware = CMDx::Middlewares::Correlate.new(id: "api-request-123")
+      #
+      # @example With conditional execution
+      #   middleware = CMDx::Middlewares::Correlate.new(unless: -> { Rails.env.test? })
+      #   middleware = CMDx::Middlewares::Correlate.new(if: :correlation_enabled?)
+      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
+      #
+      #   # 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
+      #
+      #   # 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"
+      #
+      #   # Scenario 5: Chain ID when no explicit or thread correlation
+      #   CMDx::Correlator.clear
+      #   middleware.call(task, callable)  # Uses task.chain.id
+      #
+      #   # 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
+      #
+      # @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
+      def call(task, callable)
+        # Check if correlation should be applied based on conditions
+        return callable.call(task) unless task.__cmdx_eval(conditional)
+
+        # Get correlation ID using yield for dynamic generation
+        correlation_id = task.__cmdx_yield(id) ||
+                         CMDx::Correlator.id ||
+                         task.chain.id ||
+                         CMDx::Correlator.generate
+
+        # Execute task with correlation context
+        CMDx::Correlator.use(correlation_id) do
+          callable.call(task)
+        end
+      end
+
+    end
+  end
+end