(GH-100) Add a debug server

This commit adds the code necessary to start a Puppet debug session which is
compliant with VS Code's debug adapter protocol.  Instead this is over TCP
instead of STDIN/OUT.

This commit also updates the gulpfile so that this code is added during the
extension packaging process.

Author: glennsarti

client/gulpfile.js

@@ -16,6 +16,7 @@ gulp.task('clean', function () {
 gulp.task('copy_language_server', function () {
   return gulp.src(['../server/lib/**/*',
                    '../server/vendor/**/*',
+                   '../server/puppet-debugserver',
                    '../server/puppet-languageserver'
                   ], { base: '../server'})
              .pipe(gulp.dest('./vendor/languageserver'));

server/lib/debugserver/debug_protocol.rb

@@ -0,0 +1,86 @@
+require 'debugserver/debug_protocol'
+require 'puppet-vscode'
+
+%w[json_handler message_router hooks puppet_debug_session debug_hook_handlers puppet_debug_breakpoints puppet_monkey_patches].each do |lib|
+  begin
+    require "puppet-debugserver/#{lib}"
+  rescue LoadError
+    require File.expand_path(File.join(File.dirname(__FILE__), 'puppet-debugserver', lib))
+  end
+end
+
+require 'optparse'
+require 'logger'
+
+module PuppetDebugServer
+  class CommandLineParser
+    def self.parse(options)
+      # Set defaults here
+      args = {
+        port: 8082,
+        ipaddress: '127.0.0.1',
+        stop_on_client_exit: true,
+        connection_timeout: 10,
+        debug: nil,
+      }
+
+      opt_parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: puppet-debugserver.rb [options]'
+
+        opts.on('-pPORT', '--port=PORT', "TCP Port to listen on.  Default is #{args[:port]}") do |port|
+          args[:port] = port.to_i
+        end
+
+        opts.on('-ipADDRESS', '--ip=ADDRESS', "IP Address to listen on (0.0.0.0 for all interfaces).  Default is #{args[:ipaddress]}") do |ipaddress|
+          args[:ipaddress] = ipaddress
+        end
+
+        opts.on('-tTIMEOUT', '--timeout=TIMEOUT', "Stop the Debug Server if a client does not connection within TIMEOUT seconds.  A value of zero will not timeout.  Default is #{args[:connection_timeout]} seconds") do |timeout|
+          args[:connection_timeout] = timeout.to_i
+        end
+
+        opts.on('--debug=DEBUG', "Output debug information.  Either specify a filename or 'STDOUT'.  Default is no debug output") do |debug|
+          args[:debug] = debug
+        end
+
+        opts.on('-h', '--help', 'Prints this help') do
+          puts opts
+          exit
+        end
+
+        opts.on('-v', '--version', 'Prints the Debug Server version') do
+          puts PuppetVSCode.version
+          exit
+        end
+      end
+
+      opt_parser.parse!(options.dup)
+      args
+    end
+  end
+
+  def self.log_message(severity, message)
+    PuppetVSCode::log_message(severity, message)
+  end
+
+  def self.init_puppet(options)
+    PuppetVSCode::init_logging(options)
+    log_message(:info, "Debug Server is v#{PuppetVSCode.version}")
+
+    true
+  end
+
+  def self.rpc_server(options)
+    log_message(:info, 'Starting RPC Server...')
+
+    server = PuppetVSCode::SimpleTCPServer.new
+
+    options[:servicename] = 'DEBUG SERVER'
+
+    server.add_service(options[:ipaddress], options[:port])
+    trap('INT') { server.stop }
+    server.start(PuppetDebugServer::MessageRouter, options, 2)
+
+    log_message(:info, 'Debug Server exited.')
+  end
+end

server/lib/puppet-debugserver.rb

@@ -0,0 +1,205 @@
+module PuppetDebugServer
+  module PuppetDebugSession
+    @hook_handler = nil
+    
+    def self.hooks
+      if @hook_handler.nil?
+        @hook_handler = PuppetDebugServer::Hooks.new
+
+        @hook_handler.add_hook(:hook_before_apply_exit, :debug_session)           { |args| PuppetDebugServer::PuppetDebugSession::on_hook_before_apply_exit(args) }
+        @hook_handler.add_hook(:hook_breakpoint, :debug_session)                  { |args| PuppetDebugServer::PuppetDebugSession::hook_breakpoint(args) }
+        @hook_handler.add_hook(:hook_step_breakpoint, :debug_session)             { |args| PuppetDebugServer::PuppetDebugSession::hook_step_breakpoint(args) }
+        @hook_handler.add_hook(:hook_function_breakpoint, :debug_session)         { |args| PuppetDebugServer::PuppetDebugSession::hook_function_breakpoint(args) }
+        @hook_handler.add_hook(:hook_before_compile, :debug_session)              { |args| PuppetDebugServer::PuppetDebugSession::hook_before_compile(args) }
+        @hook_handler.add_hook(:hook_exception, :debug_session)                   { |args| PuppetDebugServer::PuppetDebugSession::hook_exception(args) }
+        @hook_handler.add_hook(:hook_log_message, :debug_session)                 { |args| PuppetDebugServer::PuppetDebugSession::hook_log_message(args) }
+        @hook_handler.add_hook(:hook_after_parser_function_reset, :debug_session) { |args| PuppetDebugServer::PuppetDebugSession::hook_after_parser_function_reset(args) }
+        @hook_handler.add_hook(:hook_before_pops_evaluate, :debug_session)        { |args| PuppetDebugServer::PuppetDebugSession::hook_before_pops_evaluate(args) }
+        @hook_handler.add_hook(:hook_after_pops_evaluate, :debug_session)         { |args| PuppetDebugServer::PuppetDebugSession::hook_after_pops_evaluate(args) }
+      end
+      @hook_handler
+    end
+
+    def self.hook_before_pops_evaluate(args)
+      @session_pops_eval_depth = @session_pops_eval_depth + 1
+      target = args[1]
+      # Ignore this if there is no positioning information available
+      return unless target.is_a?(Puppet::Pops::Model::Positioned)
+      # Even if it's positioned, it can still contain invalid information.  Ignore it if
+      # it's missing required information.  This can happen when evaluting strings (e.g. watches from VSCode)
+      # i.e. not a file on disk
+      return if target.file.nil? || target.file.empty?
+
+      # Break if we hit a specific puppet function
+      if target._pcore_type.simple_name == 'CallNamedFunctionExpression'
+        # TODO Do we really need to break on a function called breakpoint?
+        if target.functor_expr.value == 'breakpoint'
+          # Re-raise the hook as a breakpoint
+          PuppetDebugServer::PuppetDebugSession.hooks.exec_hook(:hook_function_breakpoint, [target.functor_expr.value, target._pcore_type.name] +args)
+          return
+        else
+          func_names = PuppetDebugServer::PuppetDebugSession.function_breakpoints
+          func_names.each do |func|
+            next unless func['name'] == target.functor_expr.value
+            # Re-raise the hook as a breakpoint
+            PuppetDebugServer::PuppetDebugSession.hooks.exec_hook(:hook_function_breakpoint, [target.functor_expr.value, target._pcore_type.name] + args)
+            return
+          end
+        end
+      end
+
+      unless target.length == 0
+        excluded_classes = ['BlockExpression','HostClassDefinition']
+        file_path = target.file
+        breakpoints = PuppetDebugServer::PuppetDebugSession.source_breakpoints(file_path)
+
+        #target._pcore_type.simple_name
+        # TODO should check if it's an object we don't care aount
+
+        unless excluded_classes.include?(target._pcore_type.simple_name) || breakpoints.nil? || breakpoints.empty?
+          # Calculate the start and end lines of the target
+          target_start_line = target.line
+          target_end_line   = target.locator.line_for_offset(target.offset + target.length)
+
+          breakpoints.each do |bp|
+            bp_line = bp['line']
+            # TODO Hit and conditional BreakPoints?
+            if bp_line >= target_start_line && bp_line <= target_end_line
+              # Re-raise the hook as a breakpoint
+              PuppetDebugServer::PuppetDebugSession.hooks.exec_hook(:hook_breakpoint, [target._pcore_type.name, ''] + args)
+              #require 'pry'; binding.pry
+              return
+            end
+          end
+        end
+      end
+
+      # Break if we are stepping
+      case PuppetDebugServer::PuppetDebugSession.run_mode
+      when :stepin
+        # Stepping-in is basically break on everything
+        # Re-raise the hook as a step breakpoint
+        PuppetDebugServer::PuppetDebugSession.hooks.exec_hook(:hook_step_breakpoint, [target._pcore_type.name, ''] + args)
+        return
+      when :next
+        # Next will break on anything at this Pop depth or shallower
+        # Re-raise the hook as a step breakpoint
+        run_options = PuppetDebugServer::PuppetDebugSession.run_mode_options
+        if !run_options[:pops_depth_level].nil? && @session_pops_eval_depth <= run_options[:pops_depth_level]
+          PuppetDebugServer::PuppetDebugSession.hooks.exec_hook(:hook_step_breakpoint, [target._pcore_type.name, ''] + args)
+          return
+        end
+      when :stepout
+        # Stepping-Out will break on anything shallower than this Pop depth
+        # Re-raise the hook as a step breakpoint
+        run_options = PuppetDebugServer::PuppetDebugSession.run_mode_options
+        if !run_options[:pops_depth_level].nil? && @session_pops_eval_depth < run_options[:pops_depth_level]
+          PuppetDebugServer::PuppetDebugSession.hooks.exec_hook(:hook_step_breakpoint, [target._pcore_type.name, ''] + args)
+          return
+        end
+      end
+    end
+    def self.hook_after_pops_evaluate(args)
+      @session_pops_eval_depth = @session_pops_eval_depth - 1
+      target = args[1]
+      return unless target.is_a?(Puppet::Pops::Model::Positioned)
+    end
+
+    def self.hook_after_parser_function_reset(args)
+      func_object = args[0]
+
+      # TODO Do we really need to break on a function called breakpoint?
+      func_object.newfunction(:breakpoint, :type => :rvalue, :arity => -1, :doc => "Breakpoint Function") do |arguments|
+        # This function is just a place holder.  It gets interpretted at the pops_evaluate hooks but the function
+        # itself still needs to exist though.
+      end
+    end
+
+    def self.on_hook_before_apply_exit(args)
+      option = args[0]
+
+      PuppetDebugServer::PuppetDebugSession.connection.send_exited_event(option)
+      PuppetDebugServer::PuppetDebugSession.connection.send_output_event({
+        'category' => 'console',
+        'output' => "puppet exited with #{option}",
+      })
+    end
+
+    def self.hook_breakpoint(args)
+      process_breakpoint_hook('breakpoint', args)
+    end
+
+    def self.hook_function_breakpoint(args)
+      process_breakpoint_hook('function breakpoint', args)
+    end
+
+    def self.hook_step_breakpoint(args)
+      process_breakpoint_hook('step', args)
+    end
+
+    def self.process_breakpoint_hook(reason, args)
+      # If the debug session is paused, can't raise a new breakpoint
+      return if PuppetDebugServer::PuppetDebugSession.session_paused?
+      break_display_text = args[0]
+      break_description = args[1]
+
+      scope_object = nil
+      pops_target_object = nil
+      pops_depth_level = nil
+
+      # Check if the breakpoint came from the Pops::Evaluator
+      if args[2].is_a?(Puppet::Pops::Evaluator::EvaluatorImpl)
+        pops_target_object = args[3]
+        scope_object = args[4]
+        pops_depth_level = @session_pops_eval_depth
+      end
+
+      break_description = break_display_text if break_description.empty?
+      PuppetDebugServer::PuppetDebugSession.raise_and_wait_stopped_event(reason, break_display_text, break_description, {
+        :pops_target       => pops_target_object,
+        :scope             => scope_object,
+        :pops_depth_level  => pops_depth_level,
+        :puppet_stacktrace => Puppet::Pops::PuppetStack.stacktrace
+      })
+    end
+
+    def self.hook_before_compile(args)
+      PuppetDebugServer::PuppetDebugSession.session_compiler = args[0]
+
+      # Spin-wait for the configurationDone message from the client before we continue compilation
+      begin
+        sleep(0.5)
+      end while !PuppetDebugServer::PuppetDebugSession.client_completed_configuration?
+    end
+
+    def self.hook_exception(args)
+      # If the debug session is paused, can't raise a new exception
+      return if PuppetDebugServer::PuppetDebugSession.session_paused?
+
+      error_detail = args[0]
+
+      PuppetDebugServer::PuppetDebugSession.raise_and_wait_stopped_event(
+        'exception', 'Compilation Exception', error_detail.basic_message, {
+        :session_exception => error_detail,
+        :puppet_stacktrace => Puppet::Pops::PuppetStack.stacktrace_from_backtrace(error_detail)
+      })
+    end
+
+    def self.hook_log_message(args)
+      return if self.suppress_log_messages
+      msg = args[0]
+      str = msg.respond_to?(:multiline) ? msg.multiline : msg.to_s
+      str = msg.source == 'Puppet' ? str : "#{msg.source}: #{str}"
+
+      level = msg.level.to_s.capitalize 
+
+      category = 'stderr'
+      category = 'stdout' if msg.level == :notice || msg.level == :info || msg.level == :debug
+
+      PuppetDebugServer::PuppetDebugSession.connection.send_output_event({
+        'category' => category,
+        'output' => "#{level}: #{str}\n"
+      })
+    end
+  end
+end