puppet-editor-services 2.0.4

data/lib/puppet-debugserver/debug_session/puppet_session_state.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module PuppetDebugServer
+  module DebugSession
+    # The actual and saved state of Puppet during a debug session.
+    class PuppetSessionState
+      # The actual, current state of Puppet during a debug session.
+      # @return [PuppetDebugServer::DebugSession::ActualPuppetSessionState]
+      attr_reader :actual
+
+      # The state of Puppet when a debug session was paused, typically during a breakpoint or exception.
+      # @return [PuppetDebugServer::DebugSession::SavedPuppetSessionState]
+      attr_reader :saved
+
+      def initialize
+        @actual = ActualPuppetSessionState.new
+        @saved = SavedPuppetSessionState.new
+      end
+
+      # Clears the saved state. Typically only used when a paused debug session is about to start again.
+      def clear!
+        @saved.clear!
+
+        self
+      end
+    end
+
+    # The actual state of Puppet during a debug session
+    class ActualPuppetSessionState
+      # The depth of AST objects during a catalog compilation.
+      # @return [Integer]
+      attr_reader :pops_depth_level
+
+      # The compiler used to compile the catalog
+      # @return [Puppet::Parser::Compiler]
+      attr_reader :compiler
+
+      def initialize
+        @pops_depth_level = 0
+      end
+
+      # Resets back to initial state. Typically used when a debug session first starts.
+      def reset!
+        @pops_depth_level = 0
+        @compiler = nil
+      end
+
+      # Sets the compiler object. Typically set when a debug session begins catalog compilation.
+      def update_compiler(value)
+        @compiler = value
+      end
+
+      # Signals that an AST object is starting to be evaluated. Typically used during catalog compilation.
+      def increment_pops_depth
+        @pops_depth_level += 1
+      end
+
+      # Signals that an AST object has completed evaluated. Typically used during catalog compilation.
+      def decrement_pops_depth
+        @pops_depth_level -= 1
+      end
+    end
+
+    # The state of Puppet when a debug session was paused, typically during a breakpoint or exception.
+    class SavedPuppetSessionState
+      # The exception thrown when the session was paused.
+      # @return [Object]
+      attr_reader :exception
+
+      # The puppet stacktrace, not ruby stacktrace, when the session was paused.
+      # @return [Array<Object>]
+      attr_reader :puppet_stacktrace
+
+      # The Pops Object that caused the session to pause.
+      # @return [Object]
+      attr_reader :pops_target
+
+      # The Pops Scope containing the Pops Object that caused the session to pause.
+      # @return [Puppet::Parser::Scope]
+      attr_reader :scope
+
+      # The AST depth of the Pops Object that caused the session to pause.
+      # @return [Integer]
+      attr_reader :pops_depth_level
+
+      # A cache of variable references used to speed up Debug Server VariableReferences queries.
+      # @return [Hash<Integer, Object>]
+      attr_reader :variable_cache
+
+      def initialize
+        @variable_cache = {}
+      end
+
+      # Updates the saved session state
+      # @see PuppetDebugServer::DebugSession::SavedPuppetSessionState
+      # @option options :exception
+      # @option options :puppet_stacktrace
+      # @option options :pops_target
+      # @option options :scope
+      # @option options :pops_depth_level
+      def update!(options = {})
+        @exception         = options[:session_exception] unless options[:session_exception].nil?
+        @puppet_stacktrace = options[:puppet_stacktrace] unless options[:puppet_stacktrace].nil?
+        @pops_target       = options[:pops_target] unless options[:pops_target].nil?
+        @scope             = options[:scope] unless options[:scope].nil?
+        @pops_depth_level  = options[:pops_depth_level] unless options[:pops_depth_level].nil?
+        self
+      end
+
+      # Clears the saved state. Typically used a debug session is un-paused.
+      def clear!
+        @exception = nil
+        @puppet_stacktrace = nil
+        @pops_target = nil
+        @scope = nil
+        @pops_depth_level = nil
+        @variable_cache = {}
+        self
+      end
+    end
+  end
+end

