a2a-ruby 1.0.0

data/lib/a2a/utils/message_buffer.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "zlib"
+require_relative "performance"
+
+##
+# Memory-efficient message buffer for handling large messages
+#
+# Provides streaming capabilities and compression for large message handling
+# to optimize memory usage and performance.
+#
+module A2A
+  module Utils
+    class MessageBuffer
+      # Default buffer size (64KB)
+      DEFAULT_BUFFER_SIZE = 64 * 1024
+
+      # Compression threshold (1MB)
+      COMPRESSION_THRESHOLD = 1024 * 1024
+
+      attr_reader :size, :compressed, :encoding
+
+      ##
+      # Initialize a new message buffer
+      #
+      # @param initial_capacity [Integer] Initial buffer capacity
+      # @param compress [Boolean] Whether to use compression for large messages
+      # @param encoding [Encoding] Text encoding to use
+      def initialize(initial_capacity: DEFAULT_BUFFER_SIZE, compress: true, encoding: Encoding::UTF_8)
+        @buffer = StringIO.new
+        @buffer.set_encoding(encoding)
+        @initial_capacity = initial_capacity
+        @compress = compress
+        @compressed = false
+        @encoding = encoding
+        @chunks = []
+        @total_size = 0
+      end
+
+      ##
+      # Write data to the buffer
+      #
+      # @param data [String] Data to write
+      # @return [Integer] Number of bytes written
+      def write(data)
+        data = data.to_s.encode(@encoding) unless data.encoding == @encoding
+
+        if @compressed
+          # If already compressed, decompress first
+          decompress!
+        end
+
+        bytes_written = @buffer.write(data)
+        @total_size += bytes_written
+
+        # Compress if buffer gets too large
+        compress! if @compress && @total_size > COMPRESSION_THRESHOLD && !@compressed
+
+        bytes_written
+      end
+
+      ##
+      # Append data to the buffer (alias for write)
+      #
+      # @param data [String] Data to append
+      # @return [Integer] Number of bytes written
+      def <<(data)
+        write(data)
+      end
+
+      ##
+      # Read data from the buffer
+      #
+      # @param length [Integer, nil] Number of bytes to read (nil for all)
+      # @return [String] Data read from buffer
+      def read(length = nil)
+        decompress! if @compressed
+
+        @buffer.rewind
+        data = @buffer.read(length)
+        @buffer.rewind
+        data
+      end
+
+      ##
+      # Get the current size of the buffer
+      #
+      # @return [Integer] Size in bytes
+      def size
+        @compressed ? @compressed_size : @buffer.size
+      end
+
+      ##
+      # Check if buffer is empty
+      #
+      # @return [Boolean] True if buffer is empty
+      def empty?
+        size.zero?
+      end
+
+      ##
+      # Clear the buffer
+      #
+      def clear!
+        @buffer = StringIO.new
+        @buffer.set_encoding(@encoding)
+        @compressed = false
+        @compressed_size = 0
+        @total_size = 0
+        @chunks.clear
+      end
+
+      ##
+      # Get buffer contents as string
+      #
+      # @return [String] Buffer contents
+      def to_s
+        read
+      end
+
+      ##
+      # Get buffer contents as JSON
+      #
+      # @return [String] JSON representation
+      def to_json(*_args)
+        A2A::Utils::Performance.optimized_json_generate(to_s)
+      end
+
+      ##
+      # Create buffer from JSON string
+      #
+      # @param json_string [String] JSON string
+      # @return [MessageBuffer] New buffer with JSON data
+      def self.from_json(json_string)
+        data = A2A::Utils::Performance.optimized_json_parse(json_string)
+        buffer = new
+        buffer.write(data.to_s)
+        buffer
+      end
+
+      ##
+      # Stream data in chunks
+      #
+      # @param chunk_size [Integer] Size of each chunk
+      # @yield [String] Each chunk of data
+      def each_chunk(chunk_size = DEFAULT_BUFFER_SIZE)
+        return enum_for(:each_chunk, chunk_size) unless block_given?
+
+        decompress! if @compressed
+
+        @buffer.rewind
+
+        while (chunk = @buffer.read(chunk_size))
+          yield chunk
+        end
+
+        @buffer.rewind
+      end
+
+      ##
+      # Compress buffer contents
+      #
+      def compress!
+        return if @compressed || @buffer.size < COMPRESSION_THRESHOLD
+
+        @buffer.rewind
+        original_data = @buffer.read
+        @buffer.rewind
+
+        compressed_data = Zlib::Deflate.deflate(original_data)
+
+        # Only use compression if it actually saves space
+        return unless compressed_data.size < original_data.size
+
+        @buffer = StringIO.new(compressed_data)
+        @compressed = true
+        @compressed_size = compressed_data.size
+        @original_size = original_data.size
+      end
+
+      ##
+      # Decompress buffer contents
+      #
+      def decompress!
+        return unless @compressed
+
+        @buffer.rewind
+        compressed_data = @buffer.read
+        @buffer.rewind
+
+        original_data = Zlib::Inflate.inflate(compressed_data)
+
+        @buffer = StringIO.new
+        @buffer.set_encoding(@encoding)
+        @buffer.write(original_data)
+        @buffer.rewind
+
+        @compressed = false
+        @total_size = original_data.size
+      end
+
+      ##
+      # Get compression ratio
+      #
+      # @return [Float] Compression ratio (0.0 to 1.0)
+      def compression_ratio
+        return 0.0 unless @compressed && @original_size&.positive?
+
+        1.0 - (@compressed_size.to_f / @original_size)
+      end
+
+      ##
+      # Get buffer statistics
+      #
+      # @return [Hash] Buffer statistics
+      def stats
+        {
+          size: size,
+          compressed: @compressed,
+          compression_ratio: compression_ratio,
+          encoding: @encoding.name,
+          chunks: @chunks.size
+        }
+      end
+
+      ##
+      # Optimize buffer for memory usage
+      #
+      def optimize!
+        # Force garbage collection on buffer
+        GC.start if defined?(GC)
+
+        # Compress if beneficial
+        compress! if @compress && !@compressed && size > COMPRESSION_THRESHOLD
+
+        # Compact string if possible (Ruby 2.7+)
+        return unless @buffer.string.respond_to?(:squeeze!)
+
+        @buffer.string.squeeze!
+      end
+
+      ##
+      # Create a memory-mapped buffer for very large data
+      #
+      # @param file_path [String] Path to temporary file
+      # @return [MessageBuffer] Memory-mapped buffer
+      def self.create_memory_mapped(file_path)
+        # This would require additional gems like 'mmap' for true memory mapping
+        # For now, we'll use a file-backed buffer
+        buffer = new
+        buffer.instance_variable_set(:@file_backed, true)
+        buffer.instance_variable_set(:@file_path, file_path)
+        buffer
+      end
+
+      private
+
+      ##
+      # Ensure buffer has minimum capacity
+      #
+      # @param capacity [Integer] Required capacity
+      def ensure_capacity(capacity)
+        return if @buffer.size >= capacity
+
+        # Expand buffer if needed
+        current_pos = @buffer.pos
+        @buffer.seek(0, IO::SEEK_END)
+
+        # Write null bytes to expand
+        padding_needed = capacity - @buffer.size
+        @buffer.write("\0" * padding_needed) if padding_needed.positive?
+
+        @buffer.pos = current_pos
+      end
+    end
+  end
+end

