tasker-engine 1.0.0

data/lib/tasker/configuration.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Tasker
+  # Configuration class for the Tasker gem
+  #
+  # Handles global configuration options with nested configuration blocks
+  # for better organization and discoverability.
+  #
+  # All configuration types are now implemented using dry-struct for type safety,
+  # immutability, and consistent validation patterns.
+  class Configuration
+    # Simple proxy object for configuration blocks that provides dot-notation access
+    # to hash values without the overhead of OpenStruct.
+    #
+    # This enables clean configuration syntax like:
+    #   config.auth do |auth|
+    #     auth.authentication_enabled = true
+    #     auth.authenticator_class = 'MyAuth'
+    #   end
+    #
+    # While maintaining the benefits of dry-struct validation and immutability.
+    class ConfigurationProxy
+      # Initialize a new configuration proxy with hash data
+      #
+      # @param hash [Hash] The hash data to wrap
+      def initialize(hash = {})
+        @hash = hash.transform_keys(&:to_sym)
+      end
+
+      # Handle dynamic method calls for configuration access
+      #
+      # @param method_name [Symbol] The method being called
+      # @param args [Array] Arguments passed to the method
+      def method_missing(method_name, *args)
+        if method_name.to_s.end_with?('=')
+          # Setter: config.authentication_enabled = true
+          key = method_name.to_s.chomp('=').to_sym
+          @hash[key] = args.first
+        elsif @hash.key?(method_name.to_sym)
+          # Getter: config.authentication_enabled
+          @hash[method_name.to_sym]
+        else
+          super
+        end
+      end
+
+      # Check if the proxy responds to a given method
+      #
+      # @param method_name [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] True if the method is supported
+      def respond_to_missing?(method_name, include_private = false)
+        method_name.to_s.end_with?('=') || @hash.key?(method_name.to_sym) || super
+      end
+
+      # Convert the proxy back to a hash for dry-struct creation
+      #
+      # @return [Hash] The underlying hash data
+      def to_h
+        @hash
+      end
+    end
+
+    # Specialized configuration proxy for telemetry settings
+    # Handles special methods specific to TelemetryConfig
+    class TelemetryConfigurationProxy < ConfigurationProxy
+      # Handle telemetry-specific configuration method
+      #
+      # @param options [Hash] Telemetry configuration options
+      def configure_telemetry(options = {})
+        current_config = @hash[:config] || {}
+        @hash[:config] = current_config.merge(options)
+      end
+
+      # Check if the proxy responds to telemetry-specific methods
+      #
+      # @param method_name [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] True if the method is supported
+      def respond_to_missing?(method_name, include_private = false)
+        method_name.to_s == 'configure_telemetry' || super
+      end
+    end
+
+    # Initialize a new configuration with default values
+    #
+    # @return [Configuration] A new configuration instance
+    def initialize
+      # Initialize nested configurations using dry-struct types
+      @auth_config = Tasker::Types::AuthConfig.new
+      @database_config = Tasker::Types::DatabaseConfig.new
+      @telemetry_config = Tasker::Types::TelemetryConfig.new
+      @engine_config = Tasker::Types::EngineConfig.new
+      @health_config = Tasker::Types::HealthConfig.new
+      @dependency_graph_config = Tasker::Types::DependencyGraphConfig.new
+      @backoff_config = Tasker::Types::BackoffConfig.new
+      @execution_config = Tasker::Types::ExecutionConfig.new
+      @cache_config = Tasker::Types::CacheConfig.new
+    end
+
+    # Reset configuration to defaults (useful for testing)
+    def reset!
+      @auth_config = Tasker::Types::AuthConfig.new
+      @database_config = Tasker::Types::DatabaseConfig.new
+      @telemetry_config = Tasker::Types::TelemetryConfig.new
+      @engine_config = Tasker::Types::EngineConfig.new
+      @health_config = Tasker::Types::HealthConfig.new
+      @dependency_graph_config = Tasker::Types::DependencyGraphConfig.new
+      @backoff_config = Tasker::Types::BackoffConfig.new
+      @execution_config = Tasker::Types::ExecutionConfig.new
+      @cache_config = Tasker::Types::CacheConfig.new
+    end
+
+    # Create a deep copy of the configuration
+    #
+    # Since dry-struct types are immutable, we don't need to duplicate them
+    def dup
+      new_config = super
+      new_config.instance_variable_set(:@auth_config, @auth_config)
+      new_config.instance_variable_set(:@database_config, @database_config)
+      new_config.instance_variable_set(:@telemetry_config, @telemetry_config)
+      new_config.instance_variable_set(:@engine_config, @engine_config)
+      new_config.instance_variable_set(:@health_config, @health_config)
+      new_config.instance_variable_set(:@dependency_graph_config, @dependency_graph_config)
+      new_config.instance_variable_set(:@backoff_config, @backoff_config)
+      new_config.instance_variable_set(:@execution_config, @execution_config)
+      new_config.instance_variable_set(:@cache_config, @cache_config)
+      new_config
+    end
+
+    # Configure authentication and authorization settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting auth options
+    # @return [Tasker::Types::AuthConfig] The auth configuration instance
+    def auth
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @auth_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @auth_config = Tasker::Types::AuthConfig.new(yield_config.to_h)
+      end
+      @auth_config
+    end
+
+    # Alias for auth configuration for backward compatibility
+    # @return [Tasker::Types::AuthConfig] The authentication configuration instance
+    def authentication
+      @auth_config
+    end
+
+    # Configure database settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting database options
+    # @return [Tasker::Types::DatabaseConfig] The database configuration instance
+    def database
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @database_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @database_config = Tasker::Types::DatabaseConfig.new(yield_config.to_h)
+      end
+      @database_config
+    end
+
+    # Configure telemetry and observability settings
+    #
+    # @yield [TelemetryConfigurationProxy] A configuration object for setting telemetry options
+    # @return [Tasker::Types::TelemetryConfig] The telemetry configuration instance
+    def telemetry
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @telemetry_config.to_h
+        yield_config = TelemetryConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @telemetry_config = Tasker::Types::TelemetryConfig.new(yield_config.to_h)
+      end
+      @telemetry_config
+    end
+
+    # Configure core engine settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting engine options
+    # @return [Tasker::Types::EngineConfig] The engine configuration instance
+    def engine
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @engine_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @engine_config = Tasker::Types::EngineConfig.new(yield_config.to_h)
+      end
+      @engine_config
+    end
+
+    # Configure health check settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting health options
+    # @return [Tasker::Types::HealthConfig] The health configuration instance
+    def health
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @health_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @health_config = Tasker::Types::HealthConfig.new(yield_config.to_h)
+      end
+      @health_config
+    end
+
+    # Configure dependency graph calculation settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting dependency graph options
+    # @return [Tasker::Types::DependencyGraphConfig] The dependency graph configuration instance
+    def dependency_graph
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @dependency_graph_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @dependency_graph_config = Tasker::Types::DependencyGraphConfig.new(yield_config.to_h)
+      end
+      @dependency_graph_config
+    end
+
+    # Configure backoff calculation settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting backoff options
+    # @return [Tasker::Types::BackoffConfig] The backoff configuration instance
+    def backoff
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @backoff_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @backoff_config = Tasker::Types::BackoffConfig.new(yield_config.to_h)
+      end
+      @backoff_config
+    end
+
+    # Configure step execution and concurrency settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting execution options
+    # @return [Tasker::Types::ExecutionConfig] The execution configuration instance
+    def execution
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @execution_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @execution_config = Tasker::Types::ExecutionConfig.new(yield_config.to_h)
+      end
+      @execution_config
+    end
+
+    # Configure intelligent cache strategy settings
+    #
+    # @yield [ConfigurationProxy] A configuration object for setting cache options
+    # @return [Tasker::Types::CacheConfig] The cache configuration instance
+    def cache
+      if block_given?
+        # For block configuration, we need to create a new instance with the block's values
+        current_values = @cache_config.to_h
+        yield_config = ConfigurationProxy.new(current_values)
+        yield(yield_config)
+        @cache_config = Tasker::Types::CacheConfig.new(yield_config.to_h)
+      end
+      @cache_config
+    end
+
+    # Validate required configuration settings for system health
+    # Used by health check endpoints to ensure system is properly configured
+    # @return [true] if valid
+    # @raise [StandardError] if invalid configuration found
+    def validate_required_settings
+      errors = []
+
+      # Database connectivity check
+      errors << 'Database connection required' unless database_connected?
+
+      # Authentication configuration validation (if enabled)
+      if auth.authentication_enabled && auth.authenticator_class.blank?
+        errors << 'Authentication enabled but no authenticator_class configured'
+      end
+
+      # Health configuration validation (dry-struct handles validation automatically)
+      @health_config&.validate!
+
+      raise StandardError, errors.join(', ') if errors.any?
+
+      true
+    end
+
+    private
+
+    # Check if database is connected and available
+    # @return [Boolean] true if database is connected
+    def database_connected?
+      ActiveRecord::Base.connection.active?
+    rescue StandardError
+      false
+    end
+
+    # Get or create the global configuration
+    #
+    # @yield [Configuration] The configuration instance if a block is given
+    # @return [Configuration] The configuration instance
+    def self.configuration
+      @configuration ||= Configuration.new
+
+      # Yield if a block is given for backwards compatibility
+      yield(@configuration) if block_given?
+
+      @configuration
+    end
+
+    # Reset the configuration to default values
+    #
+    # @return [Configuration] A new configuration instance
+    def self.reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/tasker/constants/event_definitions.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Tasker
+  module Constants
+    # EventDefinitions provides a bridge between event constants and their metadata
+    #
+    # This class loads event metadata from system_events.yml and provides methods
+    # to find events by constant, retrieve all events by category, etc.
+    # It serves as the single source of truth for event documentation and payload schemas.
+    class EventDefinitions
+      class << self
+        # Find event definition by constant name
+        #
+        # @param constant [String] The event constant (e.g., 'task.completed')
+        # @return [Hash, nil] Event definition or nil if not found
+        def find_by(constant:)
+          event_metadata.find { |_key, data| data['constant'] == constant }&.last
+        end
+
+        # Get all events grouped by category
+        #
+        # @return [Hash] Events grouped by category (task, step, workflow, etc.)
+        def all_events
+          @all_events ||= build_all_events
+        end
+
+        # Get events for a specific category
+        #
+        # @param category [String] The event category (task, step, workflow, etc.)
+        # @return [Hash] Events in the specified category
+        def events_by_category(category)
+          all_events[category.to_s] || {}
+        end
+
+        # Get all event constants
+        #
+        # @return [Array<String>] All event constant names
+        def all_constants
+          event_metadata.values.pluck('constant').compact
+        end
+
+        # Refresh cached data (useful for testing)
+        #
+        # @return [void]
+        def refresh!
+          @event_metadata = nil
+          @all_events = nil
+        end
+
+        private
+
+        # Load and cache event metadata from system_events.yml
+        #
+        # @return [Hash] Event metadata with descriptions and schemas
+        def event_metadata
+          @event_metadata ||= load_event_metadata
+        end
+
+        # Load event metadata from YAML configuration
+        #
+        # @return [Hash] Parsed event metadata
+        def load_event_metadata
+          yaml_file = File.join(Tasker::Engine.root, 'config', 'tasker', 'system_events.yml')
+
+          unless File.exist?(yaml_file)
+            Rails.logger.warn("EventDefinitions: system_events.yml not found at #{yaml_file}")
+            return {}
+          end
+
+          yaml_data = YAML.load_file(yaml_file)
+          events_data = yaml_data['event_metadata'] || {}
+
+          # Flatten nested events structure
+          flattened = {}
+          events_data.each do |category, category_events|
+            category_events.each do |event_key, event_data|
+              # Generate the full key for this event
+              full_key = "#{category}_#{event_key}"
+
+              # Get the constant reference and resolve it to actual constant value
+              constant_ref = event_data['constant_ref']
+              constant_value = resolve_constant_reference(constant_ref)
+
+              if constant_value
+                # Enhance event data with resolved constant and category
+                enhanced_data = event_data.merge(
+                  'constant' => constant_value,
+                  'category' => category,
+                  'key' => event_key
+                )
+                flattened[full_key] = enhanced_data
+              else
+                Rails.logger.warn("EventDefinitions: Could not resolve constant #{constant_ref}")
+              end
+            end
+          end
+
+          flattened
+        rescue StandardError => e
+          Rails.logger.error("EventDefinitions: Failed to load event metadata: #{e.message}")
+          {}
+        end
+
+        # Resolve constant reference to actual constant value
+        #
+        # @param constant_ref [String] The constant reference (e.g., "Tasker::Constants::TaskEvents::COMPLETED")
+        # @return [String, nil] The constant value or nil if not found
+        def resolve_constant_reference(constant_ref)
+          return nil unless constant_ref
+
+          # Split the constant reference and navigate to it
+          # E.g., "Tasker::Constants::TaskEvents::COMPLETED" -> ["Tasker", "Constants", "TaskEvents", "COMPLETED"]
+          parts = constant_ref.split('::')
+
+          # Start with the root constant (Tasker)
+          current = Object.const_get(parts.first)
+
+          # Navigate through the nested constants
+          parts[1..].each do |part|
+            current = current.const_get(part)
+          end
+
+          current
+        rescue NameError => e
+          Rails.logger.debug { "EventDefinitions: Cannot resolve constant #{constant_ref}: #{e.message}" }
+          nil
+        end
+
+        # Build all events grouped by category
+        #
+        # @return [Hash] Events grouped by category
+        def build_all_events
+          grouped = Hash.new { |h, k| h[k] = {} }
+
+          event_metadata.each do |event_key, event_data|
+            category = event_data['category']
+            grouped[category][event_key] = event_data
+          end
+
+          grouped
+        end
+      end
+    end
+  end
+end

