a2a-ruby 1.0.0

data/lib/a2a/rails/generators/migration_generator.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+##
+# Rails generator for creating A2A database migrations
+#
+# This generator creates database tables needed for A2A task storage,
+# push notification configurations, and other persistent data.
+#
+# @example
+#   rails generate a2a:migration
+#   rails generate a2a:migration --skip-tasks
+#   rails generate a2a:migration --with-indexes
+#
+module A2A
+  module Rails
+    module Generators
+      class MigrationGenerator < ActiveRecord::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :skip_tasks, type: :boolean, default: false,
+                                  desc: "Skip creating tasks table"
+
+        class_option :skip_push_notifications, type: :boolean, default: false,
+                                               desc: "Skip creating push notification config table"
+
+        class_option :with_indexes, type: :boolean, default: true,
+                                    desc: "Add database indexes for performance"
+
+        class_option :table_prefix, type: :string, default: "a2a_",
+                                    desc: "Prefix for A2A table names"
+
+        desc "Generate A2A database migrations"
+
+        def create_tasks_migration
+          return if options[:skip_tasks]
+
+          migration_template "create_a2a_tasks.rb",
+                             "db/migrate/create_#{table_prefix}tasks.rb",
+                             migration_version: migration_version
+
+          say "Created tasks migration", :green
+        end
+
+        def create_push_notifications_migration
+          return if options[:skip_push_notifications]
+
+          migration_template "create_a2a_push_notification_configs.rb",
+                             "db/migrate/create_#{table_prefix}push_notification_configs.rb",
+                             migration_version: migration_version
+
+          say "Created push notification configs migration", :green
+        end
+
+        def create_indexes_migration
+          return unless options[:with_indexes]
+
+          migration_template "add_a2a_indexes.rb",
+                             "db/migrate/add_#{table_prefix}indexes.rb",
+                             migration_version: migration_version
+
+          say "Created indexes migration", :green
+        end
+
+        def create_models
+          template "task_model.rb", "app/models/#{table_prefix}task.rb"
+          template "push_notification_config_model.rb",
+                   "app/models/#{table_prefix}push_notification_config.rb"
+
+          say "Created A2A models", :green
+        end
+
+        def show_post_generation_instructions
+          say "\n#{'=' * 60}", :green
+          say "A2A database migrations generated successfully!", :green
+          say "=" * 60, :green
+
+          say "\nNext steps:", :yellow
+          say "1. Review the generated migrations in db/migrate/"
+          say "2. Run 'rails db:migrate' to create the tables"
+          say "3. Customize the models in app/models/ if needed"
+
+          say "\nGenerated tables:", :yellow
+          say "  #{table_prefix}tasks - Stores A2A task data"
+          say "  #{table_prefix}push_notification_configs - Stores push notification settings"
+
+          if options[:with_indexes]
+            say "\nPerformance indexes will be created for:"
+            say "  - Task lookups by ID and context_id"
+            say "  - Task status filtering"
+            say "  - Push notification config lookups"
+          end
+
+          say "\nConfiguration:", :yellow
+          say "Update config/initializers/a2a.rb to use database storage:"
+          say "  config.task_storage = :database"
+
+          say "\nFor more information, visit: https://a2a-protocol.org/sdk/ruby/storage/", :blue
+        end
+
+        private
+
+        def migration_version
+          if ::Rails.version >= "5.0"
+            "[#{::Rails::VERSION::MAJOR}.#{::Rails::VERSION::MINOR}]"
+          else
+            ""
+          end
+        end
+
+        def table_prefix
+          options[:table_prefix]
+        end
+
+        def tasks_table_name
+          "#{table_prefix}tasks"
+        end
+
+        def push_notification_configs_table_name
+          "#{table_prefix}push_notification_configs"
+        end
+
+        def with_indexes?
+          options[:with_indexes]
+        end
+
+        def model_class_name(base_name)
+          "#{table_prefix.classify}#{base_name.classify}"
+        end
+
+        def model_file_name(base_name)
+          "#{table_prefix}#{base_name.underscore}"
+        end
+
+        # Helper methods for templates
+        def json_column_type
+          # Use jsonb for PostgreSQL, json for others
+          if postgresql?
+            "jsonb"
+          else
+            "json"
+          end
+        end
+
+        def text_column_type
+          # Use text for larger content
+          "text"
+        end
+
+        def uuid_column_type
+          if postgresql?
+            "uuid"
+          else
+            "string"
+          end
+        end
+
+        def postgresql?
+          # Try to detect PostgreSQL adapter
+          return false unless defined?(ActiveRecord::Base)
+
+          begin
+            ActiveRecord::Base.connection.adapter_name.downcase.include?("postgresql")
+          rescue StandardError
+            false
+          end
+        end
+
+        def mysql?
+          return false unless defined?(ActiveRecord::Base)
+
+          begin
+            adapter_name = ActiveRecord::Base.connection.adapter_name.downcase
+            adapter_name.include?("mysql") || adapter_name.include?("trilogy")
+          rescue StandardError
+            false
+          end
+        end
+
+        def sqlite?
+          return false unless defined?(ActiveRecord::Base)
+
+          begin
+            ActiveRecord::Base.connection.adapter_name.downcase.include?("sqlite")
+          rescue StandardError
+            false
+          end
+        end
+
+        # Generate appropriate column definitions based on database adapter
+        def id_column_definition
+          if postgresql?
+            "t.uuid :id, primary_key: true, default: 'gen_random_uuid()'"
+          else
+            "t.string :id, primary_key: true, limit: 36"
+          end
+        end
+
+        def uuid_column_definition(name, **options)
+          if postgresql?
+            "t.uuid :#{name}#{format_column_options(options)}"
+          else
+            "t.string :#{name}, limit: 36#{format_column_options(options)}"
+          end
+        end
+
+        def json_column_definition(name, **options)
+          "t.#{json_column_type} :#{name}#{format_column_options(options)}"
+        end
+
+        def format_column_options(options)
+          return "" if options.empty?
+
+          formatted_options = options.map do |key, value|
+            case value
+            when String
+              "#{key}: '#{value}'"
+            when Symbol
+              "#{key}: :#{value}"
+            else
+              "#{key}: #{value}"
+            end
+          end
+
+          ", #{formatted_options.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/generators/templates/add_a2a_indexes.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class Add<%= table_prefix.classify %>Indexes < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Composite indexes for common query patterns
+    
+    # Tasks table indexes
+    add_index :<%= tasks_table_name %>, [:context_id, :status_state], 
+              name: "index_<%= tasks_table_name %>_on_context_and_status"
+    
+    add_index :<%= tasks_table_name %>, [:status_state, :created_at], 
+              name: "index_<%= tasks_table_name %>_on_status_and_created"
+    
+    add_index :<%= tasks_table_name %>, [:type, :status_state], 
+              name: "index_<%= tasks_table_name %>_on_type_and_status"
+    
+    # Index for soft delete queries
+    add_index :<%= tasks_table_name %>, [:deleted_at, :status_state], 
+              name: "index_<%= tasks_table_name %>_on_deleted_and_status"
+    
+    <% if postgresql? %>
+    # PostgreSQL-specific partial indexes for better performance
+    add_index :<%= tasks_table_name %>, :id, 
+              where: "deleted_at IS NULL",
+              name: "index_<%= tasks_table_name %>_active_tasks"
+    
+    add_index :<%= tasks_table_name %>, :status_state, 
+              where: "deleted_at IS NULL AND status_state IN ('submitted', 'working')",
+              name: "index_<%= tasks_table_name %>_active_processing"
+    
+    # JSON path indexes for common metadata queries
+    add_index :<%= tasks_table_name %>, "(metadata->>'priority')", 
+              name: "index_<%= tasks_table_name %>_on_priority"
+    
+    add_index :<%= tasks_table_name %>, "(metadata->>'source')", 
+              name: "index_<%= tasks_table_name %>_on_source"
+    <% end %>
+    
+    # Push notification configs indexes
+    add_index :<%= push_notification_configs_table_name %>, [:task_id, :active], 
+              name: "index_<%= push_notification_configs_table_name %>_on_task_and_active"
+    
+    add_index :<%= push_notification_configs_table_name %>, [:active, :last_success_at], 
+              name: "index_<%= push_notification_configs_table_name %>_on_active_and_success"
+    
+    # Index for retry logic
+    add_index :<%= push_notification_configs_table_name %>, [:retry_count, :last_failure_at], 
+              name: "index_<%= push_notification_configs_table_name %>_on_retry"
+    
+    <% if postgresql? %>
+    # PostgreSQL partial index for active configs only
+    add_index :<%= push_notification_configs_table_name %>, :task_id, 
+              where: "active = true AND deleted_at IS NULL",
+              name: "index_<%= push_notification_configs_table_name %>_active_only"
+    <% end %>
+  end
+end

