puppet-editor-services 2.0.4

data/lib/puppet_debugserver.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'dsp/dsp'
+require 'puppet_editor_services'
+
+require 'optparse'
+require 'logger'
+
+module PuppetDebugServer
+  def self.version
+    PuppetEditorServices.version
+  end
+
+  def self.require_gems(options)
+    original_verbose = $VERBOSE
+    $VERBOSE = nil
+
+    # Use specific Puppet Gem version if possible
+    # Note that puppet is required implicitly in the monkey patches
+    # so we don't need to explicity require it here
+    unless options[:puppet_version].nil?
+      available_puppet_gems = Gem::Specification
+                              .select { |item| item.name.casecmp('puppet').zero? }
+                              .map { |item| item.version.to_s }
+      if available_puppet_gems.include?(options[:puppet_version])
+        gem 'puppet', options[:puppet_version]
+      else
+        log_message(:warn, "Unable to use puppet version #{options[:puppet_version]}, as only the following versions are available [#{available_puppet_gems.join(', ')}]")
+      end
+    end
+
+    %w[
+      message_handler
+      hooks
+      puppet_debug_session
+      debug_session/break_points
+      debug_session/hook_handlers
+      debug_session/flow_control
+      debug_session/puppet_session_run_mode
+      debug_session/puppet_session_state
+      puppet_monkey_patches
+    ].each do |lib|
+      require "puppet-debugserver/#{lib}"
+    rescue LoadError
+      require File.expand_path(File.join(File.dirname(__FILE__), 'puppet-debugserver', lib))
+    end
+  ensure
+    $VERBOSE = original_verbose
+  end
+
+  class CommandLineParser
+    def self.parse(options)
+      # Set defaults here
+      args = {
+        port: nil,
+        ipaddress: 'localhost',
+        stop_on_client_exit: true,
+        connection_timeout: 10,
+        debug: nil,
+        puppet_version: 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 random 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('--puppet-version=TEXT', String, 'The version of the Puppet Gem to use (defaults to latest version if not specified or the version does not exist) e.g. --puppet-version=5.4.0') do |text|
+          args[:puppet_version] = text
+        end
+
+        opts.on('-h', '--help', 'Prints this help') do
+          puts opts
+          exit
+        end
+
+        opts.on('-v', '--version', 'Prints the Debug Server version') do
+          puts PuppetEditorServices.version
+          exit
+        end
+      end
+
+      opt_parser.parse!(options.dup)
+      args
+    end
+  end
+
+  def self.log_message(severity, message)
+    PuppetEditorServices.log_message(severity, message)
+  end
+
+  def self.init_puppet(options)
+    PuppetEditorServices.init_logging(options)
+    log_message(:info, "Debug Server is v#{PuppetDebugServer.version}")
+    log_message(:debug, 'Loading gems...')
+    require_gems(options)
+    require 'puppet'
+    log_message(:info, "Using Puppet v#{::Puppet.version}")
+
+    raise("Detected Puppet #{Puppet.version} however the Debug Server requires Puppet 5.0 and above") if Gem::Version.new(Puppet.version) < Gem::Version.new('5.0.0')
+
+    true
+  end
+
+  def self.rpc_server_async(options)
+    log_message(:info, 'Starting RPC Server (Async)...')
+
+    Thread.new do
+      Thread.current.abort_on_exception = true
+
+      require 'puppet_editor_services/protocol/debug_adapter'
+      require 'puppet_editor_services/server/tcp'
+
+      server_options = options.dup
+      protocol_options = { class: PuppetEditorServices::Protocol::DebugAdapter }.merge(options)
+      handler_options = { class: PuppetDebugServer::MessageHandler }.merge(options)
+      # TODO: Add max threads?
+      server_options[:servicename] = 'DEBUG SERVER'
+
+      log_message(:debug, 'Using TCP Server')
+      server = ::PuppetEditorServices::Server::Tcp.new(server_options, protocol_options, handler_options)
+      trap('INT') do
+        server.stop_services(true)
+        PuppetDebugServer::PuppetDebugSession.instance.flow_control.assert_flag(:terminate)
+      end
+      server.start
+
+      log_message(:info, 'Debug Server exited.')
+      # Forcibly kill the Debug Session
+      log_message(:info, 'Signalling Debug Session to terminate with extreme prejudice')
+      PuppetDebugServer::PuppetDebugSession.instance.force_terminate
+    end
+  end
+
+  def self.execute(rpc_thread)
+    debug_session = PuppetDebugServer::PuppetDebugSession.instance
+    debug_session.initialize_session
+
+    # TODO: Can I use a real mutex here? might be hard with the rpc_thread.alive? call
+    sleep(0.5) while !debug_session.flow_control.flag?(:start_puppet) && rpc_thread.alive? && !debug_session.flow_control.terminate?
+    return unless rpc_thread.alive? || debug_session.flow_control.terminate?
+
+    debug_session.run_puppet
+
+    return unless rpc_thread.alive?
+
+    debug_session.close
+    rpc_thread.join
+  end
+end

data/lib/puppet_editor_services/connection/base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PuppetEditorServices
+  module Connection
+    class Base
+      attr_reader :server, :protocol
+
+      def initialize(server)
+        @server = server
+        @protocol = server.protocol_options[:class].new(self)
+      end
+
+      # Override this method
+      # @api public
+      def error?
+        false
+      end
+
+      # Override this method
+      # @api public
+      def send_data(_data)
+        false
+      end
+
+      # Shouldn't need to override this method
+      # @api public
+      def receive_data(data)
+        @protocol.receive_data(data)
+      rescue StandardError => e
+        server.log("Protocol #{@protocol.class} raised error #{e}: #{e.backtrace}")
+      end
+
+      # Override this method
+      # @api public
+      def close_after_writing
+        true
+      end
+
+      # Override this method
+      # @api public
+      def close
+        true
+      end
+
+      # Override this method if needed
+      # @api public
+      def post_init
+        server.log("Client #{id} has connected to the server")
+      end
+
+      # Override this method if needed
+      # @api public
+      def unbind
+        server.log("Client #{id} has disconnected from the server")
+      end
+
+      def id
+        object_id.to_s
+      end
+    end
+  end
+end

data/lib/puppet_editor_services/connection/stdio.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'puppet_editor_services/connection/base'
+
+module PuppetEditorServices
+  module Connection
+    class Stdio < ::PuppetEditorServices::Connection::Base
+      def send_data(data)
+        $editor_services_stdout.write(data) # rubocop:disable Style/GlobalVars  We need this global var
+        true
+      end
+
+      def close_after_writing
+        $editor_services_stdout.flush # rubocop:disable Style/GlobalVars  We need this global var
+        server.close_connection
+        true
+      end
+
+      def close
+        server.close_connection
+        true
+      end
+    end
+  end
+end

data/lib/puppet_editor_services/connection/tcp.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'puppet_editor_services/connection/base'
+
+module PuppetEditorServices
+  module Connection
+    class Tcp < ::PuppetEditorServices::Connection::Base
+      attr_accessor :socket
+
+      def initialize(server, socket)
+        super(server)
+        @socket = socket
+      end
+
+      def send_data(data)
+        return false if socket.nil?
+
+        socket.write(data)
+        true
+      end
+
+      def close_after_writing
+        socket.flush unless socket.nil?
+        server.remove_connection_async(socket)
+        true
+      end
+
+      def close
+        server.remove_connection_async(socket)
+        true
+      end
+    end
+  end
+end

data/lib/puppet_editor_services/handler/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PuppetEditorServices
+  module Handler
+    class Base
+      attr_reader :protocol
+
+      def initialize(protocol)
+        @protocol = protocol
+      end
+
+      # @abstract
+      def handle(_message, _context = {}); end
+    end
+  end
+end

data/lib/puppet_editor_services/handler/debug_adapter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'puppet_editor_services/handler/base'
+require 'puppet_editor_services/protocol/debug_adapter_messages'
+
+module PuppetEditorServices
+  module Handler
+    class DebugAdapter < ::PuppetEditorServices::Handler::Base
+      # options
+      #    source        :request, :notification etc.
+      #    message       JSON Message that caused the error
+      #    error         Actual ruby error
+      # @abstract
+      def unhandled_exception(error, options)
+        PuppetEditorServices.log_message(:error, "Unhandled exception from #{options[:source]}. JSON Message #{options[:message]}: #{error.inspect}\n#{error.backtrace}")
+      end
+
+      # context
+      def handle(json_rpc_message, context = {})
+        unless json_rpc_message.is_a?(PuppetEditorServices::Protocol::DebugAdapterMessages::Request)
+          PuppetEditorServices.log_message(:error, "Unknown JSON RPC message type #{json_rpc_message.class}")
+          return false
+        end
+        handle_request(json_rpc_message, context)
+      end
+
+      # Example Request
+      #
+      # For a textDocument/completion request
+      # def request_textdocument_completion(connection_id, json_rpc_message)
+      #  ...
+      # end
+
+      private
+
+      def handle_request(request_message, _context)
+        method_name = rpc_name_to_ruby_method_name('request', request_message.command)
+        if respond_to?(method_name.intern)
+          begin
+            result = send(method_name, protocol.connection.id, request_message)
+            protocol.encode_and_send(result) unless result.nil?
+          rescue NoMethodError, LoadError => e
+            unhandled_exception(e, source: :request, message: request_message)
+            raise
+          rescue StandardError => e
+            unhandled_exception(e, source: :request, message: request_message)
+          end
+          return true
+        end
+
+        # Default processing
+        protocol.encode_and_send(::PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message, "This feature is not supported - Request #{request_message.command}"))
+        PuppetEditorServices.log_message(:error, "Unknown request command #{request_message.command}")
+
+        false
+      end
+
+      def rpc_name_to_ruby_method_name(prefix, rpc_name)
+        "#{prefix}_#{rpc_name.tr('/', '_').tr('$', 'dollar').downcase}"
+      end
+    end
+  end
+end

