forthic 0.2.0 → 0.3.0

data/lib/forthic/utils.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Forthic
+  # Parse a datetime string and create a Time object in the specified timezone
+  #
+  # Expected format: "YYYY-MM-DDTHH:MM:SS"
+  # Example: "2025-05-24T10:15:30"
+  #
+  # @param date_string [String] The datetime string to parse
+  # @param timezone [String] The timezone identifier (e.g., "UTC", "America/New_York")
+  # @return [Time, nil] The parsed Time object with timezone, or nil if parsing fails
+  def self.parse_zoned_datetime(date_string, timezone)
+    # Parse the date string and create a Time in the specified timezone
+    year = date_string[0, 4].to_i
+    month = date_string[5, 2].to_i
+    day = date_string[8, 2].to_i
+    hour = date_string[11, 2].to_i
+    minute = date_string[14, 2].to_i
+    second = date_string[17, 2].to_i
+
+    # Create Time object in the specified timezone using ENV['TZ']
+    old_tz = ENV['TZ']
+    begin
+      ENV['TZ'] = timezone
+      Time.new(year, month, day, hour, minute, second)
+    ensure
+      ENV['TZ'] = old_tz
+    end
+  rescue StandardError
+    # Return nil if parsing fails
+    nil
+  end
+end

data/lib/forthic/websocket/handler.rb