data/lib/a2a/rails/generators/templates/agent_controller.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+##
+# <%= controller_class_name %>
+#
+# A2A Agent controller for <%= class_name.humanize.downcase %> functionality.
+# This controller provides A2A protocol endpoints for agent-to-agent communication.
+#
+class <%= controller_class_name %> < <%= controller_parent_class %>
+  include A2A::Rails::ControllerHelpers
+
+  # Configure this agent
+  a2a_agent name: "<%= class_name.humanize %> Agent",
+            description: "<%= agent_description %>",
+            version: "1.0.0",
+            tags: <%= agent_tags.inspect %>
+
+  <% if with_authentication? %>
+  # Configure authentication for specific methods
+  <%= authentication_config %>
+  <% end %>
+
+  <% if skills.any? %>
+  # Define agent skills
+  <%= generate_skill_definitions %>
+  <% else %>
+  # Define agent skills
+  a2a_skill "default" do |skill|
+    skill.description = "<%= class_name.humanize %> default functionality"
+    skill.tags = ["<%= class_name.underscore %>", "default"]
+    skill.examples = [
+      {
+        input: { action: "process" },
+        output: { result: "processed" }
+      }
+    ]
+  end
+  <% end %>
+
+  # A2A method implementations
+
+  <% if skills.any? %>
+  <%= generate_skill_methods %>
+  <% else %>
+  ##
+  # Default processing method
+  #
+  # @param params [Hash] Request parameters
+  # @return [Hash] Processing result
+  #
+  a2a_method "process" do |params|
+    # TODO: Implement your <%= class_name.humanize.downcase %> logic here
+    {
+      agent: "<%= class_name %>",
+      action: "process",
+      params: params,
+      result: "Processing completed",
+      timestamp: Time.now.iso8601
+    }
+  end
+  <% end %>
+
+  ##
+  # Get agent status
+  #
+  # @param params [Hash] Request parameters (unused)
+  # @return [Hash] Status information
+  #
+  a2a_method "status" do |params|
+    {
+      agent: "<%= class_name %>",
+      status: "active",
+      version: "1.0.0",
+      capabilities: self.class._a2a_capabilities&.map(&:name) || [],
+      methods: self.class._a2a_methods&.keys || [],
+      timestamp: Time.now.iso8601
+    }
+  end
+
+  # Standard Rails actions
+
+  ##
+  # Serve the agent card
+  #
+  def agent_card
+    render_agent_card
+  end
+
+  ##
+  # Handle JSON-RPC requests
+  #
+  def rpc
+    handle_a2a_rpc
+  end
+
+  <% if with_authentication? %>
+  private
+
+  # Override authentication methods as needed
+  def current_user_info
+    if respond_to?(:current_user) && current_user.present?
+      {
+        id: current_user.id,
+        email: current_user.email,
+        name: current_user.name || current_user.email
+      }
+    else
+      { id: "anonymous", name: "Anonymous User" }
+    end
+  end
+
+  def current_user_permissions
+    # Customize based on your authorization system
+    if respond_to?(:current_user) && current_user.present?
+      # Example: return user roles or permissions
+      current_user.roles&.map(&:name) || ["user"]
+    else
+      ["guest"]
+    end
+  end
+  <% end %>
+end

