a2a-ruby 1.0.0

data/lib/a2a/client/middleware/rate_limit_interceptor.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+##
+# Rate limiting interceptor using token bucket algorithm
+#
+# Implements client-side rate limiting to prevent overwhelming
+# the target agent with too many requests.
+#
+module A2A
+  module Client
+    module Middleware
+      class RateLimitInterceptor
+        attr_reader :requests_per_second, :burst_size, :tokens, :last_refill
+
+        ##
+        # Initialize rate limit interceptor
+        #
+        # @param requests_per_second [Numeric] Maximum requests per second (default: 10)
+        # @param burst_size [Integer] Maximum burst size (default: 20)
+        def initialize(requests_per_second: 10, burst_size: 20)
+          @requests_per_second = requests_per_second.to_f
+          @burst_size = burst_size
+          @tokens = @burst_size.to_f
+          @last_refill = Time.now
+          @mutex = Mutex.new
+
+          validate_configuration!
+        end
+
+        ##
+        # Execute request with rate limiting
+        #
+        # @param request [Object] The request object
+        # @param context [Hash] Request context
+        # @param next_middleware [Proc] Next middleware in chain
+        # @return [Object] Response from next middleware
+        def call(request, context, next_middleware)
+          wait_for_token
+          next_middleware.call(request, context)
+        end
+
+        ##
+        # Check if a request can be made immediately
+        #
+        # @return [Boolean] True if request can be made without waiting
+        def can_make_request?
+          @mutex.synchronize do
+            refill_tokens
+            @tokens >= 1.0
+          end
+        end
+
+        ##
+        # Get current rate limit status
+        #
+        # @return [Hash] Rate limit status information
+        def status
+          @mutex.synchronize do
+            refill_tokens
+            {
+              requests_per_second: @requests_per_second,
+              burst_size: @burst_size,
+              available_tokens: @tokens.round(2),
+              tokens_full: @tokens >= @burst_size,
+              can_make_request: @tokens >= 1.0
+            }
+          end
+        end
+
+        ##
+        # Calculate time until next token is available
+        #
+        # @return [Float] Time in seconds until next token
+        def time_until_next_token
+          @mutex.synchronize do
+            refill_tokens
+            return 0.0 if @tokens >= 1.0
+
+            tokens_needed = 1.0 - @tokens
+            tokens_needed / @requests_per_second
+          end
+        end
+
+        ##
+        # Reset the rate limiter (useful for testing)
+        def reset!
+          @mutex.synchronize do
+            @tokens = @burst_size.to_f
+            @last_refill = Time.now
+          end
+        end
+
+        private
+
+        ##
+        # Wait for a token to become available
+        def wait_for_token
+          loop do
+            @mutex.synchronize do
+              refill_tokens
+
+              if @tokens >= 1.0
+                @tokens -= 1.0
+                return
+              end
+            end
+
+            # Calculate how long to sleep
+            sleep_time = time_until_next_token
+            sleep(sleep_time) if sleep_time.positive?
+          end
+        end
+
+        ##
+        # Refill tokens based on elapsed time
+        def refill_tokens
+          now = Time.now
+          elapsed = now - @last_refill
+
+          return unless elapsed.positive?
+
+          # Add tokens based on elapsed time
+          tokens_to_add = elapsed * @requests_per_second
+          @tokens = [@tokens + tokens_to_add, @burst_size].min
+          @last_refill = now
+        end
+
+        ##
+        # Validate configuration parameters
+        def validate_configuration!
+          raise ArgumentError, "requests_per_second must be positive" if @requests_per_second <= 0
+
+          raise ArgumentError, "burst_size must be positive" if @burst_size <= 0
+
+          return unless @burst_size < @requests_per_second
+
+          warn "Warning: burst_size (#{@burst_size}) is less than requests_per_second (#{@requests_per_second})"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/client/middleware/retry_interceptor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+##
+# Retry interceptor with exponential backoff
+#
+# Automatically retries failed requests with configurable backoff
+# strategy and error filtering.
+#
+module A2A
+  module Client
+    module Middleware
+      class RetryInterceptor
+        attr_reader :max_attempts, :initial_delay, :max_delay, :backoff_multiplier, :retryable_errors
+
+        # Default retryable error classes
+        DEFAULT_RETRYABLE_ERRORS = [
+          A2A::Errors::TimeoutError,
+          A2A::Errors::HTTPError,
+          A2A::Errors::TransportError,
+          A2A::Errors::AgentUnavailable,
+          A2A::Errors::ResourceExhausted,
+          Faraday::TimeoutError,
+          Faraday::ConnectionFailed
+        ].freeze
+
+        ##
+        # Initialize retry interceptor
+        #
+        # @param max_attempts [Integer] Maximum number of retry attempts (default: 3)
+        # @param initial_delay [Float] Initial delay in seconds (default: 1.0)
+        # @param max_delay [Float] Maximum delay in seconds (default: 60.0)
+        # @param backoff_multiplier [Float] Backoff multiplier (default: 2.0)
+        # @param retryable_errors [Array<Class>] List of retryable error classes
+        def initialize(max_attempts: 3, initial_delay: 1.0, max_delay: 60.0,
+                       backoff_multiplier: 2.0, retryable_errors: nil)
+          @max_attempts = max_attempts
+          @initial_delay = initial_delay
+          @max_delay = max_delay
+          @backoff_multiplier = backoff_multiplier
+          @retryable_errors = retryable_errors || DEFAULT_RETRYABLE_ERRORS
+
+          validate_configuration!
+        end
+
+        ##
+        # Execute request with retry logic
+        #
+        # @param request [Object] The request object
+        # @param context [Hash] Request context
+        # @param next_middleware [Proc] Next middleware in chain
+        # @return [Object] Response from successful request
+        def call(request, context, next_middleware)
+          attempt = 0
+          last_error = nil
+
+          loop do
+            attempt += 1
+
+            begin
+              return next_middleware.call(request, context)
+            rescue StandardError => e
+              last_error = e
+
+              # Check if we should retry
+              raise e unless should_retry?(e, attempt)
+
+              delay = calculate_delay(attempt)
+              context[:retry_attempt] = attempt
+              context[:retry_delay] = delay
+
+              sleep(delay) if delay.positive?
+              next
+
+              # Re-raise the error if we shouldn't retry or max attempts reached
+            end
+          end
+        end
+
+        ##
+        # Check if an error should trigger a retry
+        #
+        # @param error [Exception] The error that occurred
+        # @param attempt [Integer] Current attempt number
+        # @return [Boolean] True if should retry
+        def should_retry?(error, attempt)
+          return false if attempt >= @max_attempts
+          return false unless retryable_error?(error)
+
+          # Check for specific HTTP status codes that shouldn't be retried
+          if error.respond_to?(:status_code)
+            case error.status_code
+            when 400, 401, 403, 404, 422 # Client errors - don't retry
+              return false
+            when 429 # Rate limited - should retry
+              return true
+            when 500..599 # Server errors - should retry
+              return true
+            end
+          end
+
+          true
+        end
+
+        ##
+        # Check if an error is retryable
+        #
+        # @param error [Exception] The error to check
+        # @return [Boolean] True if error is retryable
+        def retryable_error?(error)
+          @retryable_errors.any? { |error_class| error.is_a?(error_class) }
+        end
+
+        ##
+        # Calculate delay for the given attempt
+        #
+        # @param attempt [Integer] Current attempt number (1-based)
+        # @return [Float] Delay in seconds
+        def calculate_delay(attempt)
+          return 0 if attempt <= 1
+
+          # Exponential backoff: initial_delay * (backoff_multiplier ^ (attempt - 2))
+          delay = @initial_delay * (@backoff_multiplier**(attempt - 2))
+
+          # Add jitter to prevent thundering herd
+          jitter = delay * 0.1 * rand
+          delay += jitter
+
+          # Cap at max_delay
+          [delay, @max_delay].min
+        end
+
+        ##
+        # Get retry statistics
+        #
+        # @return [Hash] Retry configuration and statistics
+        def stats
+          {
+            max_attempts: @max_attempts,
+            initial_delay: @initial_delay,
+            max_delay: @max_delay,
+            backoff_multiplier: @backoff_multiplier,
+            retryable_errors: @retryable_errors.map(&:name)
+          }
+        end
+
+        private
+
+        ##
+        # Validate configuration parameters
+        def validate_configuration!
+          raise ArgumentError, "max_attempts must be positive" if @max_attempts <= 0
+          raise ArgumentError, "initial_delay must be non-negative" if @initial_delay.negative?
+          raise ArgumentError, "max_delay must be positive" if @max_delay <= 0
+          raise ArgumentError, "backoff_multiplier must be positive" if @backoff_multiplier <= 0
+
+          raise ArgumentError, "initial_delay cannot be greater than max_delay" if @initial_delay > @max_delay
+        end
+      end
+    end
+  end
+end

