tasker-engine 1.0.0

data/lib/tasker/registry/base_registry.rb

@@ -0,0 +1,177 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../concerns/structured_logging'
+require 'concurrent-ruby'
+
+module Tasker
+  module Registry
+    # Base class for all registry systems in Tasker
+    #
+    # Provides common functionality including thread-safe operations,
+    # structured logging, health checks, and statistics interfaces.
+    # All registry classes should inherit from this base class.
+    class BaseRegistry
+      include Tasker::Concerns::StructuredLogging
+
+      def initialize
+        @mutex = Mutex.new
+        @telemetry_config = Tasker.configuration.telemetry
+        @registry_name = self.class.name.demodulize.underscore
+        @created_at = Time.current
+      end
+
+      protected
+
+      # Log registration events with structured format
+      #
+      # @param entity_type [String] Type of entity being registered
+      # @param entity_id [String] Unique identifier for the entity
+      # @param entity_class [Class, String] Class of the entity being registered
+      # @param options [Hash] Additional registration options
+      def log_registration(entity_type, entity_id, entity_class, options = {})
+        class_name = entity_class.is_a?(Class) ? entity_class.name : entity_class.to_s
+        log_structured(:info, 'Registry item registered',
+                       entity_type: entity_type,
+                       entity_id: entity_id,
+                       entity_class: class_name,
+                       registry_name: @registry_name,
+                       options: options,
+                       event_type: :registered)
+      end
+
+      # Log unregistration events with structured format
+      #
+      # @param entity_type [String] Type of entity being unregistered
+      # @param entity_id [String] Unique identifier for the entity
+      # @param entity_class [Class, String] Class of the entity being unregistered
+      def log_unregistration(entity_type, entity_id, entity_class)
+        class_name = entity_class.is_a?(Class) ? entity_class.name : entity_class.to_s
+        log_structured(:info, 'Registry item unregistered',
+                       entity_type: entity_type,
+                       entity_id: entity_id,
+                       entity_class: class_name,
+                       registry_name: @registry_name,
+                       event_type: :unregistered)
+      end
+
+      # Log registry operations with structured format
+      #
+      # @param operation [String] Operation being performed
+      # @param context [Hash] Additional context for the operation
+      def log_registry_operation(operation, **context)
+        log_structured(:debug, "Registry #{operation}",
+                       registry_name: @registry_name,
+                       operation: operation,
+                       **context)
+      end
+
+      # Log registry errors with structured format
+      #
+      # @param operation [String] Operation that failed
+      # @param error [Exception] The error that occurred
+      # @param context [Hash] Additional context for the error
+      def log_registry_error(operation, error, **context)
+        log_structured(:error, "Registry #{operation} failed",
+                       registry_name: @registry_name,
+                       operation: operation,
+                       error: error.message,
+                       error_class: error.class.name,
+                       **context)
+      end
+
+      # Log validation failures with structured format
+      #
+      # @param entity_type [String] Type of entity that failed validation
+      # @param entity_id [String] Unique identifier for the entity
+      # @param validation_error [String] Description of the validation failure
+      def log_validation_failure(entity_type, entity_id, validation_error)
+        log_structured(:error, 'Registry validation failed',
+                       entity_type: entity_type,
+                       entity_id: entity_id,
+                       registry_name: @registry_name,
+                       validation_error: validation_error,
+                       event_type: :validation_failed)
+      end
+
+      # Validate registration parameters
+      #
+      # @param name [String] Name of the entity
+      # @param entity_class [Class] Class of the entity
+      # @param options [Hash] Registration options
+      # @raise [ArgumentError] If parameters are invalid
+      def validate_registration_params!(name, entity_class, options = {})
+        raise ArgumentError, 'Name cannot be blank' if name.blank?
+        raise ArgumentError, 'Entity class cannot be nil' if entity_class.nil?
+        raise ArgumentError, 'Options must be a Hash' unless options.is_a?(Hash)
+      end
+
+      # Execute operations in a thread-safe manner
+      #
+      # @yield Block to execute within mutex
+      # @return [Object] Result of the block
+      def thread_safe_operation(&)
+        @mutex.synchronize(&)
+      end
+
+      # Common registry statistics interface
+      #
+      # @return [Hash] Base statistics shared by all registries
+      def base_stats
+        {
+          registry_name: @registry_name,
+          created_at: @created_at,
+          uptime_seconds: (Time.current - @created_at).to_i
+        }
+      end
+
+      # Health check interface
+      #
+      # @return [Boolean] True if registry is healthy
+      def healthy?
+        # Basic health checks that all registries should pass
+        !@mutex.locked? && respond_to?(:stats)
+      end
+
+      # Comprehensive health check with details
+      #
+      # @return [Hash] Health check results
+      def health_check
+        {
+          healthy: healthy?,
+          registry_name: @registry_name,
+          stats: stats,
+          last_check: Time.current
+        }
+      end
+
+      public
+
+      # Abstract methods that subclasses must implement
+
+      # Get comprehensive statistics for this registry
+      #
+      # @return [Hash] Registry-specific statistics
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def stats
+        raise NotImplementedError, 'Subclasses must implement #stats'
+      end
+
+      # Get all items in the registry
+      #
+      # @return [Hash] All registered items
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def all_items
+        raise NotImplementedError, 'Subclasses must implement #all_items'
+      end
+
+      # Clear all items from the registry
+      #
+      # @return [void]
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def clear!
+        raise NotImplementedError, 'Subclasses must implement #clear!'
+      end
+    end
+  end
+end