data/lib/a2a/rails/generators/templates/agent_controller_spec.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= controller_class_name %>, type: :controller do
+  describe "A2A Agent functionality" do
+    describe "GET #agent_card" do
+      it "returns the agent card" do
+        get :agent_card
+        
+        expect(response).to have_http_status(:ok)
+        expect(response.content_type).to eq("application/json; charset=utf-8")
+        
+        card = JSON.parse(response.body)
+        expect(card).to include(
+          "name" => "<%= class_name.humanize %> Agent",
+          "description" => "<%= agent_description %>",
+          "version" => "1.0.0"
+        )
+      end
+    end
+
+    describe "POST #rpc" do
+      let(:valid_rpc_request) do
+        {
+          jsonrpc: "2.0",
+          method: "status",
+          params: {},
+          id: 1
+        }
+      end
+
+      it "handles valid JSON-RPC requests" do
+        post :rpc, body: valid_rpc_request.to_json, as: :json
+        
+        expect(response).to have_http_status(:ok)
+        
+        rpc_response = JSON.parse(response.body)
+        expect(rpc_response).to include(
+          "jsonrpc" => "2.0",
+          "id" => 1
+        )
+        expect(rpc_response["result"]).to be_present
+      end
+
+      it "returns error for invalid JSON-RPC" do
+        post :rpc, body: "invalid json", as: :json
+        
+        expect(response).to have_http_status(:bad_request)
+        
+        error_response = JSON.parse(response.body)
+        expect(error_response["error"]).to be_present
+      end
+
+      <% if skills.any? %>
+      <% skills.each do |skill| %>
+      describe "<%= skill %> method" do
+        let(:<%= skill %>_request) do
+          {
+            jsonrpc: "2.0",
+            method: "<%= skill.underscore %>",
+            params: { test: "data" },
+            id: 1
+          }
+        end
+
+        it "handles <%= skill %> requests" do
+          post :rpc, body: <%= skill %>_request.to_json, as: :json
+          
+          expect(response).to have_http_status(:ok)
+          
+          rpc_response = JSON.parse(response.body)
+          expect(rpc_response["result"]).to include("skill" => "<%= skill %>")
+        end
+      end
+      <% end %>
+      <% end %>
+
+      describe "status method" do
+        let(:status_request) do
+          {
+            jsonrpc: "2.0",
+            method: "status",
+            params: {},
+            id: 1
+          }
+        end
+
+        it "returns agent status information" do
+          post :rpc, body: status_request.to_json, as: :json
+          
+          expect(response).to have_http_status(:ok)
+          
+          rpc_response = JSON.parse(response.body)
+          status_result = rpc_response["result"]
+          
+          expect(status_result).to include(
+            "agent" => "<%= class_name %>",
+            "status" => "active",
+            "version" => "1.0.0"
+          )
+        end
+      end
+    end
+
+    <% if with_authentication? %>
+    describe "authentication" do
+      context "when authentication is required" do
+        <% authentication_methods.each do |method| %>
+        describe "<%= method %> method" do
+          let(:auth_request) do
+            {
+              jsonrpc: "2.0",
+              method: "<%= method %>",
+              params: {},
+              id: 1
+            }
+          end
+
+          it "requires authentication" do
+            post :rpc, body: auth_request.to_json, as: :json
+            
+            expect(response).to have_http_status(:unauthorized)
+          end
+
+          it "allows authenticated requests" do
+            # Mock authentication - customize based on your auth system
+            allow(controller).to receive(:current_user_authenticated?).and_return(true)
+            allow(controller).to receive(:current_user_info).and_return({ id: 1, name: "Test User" })
+            
+            post :rpc, body: auth_request.to_json, as: :json
+            
+            expect(response).to have_http_status(:ok)
+          end
+        end
+        <% end %>
+      end
+    end
+    <% end %>
+  end
+
+  describe "A2A protocol compliance" do
+    it "includes A2A::Rails::ControllerHelpers" do
+      expect(controller.class.included_modules).to include(A2A::Rails::ControllerHelpers)
+    end
+
+    it "has A2A capabilities defined" do
+      capabilities = controller.class._a2a_capabilities
+      expect(capabilities).to be_present
+      expect(capabilities).to be_an(Array)
+    end
+
+    it "has A2A methods defined" do
+      methods = controller.class._a2a_methods
+      expect(methods).to be_present
+      expect(methods).to be_a(Hash)
+      expect(methods).to include("status")
+    end
+  end
+end