a2a-ruby 1.0.0

data/lib/a2a/client/auth.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "auth/oauth2"
+require_relative "auth/jwt"
+require_relative "auth/api_key"
+require_relative "auth/interceptor"
+
+##
+# Authentication strategies and utilities for A2A clients
+#
+# This module provides various authentication mechanisms for communicating
+# with A2A agents, including OAuth 2.0, JWT, and API key authentication.
+#
+# @example OAuth 2.0 authentication
+#   oauth = A2A::Client::Auth::OAuth2.new(
+#     client_id: 'your-client-id',
+#     client_secret: 'your-client-secret',
+#     token_url: 'https://auth.example.com/oauth/token'
+#   )
+#
+#   client = A2A::Client::HttpClient.new(
+#     'https://agent.example.com',
+#     middleware: [A2A::Client::Auth::Interceptor.new(oauth)]
+#   )
+#
+# @example JWT authentication
+#   jwt = A2A::Client::Auth::JWT.new(
+#     token: 'your-jwt-token'
+#   )
+#
+#   interceptor = A2A::Client::Auth::Interceptor.new(jwt)
+#
+# @example API key authentication
+#   api_key = A2A::Client::Auth::ApiKey.new(
+#     key: 'your-api-key',
+#     name: 'X-API-Key',
+#     location: 'header'
+#   )
+#
+#   interceptor = A2A::Client::Auth::Interceptor.new(api_key)
+#
+module A2A
+  module Client
+    module Auth
+      ##
+      # Create authentication strategy from configuration
+      #
+      # @param config [Hash] Authentication configuration
+      # @return [Object] Authentication strategy instance
+      def self.from_config(config)
+        case config["type"] || config[:type]
+        when "oauth2"
+          OAuth2.new(
+            client_id: config["client_id"] || config[:client_id],
+            client_secret: config["client_secret"] || config[:client_secret],
+            token_url: config["token_url"] || config[:token_url],
+            scope: config["scope"] || config[:scope]
+          )
+        when "jwt"
+          JWT.new(
+            token: config["token"] || config[:token],
+            secret: config["secret"] || config[:secret],
+            algorithm: config["algorithm"] || config[:algorithm] || "HS256",
+            payload: config["payload"] || config[:payload],
+            headers: config["headers"] || config[:headers],
+            expires_in: config["expires_in"] || config[:expires_in]
+          )
+        when "api_key"
+          ApiKey.new(
+            key: config["key"] || config[:key],
+            name: config["name"] || config[:name] || "X-API-Key",
+            location: config["location"] || config[:location] || "header"
+          )
+        else
+          raise ArgumentError, "Unknown authentication type: #{config['type'] || config[:type]}"
+        end
+      end
+
+      ##
+      # Create authentication strategy from security scheme
+      #
+      # @param scheme [Hash] Security scheme definition from agent card
+      # @param credentials [Hash] Authentication credentials
+      # @return [Object] Authentication strategy instance
+      def self.from_security_scheme(scheme, credentials)
+        case scheme["type"]
+        when "oauth2"
+          OAuth2.new(
+            client_id: credentials["client_id"],
+            client_secret: credentials["client_secret"],
+            token_url: scheme["tokenUrl"],
+            scope: credentials["scope"]
+          )
+        when "http"
+          case scheme["scheme"]
+          when "bearer"
+            JWT.new(token: credentials["token"])
+          when "basic"
+            # Basic auth configuration
+            {
+              type: "basic",
+              username: credentials["username"],
+              password: credentials["password"]
+            }
+          else
+            raise ArgumentError, "Unsupported HTTP scheme: #{scheme['scheme']}"
+          end
+        when "apiKey"
+          ApiKey.from_security_scheme(scheme, credentials["key"])
+        else
+          raise ArgumentError, "Unsupported security scheme type: #{scheme['type']}"
+        end
+      end
+
+      ##
+      # Create interceptor from configuration
+      #
+      # @param config [Hash] Authentication configuration
+      # @return [Interceptor] Configured authentication interceptor
+      def self.interceptor_from_config(config)
+        strategy = from_config(config)
+        Interceptor.new(strategy, auto_retry: config["auto_retry"] || config[:auto_retry] || true)
+      end
+
+      ##
+      # Create interceptor from security scheme
+      #
+      # @param scheme [Hash] Security scheme definition
+      # @param credentials [Hash] Authentication credentials
+      # @return [Interceptor] Configured authentication interceptor
+      def self.interceptor_from_security_scheme(scheme, credentials)
+        strategy = from_security_scheme(scheme, credentials)
+        Interceptor.new(strategy)
+      end
+    end
+  end
+end

