cmdx 0.5.0 → 1.0.0

data/lib/cmdx/middlewares/timeout.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+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
+  TimeoutError = Class.new(Interrupt)
+
+  module Middlewares
+    class Timeout < CMDx::Middleware
+
+      # @return [Integer, Float, Symbol, Proc] The timeout value in seconds
+      # @return [Hash] The conditional options for timeout application
+      attr_reader :seconds, :conditional
+
+      ##
+      # Initializes the timeout middleware.
+      #
+      # @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
+      #
+      # @example Static timeout configuration
+      #   CMDx::Middlewares::Timeout.new(seconds: 30)
+      #
+      # @example Dynamic timeout with proc
+      #   CMDx::Middlewares::Timeout.new(seconds: -> { heavy_operation? ? 120 : 30 })
+      #
+      # @example Method-based timeout
+      #   CMDx::Middlewares::Timeout.new(seconds: :calculate_timeout_limit)
+      #
+      # @example Using default timeout (3 seconds)
+      #   CMDx::Middlewares::Timeout.new
+      #
+      # @example Conditional timeout
+      #   CMDx::Middlewares::Timeout.new(seconds: 30, if: :production_mode?)
+      #   CMDx::Middlewares::Timeout.new(seconds: 60, unless: proc { Rails.env.test? })
+      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.
+      #
+      # 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 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
+      #
+      # @example Static timeout - successful execution
+      #   # Task completes in 5 seconds, timeout is 30 seconds, condition is true
+      #   result = task.call  # => success
+      #
+      # @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 Dynamic timeout with proc
+      #   # Task uses proc to calculate 120 seconds for complex operation
+      #   # Task completes in 90 seconds
+      #   result = task.call  # => success
+      #
+      # @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)
+      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
+
+        # Apply timeout protection
+        ::Timeout.timeout(limit, TimeoutError, "execution exceeded #{limit} seconds") do
+          callable.call(task)
+        end
+      rescue TimeoutError => e
+        task.fail!(reason: "[#{e.class}] #{e.message}", original_exception: e, seconds: limit)
+        task.result
+      end
+
+    end
+  end
+
+end

data/lib/cmdx/parameter.rb

@@ -1,13 +1,96 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter definition class for CMDx task parameter management.
+  #
+  # The Parameter class represents individual parameter definitions within CMDx tasks.
+  # It handles parameter configuration, validation rules, type coercion, nested parameters,
+  # and method generation for accessing parameter values within task instances.
+  #
+  # @example Basic parameter definition
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :order_id
+  #     optional :priority
+  #   end
+  #
+  # @example Parameter with type coercion and validation
+  #   class ProcessUserTask < CMDx::Task
+  #     required :age, type: :integer, numeric: { min: 18, max: 120 }
+  #     required :email, type: :string, format: { with: /@/ }
+  #   end
+  #
+  # @example Nested parameters
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :shipping_address do
+  #       required :street, :city, :state
+  #       optional :apartment
+  #     end
+  #   end
+  #
+  # @example Parameter with custom source
+  #   class ProcessUserTask < CMDx::Task
+  #     required :name, source: :user
+  #     required :company_name, source: -> { user.company }
+  #   end
+  #
+  # @example Parameter with default values
+  #   class ProcessOrderTask < CMDx::Task
+  #     optional :priority, default: "normal"
+  #     optional :notification, default: -> { user.preferences.notify? }
+  #   end
+  #
+  # @see CMDx::Task Task parameter integration
+  # @see CMDx::ParameterValue Parameter value resolution and validation
+  # @see CMDx::Parameters Parameter collection management
   class Parameter
 
-    __cmdx_attr_delegator :invalid?, :valid?, to: :errors
+    __cmdx_attr_delegator :invalid?, :valid?,
+                          to: :errors
 
+    # @return [CMDx::Task] The task class this parameter belongs to
     attr_accessor :task
