cmdx 1.0.1 → 1.1.1

data/lib/cmdx/correlator.rb

@@ -1,205 +1,110 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Thread-safe correlation ID management for tracking related operations across request boundaries.
+  # Thread-safe correlation ID management for distributed tracing and request tracking.
   #
-  # The Correlator provides a simple, thread-local storage mechanism for managing correlation
-  # identifiers throughout the execution lifecycle. It enables tracing related operations
-  # across different tasks, workflows, and service boundaries within the same execution context.
-  #
-  # Correlation IDs are automatically used by CMDx runs when available, providing seamless
-  # request tracking without requiring explicit parameter passing between tasks.
-  #
-  # ## Thread Safety
-  #
-  # All correlation operations are thread-local, ensuring that different threads maintain
-  # separate correlation contexts without interference. This is essential for concurrent
-  # request processing in multi-threaded applications.
-  #
-  # ## Integration with CMDx Runs
-  #
-  # When a new CMDx::Chain is created, it automatically uses the current thread's correlation
-  # ID as its chain identifier if available, falling back to UUID generation if none exists.
-  #
-  # @example Basic correlation usage
-  #   CMDx::Correlator.id = "req-12345"
-  #   CMDx::Correlator.id  # => "req-12345"
-  #
-  #   # Chain automatically inherits correlation ID
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.chain.id  # => "req-12345"
-  #
-  # @example Block-based correlation context
-  #   CMDx::Correlator.use("workflow-operation-456") do
-  #     # All tasks within this block share the same correlation
-  #     ProcessOrderTask.call(order_id: 123)
-  #     SendEmailTask.call(user_id: 456)
-  #   end
-  #   # Correlation context is automatically restored
-  #
-  # @example Nested correlation contexts
-  #   CMDx::Correlator.use("parent-operation") do
-  #     CMDx::Correlator.use("child-operation") do
-  #       ProcessOrderTask.call(order_id: 123)
-  #       # Uses "child-operation" as correlation ID
-  #     end
-  #     # Restored to "parent-operation"
-  #     SendEmailTask.call(user_id: 456)
-  #   end
-  #
-  # @example Manual correlation management
-  #   # Set correlation ID for current thread
-  #   CMDx::Correlator.id = "manual-correlation"
-  #
-  #   # Check current correlation
-  #   current_id = CMDx::Correlator.id
-  #
-  #   # Clear correlation when done
-  #   CMDx::Correlator.clear
-  #
-  # @example Middleware integration pattern
-  #   class CorrelationMiddleware
-  #     def call(env)
-  #       correlation_id = env['HTTP_X_CORRELATION_ID'] || CMDx::Correlator.generate
-  #
-  #       CMDx::Correlator.use(correlation_id) do
-  #         @app.call(env)
-  #       end
-  #     end
-  #   end
-  #
-  # @see CMDx::Chain Chain execution context that inherits correlation IDs
-  # @since 1.0.0
+  # Correlator provides functionality to generate, store, and manage correlation IDs
+  # across thread boundaries for request tracing, logging correlation, and distributed
+  # system monitoring. Correlation IDs are stored in thread-local storage to ensure
+  # thread safety and isolation between concurrent operations.
   module Correlator
 
-    ##
-    # Thread-local storage key for correlation identifiers.
-    #
-    # Uses a Symbol key to avoid potential conflicts with other thread-local
-    # variables and to ensure consistent access across the correlator methods.
-    #
-    # @return [Symbol] the thread-local storage key
     THREAD_KEY = :cmdx_correlation_id
 
     module_function
 
-    ##
-    # Generates a new UUID suitable for use as a correlation identifier.
+    # Generates a new correlation ID using the best available UUID algorithm.
     #
-    # Creates a RFC 4122 compliant UUID using SecureRandom, providing a globally
-    # unique identifier suitable for distributed request tracing.
+    # Attempts to use UUID v7 (time-ordered) if available in Ruby 3.3+, otherwise
+    # falls back to standard UUID v4. UUID v7 provides better database indexing
+    # performance and natural time-based ordering for correlation tracking.
     #
