a2a-ruby 1.0.0

data/lib/a2a/configuration/file_loader.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+
+module A2A
+  class Configuration
+    # Module for loading configuration from YAML files
+    module FileLoader
+      # Load configuration from YAML file
+      # @param file_path [String] Path to YAML configuration file
+      # @param environment [String, nil] Environment section to load
+      # @return [self]
+      def load_from_file(file_path, environment: nil)
+        @config_file = file_path
+        environment ||= @environment
+
+        # Validate file exists and is readable
+        raise A2A::Errors::ConfigurationError, "Configuration file not found: #{file_path}" unless File.exist?(file_path)
+
+        raise A2A::Errors::ConfigurationError, "Configuration file not readable: #{file_path}" unless File.readable?(file_path)
+
+        begin
+          content = File.read(file_path)
+
+          # Process ERB if the file contains ERB syntax
+          erb_content = if content.include?("<%") || content.include?("%>")
+                          ERB.new(content).result
+                        else
+                          content
+                        end
+
+          # Parse YAML with proper error handling
+          config_data = YAML.safe_load(erb_content, aliases: true, symbolize_names: false) || {}
+
+          unless config_data.is_a?(Hash)
+            raise A2A::Errors::ConfigurationError,
+                  "Configuration file must contain a hash/dictionary at root level"
+          end
+        rescue Psych::SyntaxError => e
+          raise A2A::Errors::ConfigurationError,
+                "Invalid YAML syntax in configuration file #{file_path}: #{e.message}"
+        rescue StandardError => e
+          raise A2A::Errors::ConfigurationError,
+                "Failed to load configuration file #{file_path}: #{e.message}"
+        end
+
+        # Load environment-specific configuration
+        env_config = config_data[environment.to_s] || config_data[environment.to_sym] || {}
+
+        unless env_config.is_a?(Hash)
+          raise A2A::Errors::ConfigurationError,
+                "Environment configuration for '#{environment}' must be a hash/dictionary"
+        end
+
+        # Apply configuration from file with validation
+        begin
+          apply_hash_config(env_config)
+        rescue StandardError => e
+          raise A2A::Errors::ConfigurationError,
+                "Failed to apply configuration from file #{file_path}: #{e.message}"
+        end
+
+        self
+      end
+
+      private
+
+      # Apply configuration from hash
+      def apply_hash_config(config_hash)
+        unknown_keys = []
+
+        config_hash.each do |key, value|
+          key_str = key.to_s
+          setter = "#{key_str}="
+
+          if respond_to?(setter)
+            begin
+              # Special handling for log_level to normalize from string to symbol
+              if key_str == "log_level" && value.is_a?(String)
+                normalized_value = value.downcase
+                valid_levels = %w[debug info warn error fatal]
+                value = normalized_value.to_sym if valid_levels.include?(normalized_value)
+              end
+              send(setter, value)
+            rescue StandardError => e
+              raise A2A::Errors::ConfigurationError,
+                    "Failed to set #{key_str}: #{e.message}"
+            end
+          else
+            # Handle nested configurations
+            case key_str
+            when "redis_config", "redis"
+              if value.is_a?(Hash)
+                @redis_config = value.transform_keys(&:to_sym)
+              elsif value.is_a?(String)
+                @redis_config = { url: value }
+              else
+                raise A2A::Errors::ConfigurationError,
+                      "redis_config must be a hash or URL string, got: #{value.class}"
+              end
+            else
+              unknown_keys << key_str
+            end
+          end
+        end
+
+        # Warn about unknown keys but don't fail
+        return if unknown_keys.empty?
+
+        logger&.warn("Unknown configuration keys: #{unknown_keys.join(', ')}")
+      end
+    end
+  end
+end