@@ -0,0 +1,548 @@
+# frozen_string_literal: true
+
+require_relative 'serializer'
+require_relative '../interpreter'
+
+module Forthic
+  module WebSocket
+    # ForthicWebSocketHandler - WebSocket message handler for Forthic runtime
+    #
+    # Mirrors the gRPC server functionality but uses JSON messages over WebSocket.
+    # Designed to work with Rails ActionCable for browser-server communication.
+    #
+    # 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
+    # - Streaming execution with progress updates (NEW for WebSocket)
+    # - Rich error handling with stack traces and context
+    #
+    # Message protocol defined in BROWSER_SERVER_WEBSOCKET_PLAN.md
+    class Handler
+      # Standard library modules (available in all runtimes)
+      # These are excluded from list_modules as they're not runtime-specific
+      STANDARD_MODULES = %w[
+        array record string math datetime json boolean core
+      ].freeze
+
+      attr_reader :runtime_modules, :timezone
+
+      # Initialize handler with optional configuration
+      #
+      # @param timezone [String] Timezone for the interpreter (default: "UTC")
+      # @param modules_config [Hash, nil] Optional modules configuration
+      def initialize(timezone: "UTC", modules_config: nil)
+        @timezone = timezone
+        @runtime_modules = {}
+
+        # TODO: Implement module loading from config when needed
+        # For now, we only have stdlib modules in Ruby
+        if modules_config
+          puts "[WEBSOCKET_HANDLER] Module config support not yet implemented"
+        end
+      end
+
+      # Handle incoming WebSocket message
+      #
+      # Routes messages to appropriate handler based on message type.
+      #
+      # @param message [Hash] Parsed JSON message from client
+      # @return [Hash, Array<Hash>] Response message(s) to send back
+      def handle_message(message)
+        message_type = message['type']
+        message_id = message['id']
+
+        puts "[WEBSOCKET] Received message: type=#{message_type} id=#{message_id}"
+
+        case message_type
+        when 'execute_word'
+          execute_word(message)
+        when 'execute_sequence'
+          execute_sequence(message)
+        when 'list_modules'
+          list_modules(message)
+        when 'get_module_info'
+          get_module_info(message)
+        when 'streaming_execute'
+          streaming_execute(message)
+        else
+          error_response(message_id, "Unknown message type: #{message_type}")
+        end
+      rescue => e
+        puts "[WEBSOCKET] ERROR handling message: #{e.message}"
+        puts e.backtrace[0..5].join("\n")
+        error_response(message['id'], "Handler error: #{e.message}")
+      end
+
+      # Execute a single word in the Ruby runtime
+      #
+      # Message format:
+      # {
+      #   "type": "execute_word",
+      #   "id": "uuid",
+      #   "params": {
+      #     "word": "MY-WORD",
+      #     "stack": [{"type": "int", "value": 42}, ...]
+      #   }
+      # }
+      #
+      # @param message [Hash] The execution request message
+      # @return [Hash] The execution response message
+      def execute_word(message)
+        params = message['params']
+        word_name = params['word']
+        stack_json = params['stack'] || []
+
+        puts "[EXECUTE_WORD] word='#{word_name}' stack_size=#{stack_json.length}"
+
+        # Deserialize the stack
+        stack = Serializer.deserialize_stack(stack_json)
+        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 = Serializer.serialize_stack(result_stack)
+        puts "[EXECUTE_WORD] Success"
+
+        {
+          'type' => 'execute_word_response',
+          'id' => message['id'],
+          'result' => {
+            'stack' => response_stack
+          }
+        }
+      rescue => e
+        puts "[EXECUTE_WORD] ERROR: #{e.message}"
+        puts "[EXECUTE_WORD] Backtrace:"
+        puts e.backtrace[0..5].join("\n")
+
+        build_error_response(message['id'], 'execute_word_response', e, word_name)
+      end
+
+      # Execute a sequence of words in one batch (optimization for remote execution)
+      #
+      # Message format:
+      # {
+      #   "type": "execute_sequence",
+      #   "id": "uuid",
+      #   "params": {
+      #     "words": ["WORD1", "WORD2", "WORD3"],
+      #     "stack": [...]
+      #   }
+      # }
+      #
+      # @param message [Hash] The execution request message
+      # @return [Hash] The execution response message
+      def execute_sequence(message)
+        params = message['params']
+        word_names = params['words'] || []
+        stack_json = params['stack'] || []
+
+        puts "[EXECUTE_SEQUENCE] words=#{word_names} stack_size=#{stack_json.length}"
+
+        # Deserialize the initial stack
+        stack = Serializer.deserialize_stack(stack_json)
+        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 = Serializer.serialize_stack(result_stack)
+        puts "[EXECUTE_SEQUENCE] Success"
+
+        {
+          'type' => 'execute_sequence_response',
+          'id' => message['id'],
+          'result' => {
+            'stack' => response_stack
+          }
+        }
+      rescue => e
+        puts "[EXECUTE_SEQUENCE] ERROR: #{e.message}"
+        puts "[EXECUTE_SEQUENCE] Backtrace:"
+        puts e.backtrace[0..5].join("\n")
+
+        build_error_response(
+          message['id'],
+          'execute_sequence_response',
+          e,
+          nil,
+          { 'word_sequence' => word_names.join(', ') }
+        )
+      end
+
+      # List available runtime-specific modules (excludes standard library)
+      #
+      # Message format:
+      # {
+      #   "type": "list_modules",
+      #   "id": "uuid"
+      # }
+      #
+      # @param message [Hash] The request message
+      # @return [Hash] List of module summaries
+      def list_modules(message)
+        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 = {
+            'name' => name,
+            'description' => "Ruby-specific #{name} module",
+            'word_count' => word_count
+          }
+          modules << summary
+        end
+
+        {
+          'type' => 'list_modules_response',
+          'id' => message['id'],
+          'result' => {
+            'modules' => modules
+          }
+        }
+      rescue => e
+        puts "[LIST_MODULES] ERROR: #{e.message}"
+        build_error_response(message['id'], 'list_modules_response', e)
+      end
+
+      # Get detailed information about a specific module
+      #
+      # Message format:
+      # {
+      #   "type": "get_module_info",
+      #   "id": "uuid",
+      #   "params": {
+      #     "module_name": "pandas"
+      #   }
+      # }
+      #
+      # @param message [Hash] The request message
+      # @return [Hash] Module information with word details
+      def get_module_info(message)
+        params = message['params']
+        module_name = params['module_name']
+
+        unless @runtime_modules.key?(module_name)
+          puts "[GET_MODULE_INFO] Module '#{module_name}' not found"
+          return {
+            'type' => 'get_module_info_response',
+            'id' => message['id'],
+            'result' => {
+              'module_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 = {
+              '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 = {
+              'name' => word_name,
+              'stack_effect' => '( -- )',
+              'description' => "#{word_name} word from #{module_name} module"
+            }
+            words << word_info
+          end
+        end
+
+        {
+          'type' => 'get_module_info_response',
+          'id' => message['id'],
+          'result' => {
+            'module_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")
+        build_error_response(message['id'], 'get_module_info_response', e)
+      end
+
+      # Execute Forthic code with streaming progress updates
+      #
+      # This is a NEW feature for WebSocket (not available in gRPC).
+      # Sends progress updates during execution for long-running operations.
+      #
+      # Message format:
+      # {
+      #   "type": "streaming_execute",
+      #   "id": "uuid",
+      #   "params": {
+      #     "code": "LOAD-DATA PROCESS ANALYZE SAVE",
+      #     "stack": [...]
+      #   }
+      # }
+      #
+      # Returns an array of messages: [progress_updates..., final_response]
+      #
+      # @param message [Hash] The execution request message
+      # @param transmit_callback [Proc, nil] Optional callback for transmitting progress (ActionCable)
+      # @return [Array<Hash>] Array of progress updates and final response
+      def streaming_execute(message, transmit_callback = nil)
+        params = message['params']
+        code = params['code']
+        stack_json = params['stack'] || []
+
+        puts "[STREAMING_EXECUTE] code='#{code}' stack_size=#{stack_json.length}"
+
+        responses = []
+
+        # Deserialize the initial stack
+        stack = Serializer.deserialize_stack(stack_json)
+
+        # Create interpreter
+        interp = StandardInterpreter.new([], @timezone)
+
+        # 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 stack items
+        stack.each { |item| interp.stack_push(item) }
+
+        # Set up progress tracking
+        interp.setup_progress_tracking(code)
+
+        # Set up progress callback
+        interp.on_word_execute = lambda do |word_name, step, total_steps|
+          # Create progress message
+          progress_message = {
+            'type' => 'streaming_progress',
+            'id' => message['id'],
+            'progress' => {
+              'step' => step,
+              'total_steps' => total_steps,
+              'current_word' => word_name,
+              'message' => "Executing #{word_name}...",
+              'partial_stack' => Serializer.serialize_stack(interp.get_stack.get_items)
+            }
+          }
+
+          puts "[STREAMING_EXECUTE] Progress: #{step}/#{total_steps} - #{word_name}"
+
+          # If we have a transmit callback (from ActionCable), use it immediately
+          # Otherwise, collect responses to return
+          if transmit_callback
+            transmit_callback.call(progress_message)
+          else
+            responses << progress_message
+          end
+        end
+
+        # Execute the code
+        interp.run(code)
+
+        # Clean up progress tracking
+        interp.reset_progress_tracking
+
+        # Get final stack
+        final_stack = interp.get_stack.get_items
+        response_stack = Serializer.serialize_stack(final_stack)
+
+        # Create final response
+        final_response = {
+          'type' => 'streaming_execute_response',
+          'id' => message['id'],
+          'result' => {
+            'stack' => response_stack
+          }
+        }
+
+        puts "[STREAMING_EXECUTE] Success"
+
+        # Return all responses (progress updates + final)
+        responses << final_response
+        responses
+      rescue => e
+        puts "[STREAMING_EXECUTE] ERROR: #{e.message}"
+        puts e.backtrace[0..5].join("\n")
+
+        # Clean up on error
+        interp.reset_progress_tracking if interp
+
+        error_response = build_error_response(message['id'], 'streaming_execute_response', e)
+        [error_response]
+      end
+
+      # Cleanup handler resources
+      def cleanup
+        # Currently no cleanup needed
+        # Future: Could close interpreter, clear modules, etc.
+      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([], @timezone)
+
+        # 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([], @timezone)
+
+        # 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 error response message
+      #
+      # @param message_id [String] The message ID
+      # @param response_type [String] The response message type
+      # @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 [Hash] Error response message
+      def build_error_response(message_id, response_type, exception, word_name = nil, context = nil)
+        # Extract stack trace
+        stack_trace = exception.backtrace || []
+
+        # Get error type name
+        error_type = exception.class.name
+
+        # Build context dictionary
+        error_context = {}
+        error_context['word_name'] = word_name if word_name
+        error_context.merge!(context) if context
+
+        # 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/websocket/')
+            word_location = line
+          end
+        end
+
+        {
+          'type' => response_type,
+          'id' => message_id,
+          'error' => {
+            'message' => exception.message,
+            'error_type' => error_type,
+            'stack_trace' => stack_trace,
+            'module_name' => module_name,
+            'word_location' => word_location,
+            'context' => error_context
+          }.compact # Remove nil values
+        }
+      end
+
+      # Build a simple error response for unknown message types
+      #
+      # @param message_id [String] The message ID
+      # @param error_message [String] The error message
+      # @return [Hash] Error response message
+      def error_response(message_id, error_message)
+        {
+          'type' => 'error',
+          'id' => message_id,
+          'error' => {
+            'message' => error_message,
+            'error_type' => 'MessageError'
+          }
+        }
+      end
+    end
+  end
+end