data/lib/a2a/client/middleware.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "middleware/retry_interceptor"
+require_relative "middleware/logging_interceptor"
+require_relative "middleware/rate_limit_interceptor"
+require_relative "middleware/circuit_breaker_interceptor"
+
+##
+# Client middleware system for A2A requests
+#
+# Provides a collection of middleware interceptors for handling
+# cross-cutting concerns like retries, logging, rate limiting,
+# and circuit breaking.
+#
+# @example Using middleware with a client
+#   retry_middleware = A2A::Client::Middleware::RetryInterceptor.new(max_attempts: 3)
+#   logging_middleware = A2A::Client::Middleware::LoggingInterceptor.new
+#
+#   client = A2A::Client::HttpClient.new(
+#     'https://agent.example.com',
+#     middleware: [retry_middleware, logging_middleware]
+#   )
+#
+module A2A
+  module Client
+    module Middleware
+      ##
+      # Base class for middleware interceptors
+      #
+      class Base
+        ##
+        # Call the middleware
+        #
+        # @param request [Object] The request object
+        # @param context [Hash] Request context
+        # @param next_middleware [Proc] Next middleware in chain
+        # @return [Object] Response from next middleware
+        def call(request, context, next_middleware)
+          raise NotImplementedError, "#{self.class}#call must be implemented"
+        end
+      end
+
+      ##
+      # Create middleware from configuration
+      #
+      # @param config [Hash] Middleware configuration
+      # @return [Base] Configured middleware instance
+      def self.from_config(config)
+        type = config["type"] || config[:type]
+
+        case type
+        when "retry"
+          RetryInterceptor.new(
+            max_attempts: config["max_attempts"] || config[:max_attempts] || 3,
+            initial_delay: config["initial_delay"] || config[:initial_delay] || 1.0,
+            max_delay: config["max_delay"] || config[:max_delay] || 60.0,
+            backoff_multiplier: config["backoff_multiplier"] || config[:backoff_multiplier] || 2.0,
+            retryable_errors: config["retryable_errors"] || config[:retryable_errors]
+          )
+        when "logging"
+          LoggingInterceptor.new(
+            logger: config["logger"] || config[:logger],
+            log_level: config["log_level"] || config[:log_level] || :info,
+            log_requests: config["log_requests"] || config[:log_requests] || true,
+            log_responses: config["log_responses"] || config[:log_responses] || true,
+            log_errors: config["log_errors"] || config[:log_errors] || true
+          )
+        when "rate_limit"
+          RateLimitInterceptor.new(
+            requests_per_second: config["requests_per_second"] || config[:requests_per_second] || 10,
+            burst_size: config["burst_size"] || config[:burst_size] || 20
+          )
+        when "circuit_breaker"
+          CircuitBreakerInterceptor.new(
+            failure_threshold: config["failure_threshold"] || config[:failure_threshold] || 5,
+            timeout: config["timeout"] || config[:timeout] || 60,
+            expected_errors: config["expected_errors"] || config[:expected_errors]
+          )
+        else
+          raise ArgumentError, "Unknown middleware type: #{type}"
+        end
+      end
+
+      ##
+      # Create default middleware stack
+      #
+      # @param config [Hash] Configuration options
+      # @return [Array<Base>] Default middleware stack
+      def self.default_stack(config = {})
+        stack = []
+
+        # Add retry middleware
+        stack << RetryInterceptor.new if config.fetch("retry", true)
+
+        # Add logging middleware
+        stack << LoggingInterceptor.new if config.fetch("logging", true)
+
+        # Add rate limiting if configured
+        if config["rate_limit"]
+          stack << RateLimitInterceptor.new(
+            requests_per_second: config["rate_limit"]["requests_per_second"] || 10
+          )
+        end
+
+        # Add circuit breaker if configured
+        if config["circuit_breaker"]
+          stack << CircuitBreakerInterceptor.new(
+            failure_threshold: config["circuit_breaker"]["failure_threshold"] || 5
+          )
+        end
+
+        stack
+      end
+    end
+  end
+end