data/lib/puppet_editor_services/handler/json_rpc.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'puppet_editor_services/handler/base'
+require 'puppet_editor_services/protocol/json_rpc_messages'
+
+module PuppetEditorServices
+  module Handler
+    class JsonRPC < ::PuppetEditorServices::Handler::Base
+      # options
+      #    source        :request, :notification etc.
+      #    message       JSON Message that caused the error
+      #    error         Actual ruby error
+      # @abstract
+      def unhandled_exception(error, options)
+        PuppetEditorServices.log_message(:error, "Unhandled exception from #{options[:source]}. JSON Message #{options[:message]}: #{error.inspect}\n#{error.backtrace}")
+      end
+
+      # context
+      #   request => original request
+      def handle(json_rpc_message, context = {})
+        case json_rpc_message
+
+        when ::PuppetEditorServices::Protocol::JsonRPCMessages::RequestMessage
+          return handle_request(json_rpc_message, context)
+
+        when ::PuppetEditorServices::Protocol::JsonRPCMessages::NotificationMessage
+          return handle_notification(json_rpc_message, context)
+
+        when ::PuppetEditorServices::Protocol::JsonRPCMessages::ResponseMessage
+          return handle_response(json_rpc_message, context)
+
+        else
+          PuppetEditorServices.log_message(:error, "Unknown JSON RPC message type #{json_rpc_message.class}")
+        end
+        false
+      end
+
+      # Example Request
+      #
+      # For a textDocument/completion request
+      # def request_textdocument_completion(connection_id, json_rpc_message)
+      #  ...
+      # end
+
+      # Example Notification
+      # For a workspace/didChangeNotification notification
+      # def notification_workspace_didchangeconfiguration(connection_id, json_rpc_message)
+      #  ...
+      # end
+
+      # Example Response
+      # A response to a client/registerCapability request
+      # def notification_workspace_didchangeconfiguration(connection_id, json_rpc_message, original_request)
+      #  ...
+      # end
+
+      private
+
+      def handle_request(request_message, _context)
+        method_name = rpc_name_to_ruby_method_name('request', request_message.rpc_method)
+        if respond_to?(method_name.intern)
+          begin
+            protocol.encode_and_send(
+              ::PuppetEditorServices::Protocol::JsonRPCMessages.reply_result(
+                request_message, send(method_name, protocol.connection.id, request_message)
+              )
+            )
+          rescue StandardError => e
+            unhandled_exception(e, source: :request, message: request_message)
+          end
+          return true
+        end
+
+        # Default processing
+        protocol.encode_and_send(::PuppetEditorServices::Protocol::JsonRPCMessages.reply_method_not_found(request_message))
+        if request_message.rpc_method.start_with?('$/')
+          PuppetEditorServices.log_message(:debug, "Ignoring RPC request #{request_message.rpc_method}")
+        else
+          PuppetEditorServices.log_message(:error, "Unknown RPC method #{request_message.rpc_method}")
+        end
+
+        false
+      end
+
+      def handle_notification(notification_message, _context)
+        method_name = rpc_name_to_ruby_method_name('notification', notification_message.rpc_method)
+        if respond_to?(method_name.intern)
+          begin
+            send(method_name, protocol.connection.id, notification_message)
+          rescue StandardError => e
+            unhandled_exception(e, source: :notification, message: notification_message)
+          end
+          return true
+        end
+
+        # Default processing
+        if notification_message.rpc_method.start_with?('$/')
+          PuppetEditorServices.log_message(:debug, "Ignoring RPC notification #{notification_message.rpc_method}")
+        else
+          PuppetEditorServices.log_message(:error, "Unknown RPC notification #{notification_message.rpc_method}")
+        end
+
+        false
+      end
+
+      def handle_response(response_message, context)
+        original_request = context[:request]
+        return false if original_request.nil?
+
+        unless response_message.is_successful # rubocop:disable Style/IfUnlessModifier Line is too long otherwise
+          PuppetEditorServices.log_message(:error, "Response for method '#{original_request.rpc_method}' with id '#{original_request.id}' failed with #{response_message.error}")
+        end
+        method_name = rpc_name_to_ruby_method_name('response', original_request.rpc_method)
+        if respond_to?(method_name.intern)
+          begin
+            send(method_name, protocol.connection.id, response_message, original_request)
+          rescue StandardError => e
+            unhandled_exception(e, source: :response, message: response_message)
+          end
+          return true
+        end
+
+        # Default processing
+        PuppetEditorServices.log_message(:error, "Unknown RPC response for method #{original_request.rpc_method}")
+        false
+      end
+
+      def rpc_name_to_ruby_method_name(prefix, rpc_name)
+        "#{prefix}_#{rpc_name.tr('/', '_').tr('$', 'dollar').downcase}"
+      end
+    end
+  end
+end