-    # @return [String] a new UUID string in standard format (e.g., "123e4567-e89b-12d3-a456-426614174000")
+    # @return [String] a new UUID correlation ID
     #
-    # @example Generating correlation IDs
-    #   id1 = CMDx::Correlator.generate  # => "018c2b95-b764-7615-a924-cc5b910ed1e5"
-    #   id2 = CMDx::Correlator.generate  # => "018c2b95-b765-7123-b456-dd7c920fe3a8"
-    #   id1 != id2  # => true
+    # @example Generate a correlation ID
+    #   Correlator.generate #=> "01234567-89ab-7def-0123-456789abcdef"
+    #
+    # @example Using the generated ID for logging
+    #   correlation_id = Correlator.generate
+    #   logger.info "Request started", correlation_id: correlation_id
     def generate
+      return SecureRandom.uuid_v7 if SecureRandom.respond_to?(:uuid_v7)
+
       SecureRandom.uuid
     end
 
-    ##
-    # Retrieves the current thread's correlation identifier.
-    #
-    # Returns the correlation ID that was previously set for the current thread,
-    # or nil if no correlation ID has been established. This method is thread-safe
-    # and will not interfere with correlation IDs set in other threads.
+    # Retrieves the current correlation ID for the active thread.
     #
-    # @return [String, nil] the current correlation ID or nil if none is set
+    # Returns the correlation ID that has been set for the current thread's
+    # execution context. Returns nil if no correlation ID has been established
+    # for the current thread.
     #
-    # @example Checking current correlation
-    #   CMDx::Correlator.id  # => nil (when none is set)
+    # @return [String, nil] the current thread's correlation ID, or nil if not set
     #
-    #   CMDx::Correlator.id = "test-correlation"
-    #   CMDx::Correlator.id  # => "test-correlation"
+    # @example Get current correlation ID
+    #   Correlator.id #=> "01234567-89ab-7def-0123-456789abcdef"
     def id
       Thread.current[THREAD_KEY]
     end
 
-    ##
-    # Sets the correlation identifier for the current thread.
+    # Sets the correlation ID for the current thread.
     #
-    # Assigns a correlation ID to the current thread's local storage, making it
-    # available for subsequent operations within the same thread context. The
-    # correlation ID will persist until explicitly changed or cleared.
+    # Establishes a correlation ID in thread-local storage that will be
+    # accessible to all operations within the current thread's execution
+    # context. This ID will persist until explicitly changed or cleared.
     #
-    # @param value [String, #to_s] the correlation identifier to set
-    # @return [String] the assigned correlation identifier
+    # @param value [String, Symbol] the correlation ID to set for this thread
     #
-    # @example Setting correlation ID
-    #   CMDx::Correlator.id = "user-request-123"
-    #   CMDx::Correlator.id  # => "user-request-123"
+    # @return [String, Symbol] the assigned correlation ID value
     #
-    # @example Type coercion
-    #   CMDx::Correlator.id = 12345
-    #   CMDx::Correlator.id  # => 12345 (stored as provided)
+    # @example Set a custom correlation ID
+    #   Correlator.id = "custom-trace-123"
+    #
+    # @example Set a generated correlation ID
+    #   Correlator.id = Correlator.generate
     def id=(value)
       Thread.current[THREAD_KEY] = value
     end
 
-    ##
-    # Clears the correlation identifier for the current thread.
-    #
-    # Removes the correlation ID from the current thread's local storage,
-    # effectively resetting the correlation context. Subsequent calls to
-    # {#id} will return nil until a new correlation ID is set.
+    # Clears the correlation ID for the current thread.
     #
-    # @return [nil] always returns nil
+    # Removes the correlation ID from thread-local storage, effectively
+    # resetting the correlation context for the current thread. Useful
+    # for cleanup between request processing or test scenarios.
     #
-    # @example Clearing correlation
-    #   CMDx::Correlator.id = "temporary-correlation"
-    #   CMDx::Correlator.id  # => "temporary-correlation"
+    # @return [nil] always returns nil after clearing
     #
-    #   CMDx::Correlator.clear
-    #   CMDx::Correlator.id  # => nil
+    # @example Clear correlation ID
+    #   Correlator.clear
+    #   Correlator.id #=> nil
     def clear
       Thread.current[THREAD_KEY] = nil
     end
 