+
+    # @return [Class] The task class this parameter is defined in
+    # @return [Parameter, nil] The parent parameter for nested parameters
+    # @return [Symbol] The parameter name
+    # @return [Symbol, Array<Symbol>] The parameter type(s) for coercion
+    # @return [Hash] The parameter configuration options
+    # @return [Array<Parameter>] Child parameters for nested parameter definitions
+    # @return [CMDx::Errors] Validation errors for this parameter
     attr_reader :klass, :parent, :name, :type, :options, :children, :errors
 
+    # Initializes a new Parameter instance.
+    #
+    # Creates a parameter definition with the specified configuration options.
+    # Automatically defines accessor methods on the task class and processes
+    # any nested parameter definitions provided via block.
+    #
+    # @param name [Symbol] The parameter name
+    # @param options [Hash] Parameter configuration options
+    # @option options [Class] :klass The task class (required)
+    # @option options [Parameter] :parent Parent parameter for nesting
+    # @option options [Symbol, Array<Symbol>] :type (:virtual) Type(s) for coercion
+    # @option options [Boolean] :required (false) Whether parameter is required
+    # @option options [Object, Proc] :default Default value or callable
+    # @option options [Symbol, Proc] :source (:context) Parameter value source
+    # @option options [Hash] :* Validation options (presence, format, etc.)
+    #
+    # @yield Optional block for defining nested parameters
+    #
+    # @raise [KeyError] If :klass option is not provided
+    #
+    # @example Basic parameter creation
+    #   Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
+    #
+    # @example Parameter with validation
+    #   Parameter.new(:email, klass: MyTask, type: :string,
+    #                 format: { with: /@/ }, presence: true)
+    #
+    # @example Nested parameter with block
+    #   Parameter.new(:address, klass: MyTask) do
+    #     required :street, :city
+    #     optional :apartment
+    #   end
     def initialize(name, **options, &)
       @klass    = options.delete(:klass) || raise(KeyError, "klass option required")
       @parent   = options.delete(:parent)
@@ -25,6 +108,26 @@ module CMDx
 
     class << self
 
+      # Defines one or more optional parameters.
+      #
+      # Creates parameter definitions that are not required for task execution.
+      # Optional parameters return nil if not provided in the call arguments.
+      #
+      # @param names [Array<Symbol>] Parameter names to define
+      # @param options [Hash] Parameter configuration options
+      # @yield Optional block for nested parameter definitions
+      #
+      # @return [Array<Parameter>] Created parameter instances
+      # @raise [ArgumentError] If no parameter names provided or :as option used with multiple names
+      #
+      # @example Single optional parameter
+      #   Parameter.optional(:priority, type: :string, default: "normal")
+      #
+      # @example Multiple optional parameters
+      #   Parameter.optional(:width, :height, type: :integer, numeric: { min: 0 })
+      #
+      # @example Optional parameter with validation
+      #   Parameter.optional(:email, type: :string, format: { with: /@/ })
       def optional(*names, **options, &)
         if names.none?
           raise ArgumentError, "no parameters given"
@@ -35,48 +138,172 @@ module CMDx
         names.filter_map { |n| new(n, **options, &) }
       end
 
+      # Defines one or more required parameters.
+      #
+      # Creates parameter definitions that must be provided for task execution.
+      # Missing required parameters will cause task validation to fail.
+      #
+      # @param names [Array<Symbol>] Parameter names to define
+      # @param options [Hash] Parameter configuration options
+      # @yield Optional block for nested parameter definitions
+      #
+      # @return [Array<Parameter>] Created parameter instances
+      # @raise [ArgumentError] If no parameter names provided or :as option used with multiple names
+      #
+      # @example Single required parameter
+      #   Parameter.required(:user_id, type: :integer)
+      #
+      # @example Multiple required parameters
+      #   Parameter.required(:first_name, :last_name, type: :string, presence: true)
+      #
+      # @example Required parameter with complex validation
+      #   Parameter.required(:age, type: :integer, numeric: { within: 18..120 })
       def required(*names, **options, &)
         optional(*names, **options.merge(required: true), &)
       end
 
     end
 
