tasker-engine 1.0.0

data/lib/tasker/handler_factory.rb

@@ -0,0 +1,322 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative 'events/custom_registry'
+require_relative 'registry/base_registry'
+require_relative 'registry/interface_validator'
+require 'concurrent-ruby'
+
+module Tasker
+  # Factory for creating task handler instances
+  #
+  # This class maintains a registry of task handlers by name and dependent system,
+  # providing namespaced handler organization while maintaining backward compatibility.
+  # It follows the Singleton pattern to ensure a single registry and uses thread-safe
+  # storage with modern registry patterns.
+  class HandlerFactory < Registry::BaseRegistry
+    include Singleton
+
+    # @return [Concurrent::Hash] Thread-safe registered handler classes by dependent system and handler name
+    attr_reader :handler_classes
+
+    # @return [Set] Set of registered namespaces for efficient enumeration
+    attr_reader :namespaces
+
+    # Initialize a new handler factory
+    #
+    # @return [HandlerFactory] A new handler factory instance
+    def initialize
+      super
+      @handler_classes = Concurrent::Hash.new
+      @namespaces = Set.new([:default])
+      log_registry_operation('initialized', namespaces: @namespaces.to_a)
+    end
+
+    # Get a task handler instance by name and optional dependent system
+    #
+    # @param name [String, Symbol] The name of the handler to retrieve
+    # @param namespace_name [String, Symbol] The dependent system namespace (defaults to 'default')
+    # @param version [String] The version of the handler (defaults to '0.1.0')
+    # @return [Object] An instance of the requested task handler
+    # @raise [Tasker::ProceduralError] If no handler is registered with the given name in the specified system
+    def get(name, namespace_name: :default, version: '0.1.0')
+      namespace_name = namespace_name.to_sym
+      name_sym = name.to_sym
+
+      thread_safe_operation do
+        # Direct namespace lookup - allows same name in different systems
+        handler_class = @handler_classes.dig(namespace_name, name_sym, version)
+        raise_handler_not_found(name, namespace_name, version) unless handler_class
+
+        log_registry_operation('handler_retrieved',
+                               entity_type: 'task_handler',
+                               entity_id: "#{namespace_name}/#{name_sym}/#{version}",
+                               handler_class: handler_class.is_a?(Class) ? handler_class.name : handler_class)
+
+        instantiate_handler(handler_class)
+      end
+    end
+
+    # Register a task handler class with a name and optional dependent system
+    #
+    # @param name [String, Symbol] The name to register the handler under
+    # @param class_or_class_name [Class, String] The handler class to register
+    # @param namespace_name [String, Symbol] The dependent system namespace (defaults to 'default')
+    # @param version [String] The version of the handler (defaults to '0.1.0')
+    # @param options [Hash] Additional registration options
+    # @option options [Boolean] :replace (false) Whether to replace existing handler
+    # @return [Boolean] True if registration successful
+    # @raise [StandardError] If custom event configuration fails (fail fast)
+    # @raise [ArgumentError] If handler already exists and replace is false
+    def register(name, class_or_class_name, namespace_name: :default, version: '0.1.0', **options)
+      name_sym = name.to_sym
+      namespace_name = namespace_name.to_sym
+      replace = options.fetch(:replace, false)
+
+      thread_safe_operation do
+        # Validate custom event configuration BEFORE modifying registry state
+        # This ensures atomic registration - either fully succeeds or fully fails
+        normalized_class = normalize_class_name(class_or_class_name)
+
+        # Validate handler interface using unified validator
+        begin
+          Registry::InterfaceValidator.validate_handler!(normalized_class.is_a?(Class) ? normalized_class : normalized_class.constantize)
+        rescue ArgumentError => e
+          log_validation_failure('task_handler', "#{namespace_name}/#{name_sym}/#{version}", e.message)
+          raise
+        end
+
+        discover_and_register_custom_events(class_or_class_name)
+
+        # Initialize nested hash structure
+        @handler_classes[namespace_name] ||= Concurrent::Hash.new
+        @handler_classes[namespace_name][name_sym] ||= Concurrent::Hash.new
+
+        # Check for existing handler
+        entity_id = "#{namespace_name}/#{name_sym}/#{version}"
+        if @handler_classes[namespace_name][name_sym].key?(version) && !replace
+          raise ArgumentError,
+                "Handler '#{name_sym}' already registered in namespace '#{namespace_name}' version '#{version}'. Use replace: true to override."
+        end
+
+        # Log replacement if needed
+        if @handler_classes[namespace_name][name_sym].key?(version)
+          existing_class = @handler_classes[namespace_name][name_sym][version]
+          log_unregistration('task_handler', entity_id,
+                             existing_class.is_a?(Class) ? existing_class : existing_class.constantize)
+        end
+
+        # Register handler
+        @handler_classes[namespace_name][name_sym][version] = normalized_class
+        @namespaces.add(namespace_name)
+
+        # Log successful registration
+        log_registration('task_handler', entity_id,
+                         normalized_class.is_a?(Class) ? normalized_class : normalized_class.constantize,
+                         { namespace_name: namespace_name, version: version, **options })
+
+        true
+      end
+    end
+
+    # List handlers, optionally filtered by namespace
+    #
+    # @param namespace [String, Symbol, nil] Optional namespace filter
+    # @return [Hash] Handlers hash, either for specific namespace or all namespaces
+    def list_handlers(namespace: nil)
+      if namespace
+        @handler_classes[namespace.to_sym] || Concurrent::Hash.new
+      else
+        @handler_classes.dup
+      end
+    end
+
+    # Get list of all registered namespaces
+    #
+    # @return [Array<Symbol>] Array of namespace symbols
+    def registered_namespaces
+      @namespaces.to_a
+    end
+
+    # Get comprehensive registry statistics
+    #
+    # @return [Hash] Detailed statistics about the registry
+    def stats
+      base_stats.merge(
+        total_namespaces: @namespaces.size,
+        total_handlers: count_total_handlers,
+        handlers_by_namespace: count_handlers_by_namespace,
+        versions_by_namespace: count_versions_by_namespace
+      )
+    end
+
+    # Get all registered handlers (required by BaseRegistry)
+    #
+    # @return [Hash] All registered handlers
+    def all_items
+      @handler_classes.dup
+    end
+
+    # Clear all registered handlers (required by BaseRegistry)
+    #
+    # @return [Boolean] True if cleared successfully
+    def clear!
+      clear_all!
+    end
+
+    # Clear all registered handlers (for testing)
+    #
+    # @return [Boolean] True if cleared successfully
+    def clear_all!
+      thread_safe_operation do
+        @handler_classes.clear
+        @namespaces = Set.new([:default])
+        log_registry_operation('cleared_all')
+        true
+      end
+    end
+
+    private
+
+    # Normalize class name for consistent storage
+    #
+    # @param class_or_class_name [Class, String] The handler class to normalize
+    # @return [Class, String] Normalized class representation
+    def normalize_class_name(class_or_class_name)
+      if class_or_class_name.is_a?(Class)
+        # Store the class directly for anonymous classes
+        class_or_class_name
+      else
+        # Store as string for named classes (original behavior)
+        class_or_class_name.to_s
+      end
+    end
+
+    # Instantiate a handler from class or string
+    #
+    # @param handler_class [Class, String] The handler class to instantiate
+    # @return [Object] New handler instance
+    # @raise [Tasker::ProceduralError] If handler class cannot be instantiated
+    def instantiate_handler(handler_class)
+      if handler_class.is_a?(Class)
+        # Direct class instantiation (used in tests with anonymous classes)
+        handler_class.new
+      else
+        # String class name instantiation (used in production)
+        handler_class.to_s.camelize.constantize.new
+      end
+    rescue NameError => e
+      error_msg = "Failed to instantiate handler: #{e.message}"
+      log_registry_error('handler_instantiation', e, handler_class: handler_class)
+      raise(Tasker::ProceduralError, error_msg)
+    end
+
+    # Raise appropriate error for handler not found
+    #
+    # @param name [String, Symbol] Handler name that was not found
+    # @param namespace_name [Symbol] The namespace that was searched
+    # @param version [String] The version that was searched
+    # @raise [Tasker::ProceduralError] Handler not found error
+    def raise_handler_not_found(name, namespace_name, version)
+      error_msg = if namespace_name == :default
+                    "No task handler for #{name}"
+                  else
+                    "No task handler for #{name} in namespace #{namespace_name} and version #{version}"
+                  end
+
+      log_registry_error('handler_not_found', StandardError.new(error_msg),
+                         handler_name: name,
+                         namespace_name: namespace_name,
+                         version: version)
+
+      raise(Tasker::ProceduralError, error_msg)
+    end
+
+    # Count total handlers across all namespaces and versions
+    #
+    # @return [Integer] Total number of registered handlers
+    def count_total_handlers
+      @handler_classes.values.sum do |namespace_handlers|
+        namespace_handlers.values.sum(&:size)
+      end
+    end
+
+    # Count handlers by namespace
+    #
+    # @return [Hash] Namespace => handler count mapping
+    def count_handlers_by_namespace
+      @handler_classes.transform_values do |namespace_handlers|
+        namespace_handlers.values.sum(&:size)
+      end
+    end
+
+    # Count versions by namespace
+    #
+    # @return [Hash] Namespace => version count mapping
+    def count_versions_by_namespace
+      @handler_classes.transform_values do |namespace_handlers|
+        namespace_handlers.keys.size
+      end
+    end
+
+    # Automatically discover and register custom events from step handlers
+    #
+    # @param handler_class [Class, String] The handler class to scan for custom events
+    # @return [void]
+    # @raise [Tasker::ConfigurationError] If custom event configuration fails
+    def discover_and_register_custom_events(handler_class)
+      # Get the actual class object
+      klass = if handler_class.is_a?(Class)
+                handler_class
+              else
+                handler_class.to_s.camelize.constantize
+              end
+
+      # Check if this is a step handler class (has custom_event_configuration method)
+      if klass.respond_to?(:custom_event_configuration)
+        # This is a step handler class - register its custom events directly
+        # Configuration failures should be visible errors, not silent warnings
+        class_events = klass.custom_event_configuration
+        register_custom_events_from_config(class_events, klass)
+        return
+      end
+
+      # Check if this is a task handler class (has step_templates instance method)
+      # We need to avoid instantiating task handler classes as it causes recursion
+      nil unless klass.instance_methods(false).include?(:step_templates)
+
+      # For task handler classes, we'll register custom events from step template definitions
+      # but we can't safely instantiate the class here due to recursion
+      # Instead, we'll let the step handlers register their own events when they're loaded
+      # This is a limitation we accept to avoid the recursive instantiation issue
+
+      # NOTE: YAML-based custom events in step templates will be handled during
+      # the task building process, not here
+    end
+
+    # Register custom events from configuration (either class-based or YAML-based)
+    #
+    # @param events_config [Array<Hash>] Array of event configurations
+    # @param handler_class [Class] The handler class that can fire these events
+    # @return [void]
+    def register_custom_events_from_config(events_config, handler_class)
+      events_config.each do |event_config|
+        # Support both symbol and string keys
+        event_name = event_config[:name] || event_config['name']
+        description = event_config[:description] || event_config['description'] ||
+                      "Custom event from #{handler_class.name}"
+
+        next unless event_name
+
+        # Add the handler class to fired_by array automatically
+        fired_by = [handler_class.name]
+
+        Tasker::Events::CustomRegistry.instance.register_event(
+          event_name,
+          description: description,
+          fired_by: fired_by
+        )
+      end
+    end
+  end
+end