data/lib/puppet-debugserver/hooks.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module PuppetDebugServer
+  # This code was inspired from Puppet-Debugger (https://raw.githubusercontent.com/nwops/puppet-debugger/master/lib/puppet-debugger/hooks.rb) which was borrowed from Pry hooks file
+
+  # Both puppet-debugger and pry are licensed with MIT
+  # https://raw.githubusercontent.com/nwops/puppet-debugger/master/LICENSE.txt
+  # https://raw.githubusercontent.com/pry/pry/master/LICENSE
+
+  class Hooks
+    def initialize
+      @hooks = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Ensure that duplicates have their @hooks object.
+    def initialize_copy
+      hooks_dup = @hooks.dup
+      @hooks.each do |k, v|
+        hooks_dup[k] = v.dup
+      end
+
+      @hooks = hooks_dup
+    end
+
+    def errors
+      @errors ||= []
+    end
+
+    # Add a new hook to be executed for the `event_name` event.
+    # @param [Symbol] event_name The name of the event.
+    # @param [Symbol] hook_name The name of the hook.
+    # @param [#call] callable The callable.
+    # @yield The block to use as the callable (if no `callable` provided).
+    # @return [PuppetDebugger::Hooks] The receiver.
+    def add_hook(event_name, hook_name, callable = nil, &block)
+      event_name = event_name.to_s
+
+      # do not allow duplicates, but allow multiple `nil` hooks
+      # (anonymous hooks)
+      raise ArgumentError, "Hook with name '#{hook_name}' already defined!" if hook_exists?(event_name, hook_name) && !hook_name.nil?
+
+      raise ArgumentError, 'Must provide a block or callable.' if !block && !callable
+
+      # ensure we only have one anonymous hook
+      @hooks[event_name].delete_if { |h, _k| h.nil? } if hook_name.nil?
+
+      if block
+        @hooks[event_name] << [hook_name, block]
+      elsif callable
+        @hooks[event_name] << [hook_name, callable]
+      end
+
+      self
+    end
+
+    # Execute the list of hooks for the `event_name` event.
+    # @param [Symbol] event_name The name of the event.
+    # @param [Array] args The arguments to pass to each hook function.
+    # @return [Object] The return value of the last executed hook.
+    def exec_hook(event_name, *args, &block)
+      PuppetDebugServer.log_message(:debug, "Starting to execute hook #{event_name}") unless event_name == :hook_log_message
+      @hooks[event_name.to_s].map do |_hook_name, callable|
+        callable.call(*args, &block)
+      rescue ::RuntimeError => e
+        errors << e
+        e
+      end.last
+      PuppetDebugServer.log_message(:debug, "Finished executing hook #{event_name}") unless event_name == :hook_log_message
+    end
+
+    # @param [Symbol] event_name The name of the event.
+    # @return [Fixnum] The number of hook functions for `event_name`.
+    def hook_count(event_name)
+      @hooks[event_name.to_s].size
+    end
+
+    # @param [Symbol] event_name The name of the event.
+    # @param [Symbol] hook_name The name of the hook
+    # @return [#call] a specific hook for a given event.
+    def get_hook(event_name, hook_name)
+      hook = @hooks[event_name.to_s].find do |current_hook_name, _callable|
+        current_hook_name == hook_name
+      end
+      hook.last if hook
+    end
+
+    # @param [Symbol] event_name The name of the event.
+    # @return [Hash] The hash of hook names / hook functions.
+    # @note Modifying the returned hash does not alter the hooks, use
+    # `add_hook`/`delete_hook` for that.
+    def get_hooks(event_name)
+      (@hooks[event_name.to_s]).to_h
+    end
+
+    # @param [Symbol] event_name The name of the event.
+    # @param [Symbol] hook_name The name of the hook.
+    #   to delete.
+    # @return [#call] The deleted hook.
+    def delete_hook(event_name, hook_name)
+      deleted_callable = nil
+
+      @hooks[event_name.to_s].delete_if do |current_hook_name, callable|
+        if current_hook_name == hook_name
+          deleted_callable = callable
+          true
+        else
+          false
+        end
+      end
+      deleted_callable
+    end
+
+    # Clear all hooks functions for a given event.
+    #
+    # @param [String] event_name The name of the event.
+    # @return [void]
+    def clear_event_hooks(event_name)
+      @hooks[event_name.to_s] = []
+    end
+
+    # @param [Symbol] event_name Name of the event.
+    # @param [Symbol] hook_name Name of the hook.
+    # @return [Boolean] Whether the hook by the name `hook_name`.
+    def hook_exists?(event_name, hook_name)
+      @hooks[event_name.to_s].map(&:first).include?(hook_name)
+    end
+
+    protected
+
+    attr_reader :hooks
+  end
+end

