forthic 0.2.0 → 0.3.0

data/lib/forthic/grpc/server.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require 'grpc'
+require_relative 'forthic_runtime_services_pb'
+require_relative 'forthic_runtime_pb'
+require_relative 'serializer'
+require_relative '../interpreter'
+
+module Forthic
+  module Grpc
+    # ForthicRuntimeServicer - Ruby gRPC server for Forthic runtime
+    #
+    # Implements the ForthicRuntime gRPC service with full stack-based execution
+    # and module discovery capabilities. Follows the pattern established in Python
+    # and TypeScript implementations.
+    #
+    # Features:
+    # - Execute individual words with stack state
+    # - Execute sequences of words (batched optimization)
+    # - List available runtime-specific modules
+    # - Get detailed module information with word metadata
+    # - Rich error handling with stack traces and context
+    class ForthicRuntimeServicer < Forthic::ForthicRuntime::Service
+      # Standard library modules (available in all runtimes)
+      # These are excluded from ListModules as they're not runtime-specific
+      STANDARD_MODULES = %w[
+        array record string math datetime json boolean core
+      ].freeze
+
+      attr_reader :runtime_modules
+
+      def initialize(modules_config = nil)
+        super()
+        @runtime_modules = {}
+
+        # TODO: Implement module loading from config when needed
+        # For now, we only have stdlib modules in Ruby
+        if modules_config
+          puts "[SERVER] Module config support not yet implemented: #{modules_config}"
+        end
+      end
+
+      # Execute a single word in the Ruby runtime
+      #
+      # @param request [Forthic::ExecuteWordRequest] The execution request
+      # @param _call [GRPC::ActiveCall] The gRPC call context
+      # @return [Forthic::ExecuteWordResponse] The execution response
+      def execute_word(request, _call)
+        word_name = request.word_name
+        puts "[EXECUTE_WORD] word='#{word_name}' stack_size=#{request.stack.length}"
+
+        # Deserialize the stack
+        stack = request.stack.map { |sv| Serializer.deserialize_value(sv) }
+        puts "[EXECUTE_WORD] Deserialized stack: #{stack.map { |x| x.class.name }}"
+
+        # Execute word with stack-based execution
+        result_stack = execute_with_stack(word_name, stack)
+        puts "[EXECUTE_WORD] Result stack: #{result_stack.map { |x| x.class.name }}"
+
+        # Serialize result stack
+        response_stack = result_stack.map { |v| Serializer.serialize_value(v) }
+        puts "[EXECUTE_WORD] Success"
+
+        Forthic::ExecuteWordResponse.new(result_stack: response_stack)
+      rescue => e
+        puts "[EXECUTE_WORD] ERROR: #{e.message}"
+        puts "[EXECUTE_WORD] Backtrace:"
+        puts e.backtrace[0..5].join("\n")
+
+        # Build rich error context
+        error = build_error_info(e, word_name)
+        Forthic::ExecuteWordResponse.new(error: error)
+      end
+
+      # Execute a sequence of words in one batch (optimization for remote execution)
+      #
+      # @param request [Forthic::ExecuteSequenceRequest] The execution request
+      # @param _call [GRPC::ActiveCall] The gRPC call context
+      # @return [Forthic::ExecuteSequenceResponse] The execution response
+      def execute_sequence(request, _call)
+        word_names = request.word_names.to_a
+        puts "[EXECUTE_SEQUENCE] words=#{word_names} stack_size=#{request.stack.length}"
+
+        # Deserialize the initial stack
+        stack = request.stack.map { |sv| Serializer.deserialize_value(sv) }
+        puts "[EXECUTE_SEQUENCE] Deserialized stack: #{stack.map { |x| x.class.name }}"
+
+        # Execute the word sequence
+        result_stack = execute_sequence_with_stack(word_names, stack)
+        puts "[EXECUTE_SEQUENCE] Result stack: #{result_stack.map { |x| x.class.name }}"
+
+        # Serialize result stack
+        response_stack = result_stack.map { |v| Serializer.serialize_value(v) }
+        puts "[EXECUTE_SEQUENCE] Success"
+
+        Forthic::ExecuteSequenceResponse.new(result_stack: response_stack)
+      rescue => e
+        puts "[EXECUTE_SEQUENCE] ERROR: #{e.message}"
+        puts "[EXECUTE_SEQUENCE] Backtrace:"
+        puts e.backtrace[0..5].join("\n")
+
+        # Build rich error context with word sequence
+        error = build_error_info(e, nil, { 'word_sequence' => word_names.join(', ') })
+        Forthic::ExecuteSequenceResponse.new(error: error)
+      end
+
+      # List available runtime-specific modules (excludes standard library)
+      #
+      # @param request [Forthic::ListModulesRequest] The request (unused)
+      # @param _call [GRPC::ActiveCall] The gRPC call context
+      # @return [Forthic::ListModulesResponse] List of module summaries
+      def list_modules(request, _call)
+        modules = []
+
+        # Only return runtime-specific modules (not standard library)
+        @runtime_modules.each do |name, mod|
+          # Get module metadata
+          word_count = if mod.respond_to?(:get_word_docs)
+                         mod.get_word_docs.length
+                       else
+                         mod.exportable.length
+                       end
+
+          summary = Forthic::ModuleSummary.new(
+            name: name,
+            description: "Ruby-specific #{name} module",
+            word_count: word_count,
+            runtime_specific: true
+          )
+          modules << summary
+        end
+
+        Forthic::ListModulesResponse.new(modules: modules)
+      rescue => e
+        puts "[LIST_MODULES] ERROR: #{e.message}"
+        Forthic::ListModulesResponse.new(modules: [])
+      end
+
+      # Get detailed information about a specific module
+      #
+      # @param request [Forthic::GetModuleInfoRequest] The request with module name
+      # @param _call [GRPC::ActiveCall] The gRPC call context
+      # @return [Forthic::GetModuleInfoResponse] Module information with word details
+      def get_module_info(request, _call)
+        module_name = request.module_name
+
+        unless @runtime_modules.key?(module_name)
+          puts "[GET_MODULE_INFO] Module '#{module_name}' not found"
+          return Forthic::GetModuleInfoResponse.new(
+            name: module_name,
+            description: "Module not found",
+            words: []
+          )
+        end
+
+        mod = @runtime_modules[module_name]
+        words = []
+
+        # Use DecoratedModule.get_word_docs() if available
+        if mod.respond_to?(:get_word_docs)
+          # DecoratedModule with word/direct_word decorators
+          word_docs = mod.get_word_docs
+          word_docs.each do |doc|
+            word_info = Forthic::WordInfo.new(
+              name: doc[:name],
+              stack_effect: doc[:stack_effect],
+              description: doc[:description]
+            )
+            words << word_info
+          end
+        else
+          # Fallback: Extract word information from exportable words
+          mod.exportable.each do |word_name|
+            word_info = Forthic::WordInfo.new(
+              name: word_name,
+              stack_effect: "( -- )",
+              description: "#{word_name} word from #{module_name} module"
+            )
+            words << word_info
+          end
+        end
+
+        Forthic::GetModuleInfoResponse.new(
+          name: module_name,
+          description: "Ruby-specific #{module_name} module",
+          words: words
+        )
+      rescue => e
+        puts "[GET_MODULE_INFO] ERROR: #{e.message}"
+        puts e.backtrace[0..5].join("\n")
+        Forthic::GetModuleInfoResponse.new(
+          name: module_name || "unknown",
+          description: "Error getting module info",
+          words: []
+        )
+      end
+
+      private
+
+      # Execute a word with given stack state
+      #
+      # @param word_name [String] The word to execute
+      # @param stack [Array] The initial stack state
+      # @return [Array] The resulting stack
+      def execute_with_stack(word_name, stack)
+        # Create a fresh interpreter for this execution
+        # (to avoid state pollution between requests)
+        interp = StandardInterpreter.new
+
+        # Register runtime-specific modules in fresh interpreter
+        @runtime_modules.each do |name, mod|
+          interp.register_module(mod)
+        end
+
+        # Import all runtime-specific modules so their words are available
+        unless @runtime_modules.empty?
+          module_names = @runtime_modules.keys
+          interp.use_modules(module_names)
+        end
+
+        # Push all stack items onto interpreter stack
+        stack.each do |item|
+          interp.stack_push(item)
+        end
+
+        # Execute the word
+        interp.run(word_name)
+
+        # Get resulting stack as a list
+        interp.get_stack.get_items
+      end
+
+      # Execute a sequence of words in one go (batched execution)
+      #
+      # @param word_names [Array<String>] List of word names to execute in order
+      # @param stack [Array] Initial stack state
+      # @return [Array] Final stack state after executing all words
+      def execute_sequence_with_stack(word_names, stack)
+        # Create a fresh interpreter for this execution
+        interp = StandardInterpreter.new
+
+        # Register runtime-specific modules
+        @runtime_modules.each do |name, mod|
+          interp.register_module(mod)
+        end
+
+        # Import all runtime-specific modules
+        unless @runtime_modules.empty?
+          module_names = @runtime_modules.keys
+          interp.use_modules(module_names)
+        end
+
+        # Push all stack items onto interpreter stack
+        stack.each do |item|
+          interp.stack_push(item)
+        end
+
+        # Execute each word in sequence
+        word_names.each do |word_name|
+          interp.run(word_name)
+        end
+
+        # Get resulting stack as a list
+        interp.get_stack.get_items
+      end
+
+      # Build rich error information from an exception
+      #
+      # @param exception [Exception] The exception that was raised
+      # @param word_name [String, nil] The word that was being executed (optional)
+      # @param context [Hash, nil] Additional context information (optional)
+      # @return [Forthic::ErrorInfo] ErrorInfo protobuf message with rich context
+      def build_error_info(exception, word_name = nil, context = nil)
+        # Extract stack trace
+        stack_trace = exception.backtrace || []
+
+        # Get error type name
+        error_type = exception.class.name
+
+        puts "[_build_error_info] error_type=#{error_type}, stack_trace_lines=#{stack_trace.length}"
+        puts "[_build_error_info] word_name=#{word_name}, context=#{context}"
+
+        # Build context dictionary
+        error_context = {}
+        error_context['word_name'] = word_name if word_name
+        error_context.merge!(context) if context
+
+        puts "[_build_error_info] error_context=#{error_context}"
+
+        # Build ErrorInfo message
+        error_info = Forthic::ErrorInfo.new(
+          message: exception.message,
+          runtime: "ruby",
+          stack_trace: stack_trace,
+          error_type: error_type
+        )
+
+        # Try to extract module information from the backtrace
+        module_name = nil
+        word_location = nil
+
+        stack_trace.each do |line|
+          # Check if this is a Forthic module
+          if line.include?('forthic/modules/')
+            module_name = line.split('forthic/modules/').last.split('.').first.gsub('_module', '')
+            word_location = line
+            break
+          elsif line.include?('forthic/grpc/')
+            word_location = line
+          end
+        end
+
+        # Add optional fields
+        error_info.word_location = word_location if word_location
+        error_info.module_name = module_name if module_name
+
+        # Add context
+        error_context.each do |key, value|
+          error_info.context[key] = value.to_s
+        end
+
+        puts "[_build_error_info] Final context: #{error_info.context.to_h}"
+
+        error_info
+      end
+    end
+
+    # Start the gRPC server
+    #
+    # @param port [Integer] Port to listen on (default: 50053)
+    # @param modules_config [String, nil] Path to modules configuration file (optional)
+    def self.serve(port: 50053, modules_config: nil)
+      server = GRPC::RpcServer.new
+      server.add_http2_port("0.0.0.0:#{port}", :this_port_is_insecure)
+
+      # Create servicer with optional config
+      servicer = ForthicRuntimeServicer.new(modules_config)
+      server.handle(servicer)
+
+      puts "Forthic Ruby gRPC server listening on port #{port}"
+
+      if modules_config
+        puts "  - Loaded modules from: #{modules_config}"
+      end
+
+      loaded = servicer.runtime_modules.keys
+      if loaded.any?
+        puts "  - Available runtime modules: #{loaded.join(', ')}"
+      else
+        puts "  - No runtime-specific modules loaded"
+      end
+
+      server.run_till_terminated_or_interrupted([1, 'int', 'SIGTERM'])
+    end
+  end
+end
+
+# Start the server when this file is run directly
+if __FILE__ == $PROGRAM_NAME
+  Forthic::Grpc.serve
+end