data/lib/a2a/client/performance_tracker.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module A2A
+  module Client
+    ##
+    # Performance tracking functionality for HTTP clients
+    #
+    module PerformanceTracker
+      ##
+      # Initialize performance tracking
+      #
+      def initialize_performance_tracking
+        @performance_stats = {
+          requests_count: 0,
+          total_time: 0.0,
+          avg_response_time: 0.0,
+          cache_hits: 0,
+          cache_misses: 0
+        }
+        @stats_mutex = Mutex.new
+      end
+
+      ##
+      # Get performance statistics
+      #
+      # @return [Hash] Performance statistics
+      def performance_stats
+        @stats_mutex.synchronize { @performance_stats.dup }
+      end
+
+      ##
+      # Reset performance statistics
+      #
+      def reset_performance_stats!
+        @stats_mutex.synchronize do
+          @performance_stats = {
+            requests_count: 0,
+            total_time: 0.0,
+            avg_response_time: 0.0,
+            cache_hits: 0,
+            cache_misses: 0
+          }
+        end
+      end
+
+      ##
+      # Record request performance metrics
+      #
+      # @param duration [Float] Request duration in seconds
+      def record_request_performance(duration)
+        @stats_mutex.synchronize do
+          @performance_stats[:requests_count] += 1
+          @performance_stats[:total_time] += duration
+          @performance_stats[:avg_response_time] =
+            @performance_stats[:total_time] / @performance_stats[:requests_count]
+        end
+      end
+    end
+  end
+end