data/lib/puppet-debugserver/message_handler.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'puppet_editor_services/handler/debug_adapter'
+
+module PuppetDebugServer
+  class MessageHandler < PuppetEditorServices::Handler::DebugAdapter
+    # region Message Helpers
+    def send_exited_event(exitcode)
+      protocol.encode_and_send(
+        PuppetEditorServices::Protocol::DebugAdapterMessages.new_event(
+          'exited',
+          'exitCode' => exitcode
+        )
+      )
+    end
+
+    def send_output_event(body_content)
+      protocol.encode_and_send(PuppetEditorServices::Protocol::DebugAdapterMessages.new_event('output', body_content))
+    end
+
+    def send_stopped_event(reason, options = {})
+      protocol.encode_and_send(
+        PuppetEditorServices::Protocol::DebugAdapterMessages.new_event(
+          'stopped',
+          { 'reason' => reason }.merge(options)
+        )
+      )
+    end
+
+    def send_termination_event
+      protocol.encode_and_send(PuppetEditorServices::Protocol::DebugAdapterMessages.new_event('terminated'))
+    end
+
+    def send_thread_event(reason, thread_id)
+      protocol.encode_and_send(
+        PuppetEditorServices::Protocol::DebugAdapterMessages.new_event(
+          'thread',
+          'reason' => reason, 'threadId' => thread_id
+        )
+      )
+    end
+    # end region
+
+    def request_configurationdone(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received configurationDone request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+
+      debug_session.flow_control.assert_flag(:client_completed_configuration)
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(request_message)
+    end
+
+    def request_continue(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received continue request.')
+
+      # Continue the debug session
+      PuppetDebugServer::PuppetDebugSession.instance.flow_control.continue!
+
+      # Send response. We only actually have one thread, but simulate the
+      # allThreadsContinued setting
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        'allThreadsContinued' => true
+      )
+    end
+
+    def request_disconnect(_connection_id, _request_message)
+      # Don't really care about the arguments - Kill everything
+      PuppetDebugServer.log_message(:info, 'Received disconnect request.  Closing connection to client...')
+      protocol.close_connection
+    end
+
+    def request_evaluate(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received evaluate request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) unless debug_session.flow_control.session_active?
+
+      obj = DSP::EvaluateRequest.new(request_message.to_h)
+      begin
+        PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+          request_message,
+          'result' => debug_session.evaluate_string(obj.arguments), 'variablesReference' => 0
+        )
+      rescue => e # rubocop:disable Style/RescueStandardError  Anything could be thrown here. Catch 'em all
+        PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(
+          request_message,
+          e.to_s
+        )
+      end
+    end
+
+    def request_initialize(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received initialize request.')
+      # Save the client capabilities for later use
+      @client_capabilities = request_message.arguments.to_h
+
+      # Send capability response
+      capabilities = DSP::Capabilities.new
+      # We can't accept breakpoints at any time so need them upfront
+      capabilities.supportsConfigurationDoneRequest  = true
+      # The different kind of breakpoints the server supports
+      capabilities.supportsFunctionBreakpoints       = true
+      capabilities.supportsConditionalBreakpoints    = false
+      capabilities.supportsHitConditionalBreakpoints = false
+      capabilities.supportsDataBreakpoints           = false
+      capabilities.supportsLogPoints                 = false
+      capabilities.supportsExceptionOptions          = false
+      # We don't have any filters
+      capabilities.exceptionBreakpointFilters        = []
+      # We only have one thread so no need for this
+      capabilities.supportsTerminateThreadsRequest   = false
+      capabilities.supportTerminateDebuggee          = false
+      # But we can terminate
+      capabilities.supportsTerminateRequest          = true
+      # We can't really restart or go backwards
+      capabilities.supportsRestartRequest            = false
+      capabilities.supportsStepBack                  = false
+      capabilities.supportsRestartFrame              = false
+      # While Puppet "variables" are immutable (and poorly named) when can create new ones
+      capabilities.supportsSetVariable               = true
+      capabilities.supportsSetExpression             = false
+      # We don't support Targets
+      capabilities.supportsGotoTargetsRequest        = false
+      capabilities.supportsStepInTargetsRequest      = false
+      # Puppet doesn't have those kind of modules
+      capabilities.supportsModulesRequest            = false
+      # We don't have that kinda memory or disassembly
+      capabilities.supportsReadMemoryRequest         = false
+      capabilities.supportsDisassembleRequest        = false
+      # Other capabilites which don't make sens in a Puppet world, yet.
+      capabilities.supportsEvaluateForHovers         = false
+      capabilities.supportsCompletionsRequest        = false
+      capabilities.additionalModuleColumns           = []
+      capabilities.supportedChecksumAlgorithms       = []
+      capabilities.supportsValueFormattingOptions    = false
+      capabilities.supportsExceptionInfoRequest      = false
+      capabilities.supportsDelayedStackTraceLoading  = false
+      capabilities.supportsLoadedSourcesRequest      = false
+
+      # Do some initialization
+      # .... dum de dum ...
+      protocol.encode_and_send(PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(request_message, capabilities))
+
+      # Send a message that we are initialized
+      # This must happen _after_ the capabilites are sent. This is pretty janky but _meh_
+      sleep(0.5) # Sleep for a small amount of time to give the client time to process the capabilites response
+      PuppetEditorServices::Protocol::DebugAdapterMessages.new_event('initialized')
+    end
+
+    def request_launch(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received launch request.')
+      # TODO: Do we care about the noDebug?
+
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      # Setup the debug session
+      # Can't use the DSP::LaunchRequest object here because the arguments are dynamic
+      # The :session_setup flag is asserted inside the setup method so no need to for us to do that here
+      debug_session.setup(self, request_message.arguments)
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(request_message)
+    end
+
+    def request_next(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received next request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      obj = DSP::NextRequest.new(request_message.to_h)
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) if debug_session.puppet_thread_id.nil? || debug_session.puppet_thread_id != obj.arguments.threadId
+
+      # Stepout the debug session
+      debug_session.flow_control.next!
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(request_message)
+    end
+
+    def request_scopes(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received scopes request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) unless debug_session.flow_control.session_active?
+
+      obj = DSP::ScopesRequest.new(request_message.to_h)
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        'scopes' => debug_session.generate_scopes_list(obj.arguments.frameId)
+      )
+    end
+
+    def request_setbreakpoints(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received setBreakpoints request.')
+      req = DSP::SetBreakpointsRequest.new(request_message.to_h)
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        'breakpoints' => debug_session.breakpoints.process_set_breakpoints_request!(req.arguments)
+      )
+    end
+
+    def request_setfunctionbreakpoints(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received setFunctionBreakpoints request.')
+      req = DSP::SetFunctionBreakpointsRequest.new(request_message.to_h)
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        'breakpoints' => debug_session.breakpoints.process_set_function_breakpoints_request!(req.arguments)
+      )
+    end
+
+    def request_stacktrace(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received stackTrace request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      obj = DSP::StackTraceRequest.new(request_message.to_h)
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) if debug_session.puppet_thread_id.nil? || debug_session.puppet_thread_id != obj.arguments.threadId
+
+      frames = debug_session.generate_stackframe_list
+
+      # TODO: Should really trim the frame information for the given stack trace request
+      #         /** The index of the first frame to return; if omitted frames start at 0. */
+      #         startFrame?: number;
+      #         /** The maximum number of frames to return. If levels is not specified or 0, all frames are returned. */
+      #         levels?: number;
+      #         /** Specifies details on how to format the stack frames. */
+      #         format?: StackFrameFormat;
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        'stackFrames' => frames, 'totalFrames' => frames.count
+      )
+    end
+
+    def request_stepin(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received stepIn request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      obj = DSP::StepInRequest.new(request_message.to_h)
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) if debug_session.puppet_thread_id.nil? || debug_session.puppet_thread_id != obj.arguments.threadId
+
+      # Stepin the debug session
+      debug_session.flow_control.step_in!
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(request_message)
+    end
+
+    def request_stepout(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received stepOut request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      obj = DSP::StepOutRequest.new(request_message.to_h)
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) if debug_session.puppet_thread_id.nil? || debug_session.puppet_thread_id != obj.arguments.threadId
+
+      # Stepout the debug session
+      debug_session.flow_control.step_out!
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(request_message)
+    end
+
+    def request_threads(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received threads request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) if debug_session.puppet_thread_id.nil?
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        # There is only one thread
+        'threads' => [{ 'id' => debug_session.puppet_thread_id, 'name' => 'puppet' }]
+      )
+    end
+
+    def request_variables(_connection_id, request_message)
+      PuppetDebugServer.log_message(:debug, 'Received variables request.')
+      debug_session = PuppetDebugServer::PuppetDebugSession.instance
+      return PuppetEditorServices::Protocol::DebugAdapterMessages.reply_error(request_message) unless debug_session.flow_control.session_active?
+
+      obj = DSP::VariablesRequest.new(request_message.to_h)
+
+      PuppetEditorServices::Protocol::DebugAdapterMessages.reply_success(
+        request_message,
+        'variables' => debug_session.generate_variables_list(obj.arguments)
+      )
+    end
+  end
+end