a2a-ruby 1.0.0

data/lib/a2a/plugin.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+##
+# Plugin architecture for extending A2A functionality
+#
+# Provides extension points for custom functionality including:
+# - Custom transport protocols
+# - Authentication strategies
+# - Request/response processing hooks
+# - Middleware components
+#
+# @example Register a plugin
+#   A2A::Plugin.register(:my_plugin, MyPlugin)
+#
+# @example Create a transport plugin
+#   class MyTransport < A2A::Plugin::Base
+#     plugin_type :transport
+#
+#     def send_request(request)
+#       # Custom transport implementation
+#     end
+#   end
+#
+module A2A
+  module Plugin
+    class << self
+      # Registry of all plugins
+      # @return [Hash<Symbol, Hash>]
+      attr_reader :registry
+
+      # Registered hooks
+      # @return [Hash<Symbol, Array>]
+      attr_reader :hooks
+
+      # Initialize plugin system
+      def initialize!
+        @registry = {}
+        @hooks = Hash.new { |h, k| h[k] = [] }
+        @loaded_plugins = Set.new
+      end
+
+      # Register a plugin
+      # @param name [Symbol] Plugin name
+      # @param plugin_class [Class] Plugin class
+      # @param **options [Hash] Plugin options
+      def register(name, plugin_class, **options)
+        initialize! unless @registry
+
+        unless plugin_class.respond_to?(:plugin_type)
+          raise A2A::Errors::PluginError, "Plugin class must include A2A::Plugin::Base"
+        end
+
+        @registry[name] = {
+          class: plugin_class,
+          type: plugin_class.plugin_type,
+          options: options,
+          loaded: false
+        }
+
+        A2A.config.logger&.info("Registered plugin: #{name} (#{plugin_class.plugin_type})")
+      end
+
+      # Load a plugin
+      # @param name [Symbol] Plugin name
+      # @param **config [Hash] Plugin configuration
+      # @return [Object] Plugin instance
+      def load(name, **config)
+        initialize! unless @registry
+
+        plugin_info = @registry[name]
+        raise A2A::Errors::PluginError, "Plugin not found: #{name}" unless plugin_info
+
+        return plugin_info[:instance] if plugin_info[:loaded]
+
+        begin
+          instance = plugin_info[:class].new(**config)
+          plugin_info[:instance] = instance
+          plugin_info[:loaded] = true
+          @loaded_plugins << name
+
+          # Register plugin hooks
+          instance.register_hooks(self) if instance.respond_to?(:register_hooks)
+
+          A2A.config.logger&.info("Loaded plugin: #{name}")
+          instance
+        rescue StandardError => e
+          raise A2A::Errors::PluginError, "Failed to load plugin #{name}: #{e.message}"
+        end
+      end
+
+      # Unload a plugin
+      # @param name [Symbol] Plugin name
+      def unload(name)
+        initialize! unless @registry
+
+        plugin_info = @registry[name]
+        return unless plugin_info && plugin_info[:loaded]
+
+        instance = plugin_info[:instance]
+
+        # Call cleanup if available
+        instance.cleanup if instance.respond_to?(:cleanup)
+
+        plugin_info[:loaded] = false
+        plugin_info[:instance] = nil
+        @loaded_plugins.delete(name)
+
+        A2A.config.logger&.info("Unloaded plugin: #{name}")
+      end
+
+      # Get loaded plugins by type
+      # @param type [Symbol] Plugin type
+      # @return [Array<Object>] Plugin instances
+      def loaded_plugins(type: nil)
+        initialize! unless @registry
+
+        plugins = @loaded_plugins.filter_map { |name| @registry[name][:instance] }
+
+        if type
+          plugins.select { |plugin| plugin.class.plugin_type == type }
+        else
+          plugins
+        end
+      end
+
+      # Register a hook
+      # @param event [Symbol] Hook event name
+      # @param callable [Proc, Method] Hook handler (optional if block given)
+      # @param priority [Integer] Hook priority (lower = higher priority)
+      def add_hook(event, callable = nil, priority: 50, &block)
+        initialize! unless @hooks
+
+        handler = callable || block
+        raise ArgumentError, "Must provide callable or block" unless handler
+
+        @hooks[event] << { callable: handler, priority: priority }
+        @hooks[event].sort_by! { |hook| hook[:priority] }
+      end
+
+      # Execute hooks for an event
+      # @param event [Symbol] Hook event name
+      # @param *args [Array] Arguments to pass to hooks
+      # @return [Array] Results from all hooks
+      def execute_hooks(event, *args)
+        initialize! unless @hooks
+
+        results = []
+        @hooks[event].each do |hook|
+          result = hook[:callable].call(*args)
+          results << result
+        rescue StandardError => e
+          A2A.config.logger&.error("Hook execution failed for #{event}: #{e.message}")
+          raise A2A::Errors::PluginError, "Hook execution failed: #{e.message}"
+        end
+        results
+      end
+
+      # Check if a plugin is loaded
+      # @param name [Symbol] Plugin name
+      # @return [Boolean]
+      def loaded?(name)
+        initialize! unless @registry
+        @loaded_plugins.include?(name)
+      end
+
+      # List all registered plugins
+      # @return [Hash] Plugin registry information
+      def list
+        initialize! unless @registry
+
+        @registry.transform_values do |info|
+          {
+            type: info[:type],
+            loaded: info[:loaded],
+            options: info[:options]
+          }
+        end
+      end
+
+      # Clear all plugins (for testing)
+      def clear!
+        @loaded_plugins&.each { |name| unload(name) }
+        @registry&.clear
+        @hooks&.clear
+        initialize!
+      end
+    end
+
+    ##
+    # Base class for all A2A plugins
+    #
+    class Base
+      class << self
+        # Define plugin type
+        # @param type [Symbol] Plugin type
+        def plugin_type(type = nil)
+          if type
+            @plugin_type = type
+          else
+            @plugin_type || (superclass.respond_to?(:plugin_type) ? superclass.plugin_type : nil)
+          end
+        end
+
+        # Define plugin dependencies
+        # @param *deps [Array<Symbol>] Plugin dependencies
+        def depends_on(*deps)
+          @dependencies = deps
+        end
+
+        # Get plugin dependencies
+        # @return [Array<Symbol>]
+        def dependencies
+          @dependencies || []
+        end
+
+        # Inherited hook to ensure plugin types are properly inherited
+        def inherited(subclass)
+          super
+          # Ensure subclass inherits plugin type if not explicitly set
+          return unless @plugin_type && !subclass.instance_variable_defined?(:@plugin_type)
+
+          subclass.instance_variable_set(:@plugin_type, @plugin_type)
+        end
+      end
+
+      # Initialize plugin
+      # @param **config [Hash] Plugin configuration
+      def initialize(**config)
+        @config = config
+        @logger = A2A.config.logger
+        setup if respond_to?(:setup, true)
+      end
+
+      # Get plugin configuration
+      # @return [Hash]
+      attr_reader :config
+
+      # Get logger instance
+      # @return [Logger]
+      attr_reader :logger
+
+      # Register hooks (override in subclasses)
+      # @param plugin_manager [A2A::Plugin] Plugin manager
+      def register_hooks(plugin_manager)
+        # Override in subclasses to register hooks
+      end
+
+      # Cleanup resources (override in subclasses)
+      def cleanup
+        # Override in subclasses for cleanup
+      end
+    end
+
+    ##
+    # Transport plugin interface
+    #
+    class TransportPlugin < A2A::Plugin::Base
+      plugin_type :transport
+
+      # Send a request (must be implemented by subclasses)
+      # @param request [Hash] Request data
+      # @param **options [Hash] Transport options
+      # @return [Object] Response
+      def send_request(request, **options)
+        raise NotImplementedError, "Transport plugins must implement #send_request"
+      end
+
+      # Check if transport supports streaming
+      # @return [Boolean]
+      def supports_streaming?
+        false
+      end
+
+      # Create streaming connection (optional)
+      # @param **options [Hash] Connection options
+      # @return [Object] Stream connection
+      def create_stream(**options)
+        raise NotImplementedError, "Streaming not supported by this transport"
+      end
+    end
+
+    ##
+    # Authentication plugin interface
+    #
+    class AuthPlugin < A2A::Plugin::Base
+      plugin_type :auth
+
+      # Authenticate a request (must be implemented by subclasses)
+      # @param request [Hash] Request data
+      # @param **options [Hash] Authentication options
+      # @return [Hash] Authenticated request
+      def authenticate_request(request, **options)
+        raise NotImplementedError, "Auth plugins must implement #authenticate_request"
+      end
+
+      # Validate authentication (optional)
+      # @param credentials [Object] Credentials to validate
+      # @return [Boolean] Whether credentials are valid
+      def validate_credentials(_credentials)
+        true
+      end
+    end
+
+    ##
+    # Middleware plugin interface
+    #
+    class MiddlewarePlugin < A2A::Plugin::Base
+      plugin_type :middleware
+
+      # Process request (must be implemented by subclasses)
+      # @param request [Hash] Request data
+      # @param next_middleware [Proc] Next middleware in chain
+      # @return [Object] Response
+      def call(request, next_middleware)
+        raise NotImplementedError, "Middleware plugins must implement #call"
+      end
+    end
+
+    ##
+    # Hook events for plugin system
+    #
+    module Events
+      # Request processing hooks
+      BEFORE_REQUEST = :before_request
+      AFTER_REQUEST = :after_request
+      REQUEST_ERROR = :request_error
+
+      # Response processing hooks
+      BEFORE_RESPONSE = :before_response
+      AFTER_RESPONSE = :after_response
+      RESPONSE_ERROR = :response_error
+
+      # Task lifecycle hooks
+      TASK_CREATED = :task_created
+      TASK_UPDATED = :task_updated
+      TASK_COMPLETED = :task_completed
+      TASK_FAILED = :task_failed
+
+      # Agent card hooks
+      AGENT_CARD_GENERATED = :agent_card_generated
+      AGENT_CARD_REQUESTED = :agent_card_requested
+
+      # All available events
+      ALL = constants.map { |const| const_get(const) }.freeze
+    end
+  end
+end
+
+# Add plugin error to errors module
+##
+# Plugin-related errors
+#
+module A2A
+  module Errors
+    class PluginError < A2A::Errors::A2AError
+    end
+  end
+end