data/lib/a2a/client/base.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+##
+# Abstract base class for A2A clients
+#
+# Provides the common interface and functionality for all A2A client implementations.
+# Concrete clients should inherit from this class and implement the abstract methods.
+#
+module A2A
+  module Client
+    class Base
+      attr_reader :config, :middleware, :consumers
+
+      ##
+      # Initialize a new client
+      #
+      # @param config [Config, nil] Client configuration
+      # @param middleware [Array] List of middleware interceptors
+      # @param consumers [Array] List of event consumers
+      def initialize(config: nil, middleware: [], consumers: [])
+        @config = config || Config.new
+        @middleware = middleware.dup
+        @consumers = consumers.dup
+        @task_callbacks = {}
+      end
+
+      ##
+      # Send a message to the agent
+      #
+      # @param message [Message, Hash] The message to send
+      # @param context [Hash, nil] Optional context information
+      # @return [Enumerator, Message] Stream of responses or single response
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def send_message(message, context: nil)
+        raise NotImplementedError, "#{self.class}#send_message must be implemented"
+      end
+
+      ##
+      # Get a task by ID
+      #
+      # @param task_id [String] The task ID
+      # @param context [Hash, nil] Optional context information
+      # @param history_length [Integer, nil] Maximum number of history messages to include
+      # @return [Task] The task
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def get_task(task_id, context: nil, history_length: nil)
+        raise NotImplementedError, "#{self.class}#get_task must be implemented"
+      end
+
+      ##
+      # Cancel a task
+      #
+      # @param task_id [String] The task ID to cancel
+      # @param context [Hash, nil] Optional context information
+      # @return [Task] The updated task
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def cancel_task(task_id, context: nil)
+        raise NotImplementedError, "#{self.class}#cancel_task must be implemented"
+      end
+
+      ##
+      # Get the agent card
+      #
+      # @param context [Hash, nil] Optional context information
+      # @param authenticated [Boolean] Whether to get authenticated extended card
+      # @return [AgentCard] The agent card
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def get_card(context: nil, authenticated: false)
+        raise NotImplementedError, "#{self.class}#get_card must be implemented"
+      end
+
+      ##
+      # Resubscribe to a task for streaming updates
+      #
+      # @param task_id [String] The task ID to resubscribe to
+      # @param context [Hash, nil] Optional context information
+      # @return [Enumerator] Stream of task updates
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def resubscribe(task_id, context: nil)
+        raise NotImplementedError, "#{self.class}#resubscribe must be implemented"
+      end
+
+      ##
+      # Set a callback for task updates
+      #
+      # @param task_id [String] The task ID
+      # @param push_notification_config [PushNotificationConfig, Hash] The push notification configuration
+      # @param context [Hash, nil] Optional context information
+      # @return [void]
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def set_task_callback(task_id, push_notification_config, context: nil)
+        raise NotImplementedError, "#{self.class}#set_task_callback must be implemented"
+      end
+
+      ##
+      # Get the callback configuration for a task
+      #
+      # @param task_id [String] The task ID
+      # @param push_notification_config_id [String] The push notification config ID
+      # @param context [Hash, nil] Optional context information
+      # @return [TaskPushNotificationConfig] The callback configuration
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def get_task_callback(task_id, push_notification_config_id, context: nil)
+        raise NotImplementedError, "#{self.class}#get_task_callback must be implemented"
+      end
+
+      ##
+      # List all callback configurations for a task
+      #
+      # @param task_id [String] The task ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Array<TaskPushNotificationConfig>] List of callback configurations
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def list_task_callbacks(task_id, context: nil)
+        raise NotImplementedError, "#{self.class}#list_task_callbacks must be implemented"
+      end
+
+      ##
+      # Delete a callback configuration for a task
+      #
+      # @param task_id [String] The task ID
+      # @param push_notification_config_id [String] The push notification config ID
+      # @param context [Hash, nil] Optional context information
+      # @return [void]
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def delete_task_callback(task_id, push_notification_config_id, context: nil)
+        raise NotImplementedError, "#{self.class}#delete_task_callback must be implemented"
+      end
+
+      ##
+      # Add middleware to the client
+      #
+      # @param interceptor [Object] The middleware interceptor
+      # @return [void]
+      def add_middleware(interceptor)
+        @middleware << interceptor
+      end
+
+      ##
+      # Remove middleware from the client
+      #
+      # @param interceptor [Object] The middleware interceptor to remove
+      # @return [void]
+      def remove_middleware(interceptor)
+        @middleware.delete(interceptor)
+      end
+
+      ##
+      # Add an event consumer
+      #
+      # @param consumer [Object] The event consumer
+      # @return [void]
+      def add_consumer(consumer)
+        @consumers << consumer
+      end
+
+      ##
+      # Remove an event consumer
+      #
+      # @param consumer [Object] The event consumer to remove
+      # @return [void]
+      def remove_consumer(consumer)
+        @consumers.delete(consumer)
+      end
+
+      ##
+      # Check if the client supports streaming
+      #
+      # @return [Boolean] True if streaming is supported and enabled
+      def streaming?
+        @config.streaming?
+      end
+
+      ##
+      # Check if the client supports polling
+      #
+      # @return [Boolean] True if polling is supported and enabled
+      def polling?
+        @config.polling?
+      end
+
+      ##
+      # Get the supported transports
+      #
+      # @return [Array<String>] List of supported transport protocols
+      def supported_transports
+        @config.supported_transports
+      end
+
+      ##
+      # Negotiate transport with agent card
+      #
+      # @param agent_card [AgentCard] The agent card
+      # @return [String] The negotiated transport protocol
+      def negotiate_transport(agent_card)
+        # Use client preference if enabled
+        if @config.use_client_preference?
+          preferred = @config.preferred_transport
+          return preferred if agent_supports_transport?(agent_card, preferred)
+        end
+
+        # Find first mutually supported transport
+        @config.supported_transports.each do |transport|
+          return transport if agent_supports_transport?(agent_card, transport)
+        end
+
+        # Fallback to agent's preferred transport if we support it
+        agent_preferred = agent_card.preferred_transport
+        return agent_preferred if @config.supports_transport?(agent_preferred)
+
+        # No compatible transport found
+        raise A2A::Errors::ClientError, "No compatible transport protocol found"
+      end
+
+      ##
+      # Get the endpoint URL for a specific transport
+      #
+      # @param agent_card [AgentCard] The agent card
+      # @param transport [String] The transport protocol
+      # @return [String] The endpoint URL
+      def get_endpoint_url(agent_card, transport)
+        # Check if the transport matches the preferred transport
+        return agent_card.url if agent_card.preferred_transport == transport
+
+        # Look for the transport in additional interfaces
+        interface = agent_card.additional_interfaces&.find { |iface| iface.transport == transport }
+        return interface.url if interface
+
+        # Fallback to main URL if no specific interface found
+        agent_card.url
+      end
+
+      protected
+
+      ##
+      # Execute middleware chain for a request
+      #
+      # @param request [Object] The request object
+      # @param context [Hash] The request context
+      # @yield [request, context] The block to execute after middleware
+      # @return [Object] The result of the block execution
+      def execute_with_middleware(request, context = {}, &block)
+        # Create a chain of middleware calls
+        chain = @middleware.reverse.reduce(proc(&block)) do |next_call, middleware|
+          proc { |req, ctx| middleware.call(req, ctx, next_call) }
+        end
+
+        # Execute the chain
+        chain.call(request, context)
+      end
+
+      ##
+      # Process events with registered consumers
+      #
+      # @param event [Object] The event to process
+      # @return [void]
+      def process_event(event)
+        @consumers.each do |consumer|
+          consumer.call(event)
+        rescue StandardError => e
+          # Log error but don't fail the entire processing
+          warn "Error in event consumer: #{e.message}"
+        end
+      end
+
+      ##
+      # Convert a message hash or object to a Message instance
+      #
+      # @param message [Message, Hash] The message to convert
+      # @return [Message] The message instance
+      def ensure_message(message)
+        return message if message.is_a?(A2A::Types::Message)
+
+        A2A::Types::Message.from_h(message)
+      end
+
+      ##
+      # Convert a task hash or object to a Task instance
+      #
+      # @param task [Task, Hash] The task to convert
+      # @return [Task] The task instance
+      def ensure_task(task)
+        return task if task.is_a?(A2A::Types::Task)
+
+        A2A::Types::Task.from_h(task)
+      end
+
+      ##
+      # Convert an agent card hash or object to an AgentCard instance
+      #
+      # @param agent_card [AgentCard, Hash] The agent card to convert
+      # @return [AgentCard] The agent card instance
+      def ensure_agent_card(agent_card)
+        return agent_card if agent_card.is_a?(A2A::Types::AgentCard)
+
+        A2A::Types::AgentCard.from_h(agent_card)
+      end
+
+      private
+
+      ##
+      # Check if an agent supports a specific transport
+      #
+      # @param agent_card [AgentCard] The agent card
+      # @param transport [String] The transport to check
+      # @return [Boolean] True if the agent supports the transport
+      def agent_supports_transport?(agent_card, transport)
+        return true if agent_card.preferred_transport == transport
+
+        agent_card.additional_interfaces&.any? { |iface| iface.transport == transport }
+      end
+    end
+  end
+end

