a2a-ruby 1.0.0

data/lib/a2a/protocol/json_rpc.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Try to use Oj for faster JSON parsing if available
+begin
+  require "oj"
+  OJ_AVAILABLE = true
+rescue LoadError
+  OJ_AVAILABLE = false
+end
+
+module A2A
+  module Protocol
+    ##
+    # JSON-RPC 2.0 implementation for A2A protocol
+    #
+    # This class provides parsing and building functionality for JSON-RPC 2.0 requests
+    # and responses, including support for batch requests and proper error handling.
+    # Optimized for performance with optional Oj JSON parser support.
+    #
+    # @see https://www.jsonrpc.org/specification JSON-RPC 2.0 Specification
+    class JsonRpc
+      # JSON-RPC 2.0 version string
+      JSONRPC_VERSION = "2.0"
+
+      # Standard JSON-RPC error codes
+      PARSE_ERROR = -32_700
+      INVALID_REQUEST = -32_600
+      METHOD_NOT_FOUND = -32_601
+      INVALID_PARAMS = -32_602
+      INTERNAL_ERROR = -32_603
+
+      # A2A-specific error codes
+      TASK_NOT_FOUND = -32_001
+      TASK_NOT_CANCELABLE = -32_002
+      INVALID_TASK_STATE = -32_003
+      AUTHENTICATION_REQUIRED = -32_004
+      AUTHORIZATION_FAILED = -32_005
+      RATE_LIMIT_EXCEEDED = -32_006
+      AGENT_UNAVAILABLE = -32_007
+      PROTOCOL_VERSION_MISMATCH = -32_008
+      CAPABILITY_NOT_SUPPORTED = -32_009
+      RESOURCE_EXHAUSTED = -32_010
+
+      ##
+      # Parse JSON string using optimized parser if available
+      #
+      # @param json_string [String] JSON string to parse
+      # @return [Hash, Array] Parsed JSON data
+      def self.parse_json(json_string)
+        if OJ_AVAILABLE
+          Oj.load(json_string, mode: :strict, symbol_keys: false)
+        else
+          JSON.parse(json_string)
+        end
+      end
+
+      ##
+      # Generate JSON string using optimized generator if available
+      #
+      # @param object [Object] Object to serialize
+      # @return [String] JSON string
+      def self.generate_json(object)
+        if OJ_AVAILABLE
+          Oj.dump(object, mode: :compat)
+        else
+          JSON.generate(object)
+        end
+      end
+
+      ##
+      # Parse a JSON-RPC 2.0 request from JSON string
+      #
+      # @param json_string [String] The JSON string to parse
+      # @return [Request, Array<Request>] Single request or array for batch requests
+      # @raise [A2A::Errors::ParseError] If JSON is invalid
+      # @raise [A2A::Errors::InvalidRequest] If request format is invalid
+      def self.parse_request(json_string)
+        # Performance optimization: early return for empty strings
+        return nil if json_string.nil? || (json_string.respond_to?(:empty?) && json_string.empty?)
+
+        # Ensure we have a string
+        json_string = json_string.to_s unless json_string.is_a?(String)
+
+        begin
+          # Use optimized JSON parser if available
+          parsed = parse_json(json_string)
+        rescue JSON::ParserError, Oj::ParseError => e
+          raise A2A::Errors::ParseError, "Invalid JSON: #{e.message}"
+        end
+
+        if parsed.is_a?(Array)
+          # Batch request
+          raise A2A::Errors::InvalidRequest, "Empty batch request" if parsed.empty?
+
+          # Performance optimization: use map! for in-place modification
+          parsed.map! { |req| parse_single_request(req) }
+        else
+          # Single request
+          parse_single_request(parsed)
+        end
+      end
+
+      ##
+      # Build a JSON-RPC 2.0 response
+      #
+      # @param result [Object, nil] The result value (mutually exclusive with error)
+      # @param error [Hash, nil] The error object (mutually exclusive with result)
+      # @param id [String, Integer, nil] The request ID
+      # @return [Hash] The response hash
+      def self.build_response(id:, **kwargs)
+        result_provided = kwargs.key?(:result)
+        error_provided = kwargs.key?(:error)
+
+        raise ArgumentError, "Cannot specify both result and error" if result_provided && error_provided
+        raise ArgumentError, "Must specify either result or error" unless result_provided || error_provided
+
+        response = {
+          jsonrpc: JSONRPC_VERSION,
+          id: id
+        }
+
+        if error_provided
+          response[:error] = normalize_error(kwargs[:error])
+        else
+          response[:result] = kwargs[:result]
+        end
+
+        response
+      end
+
+      ##
+      # Build a JSON-RPC 2.0 batch response
+      #
+      # @param responses [Array<Hash>] Array of individual responses
+      # @return [Array<Hash>] The batch response array
+      def self.build_batch_response(responses)
+        # Filter out notification responses (id: nil)
+        responses.reject { |resp| resp[:id].nil? }
+      end
+
+      ##
+      # Build an error response
+      #
+      # @param code [Integer] The error code
+      # @param message [String] The error message
+      # @param data [Object, nil] Additional error data
+      # @param id [String, Integer, nil] The request ID
+      # @return [Hash] The error response hash
+      def self.build_error_response(code:, message:, id:, data: nil)
+        error = { code: code, message: message }
+        error[:data] = data if data
+
+        build_response(error: error, id: id)
+      end
+
+      ##
+      # Check if a hash represents a valid JSON-RPC 2.0 request
+      #
+      # @param hash [Hash] The hash to validate
+      # @return [Boolean] True if valid request format
+      def self.valid_request?(hash)
+        return false unless hash.is_a?(Hash)
+        return false unless hash["jsonrpc"] == JSONRPC_VERSION
+        return false unless hash["method"].is_a?(String)
+
+        # id can be string, number, or null (for notifications)
+        id = hash["id"]
+        return false unless id.nil? || id.is_a?(String) || id.is_a?(Integer)
+
+        # params is optional but must be object or array if present
+        params = hash["params"]
+        return false if params && !params.is_a?(Hash) && !params.is_a?(Array)
+
+        true
+      end
+
+      private_class_method def self.parse_single_request(hash)
+        raise A2A::Errors::InvalidRequest, "Invalid request format" unless valid_request?(hash)
+
+        Request.new(
+          jsonrpc: hash["jsonrpc"],
+          method: hash["method"],
+          params: hash["params"] || {},
+          id: hash["id"]
+        )
+      end
+
+      private_class_method def self.normalize_error(error)
+        if error.is_a?(A2A::Errors::A2AError)
+          error.to_json_rpc_error
+        elsif error.is_a?(Hash)
+          error
+        else
+          { code: INTERNAL_ERROR, message: error.to_s }
+        end
+      end
+    end
+
+    ##
+    # Represents a JSON-RPC 2.0 request
+    class Request
+      attr_reader :jsonrpc, :method, :params, :id
+
+      ##
+      # Initialize a new request
+      #
+      # @param jsonrpc [String] The JSON-RPC version (should be "2.0")
+      # @param method [String] The method name
+      # @param params [Hash, Array] The method parameters
+      # @param id [String, Integer, nil] The request ID (nil for notifications)
+      def initialize(jsonrpc:, method:, params: {}, id: nil)
+        @jsonrpc = jsonrpc
+        @method = method
+        @params = params
+        @id = id
+      end
+
+      ##
+      # Check if this is a notification (no response expected)
+      #
+      # @return [Boolean] True if this is a notification
+      def notification?
+        @id.nil?
+      end
+
+      ##
+      # Convert to hash representation
+      #
+      # @return [Hash] The request as a hash
+      def to_h
+        hash = {
+          jsonrpc: @jsonrpc,
+          method: @method
+        }
+
+        hash[:params] = @params unless @params.nil? || (@params.respond_to?(:empty?) && @params.empty?)
+        hash[:id] = @id unless @id.nil?
+
+        hash
+      end
+
+      ##
+      # Convert to JSON string
+      #
+      # @return [String] The request as JSON
+      def to_json(*_args)
+        # Use optimized JSON generator if available
+        JsonRpc.generate_json(to_h)
+      end
+    end
+  end
+end