data/lib/a2a/plugin_manager.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "plugin"
+
+##
+# Plugin manager for loading and managing A2A plugins
+#
+# Handles plugin lifecycle, dependency resolution, and integration
+# with the A2A framework components.
+#
+module A2A
+  class PluginManager
+    # Initialize plugin manager
+    # @param config [A2A::Configuration] Configuration instance
+    def initialize(config = A2A.config)
+      @config = config
+      @logger = config.logger
+      @auto_load_plugins = []
+      @plugin_configs = {}
+    end
+
+    # Configure auto-loading plugins
+    # @param plugins [Hash<Symbol, Hash>] Plugin configurations
+    def configure_plugins(plugins)
+      @plugin_configs = plugins
+
+      plugins.each do |name, plugin_config|
+        @auto_load_plugins << name if plugin_config[:auto_load]
+      end
+    end
+
+    # Load all configured plugins
+    def load_all_plugins
+      @auto_load_plugins.each do |plugin_name|
+        load_plugin(plugin_name)
+      end
+    end
+
+    # Load a specific plugin
+    # @param name [Symbol] Plugin name
+    # @param **config [Hash] Plugin configuration override
+    def load_plugin(name, **config)
+      plugin_config = @plugin_configs[name] || {}
+      merged_config = plugin_config.merge(config)
+
+      # Load dependencies first
+      if A2A::Plugin.registry[name]
+        dependencies = A2A::Plugin.registry[name][:class].dependencies
+        dependencies.each do |dep|
+          load_plugin(dep) unless A2A::Plugin.loaded?(dep)
+        end
+      end
+
+      A2A::Plugin.load(name, **merged_config)
+    rescue A2A::Errors::PluginError => e
+      @logger&.error("Failed to load plugin #{name}: #{e.message}")
+      raise
+    end
+
+    # Unload a plugin
+    # @param name [Symbol] Plugin name
+    def unload_plugin(name)
+      A2A::Plugin.unload(name)
+    end
+
+    # Get transport plugins
+    # @return [Array<A2A::Plugin::TransportPlugin>]
+    def transport_plugins
+      A2A::Plugin.loaded_plugins(type: :transport)
+    end
+
+    # Get authentication plugins
+    # @return [Array<A2A::Plugin::AuthPlugin>]
+    def auth_plugins
+      A2A::Plugin.loaded_plugins(type: :auth)
+    end
+
+    # Get middleware plugins
+    # @return [Array<A2A::Plugin::MiddlewarePlugin>]
+    def middleware_plugins
+      A2A::Plugin.loaded_plugins(type: :middleware)
+    end
+
+    # Find transport plugin by name
+    # @param transport_name [String] Transport protocol name
+    # @return [A2A::Plugin::TransportPlugin, nil]
+    def find_transport(transport_name)
+      transport_plugins.find do |plugin|
+        plugin.respond_to?(:transport_name) &&
+          plugin.transport_name == transport_name
+      end
+    end
+
+    # Find auth plugin by name
+    # @param auth_name [String] Authentication strategy name
+    # @return [A2A::Plugin::AuthPlugin, nil]
+    def find_auth_strategy(auth_name)
+      auth_plugins.find do |plugin|
+        plugin.respond_to?(:strategy_name) &&
+          plugin.strategy_name == auth_name
+      end
+    end
+
+    # Execute request hooks
+    # @param event [Symbol] Hook event
+    # @param request [Hash] Request data
+    # @return [Hash] Modified request
+    def execute_request_hooks(event, request)
+      results = A2A::Plugin.execute_hooks(event, request)
+
+      # Apply modifications from hooks
+      results.each do |result|
+        request.merge!(result) if result.is_a?(Hash)
+      end
+
+      request
+    end
+
+    # Execute response hooks
+    # @param event [Symbol] Hook event
+    # @param response [Object] Response data
+    # @param request [Hash] Original request
+    # @return [Object] Modified response
+    def execute_response_hooks(event, response, request = nil)
+      results = A2A::Plugin.execute_hooks(event, response, request)
+
+      # Return last non-nil result or original response
+      results.reverse.find { |result| !result.nil? } || response
+    end
+
+    # Create middleware chain from plugins
+    # @return [Array<Proc>] Middleware chain
+    def build_middleware_chain
+      middleware_plugins.map do |plugin|
+        proc { |request, next_middleware| plugin.call(request, next_middleware) }
+      end
+    end
+
+    # Get plugin status
+    # @return [Hash] Plugin status information
+    def status
+      {
+        loaded_plugins: A2A::Plugin.loaded_plugins.size,
+        registered_plugins: A2A::Plugin.registry.size,
+        plugins_by_type: {
+          transport: transport_plugins.size,
+          auth: auth_plugins.size,
+          middleware: middleware_plugins.size
+        },
+        auto_load_plugins: @auto_load_plugins,
+        plugin_list: A2A::Plugin.list
+      }
+    end
+
+    private
+
+    attr_reader :config, :logger
+  end
+end

