tasker-engine 1.0.0

data/lib/tasker/telemetry/plugin_registry.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require_relative '../registry/base_registry'
+require_relative '../registry/interface_validator'
+require 'concurrent-ruby'
+
+module Tasker
+  module Telemetry
+    # Registry for managing export plugins
+    #
+    # Provides centralized management of export plugins with discovery,
+    # registration, and format-based lookup capabilities. Now modernized
+    # with BaseRegistry patterns for consistency across all registry systems.
+    #
+    # @example Register a plugin
+    #   registry = Tasker::Telemetry::PluginRegistry.instance
+    #   registry.register('my_exporter', MyExporter.new)
+    #
+    # @example Find plugins by format
+    #   json_plugins = registry.find_by_format('json')
+    #   csv_plugins = registry.find_by_format('csv')
+    #
+    # @example Auto-discover plugins
+    #   registry.auto_discover_plugins
+    class PluginRegistry < Registry::BaseRegistry
+      include Singleton
+
+      def initialize
+        super
+        @plugins = Concurrent::Hash.new
+        @formats = Concurrent::Hash.new
+        log_registry_operation('initialized', total_plugins: 0, total_formats: 0)
+      end
+
+      # Register a plugin
+      #
+      # @param name [String, Symbol] Plugin identifier
+      # @param plugin [Object] Plugin instance
+      # @param replace [Boolean] Whether to replace existing plugin
+      # @param options [Hash] Plugin options
+      # @return [Boolean] True if registration successful
+      def register(name, plugin, replace: false, **options)
+        name = name.to_s
+
+        thread_safe_operation do
+          # Validate plugin interface
+          begin
+            Registry::InterfaceValidator.validate_plugin!(plugin)
+          rescue ArgumentError => e
+            log_validation_failure('telemetry_plugin', name, e.message)
+            raise
+          end
+
+          # Check for existing plugin
+          if @plugins.key?(name) && !replace
+            raise ArgumentError, "Plugin '#{name}' already registered. Use replace: true to override."
+          end
+
+          # Remove existing plugin if replacing
+          if @plugins.key?(name)
+            existing_config = @plugins[name]
+            unregister_format_mappings(name, existing_config[:supported_formats])
+            log_unregistration('telemetry_plugin', name, existing_config[:instance].class)
+          end
+
+          # Get supported formats
+          supported_formats = get_supported_formats(plugin)
+
+          # Register plugin
+          plugin_config = {
+            instance: plugin,
+            name: name,
+            options: options.merge(replace: replace),
+            registered_at: Time.current,
+            supported_formats: supported_formats
+          }
+
+          @plugins[name] = plugin_config
+
+          # Index by supported formats
+          register_format_mappings(name, supported_formats)
+
+          log_registration('telemetry_plugin', name, plugin.class,
+                           { supported_formats: supported_formats, format_count: supported_formats.size, **options })
+
+          true
+        end
+      end
+
+      # Unregister a plugin
+      #
+      # @param name [String, Symbol] Plugin identifier
+      # @return [Boolean] True if unregistered successfully
+      def unregister(name)
+        name = name.to_s
+
+        thread_safe_operation do
+          plugin_config = @plugins.delete(name)
+
+          if plugin_config
+            # Remove from format index
+            unregister_format_mappings(name, plugin_config[:supported_formats])
+
+            log_unregistration('telemetry_plugin', name, plugin_config[:instance].class)
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # Get all registered plugins
+      #
+      # @return [Hash] Hash of plugin name => plugin info
+      def all_plugins
+        @plugins.dup
+      end
+
+      # Get all registered plugins (required by BaseRegistry)
+      #
+      # @return [Hash] All registered plugins
+      def all_items
+        all_plugins
+      end
+
+      # Get plugin by name
+      #
+      # @param name [String, Symbol] Plugin identifier
+      # @return [Object, nil] Plugin instance or nil if not found
+      def get_plugin(name)
+        plugin_config = @plugins[name.to_s]
+        plugin_config&.dig(:instance)
+      end
+
+      # Find plugins that support a specific format
+      #
+      # @param format [String, Symbol] Format to search for
+      # @return [Array<Object>] Array of plugin instances
+      def find_by_format(format)
+        format = format.to_s.downcase
+        plugin_names = @formats[format].to_a
+
+        plugin_names.filter_map { |name| get_plugin(name) }
+      end
+
+      # Find plugins by criteria (supports keyword arguments for test compatibility)
+      #
+      # @param format [String, Symbol] Format to search for
+      # @return [Array<Object>] Array of plugin instances
+      def find_by(format:)
+        find_by_format(format)
+      end
+
+      # Get supported formats across all plugins
+      #
+      # @return [Array<String>] Array of supported format names
+      def supported_formats
+        @formats.keys.sort
+      end
+
+      # Check if a format is supported by any plugin
+      #
+      # @param format [String, Symbol] Format to check
+      # @return [Boolean] True if format is supported
+      def supports_format?(format)
+        @formats.key?(format.to_s.downcase)
+      end
+
+      # Auto-discover plugins in the plugins directory
+      #
+      # @param directory [String] Directory to search for plugins
+      # @return [Integer] Number of plugins discovered
+      def auto_discover_plugins(directory = nil)
+        directory ||= File.join(File.dirname(__FILE__), 'plugins')
+
+        return 0 unless Dir.exist?(directory)
+
+        discovered_count = 0
+
+        Dir.glob(File.join(directory, '*_exporter.rb')).each do |file|
+          require file
+
+          # Extract class name from filename
+          class_name = File.basename(file, '.rb').camelize
+          full_class_name = "Tasker::Telemetry::Plugins::#{class_name}"
+
+          # Try to instantiate the plugin
+          plugin_class = full_class_name.constantize
+          plugin_instance = plugin_class.new
+
+          register(class_name.underscore, plugin_instance, auto_discovered: true)
+          discovered_count += 1
+
+          log_registry_operation('auto_discovered_plugin',
+                                 plugin_name: class_name,
+                                 plugin_class: full_class_name,
+                                 file_path: file)
+        rescue StandardError => e
+          log_registry_error('auto_discovery_failed', e,
+                             file_path: file,
+                             class_name: File.basename(file, '.rb').camelize)
+        end
+
+        discovered_count
+      end
+
+      # Get comprehensive registry statistics
+      #
+      # @return [Hash] Detailed statistics about the registry
+      def stats
+        base_stats.merge(
+          total_plugins: @plugins.size,
+          total_formats: @formats.size,
+          supported_formats: @formats.keys.sort,
+          plugins_by_format: @formats.transform_values(&:size),
+          average_formats_per_plugin: calculate_average_formats_per_plugin,
+          most_popular_formats: find_most_popular_formats,
+          plugin_distribution: calculate_plugin_distribution
+        )
+      end
+
+      # Clear all registered plugins (required by BaseRegistry)
+      #
+      # @return [Boolean] True if cleared successfully
+      def clear!
+        thread_safe_operation do
+          @plugins.clear
+          @formats.clear
+          log_registry_operation('cleared_all')
+          true
+        end
+      end
+
+      # Legacy method for backward compatibility
+      #
+      # @return [Boolean] True if cleared successfully
+      def clear_all!
+        clear!
+      end
+
+      private
+
+      # Register format mappings for a plugin
+      #
+      # @param plugin_name [String] Name of the plugin
+      # @param formats [Array<String>] Formats to map
+      def register_format_mappings(plugin_name, formats)
+        formats.each do |format|
+          format_key = format.to_s.downcase
+          @formats[format_key] ||= []
+          @formats[format_key] << plugin_name unless @formats[format_key].include?(plugin_name)
+        end
+      end
+
+      # Unregister format mappings for a plugin
+      #
+      # @param plugin_name [String] Name of the plugin
+      # @param formats [Array<String>] Formats to unmap
+      def unregister_format_mappings(plugin_name, formats)
+        formats.each do |format|
+          format_key = format.to_s.downcase
+          @formats[format_key]&.delete(plugin_name)
+          @formats.delete(format_key) if @formats[format_key] && @formats[format_key].empty?
+        end
+      end
+
+      # Get supported formats from a plugin
+      #
+      # @param plugin [Object] Plugin instance
+      # @return [Array<String>] Array of supported formats
+      def get_supported_formats(plugin)
+        return [] unless plugin.respond_to?(:supported_formats)
+
+        formats = plugin.supported_formats
+        Array(formats).map(&:to_s).map(&:downcase).uniq
+      rescue StandardError => e
+        log_registry_error('format_discovery_failed', e,
+                           plugin_class: plugin.class.name)
+        []
+      end
+
+      # Calculate average formats per plugin
+      #
+      # @return [Float] Average number of formats per plugin
+      def calculate_average_formats_per_plugin
+        return 0.0 if @plugins.empty?
+
+        total_formats = @plugins.values.sum { |config| config[:supported_formats].size }
+        (total_formats.to_f / @plugins.size).round(2)
+      end
+
+      # Find the most popular formats (top 5)
+      #
+      # @return [Array<Hash>] Array of format popularity data
+      def find_most_popular_formats
+        @formats
+          .map { |format, plugins| { format: format, plugin_count: plugins.size } }
+          .sort_by { |data| -data[:plugin_count] }
+          .first(5)
+      end
+
+      # Calculate plugin distribution statistics
+      #
+      # @return [Hash] Distribution statistics
+      def calculate_plugin_distribution
+        formats_per_plugin = @plugins.values.map { |config| config[:supported_formats].size }
+
+        return { distribution: 'empty' } if formats_per_plugin.empty?
+
+        {
+          distribution: calculate_distribution_type(formats_per_plugin),
+          average_formats_per_plugin: calculate_average_formats_per_plugin,
+          max_formats_per_plugin: formats_per_plugin.max,
+          min_formats_per_plugin: formats_per_plugin.min
+        }
+      end
+
+      # Calculate distribution type based on formats per plugin
+      #
+      # @param formats_per_plugin [Array<Integer>] Array of format counts
+      # @return [String] Distribution type
+      def calculate_distribution_type(formats_per_plugin)
+        return 'empty' if formats_per_plugin.empty?
+        return 'uniform' if formats_per_plugin.uniq.size == 1
+
+        avg = formats_per_plugin.sum.to_f / formats_per_plugin.size
+        variance = formats_per_plugin.sum { |count| (count - avg)**2 } / formats_per_plugin.size
+
+        variance < 2 ? 'even' : 'varied'
+      end
+    end
+  end
+end