data/lib/a2a/client/config.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+
+##
+# Configuration class for A2A clients
+#
+# Manages client behavior including transport preferences, streaming options,
+# authentication settings, and operational parameters.
+#
+module A2A
+  module Client
+    class Config
+      attr_accessor :streaming, :polling, :supported_transports, :use_client_preference,
+                    :accepted_output_modes, :push_notification_configs, :timeout,
+                    :retry_attempts, :retry_delay, :max_retry_delay, :backoff_multiplier,
+                    :endpoint_url, :authentication, :headers, :user_agent
+
+      ##
+      # Initialize a new client configuration
+      #
+      # @param streaming [Boolean] Enable streaming responses (default: true)
+      # @param polling [Boolean] Enable polling for task updates (default: false)
+      # @param supported_transports [Array<String>] Supported transport protocols
+      # @param use_client_preference [Boolean] Use client transport preference (default: true)
+      # @param accepted_output_modes [Array<String>] Accepted output modes
+      # @param push_notification_configs [Array<Hash>] Push notification configurations
+      # @param timeout [Integer] Request timeout in seconds (default: 30)
+      # @param retry_attempts [Integer] Number of retry attempts (default: 3)
+      # @param retry_delay [Float] Initial retry delay in seconds (default: 1.0)
+      # @param max_retry_delay [Float] Maximum retry delay in seconds (default: 60.0)
+      # @param backoff_multiplier [Float] Backoff multiplier for retries (default: 2.0)
+      # @param endpoint_url [String] Base endpoint URL
+      # @param authentication [Hash] Authentication configuration
+      # @param headers [Hash] Additional HTTP headers
+      # @param user_agent [String] User agent string
+      def initialize(streaming: true, polling: false, supported_transports: nil,
+                     use_client_preference: true, accepted_output_modes: nil,
+                     push_notification_configs: nil, timeout: 30, retry_attempts: 3,
+                     retry_delay: 1.0, max_retry_delay: 60.0, backoff_multiplier: 2.0,
+                     endpoint_url: nil, authentication: nil, headers: nil, user_agent: nil)
+        @streaming = streaming
+        @polling = polling
+        @supported_transports = supported_transports || [A2A::Types::TRANSPORT_JSONRPC]
+        @use_client_preference = use_client_preference
+        @accepted_output_modes = accepted_output_modes || %w[text file data]
+        @push_notification_configs = push_notification_configs || []
+        @timeout = timeout
+        @retry_attempts = retry_attempts
+        @retry_delay = retry_delay
+        @max_retry_delay = max_retry_delay
+        @backoff_multiplier = backoff_multiplier
+        @endpoint_url = endpoint_url
+        @authentication = authentication || {}
+        @headers = headers || {}
+        @user_agent = user_agent || "a2a-ruby/#{A2A::VERSION}"
+
+        validate!
+      end
+
+      ##
+      # Check if streaming is enabled
+      #
+      # @return [Boolean] True if streaming is enabled
+      def streaming?
+        @streaming
+      end
+
+      ##
+      # Check if polling is enabled
+      #
+      # @return [Boolean] True if polling is enabled
+      def polling?
+        @polling
+      end
+
+      ##
+      # Check if client preference should be used for transport negotiation
+      #
+      # @return [Boolean] True if client preference should be used
+      def use_client_preference?
+        @use_client_preference
+      end
+
+      ##
+      # Get the preferred transport protocol
+      #
+      # @return [String] The preferred transport protocol
+      def preferred_transport
+        @supported_transports.first
+      end
+
+      ##
+      # Check if a transport is supported
+      #
+      # @param transport [String] The transport to check
+      # @return [Boolean] True if the transport is supported
+      def supports_transport?(transport)
+        @supported_transports.include?(transport)
+      end
+
+      ##
+      # Add a supported transport
+      #
+      # @param transport [String] The transport to add
+      def add_transport(transport)
+        @supported_transports << transport unless @supported_transports.include?(transport)
+      end
+
+      ##
+      # Remove a supported transport
+      #
+      # @param transport [String] The transport to remove
+      def remove_transport(transport)
+        @supported_transports.delete(transport)
+      end
+
+      ##
+      # Get authentication configuration for a specific type
+      #
+      # @param type [String] The authentication type
+      # @return [Hash, nil] The authentication configuration
+      def auth_config(type)
+        @authentication[type]
+      end
+
+      ##
+      # Set authentication configuration
+      #
+      # @param type [String] The authentication type
+      # @param config [Hash] The authentication configuration
+      def set_auth_config(type, config)
+        @authentication[type] = config
+      end
+
+      ##
+      # Get all HTTP headers including authentication headers
+      #
+      # @return [Hash] All HTTP headers
+      def all_headers
+        auth_headers = build_auth_headers
+        @headers.merge(auth_headers)
+      end
+
+      ##
+      # Create a copy of the configuration
+      #
+      # @return [Config] A new configuration instance
+      def dup
+        self.class.new(
+          streaming: @streaming,
+          polling: @polling,
+          supported_transports: @supported_transports.dup,
+          use_client_preference: @use_client_preference,
+          accepted_output_modes: @accepted_output_modes.dup,
+          push_notification_configs: @push_notification_configs.dup,
+          timeout: @timeout,
+          retry_attempts: @retry_attempts,
+          retry_delay: @retry_delay,
+          max_retry_delay: @max_retry_delay,
+          backoff_multiplier: @backoff_multiplier,
+          endpoint_url: @endpoint_url,
+          authentication: @authentication.dup,
+          headers: @headers.dup,
+          user_agent: @user_agent
+        )
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "timeout must be positive" if @timeout <= 0
+        raise ArgumentError, "retry_attempts must be non-negative" if @retry_attempts.negative?
+        raise ArgumentError, "retry_delay must be positive" if @retry_delay <= 0
+        raise ArgumentError, "max_retry_delay must be positive" if @max_retry_delay <= 0
+        raise ArgumentError, "backoff_multiplier must be positive" if @backoff_multiplier <= 0
+
+        @supported_transports.each do |transport|
+          raise ArgumentError, "unsupported transport: #{transport}" unless A2A::Types::VALID_TRANSPORTS.include?(transport)
+        end
+      end
+
+      def build_auth_headers
+        headers = {}
+
+        # Add API key authentication
+        if (api_key_config = @authentication["api_key"])
+          case api_key_config["in"]
+          when "header"
+            headers[api_key_config["name"]] = api_key_config["value"]
+          end
+        end
+
+        # Add bearer token authentication
+        if (bearer_config = @authentication["bearer"])
+          headers["Authorization"] = "Bearer #{bearer_config['token']}"
+        end
+
+        # Add basic authentication
+        if (basic_config = @authentication["basic"])
+          require "base64"
+          credentials = Base64.strict_encode64("#{basic_config['username']}:#{basic_config['password']}")
+          headers["Authorization"] = "Basic #{credentials}"
+        end
+
+        headers
+      end
+    end
+  end
+end