+    # Defines nested optional parameters within this parameter.
+    #
+    # Creates child parameter definitions that inherit this parameter as their source.
+    # Child parameters are only validated if the parent parameter is provided.
+    #
+    # @param names [Array<Symbol>] Child parameter names to define
+    # @param options [Hash] Parameter configuration options
+    # @yield Optional block for further nested parameter definitions
+    #
+    # @return [Array<Parameter>] Created child parameter instances
+    #
+    # @example Nested optional parameters
+    #   address_param.optional(:apartment, :unit, type: :string)
+    #
+    # @example Nested parameter with validation
+    #   user_param.optional(:age, type: :integer, numeric: { min: 0 })
     def optional(*names, **options, &)
       parameters = Parameter.optional(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
     end
 
+    # Defines nested required parameters within this parameter.
+    #
+    # Creates child parameter definitions that are required if the parent parameter
+    # is provided. Child parameters inherit this parameter as their source.
+    #
+    # @param names [Array<Symbol>] Child parameter names to define
+    # @param options [Hash] Parameter configuration options
+    # @yield Optional block for further nested parameter definitions
+    #
+    # @return [Array<Parameter>] Created child parameter instances
+    #
+    # @example Nested required parameters
+    #   address_param.required(:street, :city, :state, type: :string)
+    #
+    # @example Nested parameter with validation
+    #   payment_param.required(:amount, type: :float, numeric: { min: 0.01 })
     def required(*names, **options, &)
       parameters = Parameter.required(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
     end
 
+    # Checks if this parameter is required.
+    #
+    # @return [Boolean] true if parameter is required, false otherwise
+    #
+    # @example
+    #   required_param.required?  # => true
+    #   optional_param.required?  # => false
     def required?
       !!@required
     end
 
+    # Checks if this parameter is optional.
+    #
+    # @return [Boolean] true if parameter is optional, false otherwise
+    #
+    # @example
+    #   required_param.optional?  # => false
+    #   optional_param.optional?  # => true
     def optional?
       !required?
     end
 
+    # Gets the method name that will be defined on the task class.
+    #
+    # The method name is generated using NameAffix utility and can be customized
+    # with :as, :prefix, and :suffix options.
+    #
+    # @return [Symbol] The generated method name
+    #
+    # @example Default method name
+    #   Parameter.new(:user_id, klass: Task).method_name  # => :user_id
+    #
+    # @example Custom method name
+    #   Parameter.new(:id, klass: Task, as: :user_id).method_name  # => :user_id
+    #
+    # @example Method name with prefix
+    #   Parameter.new(:name, klass: Task, prefix: "get_").method_name  # => :get_name
     def method_name
       @method_name ||= Utils::NameAffix.call(name, method_source, options)
     end
 
+    # Gets the source object/method that provides the parameter value.
+    #
+    # Determines where the parameter value should be retrieved from, defaulting
+    # to :context or inheriting from parent parameter.
+    #
+    # @return [Symbol] The source method name
+    #
+    # @example Default source
+    #   Parameter.new(:user_id, klass: Task).method_source  # => :context
+    #
+    # @example Custom source
+    #   Parameter.new(:name, klass: Task, source: :user).method_source  # => :user
+    #
+    # @example Inherited source from parent
+    #   child_param.method_source  # => parent parameter's method_name
     def method_source
       @method_source ||= options[:source] || parent&.method_name || :context
     end
 
+    # Converts the parameter to a hash representation.
+    #
+    # @return [Hash] Serialized parameter data including configuration and children
+    #
+    # @example
+    #   param.to_h
+    #   # => {
+    #   #   source: :context,
+    #   #   name: :user_id,
+    #   #   type: :integer,
+    #   #   required: true,
+    #   #   options: { numeric: { min: 1 } },
+    #   #   children: []
+    #   # }
     def to_h
       ParameterSerializer.call(self)
     end
 
+    # Converts the parameter to a string representation for inspection.
+    #
+    # @return [String] Human-readable parameter description
+    #
+    # @example
+    #   param.to_s
+    #   # => "Parameter: name=user_id type=integer source=context required=true options={numeric: {min: 1}}"
     def to_s
       ParameterInspector.call(to_h)
     end
 
     private
 
+    # Defines the accessor method on the task class for this parameter.
+    #
+    # Creates a private method that handles parameter value resolution,
+    # type coercion, validation, and error handling with caching.
+    #
+    # @param parameter [Parameter] The parameter to define method for
+    # @return [void]
     def define_attribute(parameter)
       klass.send(:define_method, parameter.method_name) do
         @parameters_cache ||= {}

data/lib/cmdx/parameter_inspector.rb

@@ -1,14 +1,75 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter inspection utility for generating human-readable parameter descriptions.
+  #
+  # The ParameterInspector module provides functionality to convert parameter
+  # hash representations into formatted, human-readable strings. It handles
+  # nested parameter structures with proper indentation and ordering.
+  #
+  # @example Basic parameter inspection
+  #   parameter_hash = {
+  #     name: :user_id,
+  #     type: :integer,
+  #     source: :context,
+  #     required: true,
+  #     options: { numeric: { min: 1 } },
+  #     children: []
+  #   }
+  #   ParameterInspector.call(parameter_hash)
+  #   # => "Parameter: name=user_id type=integer source=context required=true options={numeric: {min: 1}}"
+  #
+  # @example Nested parameter inspection
+  #   nested_parameter = {
+  #     name: :address,
+  #     type: :virtual,
+  #     source: :context,
+  #     required: true,
+  #     options: {},
+  #     children: [
+  #       { name: :street, type: :string, source: :address, required: true, options: {}, children: [] }
+  #     ]
+  #   }
+  #   ParameterInspector.call(nested_parameter)
+  #   # => "Parameter: name=address type=virtual source=context required=true options={}
+  #   #       ↳ Parameter: name=street type=string source=address required=true options={}"
+  #
+  # @see CMDx::Parameter Parameter hash serialization via to_h
+  # @see CMDx::ParameterSerializer Parameter-to-hash conversion
   module ParameterInspector
 
+    # Ordered keys for consistent parameter inspection output.
+    #
+    # Defines the order in which parameter attributes are displayed
+    # in the inspection string, with children handled specially.
     ORDERED_KEYS = %i[
       name type source required options children
     ].freeze
 
     module_function
 
+    # Converts a parameter hash to a human-readable string representation.
+    #
+    # Formats parameter data into a structured string with proper ordering
+    # and indentation for nested parameters. Child parameters are displayed
+    # with increased indentation and arrow prefixes.
+    #
+    # @param parameter [Hash] The parameter hash to inspect
+    # @param depth [Integer] The current nesting depth for indentation (default: 1)
+    # @return [String] Formatted parameter description
+    #
+    # @example Single parameter inspection
+    #   ParameterInspector.call(param_hash)
+    #   # => "Parameter: name=user_id type=integer source=context required=true"
+    #
+    # @example Nested parameter inspection with custom depth
+    #   ParameterInspector.call(param_hash, 2)
+    #   # => "Parameter: name=address type=virtual source=context required=true
+    #   #         ↳ Parameter: name=street type=string source=address required=true"
+    #
+    # @example Parameter with options
+    #   ParameterInspector.call(param_with_validation)
+    #   # => "Parameter: name=email type=string source=context required=true options={format: {with: /@/}}"
     def call(parameter, depth = 1)
       ORDERED_KEYS.filter_map do |key|
         value = parameter[key]