-    ##
-    # Temporarily sets a correlation identifier for the duration of a block.
+    # Temporarily sets a correlation ID for the duration of a block execution.
     #
-    # Establishes a correlation context for the given block, automatically
-    # restoring the previous correlation ID when the block completes. This
-    # method is exception-safe and will restore the original context even
-    # if the block raises an error.
+    # Establishes a correlation ID context for the provided block, automatically
+    # restoring the previous correlation ID when the block completes. This ensures
+    # proper correlation ID isolation for nested operations or temporary contexts.
     #
-    # This is the preferred method for managing correlation contexts as it
-    # ensures proper cleanup and supports nested correlation scopes.
+    # @param value [String, Symbol] the temporary correlation ID to use during block execution
     #
-    # @param value [String, #to_s] the correlation identifier to use during block execution
-    # @yieldreturn [Object] the return value of the block
     # @return [Object] the return value of the executed block
     #
-    # @example Basic usage
-    #   result = CMDx::Correlator.use("operation-123") do
-    #     ProcessOrderTask.call(order_id: 456)
-    #   end
-    #   # Correlation context is automatically restored
-    #
-    # @example Nested contexts
-    #   CMDx::Correlator.use("parent") do
-    #     CMDx::Correlator.id  # => "parent"
-    #
-    #     CMDx::Correlator.use("child") do
-    #       CMDx::Correlator.id  # => "child"
-    #     end
+    # @raise [TypeError] if the provided value is not a String or Symbol
     #
-    #     CMDx::Correlator.id  # => "parent" (restored)
+    # @example Use temporary correlation ID
+    #   Correlator.use("temp-id-123") do
+    #     logger.info "Processing with temporary ID"
+    #     perform_operation
     #   end
     #
-    # @example Exception safety
-    #   CMDx::Correlator.id = "original"
-    #
-    #   begin
-    #     CMDx::Correlator.use("temporary") do
-    #       raise StandardError, "something went wrong"
-    #     end
-    #   rescue StandardError
-    #     CMDx::Correlator.id  # => "original" (still restored)
+    # @example Nested correlation contexts
+    #   Correlator.id = "parent-id"
+    #   Correlator.use("child-id") do
+    #     puts Correlator.id #=> "child-id"
     #   end
+    #   puts Correlator.id #=> "parent-id"
     def use(value)
       unless value.is_a?(String) || value.is_a?(Symbol)
         raise TypeError,

data/lib/cmdx/error.rb

@@ -2,224 +2,59 @@
 
 module CMDx
 
-  ##
-  # Base exception class for all CMDx-specific errors.
-  # All other CMDx exceptions inherit from this class, providing a common
-  # hierarchy for error handling and rescue operations.
+  # Base exception class for all CMDx-related errors.
   #
-  # This allows for catching all CMDx-related exceptions with a single rescue clause
-  # while still maintaining specific error types for detailed error handling.
-  #
-  # @example Catching all CMDx errors
-  #   begin
-  #     ProcessOrderTask.call(invalid_params)
-  #   rescue CMDx::Error => e
-  #     logger.error "CMDx error occurred: #{e.message}"
-  #   end
-  #
-  # @example Specific error handling
-  #   begin
-  #     ProcessOrderTask.call(order_id: "invalid")
-  #   rescue CMDx::CoercionError => e
-  #     # Handle type coercion failures
-  #   rescue CMDx::ValidationError => e
-  #     # Handle validation failures
-  #   rescue CMDx::Error => e
-  #     # Handle any other CMDx errors
-  #   end
-  #
-  # @see StandardError Ruby's standard error base class
-  # @since 1.0.0
+  # This serves as the root exception class for all errors raised by the CMDx
+  # framework. It inherits from StandardError and provides a common base for
+  # handling CMDx-specific exceptions.
   Error = Class.new(StandardError)
 