data/lib/tasker/health/readiness_checker.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Tasker
+  module Health
+    # ReadinessChecker validates basic system readiness
+    #
+    # Performs lightweight checks to determine if the system can accept new requests.
+    # Designed for Kubernetes readiness probes with fast response times.
+    #
+    # @example Basic usage
+    #   checker = Tasker::Health::ReadinessChecker.new
+    #   result = checker.check
+    #   puts result[:ready]  # true/false
+    #
+    # @example With custom timeout
+    #   checker = Tasker::Health::ReadinessChecker.new(timeout: 3.0)
+    #   result = checker.check
+    class ReadinessChecker
+      # @return [Float] Timeout for readiness checks in seconds
+      attr_reader :timeout
+
+      # Initialize readiness checker
+      #
+      # @param timeout [Float] Maximum time to wait for checks (default: 5.0 seconds)
+      def initialize(timeout: nil)
+        @timeout = timeout || Tasker.configuration.health.readiness_timeout_seconds
+      end
+
+      # Class method for simple readiness check
+      #
+      # @return [Boolean] Whether system is ready
+      def self.ready?
+        new.check[:ready]
+      end
+
+      # Class method for detailed readiness status
+      #
+      # @return [Hash] Detailed readiness status
+      def self.detailed_status
+        new.check
+      end
+
+      # Perform readiness check
+      #
+      # @return [Hash] Readiness status with details
+      #   - :ready [Boolean] Overall readiness status
+      #   - :checks [Hash] Individual check results
+      #   - :message [String] Status message
+      #   - :timestamp [Time] When check was performed
+      def check
+        start_time = Time.current
+        checks = {}
+
+        begin
+          # Use timeout protection for all checks
+          Timeout.timeout(@timeout) do
+            checks[:database] = check_database_connection_with_timing
+            checks[:cache] = check_cache_availability_with_timing
+          end
+
+          ready = checks.values.all? { |check| check[:status] == 'healthy' }
+          failed_checks = checks.select { |_name, check| check[:status] == 'unhealthy' }.keys.map(&:to_s)
+
+          result = {
+            ready: ready,
+            checks: checks,
+            message: ready ? 'System is ready' : 'System is not ready',
+            timestamp: Time.current,
+            check_duration: Time.current - start_time
+          }
+
+          # Add failed_checks if there are any failures
+          result[:failed_checks] = failed_checks unless failed_checks.empty?
+          result
+        rescue Timeout::Error
+          {
+            ready: false,
+            checks: checks,
+            message: "Readiness check timed out after #{@timeout} seconds",
+            timestamp: Time.current,
+            check_duration: Time.current - start_time
+          }
+        rescue StandardError => e
+          {
+            ready: false,
+            checks: checks,
+            message: "Readiness check failed: #{e.message}",
+            error: e.class.name,
+            timestamp: Time.current,
+            check_duration: Time.current - start_time
+          }
+        end
+      end
+
+      private
+
+      # Check database connection with timing
+      #
+      # @return [Hash] Database check result with response time
+      def check_database_connection_with_timing
+        start_time = Time.current
+        ActiveRecord::Base.connection.execute('SELECT 1')
+        response_time = ((Time.current - start_time) * 1000).round(2)
+
+        {
+          status: 'healthy',
+          message: 'Database connection active',
+          response_time_ms: response_time
+        }
+      rescue StandardError => e
+        response_time = ((Time.current - start_time) * 1000).round(2)
+        {
+          status: 'unhealthy',
+          message: "Database connection failed: #{e.message}",
+          error: "#{e.class.name}: #{e.message}",
+          response_time_ms: response_time
+        }
+      end
+
+      # Check cache availability with timing and strategy awareness
+      #
+      # Enhanced with cache strategy detection to provide detailed capability information
+      # @return [Hash] Cache check result with response time and strategy details
+      def check_cache_availability_with_timing
+        start_time = Time.current
+
+        # Get cache strategy for enhanced diagnostics
+        cache_strategy = Tasker::CacheStrategy.detect
+
+        # Simple cache test - write and read a test key
+        test_key = "tasker_readiness_check_#{SecureRandom.hex(8)}"
+        test_value = Time.current.to_i
+
+        Rails.cache.write(test_key, test_value, expires_in: 1.minute)
+        cached_value = Rails.cache.read(test_key)
+        Rails.cache.delete(test_key) # cleanup
+
+        response_time = ((Time.current - start_time) * 1000).round(2)
+
+        if cached_value == test_value
+          {
+            status: 'healthy',
+            message: 'Cache is available',
+            response_time_ms: response_time,
+            cache_store: cache_strategy.store_class_name,
+            coordination_strategy: cache_strategy.coordination_mode,
+            distributed: cache_strategy.supports?(:distributed),
+            atomic_operations: cache_strategy.supports?(:atomic_increment),
+            locking_support: cache_strategy.supports?(:locking)
+          }
+        else
+          {
+            status: 'unhealthy',
+            message: 'Cache read/write test failed',
+            error: 'CacheTestFailed',
+            response_time_ms: response_time,
+            cache_store: cache_strategy.store_class_name,
+            coordination_strategy: cache_strategy.coordination_mode
+          }
+        end
+      rescue StandardError => e
+        response_time = ((Time.current - start_time) * 1000).round(2)
+
+        # Try to get cache strategy info even if test failed
+        strategy_info = begin
+          strategy = Tasker::CacheStrategy.detect
+          {
+            cache_store: strategy.store_class_name,
+            coordination_strategy: strategy.coordination_mode
+          }
+        rescue StandardError
+          { cache_store: 'Unknown', coordination_strategy: 'unknown' }
+        end
+
+        {
+          status: 'unhealthy',
+          message: "Cache check failed: #{e.message}",
+          error: "#{e.class.name}: #{e.message}",
+          response_time_ms: response_time
+        }.merge(strategy_info)
+      end
+    end
+  end
+end