data/lib/tasker/constants/registry_events.rb

@@ -0,0 +1,54 @@
+# typed: false
+# frozen_string_literal: true
+
+module Tasker
+  module Constants
+    # Registry system events
+    #
+    # Events published by registry systems for registration,
+    # unregistration, validation, and coordination activities.
+    module RegistryEvents
+      # Handler registration events
+      HANDLER_REGISTERED = 'handler.registered'
+      HANDLER_UNREGISTERED = 'handler.unregistered'
+      HANDLER_VALIDATION_FAILED = 'handler.validation_failed'
+
+      # Plugin registration events
+      PLUGIN_REGISTERED = 'plugin.registered'
+      PLUGIN_UNREGISTERED = 'plugin.unregistered'
+      PLUGIN_VALIDATION_FAILED = 'plugin.validation_failed'
+
+      # Subscriber registration events
+      SUBSCRIBER_REGISTERED = 'subscriber.registered'
+      SUBSCRIBER_UNREGISTERED = 'subscriber.unregistered'
+      SUBSCRIBER_VALIDATION_FAILED = 'subscriber.validation_failed'
+
+      # Registry coordination events
+      REGISTRY_SYNC_REQUESTED = 'registry.sync_requested'
+      REGISTRY_HEALTH_CHECK = 'registry.health_check'
+      REGISTRY_STATS_COLLECTED = 'registry.stats_collected'
+
+      # Cross-registry events
+      CROSS_REGISTRY_DISCOVERY = 'registry.cross_discovery'
+      REGISTRY_COORDINATION_COMPLETE = 'registry.coordination_complete'
+
+      # All registry events for convenient bulk subscription
+      ALL_REGISTRY_EVENTS = [
+        HANDLER_REGISTERED,
+        HANDLER_UNREGISTERED,
+        HANDLER_VALIDATION_FAILED,
+        PLUGIN_REGISTERED,
+        PLUGIN_UNREGISTERED,
+        PLUGIN_VALIDATION_FAILED,
+        SUBSCRIBER_REGISTERED,
+        SUBSCRIBER_UNREGISTERED,
+        SUBSCRIBER_VALIDATION_FAILED,
+        REGISTRY_SYNC_REQUESTED,
+        REGISTRY_HEALTH_CHECK,
+        REGISTRY_STATS_COLLECTED,
+        CROSS_REGISTRY_DISCOVERY,
+        REGISTRY_COORDINATION_COMPLETE
+      ].freeze
+    end
+  end
+end