-  ##
-  # Raised when a value cannot be coerced to the specified type.
-  # This exception occurs during parameter processing when type coercion fails,
-  # typically due to incompatible data formats or invalid input values.
-  #
-  # CoercionError is raised by the various coercion modules when they encounter
-  # values that cannot be converted to the target type. Each coercion module
-  # provides specific error messages indicating the expected type and the
-  # problematic value.
-  #
-  # @example Integer coercion failure
-  #   class MyTask < CMDx::Task
-  #     required :count, type: :integer
-  #   end
-  #
-  #   # This will raise CoercionError during parameter processing
-  #   MyTask.call(count: "not_a_number")
-  #   # => CMDx::CoercionError: could not coerce into an integer
-  #
-  # @example Date coercion failure
-  #   class ScheduleTask < CMDx::Task
-  #     required :due_date, type: :date
-  #   end
-  #
-  #   ScheduleTask.call(due_date: "invalid_date")
-  #   # => CMDx::CoercionError: could not coerce into a date
+  # Raised when parameter coercion fails during task execution.
   #
-  # @example Handling coercion errors
-  #   begin
-  #     MyTask.call(count: "invalid")
-  #   rescue CMDx::CoercionError => e
-  #     # Log the coercion failure and provide user-friendly message
-  #     logger.warn "Invalid input format: #{e.message}"
-  #     render json: { error: "Please provide a valid number" }
-  #   end
-  #
-  # @see Parameter Parameter type definitions and coercion
-  # @see ParameterValue Parameter value processing and coercion
-  # @since 1.0.0
+  # This error occurs when a parameter value cannot be converted to the expected
+  # type using the registered coercion handlers. It indicates that the provided
+  # value is incompatible with the parameter's defined type.
   CoercionError = Class.new(Error)
 
-  ##
-  # Raised when a task class doesn't implement the required `call` method.
-  # This exception enforces the CMDx contract that all task classes must
-  # provide a `call` method containing their business logic.
-  #
-  # This error typically occurs during development when creating new task
-  # classes that inherit from CMDx::Task but forget to implement the
-  # abstract `call` method.
-  #
-  # @example Missing call method
-  #   class IncompleteTask < CMDx::Task
-  #     required :data, type: :string
-  #     # Missing call method implementation
-  #   end
-  #
-  #   IncompleteTask.call(data: "test")
-  #   # => CMDx::UndefinedCallError: call method not defined in IncompleteTask
+  # Raised when a deprecated task is used.
   #
-  # @example Proper task implementation
-  #   class CompleteTask < CMDx::Task
-  #     required :data, type: :string
-  #
-  #     def call
-  #       # Business logic implementation
-  #       context.result = process(data)
-  #     end
-  #   end
-  #
-  # @example Handling undefined call errors
-  #   begin
-  #     SomeTask.call(params)
-  #   rescue CMDx::UndefinedCallError => e
-  #     # This should typically only happen during development
-  #     logger.error "Task implementation incomplete: #{e.message}"
-  #     raise # Re-raise as this is a programming error
-  #   end
+  # This error occurs when a deprecated task is called. It indicates that the
+  # task is no longer supported and should be replaced with a newer alternative.
+  DeprecationError = Class.new(Error)
+
+  # Raised when an abstract method is called without being implemented.
   #
-  # @see Task Task base class and call method requirement
-  # @see Workflow Workflow base class and call method requirement
-  # @since 1.0.0
+  # This error occurs when a subclass fails to implement required abstract methods
+  # such as call methods in validators, callbacks, or middleware. It indicates
+  # incomplete implementation of required functionality.
   UndefinedCallError = Class.new(Error)
 
-  ##
-  # Raised when an unknown or unsupported coercion type is specified.
-  # This exception occurs when parameter definitions reference type coercions
-  # that don't exist or aren't registered in the CMDx coercion system.
-  #
-  # This error helps catch typos in type specifications and ensures that
-  # only supported data types are used in parameter definitions.
+  # Raised when attempting to use an unregistered callback.
   #