data/lib/a2a/protocol/message.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Placeholder - will be implemented in task 2.2
+module A2A
+  module Protocol
+    # Placeholder - will be implemented in task 2.2
+  end
+end

data/lib/a2a/protocol/task.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Placeholder - will be implemented in task 6.1
+module A2A
+  module Protocol
+    # Placeholder - will be implemented in task 6.1
+  end
+end

data/lib/a2a/rails/a2a_controller.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require_relative "../utils/rails_detection"
+
+##
+# Main controller for A2A Rails engine
+#
+# This controller handles all A2A protocol endpoints including JSON-RPC requests,
+# agent card serving, and streaming responses.
+#
+module A2A
+  module Rails
+    class A2aController < ApplicationController
+      include A2A::Rails::ControllerHelpers
+      include A2A::Utils::RailsDetection
+
+      # Skip CSRF protection for A2A endpoints
+      skip_before_action :verify_authenticity_token
+
+      # Handle JSON-RPC requests
+      def rpc
+        request_body = request.body.read
+
+        begin
+          json_rpc_request = A2A::Protocol::JsonRpc.parse_request(request_body)
+
+          # Handle batch requests
+          if json_rpc_request.is_a?(Array)
+            responses = json_rpc_request.map { |req| handle_single_request(req) }
+            render json: responses
+          else
+            response = handle_single_request(json_rpc_request)
+            render json: response
+          end
+        rescue A2A::Errors::A2AError => e
+          render json: build_error_response(e), status: :bad_request
+        rescue StandardError => e
+          error = A2A::Errors::InternalError.new(e.message)
+          render json: build_error_response(error), status: :internal_server_error
+        end
+      end
+
+      # Serve agent card
+      def agent_card
+        card = generate_agent_card
+
+        # Support different output formats
+        case request.format.symbol
+        when :json
+          render json: card.to_h
+        when :jws
+          # TODO: Implement JWS signing
+          render json: { error: "JWS format not yet implemented" }, status: :not_implemented
+        else
+          render json: card.to_h
+        end
+      rescue StandardError => e
+        render json: { error: e.message }, status: :internal_server_error
+      end
+
+      # Serve authenticated agent card
+      def authenticated_agent_card
+        # Ensure authentication is present
+        unless authenticated?
+          render json: { error: "Authentication required" }, status: :unauthorized
+          return
+        end
+
+        card = generate_authenticated_agent_card
+        render json: card.to_h
+      rescue StandardError => e
+        render json: { error: e.message }, status: :internal_server_error
+      end
+
+      # List capabilities
+      def capabilities
+        capabilities = collect_capabilities
+        render json: { capabilities: capabilities }
+      rescue StandardError => e
+        render json: { error: e.message }, status: :internal_server_error
+      end
+
+      # Health check endpoint
+      def health
+        render json: {
+          status: "healthy",
+          version: A2A::VERSION,
+          timestamp: Time.now.iso8601,
+          rails_version: rails_version || "unknown"
+        }
+      end
+
+      # Server-Sent Events streaming endpoint
+      def stream
+        task_id = params[:task_id]
+
+        begin
+          task = A2A::Server::TaskManager.instance.get_task(task_id)
+
+          response.headers["Content-Type"] = "text/event-stream"
+          response.headers["Cache-Control"] = "no-cache"
+          response.headers["Connection"] = "keep-alive"
+
+          # Set up SSE stream
+          sse = A2A::Transport::SSE.new(response.stream)
+
+          # Send initial task status
+          sse.write_event("task-status", task.to_h)
+
+          # Subscribe to task updates
+          subscription = A2A::Server::TaskManager.instance.subscribe_to_task(task_id) do |event|
+            case event
+            when A2A::Types::TaskStatusUpdateEvent
+              sse.write_event("task-status-update", event.to_h)
+            when A2A::Types::TaskArtifactUpdateEvent
+              sse.write_event("task-artifact-update", event.to_h)
+            end
+          end
+
+          # Keep connection alive until client disconnects
+          loop do
+            break if response.stream.closed?
+
+            sleep 1
+            sse.write_event("heartbeat", { timestamp: Time.now.iso8601 })
+          end
+        rescue A2A::Errors::TaskNotFound
+          render json: { error: "Task not found" }, status: :not_found
+        rescue StandardError => e
+          render json: { error: e.message }, status: :internal_server_error
+        ensure
+          subscription&.unsubscribe
+          response.stream.close
+        end
+      end
+
+      # Webhook endpoint for push notifications
+      def webhook
+        task_id = params[:task_id]
+
+        begin
+          # Verify webhook authentication if configured
+          verify_webhook_authentication! if webhook_authentication_required?
+
+          # Process webhook payload
+          payload = JSON.parse(request.body.read)
+
+          # Handle different webhook types
+          case payload["type"]
+          when "task_status_update"
+            handle_task_status_webhook(task_id, payload)
+          when "task_artifact_update"
+            handle_task_artifact_webhook(task_id, payload)
+          else
+            render json: { error: "Unknown webhook type" }, status: :bad_request
+            return
+          end
+
+          render json: { status: "processed" }
+        rescue JSON::ParserError
+          render json: { error: "Invalid JSON payload" }, status: :bad_request
+        rescue A2A::Errors::TaskNotFound
+          render json: { error: "Task not found" }, status: :not_found
+        rescue A2A::Errors::AuthenticationError
+          render json: { error: "Webhook authentication failed" }, status: :unauthorized
+        rescue StandardError => e
+          render json: { error: e.message }, status: :internal_server_error
+        end
+      end
+
+      private
+
+      def handle_single_request(json_rpc_request)
+        # Delegate to the A2A request handler
+        handle_a2a_request(json_rpc_request)
+      rescue A2A::Errors::A2AError => e
+        build_error_response(e, json_rpc_request.id)
+      rescue StandardError => e
+        error = A2A::Errors::InternalError.new(e.message)
+        build_error_response(error, json_rpc_request.id)
+      end
+
+      def build_error_response(error, id = nil)
+        A2A::Protocol::JsonRpc.build_response(
+          error: error.to_json_rpc_error,
+          id: id
+        )
+      end
+
+      def generate_authenticated_agent_card
+        # Generate extended agent card with authentication context
+        card = generate_agent_card
+
+        # Add authenticated-specific information
+        card_hash = card.to_h
+        card_hash[:authenticated_user] = current_user_info if respond_to?(:current_user_info)
+        card_hash[:permissions] = current_user_permissions if respond_to?(:current_user_permissions)
+
+        A2A::Types::AgentCard.from_h(card_hash)
+      end
+
+      def collect_capabilities
+        # Collect all registered A2A capabilities from controllers
+        capabilities = []
+
+        # Scan all controllers that include A2A::Server::Agent
+        ObjectSpace.each_object(Class) do |klass|
+          if klass < ActionController::Base && klass.included_modules.include?(A2A::Server::Agent)
+            capabilities.concat(klass._a2a_capabilities || [])
+          end
+        end
+
+        capabilities.map(&:to_h)
+      end
+
+      def authenticated?
+        # Check if request is authenticated
+        # This can be overridden by applications to integrate with their auth system
+        request.headers["Authorization"].present? ||
+          (respond_to?(:current_user) && current_user.present?)
+      end
+
+      def webhook_authentication_required?
+        A2A.config.webhook_authentication_required || false
+      end
+
+      def verify_webhook_authentication!
+        # Verify webhook signature or token
+        # This should be implemented based on the specific authentication method
+        auth_header = request.headers["Authorization"]
+
+        return if auth_header.present?
+
+        raise A2A::Errors::AuthenticationError, "Missing webhook authentication"
+
+        # TODO: Implement specific webhook authentication logic
+        # This could verify HMAC signatures, JWT tokens, etc.
+      end
+
+      def handle_task_status_webhook(task_id, payload)
+        # Process task status update webhook
+        status_data = payload["status"]
+        status = A2A::Types::TaskStatus.from_h(status_data)
+
+        A2A::Server::TaskManager.instance.update_task_status(task_id, status)
+      end
+
+      def handle_task_artifact_webhook(task_id, payload)
+        # Process task artifact update webhook
+        artifact_data = payload["artifact"]
+        artifact = A2A::Types::Artifact.from_h(artifact_data)
+        append = payload["append"] || false
+
+        A2A::Server::TaskManager.instance.update_task_artifact(task_id, artifact, append: append)
+      end
+    end
+  end
+end