data/lib/a2a/plugins/example_auth.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+##
+# Example custom authentication plugin
+#
+# Demonstrates how to create a custom authentication plugin
+# for the A2A plugin architecture.
+#
+module A2A
+  module Plugins
+    class ExampleAuth < A2A::Plugin::AuthPlugin
+      # Authentication strategy name
+      def strategy_name
+        "example"
+      end
+
+      # Authenticate request
+      # @param request [Hash] Request data
+      # @param **options [Hash] Authentication options
+      # @return [Hash] Authenticated request
+      def authenticate_request(request, **options)
+        logger&.info("Authenticating request with Example Auth")
+
+        # Add custom authentication header
+        request[:headers] ||= {}
+        request[:headers]["X-Example-Auth"] = generate_token(options)
+
+        request
+      end
+
+      # Validate credentials
+      # @param credentials [Hash] Credentials to validate
+      # @return [Boolean] Whether credentials are valid
+      def validate_credentials(credentials)
+        return false unless credentials.is_a?(Hash)
+        return false unless credentials[:api_key]
+
+        # Simple validation - in real implementation, validate against backend
+        credentials[:api_key].start_with?("example_")
+      end
+
+      # Register hooks for this plugin
+      def register_hooks(plugin_manager)
+        plugin_manager.add_hook(A2A::Plugin::Events::BEFORE_REQUEST) do |request|
+          logger&.debug("Example Auth: Validating request authentication")
+
+          # Add request timestamp for security
+          request[:auth_timestamp] = Time.now.to_i
+        end
+
+        plugin_manager.add_hook(A2A::Plugin::Events::REQUEST_ERROR) do |error, request|
+          if error.is_a?(A2A::Errors::AuthenticationError)
+            logger&.warn("Example Auth: Authentication failed for request #{request[:id]}")
+          end
+        end
+      end
+
+      private
+
+      def setup
+        @secret_key = config[:secret_key] || "default_secret"
+        logger&.info("Example Auth plugin initialized")
+      end
+
+      def cleanup
+        @secret_key = nil
+        logger&.info("Example Auth plugin cleaned up")
+      end
+
+      def generate_token(options)
+        # Simple token generation - in real implementation, use proper JWT or similar
+        payload = {
+          timestamp: Time.now.to_i,
+          client_id: options[:client_id] || "unknown"
+        }
+
+        Base64.encode64("#{payload.to_json}:#{@secret_key}").strip
+      end
+    end
+  end
+end

