cmdx 1.0.1 → 1.1.1

data/lib/cmdx/middleware_registry.rb

@@ -1,103 +1,108 @@
 # 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.
+  # Registry for managing middleware definitions and execution within tasks.
   #
-  # 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
+  # This registry handles the registration and execution of middleware that can
+  # wrap task execution, providing cross-cutting concerns like logging, timing,
+  # authentication, and error handling.
+  class MiddlewareRegistry
+
+    # @return [Hash] hash containing middleware classes/objects and their configurations
+    attr_reader :registry
 
-    # Adds middleware to the registry.
+    # Initializes a new middleware registry.
+    #
+    # @param registry [Hash] optional hash of initial middleware configurations
+    #
+    # @return [MiddlewareRegistry] a new middleware registry instance
+    #
+    # @example Creating an empty registry
+    #   MiddlewareRegistry.new
+    #
+    # @example Creating a registry with initial middleware
+    #   MiddlewareRegistry.new(TimeoutMiddleware => [[], {timeout: 30}, nil])
+    def initialize(registry = {})
+      @registry = registry.to_h
+    end
+
+    # Registers a middleware with the registry.
+    #
+    # @param middleware [Class, Object] the middleware class or instance to register
+    # @param args [Array] positional arguments to pass to middleware initialization
+    # @param kwargs [Hash] keyword arguments to pass to middleware initialization
+    # @param block [Proc] optional block to pass to middleware initialization
     #
-    # @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 Register a middleware class
+    #   registry.register(TimeoutMiddleware, 30)
     #
-    # @example Add middleware instance
-    #   registry.use(LoggingMiddleware.new(log_level: :info))
+    # @example Register a middleware with keyword arguments
+    #   registry.register(LoggingMiddleware, level: :info)
     #
-    # @example Add proc middleware
-    #   registry.use(proc { |task, callable| callable.call(task) })
-    def use(middleware, *args, &block)
-      self << [middleware, args, block]
+    # @example Register a middleware with a block
+    #   registry.register(CustomMiddleware) { |task| puts "Processing #{task.id}" }
+    def register(middleware, *args, **kwargs, &block)
+      registry[middleware] = [args, kwargs, 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
+    # Executes all registered middleware around the provided task.
+    #
+    # @param task [Task] the task instance to execute middleware around
+    # @param block [Proc] the block to execute after all middleware processing
+    #
+    # @return [Object] the result of the middleware chain execution
+    #
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Execute middleware around a task
+    #   registry.call(task) { |task| task.process }
+    #
+    # @example Execute with early return if no middleware
+    #   registry.call(task) { |task| puts "No middleware to execute" }
     def call(task, &)
-      return yield(task) if empty?
+      raise ArgumentError, "block required" unless block_given?
+
+      return yield(task) if registry.empty?
 
       build_chain(&).call(task)
     end
 
+    # Returns a hash representation of the registry.
+    #
+    # @return [Hash] deep copy of registry with duplicated configuration arrays
+    # @option return [Array] args duplicated positional arguments array
+    # @option return [Hash] kwargs duplicated keyword arguments hash
+    # @option return [Proc, nil] block the original block reference (not duplicated)
+    #
+    # @example Getting registry hash
+    #   registry.to_h
+    #   #=> { TimeoutMiddleware => [[30], {}, nil] }
+    def to_h
+      registry.transform_values do |config|
+        args, kwargs, block = config
+        [args.dup, kwargs.dup, block]
+      end
+    end
+
     private
 
-    # Builds the middleware call chain.
+    # Builds the middleware execution chain by wrapping middleware around the call block.
+    #
+    # @param call_block [Proc] the final block to execute after all middleware
     #
-    # Creates a nested chain of callables where each middleware wraps the next,
-    # with the provided block as the innermost callable.
+    # @return [Proc] the complete middleware chain as a callable proc
     #
-    # @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)|
+    # @example Building a middleware chain (internal use)
+    #   build_chain { |task| task.process }
+    def build_chain(&call_block)
+      registry.reverse_each.reduce(call_block) do |next_callable, (middleware, config)|
         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
+          args, kwargs, block = config
+          instance = middleware.respond_to?(:new) ? middleware.new(*args, **kwargs, &block) : middleware
+          instance.call(task, next_callable)
         end
       end
     end

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