-  # @example Unknown type specification
-  #   class MyTask < CMDx::Task
-  #     required :value, type: :unknown_type  # Typo or unsupported type
-  #   end
-  #
-  #   MyTask.call(value: "test")
-  #   # => CMDx::UnknownCoercionError: unknown coercion unknown_type
-  #
-  # @example Common typos
-  #   class TaskWithTypo < CMDx::Task
-  #     required :count, type: :integr      # Should be :integer
-  #     required :flag, type: :bool         # Should be :boolean
-  #     required :data, type: :json         # Should be :hash
-  #   end
-  #
-  # @example Supported types
-  #   class ProperTask < CMDx::Task
-  #     required :id, type: :integer
-  #     required :active, type: :boolean
-  #     required :metadata, type: :hash
-  #     required :tags, type: :array
-  #     required :name, type: :string
-  #     required :score, type: :float
-  #     required :created_at, type: :date_time
-  #   end
-  #
-  # @example Handling unknown coercion errors
-  #   begin
-  #     MyTask.call(params)
-  #   rescue CMDx::UnknownCoercionError => e
-  #     # This indicates a programming error in parameter definition
-  #     logger.error "Invalid type specification: #{e.message}"
-  #     raise # Re-raise as this should be fixed in code
-  #   end
+  # This error occurs when trying to reference a callback that hasn't been
+  # registered in the callback registry. It indicates that the callback name
+  # is not recognized or was misspelled.
+  UnknownCallbackError = Class.new(Error)
+
+  # Raised when attempting to use an unregistered coercion type.
   #
-  # @see Parameter Parameter type definitions
-  # @see ParameterValue Type coercion processing
-  # @since 1.0.0
+  # This error occurs when trying to use a parameter type that doesn't have
+  # a corresponding coercion handler registered. It indicates that the specified
+  # type is not supported by the coercion system.
   UnknownCoercionError = Class.new(Error)
 
-  ##
-  # Raised when a parameter value fails validation rules.
-  # This exception occurs during parameter processing when values don't meet
-  # the specified validation criteria, such as format requirements, length
-  # constraints, or custom validation logic.
-  #
-  # ValidationError provides detailed feedback about why validation failed,
-  # helping developers and users understand what corrections are needed.
-  #
-  # @example Presence validation failure
-  #   class CreateUserTask < CMDx::Task
-  #     required :email, type: :string, presence: true
-  #   end
-  #
-  #   CreateUserTask.call(email: "")
-  #   # => CMDx::ValidationError: cannot be empty
+  # Raised when attempting to use an unregistered validator.
   #
-  # @example Format validation failure
-  #   class ValidateEmailTask < CMDx::Task
-  #     required :email, type: :string, format: { with: /@/ }
-  #   end
-  #
-  #   ValidateEmailTask.call(email: "invalid-email")
-  #   # => CMDx::ValidationError: is an invalid format
-  #
-  # @example Length validation failure
-  #   class SetPasswordTask < CMDx::Task
-  #     required :password, type: :string, length: { min: 8 }
-  #   end
-  #
-  #   SetPasswordTask.call(password: "short")
-  #   # => CMDx::ValidationError: length must be at least 8
-  #
-  # @example Custom validation failure
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :quantity, type: :integer, custom: -> (val) { val > 0 }
-  #   end
-  #
-  #   ProcessOrderTask.call(quantity: -1)
-  #   # => CMDx::ValidationError: is not valid
-  #
-  # @example Handling validation errors
-  #   begin
-  #     CreateUserTask.call(email: "", password: "short")
-  #   rescue CMDx::ValidationError => e
-  #     # Provide user-friendly feedback
-  #     render json: {
-  #       error: "Validation failed",
-  #       message: e.message,
-  #       field: extract_field_from_context(e)
-  #     }
-  #   end
+  # This error occurs when trying to reference a validator that hasn't been
+  # registered in the validator registry. It indicates that the validator name
+  # is not recognized or was misspelled.
+  UnknownValidatorError = Class.new(Error)
+
+  # Raised when parameter validation fails during task execution.
   #
-  # @see Parameter Parameter validation options
-  # @see ParameterValue Validation processing
-  # @see Validators Validation modules (Presence, Format, Length, etc.)
-  # @since 1.0.0
+  # This error occurs when a parameter value doesn't meet the validation criteria
+  # defined by the validator. It indicates that the provided value violates
+  # business rules or data integrity constraints.
   ValidationError = Class.new(Error)
 
 end