data/lib/a2a/plugins/example_middleware.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+##
+# Example custom middleware plugin
+#
+# Demonstrates how to create a custom middleware plugin
+# for the A2A plugin architecture.
+#
+module A2A
+  module Plugins
+    class ExampleMiddleware < A2A::Plugin::MiddlewarePlugin
+      # Middleware name for identification
+      def middleware_name
+        "example"
+      end
+
+      # Process request through middleware
+      # @param request [Hash] Request data
+      # @param next_middleware [Proc] Next middleware in chain
+      # @return [Object] Response
+      def call(request, next_middleware)
+        start_time = Time.now
+
+        logger&.info("Example Middleware: Processing request #{request[:id]}")
+
+        # Pre-processing
+        request = preprocess_request(request)
+
+        begin
+          # Call next middleware in chain
+          response = next_middleware.call(request)
+
+          # Post-processing
+          response = postprocess_response(response, request)
+
+          # Log success
+          duration = Time.now - start_time
+          logger&.info("Example Middleware: Request completed in #{duration.round(3)}s")
+
+          response
+        rescue StandardError => e
+          # Error handling
+          duration = Time.now - start_time
+          logger&.error("Example Middleware: Request failed after #{duration.round(3)}s: #{e.message}")
+
+          # Execute error hooks
+          A2A::Plugin.execute_hooks(A2A::Plugin::Events::REQUEST_ERROR, e, request)
+
+          raise
+        end
+      end
+
+      # Register hooks for this plugin
+      def register_hooks(plugin_manager)
+        plugin_manager.add_hook(A2A::Plugin::Events::BEFORE_REQUEST, priority: 10) do |request|
+          logger&.debug("Example Middleware: Adding request metadata")
+          request[:middleware_metadata] ||= {}
+          request[:middleware_metadata][:example] = {
+            processed_at: Time.now.iso8601,
+            version: "1.0.0"
+          }
+        end
+      end
+
+      private
+
+      def setup
+        @request_counter = 0
+        @error_counter = 0
+        logger&.info("Example Middleware plugin initialized")
+      end
+
+      def cleanup
+        logger&.info("Example Middleware plugin cleaned up (processed #{@request_counter} requests, #{@error_counter} errors)")
+      end
+
+      def preprocess_request(request)
+        @request_counter += 1
+
+        # Add request ID if not present
+        request[:id] ||= SecureRandom.uuid
+
+        # Add processing metadata
+        request[:processing] ||= {}
+        request[:processing][:middleware_start] = Time.now.to_f
+
+        # Validate request structure
+        validate_request_structure(request)
+
+        request
+      end
+
+      def postprocess_response(response, request)
+        # Add processing time to response metadata
+        if request[:processing] && request[:processing][:middleware_start]
+          processing_time = Time.now.to_f - request[:processing][:middleware_start]
+
+          if response.is_a?(Hash)
+            response[:metadata] ||= {}
+            response[:metadata][:processing_time] = processing_time
+          end
+        end
+
+        response
+      end
+
+      def validate_request_structure(request)
+        raise A2A::Errors::InvalidRequest, "Request must be a hash" unless request.is_a?(Hash)
+
+        return if request[:method]
+
+        raise A2A::Errors::InvalidRequest, "Request must have a method"
+
+        # Additional validation can be added here
+      end
+    end
+  end
+end