data/lib/tasker/telemetry/plugins/base_exporter.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Telemetry
+    module Plugins
+      # Base class for telemetry export plugins
+      #
+      # Provides a standard interface and common functionality for all export plugins.
+      # Plugins should inherit from this class and implement the required methods.
+      #
+      # @example Creating a custom exporter
+      #   class MyCustomExporter < Tasker::Telemetry::Plugins::BaseExporter
+      #     def export(metrics_data, options = {})
+      #       # Implementation here
+      #       log_plugin_event(:info, "Custom export completed", metrics_count: metrics_data.size)
+      #     end
+      #
+      #     def supports_format?(format)
+      #       format.to_s == 'custom'
+      #     end
+      #
+      #     def supported_formats
+      #       ['custom']
+      #     end
+      #   end
+      class BaseExporter
+        include Tasker::Concerns::StructuredLogging
+
+        # Plugin metadata
+        attr_reader :name, :version, :description
+
+        def initialize(name: nil, version: '1.0.0', description: nil)
+          # Safe class name extraction for test environments where class.name might be nil
+          default_name = if self.class.name
+                           self.class.name.demodulize.underscore
+                         else
+                           'anonymous_exporter'
+                         end
+
+          @name = name || default_name
+          @version = version
+          @description = description || "#{@name} telemetry exporter"
+        end
+
+        # Export metrics data (must be implemented by subclasses)
+        #
+        # @param metrics_data [Hash] Metrics data to export
+        # @param options [Hash] Export options
+        # @return [Hash] Export result with :success, :format, :data keys
+        # @raise [NotImplementedError] If not implemented by subclass
+        def export(metrics_data, options = {})
+          raise NotImplementedError, "#{self.class.name} must implement #export method"
+        end
+
+        # Check if plugin supports a specific format (must be implemented by subclasses)
+        #
+        # @param format [String, Symbol] Format to check
+        # @return [Boolean] Whether format is supported
+        # @raise [NotImplementedError] If not implemented by subclass
+        def supports_format?(format)
+          raise NotImplementedError, "#{self.class.name} must implement #supports_format? method"
+        end
+
+        # Get supported formats (should be implemented by subclasses)
+        #
+        # @return [Array<String>] Supported export formats
+        def supported_formats
+          []
+        end
+
+        # Plugin lifecycle callbacks (optional overrides)
+
+        # Called when cache sync occurs
+        #
+        # @param sync_data [Hash] Cache sync information
+        def on_cache_sync(sync_data)
+          # Default: no action
+        end
+
+        # Called when export is requested
+        #
+        # @param request_data [Hash] Export request information
+        def on_export_request(request_data)
+          # Default: no action
+        end
+
+        # Called when export completes
+        #
+        # @param completion_data [Hash] Export completion information
+        def on_export_complete(completion_data)
+          # Default: no action
+        end
+
+        # Safe export wrapper with error handling and timing
+        #
+        # @param metrics_data [Hash] Metrics data to export
+        # @param options [Hash] Export options
+        # @return [Hash] Export result with success/error information
+        def safe_export(metrics_data, options = {})
+          start_time = Time.current
+
+          begin
+            # Validate metrics data structure
+            validate_metrics_data!(metrics_data) if respond_to?(:validate_metrics_data!, true)
+
+            result = export(metrics_data, options)
+
+            duration = ((Time.current - start_time) * 1000).round(2)
+
+            log_plugin_event(:info, 'Plugin export completed',
+                             metrics_count: metrics_data.size,
+                             duration_ms: duration,
+                             success: true)
+
+            {
+              success: true,
+              format: result[:format] || 'unknown',
+              data: result[:data],
+              result: result, # Include the full result for test compatibility
+              plugin: { name: @name, version: @version }, # Add plugin field for test compatibility
+              metrics_count: metrics_data.size,
+              duration_ms: duration,
+              plugin_name: @name,
+              plugin_version: @version
+            }
+          rescue StandardError => e
+            duration = ((Time.current - start_time) * 1000).round(2)
+
+            log_plugin_event(:error, 'Plugin export failed',
+                             metrics_count: metrics_data.size,
+                             duration_ms: duration,
+                             error: e.message,
+                             success: false)
+
+            {
+              success: false,
+              error: e.message,
+              metrics_count: metrics_data.size,
+              duration_ms: duration,
+              plugin_name: @name,
+              plugin_version: @version
+            }
+          end
+        end
+
+        # Get plugin metadata
+        #
+        # @return [Hash] Plugin metadata
+        def metadata
+          # Use class constants when available, otherwise use instance variables
+          version = if self.class.const_defined?(:VERSION)
+                      self.class.const_get(:VERSION)
+                    else
+                      @version == '1.0.0' ? 'unknown' : @version
+                    end
+
+          description = if self.class.const_defined?(:DESCRIPTION)
+                          self.class.const_get(:DESCRIPTION)
+                        else
+                          nil # Return nil when no DESCRIPTION constant is defined
+                        end
+
+          {
+            name: @name,
+            version: version,
+            description: description,
+            supported_formats: supported_formats,
+            class_name: self.class.name
+          }
+        end
+
+        # Alias for metadata (for test compatibility)
+        alias plugin_info metadata
+
+        private
+
+        # Validate metrics data structure
+        #
+        # @param metrics_data [Hash] Metrics data to validate
+        # @raise [ArgumentError] If data structure is invalid
+        def validate_metrics_data!(metrics_data)
+          raise ArgumentError, "Metrics data must be a Hash, got #{metrics_data.class}" unless metrics_data.is_a?(Hash)
+
+          raise ArgumentError, 'Metrics data must contain :metrics key' unless metrics_data.key?(:metrics)
+
+          return if metrics_data.key?(:timestamp)
+
+          raise ArgumentError, 'Metrics data must contain :timestamp key'
+        end
+
+        protected
+
+        # Structured logging helper for plugin events
+        #
+        # @param level [Symbol] Log level
+        # @param message [String] Log message
+        # @param context [Hash] Additional context
+        def log_plugin_event(level, message, **context)
+          # Safe class name extraction to avoid demodulize errors
+          class_name = self.class.name || 'AnonymousExporter'
+
+          log_structured(level, message,
+                         entity_type: 'telemetry_plugin',
+                         entity_id: @name,
+                         plugin_name: @name,
+                         plugin_version: @version,
+                         plugin_class: class_name,
+                         **context)
+        rescue StandardError => e
+          # Fallback logging if structured logging fails
+          Rails.logger.debug { "Structured logging failed: #{e.message}" }
+          Rails.logger.debug { "#{level.upcase}: #{message}" }
+        end
+
+        # Structured logging helper for plugin performance events
+        #
+        # @param operation [String] Operation name
+        # @param duration [Float] Duration in seconds
+        # @param context [Hash] Additional context
+        def log_plugin_performance(operation, duration, **context)
+          log_performance_event("plugin_#{operation}", duration,
+                                entity_type: 'telemetry_plugin',
+                                entity_id: @name,
+                                plugin_name: @name,
+                                plugin_version: @version,
+                                **context)
+        end
+
+        # Structured logging helper for plugin errors
+        #
+        # @param exception [Exception] Exception to log
+        # @param context [Hash] Additional context
+        def log_plugin_exception(exception, **context)
+          log_exception(exception,
+                        context: {
+                          entity_type: 'telemetry_plugin',
+                          entity_id: @name,
+                          plugin_name: @name,
+                          plugin_version: @version,
+                          **context
+                        })
+        end
+      end
+    end
+  end
+end