data/lib/tasker/registry/event_publisher.rb

@@ -0,0 +1,91 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../concerns/event_publisher'
+
+module Tasker
+  module Registry
+    # Event publishing capabilities for registry systems
+    #
+    # Provides standardized event publishing for registration,
+    # unregistration, and validation events across all registries.
+    module EventPublisher
+      extend ActiveSupport::Concern
+
+      included do
+        include Tasker::Concerns::EventPublisher
+      end
+
+      # Publish registration event
+      #
+      # @param entity_type [String] Type of entity being registered
+      # @param entity_id [String] Unique identifier for the entity
+      # @param entity_class [Class, String] Class of the entity being registered
+      # @param options [Hash] Additional registration options
+      def publish_registration_event(entity_type, entity_id, entity_class, options = {})
+        event_name = "#{entity_type}.registered"
+        class_name = entity_class.is_a?(Class) ? entity_class.name : entity_class.to_s
+
+        publish_event(event_name, {
+                        registry_name: @registry_name,
+                        entity_type: entity_type,
+                        entity_id: entity_id,
+                        entity_class: class_name,
+                        options: options,
+                        registered_at: Time.current,
+                        correlation_id: correlation_id
+                      })
+      end
+
+      # Publish unregistration event
+      #
+      # @param entity_type [String] Type of entity being unregistered
+      # @param entity_id [String] Unique identifier for the entity
+      # @param entity_class [Class, String] Class of the entity being unregistered
+      def publish_unregistration_event(entity_type, entity_id, entity_class)
+        event_name = "#{entity_type}.unregistered"
+        class_name = entity_class.is_a?(Class) ? entity_class.name : entity_class.to_s
+
+        publish_event(event_name, {
+                        registry_name: @registry_name,
+                        entity_type: entity_type,
+                        entity_id: entity_id,
+                        entity_class: class_name,
+                        unregistered_at: Time.current,
+                        correlation_id: correlation_id
+                      })
+      end
+
+      # Publish validation failure event
+      #
+      # @param entity_type [String] Type of entity that failed validation
+      # @param entity_class [Class, String] Class of the entity that failed validation
+      # @param error [StandardError] The validation error that occurred
+      def publish_validation_failed_event(entity_type, entity_class, error)
+        event_name = "#{entity_type}.validation_failed"
+        class_name = entity_class.is_a?(Class) ? entity_class.name : entity_class.to_s
+
+        publish_event(event_name, {
+                        registry_name: @registry_name,
+                        entity_type: entity_type,
+                        entity_class: class_name,
+                        validation_error: error.message,
+                        failed_at: Time.current,
+                        correlation_id: correlation_id
+                      })
+      end
+
+      # Publish registry statistics collection event
+      #
+      # @param stats [Hash] Registry statistics
+      def publish_registry_stats_event(stats)
+        publish_event('registry.stats_collected', {
+                        registry_name: @registry_name,
+                        stats: stats,
+                        collected_at: Time.current,
+                        correlation_id: correlation_id
+                      })
+      end
+    end
+  end
+end

data/lib/tasker/registry/interface_validator.rb