data/lib/puppet_editor_services/logging.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PuppetEditorServices
+  def self.log_message(severity, message)
+    return if @logger.nil?
+
+    case severity
+    when :debug
+      @logger.debug(message)
+    when :info
+      @logger.info(message)
+    when :warn
+      @logger.warn(message)
+    when :error
+      @logger.error(message)
+    when :fatal
+      @logger.fatal(message)
+    else
+      @logger.unknown(message)
+    end
+    @log_file.fsync unless @log_file.nil?
+  end
+
+  def self.init_logging(options)
+    @log_file = nil
+    if options[:debug].nil?
+      @logger = nil
+    elsif (options[:debug].casecmp 'stdout').zero?
+      @logger = Logger.new($stdout)
+    elsif !options[:debug].to_s.empty?
+      # Log to file
+      begin
+        @log_file = File.open(options[:debug], 'w')
+      rescue Errno::ENOENT => e
+        # We can't open the log file and we can't log to STDOUT if we're in STDIO mode
+        # So log the error to STDERR and disable logging
+        $stderr.puts "Error opening log file #{options[:debug]} : #{e}" # rubocop:disable Style/StderrPuts
+        @log_file = nil
+        return
+      end
+      @log_file.sync = true
+      @logger = Logger.new(@log_file)
+    end
+  end
+end

data/lib/puppet_editor_services/protocol/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PuppetEditorServices
+  module Protocol
+    class Base
+      attr_reader :connection, :handler
+
+      def initialize(connection)
+        @connection = connection
+        @handler = connection.server.handler_options[:class].new(self)
+      end
+
+      # @abstract
+      def receive_data(data); end
+
+      def close_connection
+        connection.close unless connection.nil?
+      end
+
+      def connection_error?
+        return false if connection.nil?
+
+        connection.error?
+      end
+    end
+  end
+end