data/lib/a2a/configuration/inheritance.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module A2A
+  class Configuration
+    # Module for configuration inheritance support
+    module Inheritance
+      # Create a child configuration with inheritance
+      # @param **overrides [Hash] Configuration overrides
+      # @return [Configuration] New configuration instance
+      def child(**overrides)
+        # Create new instance without loading defaults to avoid overwriting parent values
+        child_config = self.class.allocate
+        child_config.instance_variable_set(:@environment, @environment)
+        child_config.instance_variable_set(:@parent_config, self)
+        child_config.instance_variable_set(:@overrides, overrides)
+        child_config.instance_variable_set(:@config_file, nil)
+
+        # Copy all instance variables from parent to child (deep copy for complex objects)
+        instance_variables.each do |var|
+          next if %i[@parent_config @overrides @config_file].include?(var)
+
+          value = instance_variable_get(var)
+          # Deep copy arrays and hashes to prevent shared references
+          copied_value = case value
+                         when Array
+                           value.dup
+                         when Hash
+                           value.dup
+                         else
+                           value
+                         end
+          child_config.instance_variable_set(var, copied_value)
+        end
+
+        # Apply overrides after copying parent values
+        child_config.send(:apply_overrides, overrides)
+
+        child_config
+      end
+
+      # Get configuration value with inheritance support
+      # @param key [Symbol, String] Configuration key
+      # @return [Object] Configuration value
+      def get(key)
+        # Convert key to instance variable name
+        ivar_name = "@#{key}"
+
+        # Check if we have the instance variable set
+        if instance_variable_defined?(ivar_name)
+          value = instance_variable_get(ivar_name)
+          # Return value if it's not nil, or if we don't have a parent
+          return value unless value.nil? && @parent_config
+        end
+
+        # Fall back to parent configuration if value is nil and parent exists
+        @parent_config&.get(key)
+      end
+
+      # Validate that child configuration properly inherits from parent
+      # @return [Boolean] true if inheritance is working correctly
+      def validate_inheritance!
+        return true unless @parent_config
+
+        # Check that we can access parent values when child values are nil
+        parent_attrs = @parent_config.to_h
+        parent_attrs.each do |key, parent_value|
+          next if parent_value.nil?
+
+          # Get child value directly (not through inheritance)
+          child_ivar = "@#{key}"
+          child_value = instance_variable_defined?(child_ivar) ? instance_variable_get(child_ivar) : nil
+
+          # If child value is nil, get should return parent value
+          next unless child_value.nil?
+
+          inherited_value = get(key)
+          unless inherited_value == parent_value
+            raise A2A::Errors::ConfigurationError,
+                  "Inheritance failed for #{key}: expected #{parent_value.inspect}, got #{inherited_value.inspect}"
+          end
+        end
+
+        true
+      end
+
+      # Merge configuration from another configuration object
+      # @param other [Configuration] Configuration to merge from
+      # @return [self]
+      def merge!(other)
+        return self unless other.is_a?(A2A::Configuration)
+
+        other.to_h.each do |key, value|
+          setter = "#{key}="
+          send(setter, value) if respond_to?(setter)
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/a2a/configuration/validator.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module A2A
+  class Configuration
+    # Module for configuration validation
+    module Validator
+      # Validate the configuration
+      # @raise [A2A::Errors::ConfigurationError] if configuration is invalid
+      def validate!
+        errors = []
+
+        begin
+          validate_basic_config
+        rescue A2A::Errors::ConfigurationError => e
+          errors << e.message
+        end
+
+        begin
+          validate_transport_config
+        rescue A2A::Errors::ConfigurationError => e
+          errors << e.message
+        end
+
+        if rails_integration
+          begin
+            validate_rails_config
+          rescue A2A::Errors::ConfigurationError => e
+            errors << e.message
+          end
+        end
+
+        begin
+          validate_redis_config
+        rescue A2A::Errors::ConfigurationError => e
+          errors << e.message
+        end
+
+        begin
+          validate_environment_config
+        rescue A2A::Errors::ConfigurationError => e
+          errors << e.message
+        end
+
+        begin
+          validate_timeout_values
+        rescue A2A::Errors::ConfigurationError => e
+          errors << e.message
+        end
+
+        begin
+          validate_boolean_options
+        rescue A2A::Errors::ConfigurationError => e
+          errors << e.message
+        end
+
+        unless errors.empty?
+          raise A2A::Errors::ConfigurationError,
+                "Configuration validation failed:\n  - #{errors.join("\n  - ")}"
+        end
+
+        true
+      end
+
+      private
+
+      # Validation methods
+      def validate_basic_config
+        raise A2A::Errors::ConfigurationError, "default_timeout must be positive" if default_timeout <= 0
+
+        validate_log_level
+        validate_protocol_version
+      end
+
+      # Validate log level with proper string/symbol handling
+      def validate_log_level
+        return if log_level.nil?
+
+        # Accept both string and symbol log levels, normalize to symbol
+        normalized_level = log_level.to_s.downcase
+        valid_levels = %w[debug info warn error fatal]
+
+        unless valid_levels.include?(normalized_level)
+          raise A2A::Errors::ConfigurationError,
+                "log_level must be one of: #{valid_levels.join(', ')}. Got: #{log_level.inspect}"
+        end
+
+        # Normalize to symbol for internal use
+        @log_level = normalized_level.to_sym
+      end
+
+      # Validate protocol version with proper nil/blank handling
+      def validate_protocol_version
+        return if protocol_version.nil?
+
+        if protocol_version.respond_to?(:strip) && protocol_version.strip.empty?
+          raise A2A::Errors::ConfigurationError,
+                "protocol_version cannot be blank"
+        elsif protocol_version.respond_to?(:empty?) && protocol_version.empty?
+          raise A2A::Errors::ConfigurationError,
+                "protocol_version cannot be empty"
+        end
+      end
+
+      def validate_transport_config
+        valid_transports = %w[JSONRPC GRPC HTTP+JSON]
+        unless valid_transports.include?(default_transport)
+          raise A2A::Errors::ConfigurationError, "default_transport must be one of: #{valid_transports.join(', ')}"
+        end
+
+        unless default_input_modes.is_a?(Array) && default_input_modes.all?(String)
+          raise A2A::Errors::ConfigurationError, "default_input_modes must be an array of strings"
+        end
+
+        return if default_output_modes.is_a?(Array) && default_output_modes.all?(String)
+
+        raise A2A::Errors::ConfigurationError, "default_output_modes must be an array of strings"
+      end
+
+      def validate_rails_config
+        raise A2A::Errors::ConfigurationError, "mount_path must start with '/'" if mount_path && !mount_path.start_with?("/")
+
+        # Only validate Rails version if Rails is available and version checking is needed
+        return unless rails_available? && rails_version_requires_validation?
+
+        current_version = rails_version
+        raise A2A::Errors::ConfigurationError,
+              "Rails integration requires Rails 6.0 or higher. Current version: #{current_version}"
+      end
+
+      def validate_redis_config
+        raise A2A::Errors::ConfigurationError, "redis_config must be a hash" if redis_config && !redis_config.is_a?(Hash)
+
+        return unless redis_config && redis_config[:url] && !redis_config[:url].is_a?(String)
+
+        raise A2A::Errors::ConfigurationError, "redis_config[:url] must be a string"
+      end
+
+      def validate_environment_config
+        return if environment.nil?
+
+        raise A2A::Errors::ConfigurationError, "environment must be a string" unless environment.is_a?(String)
+
+        valid_environments = %w[development test production staging]
+        return if valid_environments.include?(environment)
+
+        logger&.warn("Unknown environment: #{environment}. Valid environments: #{valid_environments.join(', ')}")
+      end
+
+      def validate_timeout_values
+        return unless default_timeout && (!default_timeout.is_a?(Numeric) || default_timeout <= 0)
+
+        raise A2A::Errors::ConfigurationError,
+              "default_timeout must be a positive number, got: #{default_timeout.inspect}"
+      end
+
+      def validate_boolean_options
+        boolean_options = {
+          streaming_enabled: streaming_enabled,
+          push_notifications_enabled: push_notifications_enabled,
+          rails_integration: rails_integration,
+          auto_mount: auto_mount,
+          middleware_enabled: middleware_enabled,
+          authentication_required: authentication_required,
+          cors_enabled: cors_enabled,
+          rate_limiting_enabled: rate_limiting_enabled,
+          logging_enabled: logging_enabled,
+          webhook_authentication_required: webhook_authentication_required
+        }
+
+        boolean_options.each do |option, value|
+          next if value.nil?
+          next if [true, false].include?(value)
+
+          raise A2A::Errors::ConfigurationError,
+                "#{option} must be true or false, got: #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/configuration.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require_relative "utils/rails_detection"
+require_relative "configuration/defaults"
+require_relative "configuration/environment_loader"
+require_relative "configuration/file_loader"
+require_relative "configuration/validator"
+require_relative "configuration/inheritance"
+
+##
+# Global configuration for the A2A Ruby SDK
+#
+# Supports environment variables, per-environment configuration,
+# configuration inheritance, and validation.
+#
+# @example Configure the SDK programmatically
+#   A2A.configure do |config|
+#     config.default_timeout = 30
+#     config.log_level = :debug
+#     config.protocol_version = "0.3.0"
+#   end
+#
+# @example Load from environment variables
+#   # Set A2A_DEFAULT_TIMEOUT=60 in environment
+#   config = A2A::Configuration.new
+#   config.default_timeout # => 60
+#
+# @example Load from YAML file
+#   A2A.configure_from_file('config/a2a.yml')
+#
+module A2A
+  class Configuration
+    include A2A::Utils::RailsDetection
+    include Defaults
+    include EnvironmentLoader
+    include FileLoader
+    include Validator
+    include Inheritance
+
+    # Default timeout for HTTP requests in seconds
+    # @return [Integer]
+    attr_accessor :default_timeout
+
+    # Default log level
+    # @return [Symbol]
+    attr_accessor :log_level
+
+    # A2A protocol version to use
+    # @return [String]
+    attr_accessor :protocol_version
+
+    # Default transport protocol
+    # @return [String]
+    attr_accessor :default_transport
+
+    # Enable/disable streaming support
+    # @return [Boolean]
+    attr_accessor :streaming_enabled
+
+    # Enable/disable push notifications
+    # @return [Boolean]
+    attr_accessor :push_notifications_enabled
+
+    # Default input MIME types
+    # @return [Array<String>]
+    attr_accessor :default_input_modes
+
+    # Default output MIME types
+    # @return [Array<String>]
+    attr_accessor :default_output_modes
+
+    # Redis configuration for task storage and rate limiting
+    # @return [Hash]
+    attr_accessor :redis_config
+
+    # Enable Rails integration
+    # @return [Boolean]
+    attr_accessor :rails_integration
+
+    # Rails mount path for A2A endpoints
+    # @return [String]
+    attr_accessor :mount_path
+
+    # Enable automatic mounting of A2A routes
+    # @return [Boolean]
+    attr_accessor :auto_mount
+
+    # Enable A2A middleware stack
+    # @return [Boolean]
+    attr_accessor :middleware_enabled
+
+    # Require authentication for A2A endpoints
+    # @return [Boolean]
+    attr_accessor :authentication_required
+
+    # Enable CORS middleware
+    # @return [Boolean]
+    attr_accessor :cors_enabled
+
+    # Enable rate limiting middleware
+    # @return [Boolean]
+    attr_accessor :rate_limiting_enabled
+
+    # Enable logging middleware
+    # @return [Boolean]
+    attr_accessor :logging_enabled
+
+    # Require authentication for webhook endpoints
+    # @return [Boolean]
+    attr_accessor :webhook_authentication_required
+
+    # Custom logger instance
+    # @return [Logger, nil]
+    attr_accessor :logger
+
+    # User agent string for HTTP requests
+    # @return [String]
+    attr_accessor :user_agent
+
+    # Environment for configuration (development, test, production)
+    # @return [String]
+    attr_accessor :environment
+
+    # Configuration file path
+    # @return [String, nil]
+    attr_accessor :config_file
+
+    # Parent configuration for inheritance
+    # @return [Configuration, nil]
+    attr_accessor :parent_config
+
+    # Configuration overrides
+    # @return [Hash]
+    attr_accessor :overrides
+
+    def initialize(environment: nil, parent: nil, **overrides)
+      @environment = environment || detect_environment
+      @parent_config = parent
+      @overrides = overrides
+      @config_file = nil
+
+      load_defaults
+      load_from_environment
+      apply_overrides(overrides)
+    end
+
+    private
+
+    # Apply configuration overrides
+    def apply_overrides(overrides)
+      overrides.each do |key, value|
+        setter = "#{key}="
+        unless respond_to?(setter, true) # Check for both public and private methods
+          raise A2A::Errors::ConfigurationError, "Unknown configuration option: #{key}"
+        end
+
+        send(setter, value)
+      end
+    end
+
+    public
+
+    # Get the logger instance
+    # @return [Logger]
+    def logger
+      @logger ||= if rails_available? && rails_logger
+                    rails_logger
+                  else
+                    require "logger"
+                    Logger.new($stdout, level: log_level)
+                  end
+    end
+
+    # Convert configuration to hash
+    # @return [Hash] Configuration as hash
+    def to_h
+      {
+        environment: @environment,
+        default_timeout: @default_timeout,
+        log_level: @log_level,
+        protocol_version: @protocol_version,
+        default_transport: @default_transport,
+        streaming_enabled: @streaming_enabled,
+        push_notifications_enabled: @push_notifications_enabled,
+        default_input_modes: @default_input_modes,
+        default_output_modes: @default_output_modes,
+        redis_config: @redis_config,
+        rails_integration: @rails_integration,
+        mount_path: @mount_path,
+        auto_mount: @auto_mount,
+        middleware_enabled: @middleware_enabled,
+        authentication_required: @authentication_required,
+        cors_enabled: @cors_enabled,
+        rate_limiting_enabled: @rate_limiting_enabled,
+        logging_enabled: @logging_enabled,
+        webhook_authentication_required: @webhook_authentication_required,
+        user_agent: @user_agent
+      }
+    end
+  end
+end