@@ -0,0 +1,140 @@
+# typed: false
+# frozen_string_literal: true
+
+module Tasker
+  module Registry
+    # Unified interface validation for all registry systems
+    #
+    # Provides consistent validation patterns for handlers, subscribers, plugins,
+    # and other registry items to ensure they implement required interfaces.
+    class InterfaceValidator
+      class << self
+        # Validate a task handler class
+        #
+        # @param handler_class [Class] The handler class to validate
+        # @raise [ArgumentError] If validation fails
+        def validate_handler!(handler_class)
+          validate_class_methods!(handler_class, HANDLER_INTERFACE)
+          validate_instance_methods!(handler_class, HANDLER_INSTANCE_INTERFACE)
+        end
+
+        # Validate an event subscriber class
+        #
+        # @param subscriber_class [Class] The subscriber class to validate
+        # @raise [ArgumentError] If validation fails
+        def validate_subscriber!(subscriber_class)
+          validate_instance_methods!(subscriber_class, SUBSCRIBER_INTERFACE)
+        end
+
+        # Validate a telemetry plugin instance
+        #
+        # @param plugin_instance [Object] The plugin instance to validate
+        # @raise [ArgumentError] If validation fails
+        def validate_plugin!(plugin_instance)
+          validate_instance_methods!(plugin_instance.class, PLUGIN_INTERFACE)
+          validate_method_arity!(plugin_instance, PLUGIN_ARITY_REQUIREMENTS)
+        end
+
+        # Validate an export coordinator plugin
+        #
+        # @param plugin_instance [Object] The export plugin instance to validate
+        # @raise [ArgumentError] If validation fails
+        def validate_export_plugin!(plugin_instance)
+          validate_instance_methods!(plugin_instance.class, EXPORT_PLUGIN_INTERFACE)
+          validate_method_arity!(plugin_instance, EXPORT_PLUGIN_ARITY_REQUIREMENTS)
+        end
+
+        private
+
+        # Interface definitions for different types of registry items
+        HANDLER_INTERFACE = {
+          required_class_methods: [],
+          optional_class_methods: %i[process configure dependencies]
+        }.freeze
+
+        HANDLER_INSTANCE_INTERFACE = {
+          required_instance_methods: [],
+          optional_instance_methods: %i[initialize before_process after_process step_templates]
+        }.freeze
+
+        SUBSCRIBER_INTERFACE = {
+          required_instance_methods: [:call],
+          optional_instance_methods: %i[initialize filter_events]
+        }.freeze
+
+        PLUGIN_INTERFACE = {
+          required_instance_methods: %i[export supports_format?],
+          optional_instance_methods: %i[supported_formats metadata validate_data]
+        }.freeze
+
+        EXPORT_PLUGIN_INTERFACE = {
+          required_instance_methods: %i[export supports_format?],
+          optional_instance_methods: %i[supported_formats on_cache_sync on_export_request on_export_complete]
+        }.freeze
+
+        # Method arity requirements for validation
+        PLUGIN_ARITY_REQUIREMENTS = {
+          export: { min: 1, max: 2 },
+          supports_format?: { min: 1, max: 1 }
+        }.freeze
+
+        EXPORT_PLUGIN_ARITY_REQUIREMENTS = {
+          export: { min: 1, max: 2 },
+          supports_format?: { min: 1, max: 1 },
+          on_cache_sync: { min: 0, max: 1 },
+          on_export_request: { min: 0, max: 1 },
+          on_export_complete: { min: 0, max: 1 }
+        }.freeze
+
+        # Validate that a class implements required class methods
+        #
+        # @param klass [Class] The class to validate
+        # @param interface [Hash] Interface definition with required/optional methods
+        def validate_class_methods!(klass, interface)
+          interface[:required_class_methods]&.each do |method|
+            raise ArgumentError, "#{klass} must implement class method #{method}" unless klass.respond_to?(method)
+          end
+        end
+
+        # Validate that a class implements required instance methods
+        #
+        # @param klass [Class] The class to validate
+        # @param interface [Hash] Interface definition with required/optional methods
+        def validate_instance_methods!(klass, interface)
+          interface[:required_instance_methods]&.each do |method|
+            unless klass.instance_methods.include?(method)
+              raise ArgumentError, "#{klass} must implement instance method #{method}"
+            end
+          end
+        end
+
+        # Validate method arity for specific methods
+        #
+        # @param instance [Object] The instance to validate
+        # @param arity_requirements [Hash] Method name => arity requirements mapping
+        def validate_method_arity!(instance, arity_requirements)
+          arity_requirements.each do |method, requirements|
+            next unless instance.respond_to?(method)
+
+            method_obj = instance.method(method)
+            arity = method_obj.arity
+
+            # Handle negative arity (variable arguments)
+            if arity.negative?
+              min_required = arity.abs - 1
+              if min_required > requirements[:max]
+                raise ArgumentError,
+                      "#{method} requires too many arguments (min: #{min_required}, max allowed: #{requirements[:max]})"
+              end
+            else
+              unless arity.between?(requirements[:min], requirements[:max])
+                raise ArgumentError,
+                      "#{method} arity mismatch (expected: #{requirements[:min]}-#{requirements[:max]}, got: #{arity})"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end