data/lib/a2a/utils/performance.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+##
+# Performance optimization utilities
+#
+# Provides tools for profiling, memory optimization, and performance monitoring
+# across the A2A Ruby gem.
+#
+module A2A
+  module Utils
+    class Performance
+      # Memory usage tracking
+      @memory_snapshots = []
+      @performance_data = {}
+
+      class << self
+        attr_reader :memory_snapshots, :performance_data
+
+        ##
+        # Profile a block of code and return execution time
+        #
+        # @param label [String] Label for the profiling session
+        # @yield Block to profile
+        # @return [Object] Result of the block
+        def profile(label = "operation")
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          start_memory = memory_usage
+
+          result = yield
+
+          end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end_memory = memory_usage
+
+          duration = end_time - start_time
+          memory_delta = end_memory - start_memory
+
+          record_performance_data(label, duration, memory_delta)
+
+          if A2A.configuration.respond_to?(:performance_logging) && A2A.configuration.performance_logging
+            A2A.logger.info("Performance [#{label}]: #{duration.round(4)}s, Memory: #{format_bytes(memory_delta)}")
+          end
+
+          result
+        end
+
+        ##
+        # Get current memory usage in bytes
+        #
+        # @return [Integer] Memory usage in bytes
+        def memory_usage
+          if defined?(GC.stat)
+            # Use GC stats for more accurate memory tracking
+            GC.stat(:heap_allocated_pages) * GC.stat(:heap_page_size)
+          else
+            # Fallback to process memory (less accurate)
+            `ps -o rss= -p #{Process.pid}`.to_i * 1024
+          end
+        rescue StandardError
+          0
+        end
+
+        ##
+        # Take a memory snapshot
+        #
+        # @param label [String] Label for the snapshot
+        def memory_snapshot(label = Time.now.to_s)
+          snapshot = {
+            label: label,
+            timestamp: Time.now,
+            memory: memory_usage,
+            gc_stats: defined?(GC.stat) ? GC.stat : {}
+          }
+
+          @memory_snapshots << snapshot
+
+          # Keep only last 100 snapshots
+          @memory_snapshots = @memory_snapshots.last(100) if @memory_snapshots.size > 100
+
+          snapshot
+        end
+
+        ##
+        # Optimize garbage collection
+        #
+        def optimize_gc!
+          return unless defined?(GC)
+
+          # Force garbage collection
+          GC.start
+
+          # Compact heap if available (Ruby 2.7+)
+          GC.compact if GC.respond_to?(:compact)
+
+          # Tune GC settings for better performance
+          return unless defined?(GC.tune)
+
+          GC.tune(
+            heap_growth_factor: 1.8,
+            heap_growth_max_slots: 0,
+            heap_init_slots: 10_000,
+            heap_free_slots: 4096,
+            heap_oldobject_limit_factor: 2.0
+          )
+        end
+
+        ##
+        # Optimize JSON parsing performance
+        #
+        # @param json_string [String] JSON string to parse
+        # @return [Hash, Array] Parsed JSON
+        def optimized_json_parse(json_string)
+          # Use Oj if available for better performance
+          if defined?(Oj)
+            Oj.load(json_string, mode: :strict)
+          else
+            JSON.parse(json_string)
+          end
+        end
+
+        ##
+        # Optimize JSON generation performance
+        #
+        # @param object [Object] Object to serialize
+        # @return [String] JSON string
+        def optimized_json_generate(object)
+          # Use Oj if available for better performance
+          if defined?(Oj)
+            Oj.dump(object, mode: :compat)
+          else
+            JSON.generate(object)
+          end
+        end
+
+        ##
+        # Create an optimized string buffer for large message handling
+        #
+        # @param initial_capacity [Integer] Initial buffer capacity
+        # @return [StringIO] Optimized string buffer
+        def create_string_buffer(initial_capacity = 8192)
+          buffer = StringIO.new
+          buffer.set_encoding(Encoding::UTF_8)
+
+          # Pre-allocate capacity if possible
+          buffer.capacity = initial_capacity if buffer.respond_to?(:capacity=)
+
+          buffer
+        end
+
+        ##
+        # Batch process items for better performance
+        #
+        # @param items [Array] Items to process
+        # @param batch_size [Integer] Size of each batch
+        # @yield [Array] Block to process each batch
+        # @return [Array] Results from all batches
+        def batch_process(items, batch_size = 100)
+          results = []
+
+          items.each_slice(batch_size) do |batch|
+            batch_result = yield(batch)
+            results.concat(Array(batch_result))
+          end
+
+          results
+        end
+
+        ##
+        # Get performance statistics
+        #
+        # @return [Hash] Performance statistics
+        def statistics
+          {
+            memory_snapshots: @memory_snapshots.size,
+            current_memory: memory_usage,
+            performance_data: @performance_data,
+            gc_stats: defined?(GC.stat) ? GC.stat : {}
+          }
+        end
+
+        ##
+        # Reset performance tracking data
+        #
+        def reset!
+          @memory_snapshots.clear
+          @performance_data.clear
+        end
+
+        ##
+        # Check if performance optimizations are available
+        #
+        # @return [Hash] Available optimizations
+        def available_optimizations
+          {
+            oj_json: defined?(Oj),
+            gc_compact: defined?(GC) && GC.respond_to?(:compact),
+            gc_tune: defined?(GC.tune),
+            net_http_persistent: defined?(Net::HTTP::Persistent)
+          }
+        end
+
+        private
+
+        ##
+        # Record performance data
+        #
+        # @param label [String] Operation label
+        # @param duration [Float] Duration in seconds
+        # @param memory_delta [Integer] Memory change in bytes
+        def record_performance_data(label, duration, memory_delta)
+          @performance_data[label] ||= {
+            count: 0,
+            total_time: 0.0,
+            avg_time: 0.0,
+            min_time: Float::INFINITY,
+            max_time: 0.0,
+            total_memory: 0,
+            avg_memory: 0.0
+          }
+
+          data = @performance_data[label]
+          data[:count] += 1
+          data[:total_time] += duration
+          data[:avg_time] = data[:total_time] / data[:count]
+          data[:min_time] = [data[:min_time], duration].min
+          data[:max_time] = [data[:max_time], duration].max
+          data[:total_memory] += memory_delta
+          data[:avg_memory] = data[:total_memory].to_f / data[:count]
+        end
+
+        ##
+        # Format bytes for human-readable output
+        #
+        # @param bytes [Integer] Number of bytes
+        # @return [String] Formatted string
+        def format_bytes(bytes)
+          return "0 B" if bytes.zero?
+
+          units = %w[B KB MB GB TB]
+          exp = (Math.log(bytes.abs) / Math.log(1024)).floor
+          exp = [exp, units.length - 1].min
+
+          "#{(bytes / (1024.0**exp)).round(2)} #{units[exp]}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/utils/rails_detection.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+##
+# Utility module for Rails detection and compatibility
+#
+# Provides consistent Rails detection methods that can be used throughout
+# the A2A Ruby gem to handle Rails availability gracefully.
+#
+module A2A
+  module Utils
+    module RailsDetection
+      # Check if Rails is available and properly defined
+      # @return [Boolean] true if Rails is available
+      def rails_available?
+        defined?(::Rails) && ::Rails.respond_to?(:version)
+      end
+
+      # Check if Rails version requires validation
+      # @return [Boolean] true if Rails version is less than 6.0
+      def rails_version_requires_validation?
+        return false unless rails_available?
+
+        begin
+          ::Rails.version < "6.0"
+        rescue StandardError
+          # If we can't get the version, assume validation is not required
+          false
+        end
+      end
+
+      # Check if Rails version is supported (6.0+)
+      # @return [Boolean] true if Rails version is 6.0 or higher
+      def rails_version_supported?
+        return false unless rails_available?
+
+        begin
+          ::Rails.version >= "6.0"
+        rescue StandardError
+          false
+        end
+      end
+
+      # Get Rails logger if available
+      # @return [Logger, nil] Rails logger or nil if not available
+      def rails_logger
+        return nil unless rails_available?
+        return nil unless ::Rails.respond_to?(:logger)
+
+        ::Rails.logger
+      end
+
+      # Get Rails environment if available
+      # @return [String, nil] Rails environment or nil if not available
+      def rails_environment
+        return nil unless rails_available?
+        return nil unless ::Rails.respond_to?(:env)
+
+        ::Rails.env
+      end
+
+      # Get Rails application if available
+      # @return [Rails::Application, nil] Rails application or nil if not available
+      def rails_application
+        return nil unless rails_available?
+        return nil unless ::Rails.respond_to?(:application)
+
+        ::Rails.application
+      end
+
+      # Check if we're in a Rails production environment
+      # @return [Boolean] true if in Rails production environment
+      def rails_production?
+        env = rails_environment
+        env && env == "production"
+      end
+
+      # Check if we're in a Rails development environment
+      # @return [Boolean] true if in Rails development environment
+      def rails_development?
+        env = rails_environment
+        env && env == "development"
+      end
+
+      # Get Rails version string if available
+      # @return [String, nil] Rails version or nil if not available
+      def rails_version
+        return nil unless rails_available?
+
+        begin
+          ::Rails.version
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end