data/lib/a2a/configuration/defaults.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module A2A
+  class Configuration
+    # Module for handling default configuration values
+    module Defaults
+      private
+
+      # Load default configuration values
+      def load_defaults
+        @default_timeout = 30
+        @log_level = :info
+        @protocol_version = "0.3.0"
+        @default_transport = "JSONRPC"
+        @streaming_enabled = true
+        @push_notifications_enabled = true
+        @default_input_modes = ["text/plain", "application/json"]
+        @default_output_modes = ["text/plain", "application/json"]
+        @redis_config = { url: "redis://localhost:6379/0" }
+        @rails_integration = defined?(Rails) ? true : false
+        @mount_path = "/a2a"
+        @auto_mount = true
+        @middleware_enabled = true
+        @authentication_required = false
+        @cors_enabled = true
+        @rate_limiting_enabled = false
+        @logging_enabled = true
+        @webhook_authentication_required = false
+        @logger = nil
+        @user_agent = "A2A-Ruby/#{A2A::VERSION}"
+      end
+    end
+  end
+end

data/lib/a2a/configuration/environment_loader.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module A2A
+  class Configuration
+    # Module for loading configuration from environment variables
+    module EnvironmentLoader
+      private
+
+      # Load configuration from environment variables
+      def load_from_environment
+        @default_timeout = env_int("A2A_DEFAULT_TIMEOUT", @default_timeout)
+        @log_level = env_symbol("A2A_LOG_LEVEL", @log_level)
+        @protocol_version = env_string("A2A_PROTOCOL_VERSION", @protocol_version)
+        @default_transport = env_string("A2A_DEFAULT_TRANSPORT", @default_transport)
+        @streaming_enabled = env_bool("A2A_STREAMING_ENABLED", @streaming_enabled)
+        @push_notifications_enabled = env_bool("A2A_PUSH_NOTIFICATIONS_ENABLED", @push_notifications_enabled)
+        @default_input_modes = env_array("A2A_DEFAULT_INPUT_MODES", @default_input_modes)
+        @default_output_modes = env_array("A2A_DEFAULT_OUTPUT_MODES", @default_output_modes)
+        @rails_integration = env_bool("A2A_RAILS_INTEGRATION", @rails_integration)
+        @mount_path = env_string("A2A_MOUNT_PATH", @mount_path)
+        @auto_mount = env_bool("A2A_AUTO_MOUNT", @auto_mount)
+        @middleware_enabled = env_bool("A2A_MIDDLEWARE_ENABLED", @middleware_enabled)
+        @authentication_required = env_bool("A2A_AUTHENTICATION_REQUIRED", @authentication_required)
+        @cors_enabled = env_bool("A2A_CORS_ENABLED", @cors_enabled)
+        @rate_limiting_enabled = env_bool("A2A_RATE_LIMITING_ENABLED", @rate_limiting_enabled)
+        @logging_enabled = env_bool("A2A_LOGGING_ENABLED", @logging_enabled)
+        @webhook_authentication_required = env_bool("A2A_WEBHOOK_AUTHENTICATION_REQUIRED",
+                                                    @webhook_authentication_required)
+        @user_agent = env_string("A2A_USER_AGENT", @user_agent)
+
+        # Redis configuration from environment
+        redis_url = ENV["REDIS_URL"] || ENV.fetch("A2A_REDIS_URL", nil)
+        return unless redis_url
+
+        @redis_config = { url: redis_url }
+      end
+
+      # Detect current environment
+      def detect_environment
+        return ENV["A2A_ENV"] if ENV["A2A_ENV"]
+        return ENV["RAILS_ENV"] if ENV["RAILS_ENV"]
+        return ENV["RACK_ENV"] if ENV["RACK_ENV"]
+        return rails_environment if rails_environment
+
+        "development"
+      end
+
+      # Environment variable helpers
+      def env_string(key, default)
+        ENV[key] || default
+      end
+
+      def env_int(key, default)
+        value = ENV.fetch(key, nil)
+        value ? value.to_i : default
+      end
+
+      def env_bool(key, default)
+        value = ENV.fetch(key, nil)
+        return default if value.nil?
+
+        %w[true yes 1 on].include?(value.downcase)
+      end
+
+      def env_symbol(key, default)
+        value = ENV.fetch(key, nil)
+        value ? value.to_sym : default
+      end
+
+      def env_array(key, default)
+        value = ENV.fetch(key, nil)
+        value ? value.split(",").map(&:strip) : default
+      end
+    end
+  end
+end