puppet-editor-services 2.0.4

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module PuppetDebugServer
+  module DebugSession
+    # Manages storing and validating breakpoints for the Debug Session.
+    class BreakPoints
+      # @param debug_session [PuppetDebugServer::PuppetDebugSession] The debug session to manage the flow for.
+      def initialize(debug_session)
+        @debug_session = debug_session
+
+        @breakpoint_mutex = Mutex.new
+        @source_breakpoints = {}
+        @function_breakpoints = []
+      end
+
+      # Takes the arguments for the setBreakpoints request and then validates that the breakpoints requested
+      # are valid and exist.
+      #
+      # @todo Do we care about Breakpoint.Id? That seems to be only required for activating/deactivating breakpoints dynamically.
+      # @param arguments [DSP::SetBreakpointsArguments]
+      # @return [Array<DSP::Breakpoint>] All of the breakpoints, in the same order as arguments, with validation set correctly.
+      def process_set_breakpoints_request!(arguments)
+        file_path = File.expand_path(arguments.source.path) # Rub-ify the filepath. Important on Windows platforms.
+        file_contents = {}
+
+        if File.exist?(file_path)
+          # Open the file and extact the lines we need
+          line_list = arguments.breakpoints.map(&:line) # These are 1-based line numbers
+
+          begin
+            # TODO: This could be slow on big files....
+            IO.foreach(file_path, mode: 'rb', encoding: 'UTF-8').each_with_index do |item, index|
+              # index here zero-based whereas we want one-based indexing
+              file_contents[index + 1] = item if line_list.include?(index + 1)
+            end
+          rescue StandardError => e
+            PuppetDebugServer.log_message(:error, "Error reading file #{arguments.source.path} for source breakpoints: #{e}")
+          end
+        else
+          PuppetDebugServer.log_message(:debug, "Unable to set source breakpoints for non-existant file #{arguments.source.path}")
+        end
+
+        # Create the initial list of breakpoint responses
+        break_points = arguments.breakpoints.map do
+          DSP::Breakpoint.new.from_h!(
+            'verified' => false,
+            'source' => arguments.source.to_h
+          )
+        end
+
+        # The internal list of break points only cares about valid breakpoints
+        @breakpoint_mutex.synchronize { @source_breakpoints[canonical_file_path(file_path)] = [] }
+        # Verify that each breakpoints is valid
+        arguments.breakpoints.each_with_index do |sbp, bp_index|
+          line_text = file_contents[sbp.line]
+          bp = break_points[bp_index]
+
+          if line_text.nil?
+            bp.message = 'Line does not exist'
+            next
+          end
+
+          bp.line = sbp.line
+
+          # Strip whitespace
+          line_text.strip!
+          # Strip block comments i.e. `  # something`
+          line_text = line_text.partition('#')[0]
+
+          if line_text.empty?
+            bp.message = 'Line is blank'
+          else
+            bp.verified = true
+            @breakpoint_mutex.synchronize { @source_breakpoints[canonical_file_path(file_path)] << bp }
+          end
+        end
+
+        break_points
+      end
+
+      # Takes the arguments for the setFunctionBreakpoints request and then validates that the breakpoints requested are valid.
+      #
+      # @todo Do we care about Breakpoint.Id? That seems to be only required for activating/deactivating breakpoints dynamically.
+      # @param arguments [DSP::SetFunctionBreakpointsArguments]
+      # @return [Array<DSP::Breakpoint>] All of the breakpoints, in the same order as arguments, with validation set correctly.
+      def process_set_function_breakpoints_request!(arguments)
+        # Update this internal list of active breakpoints
+        @breakpoint_mutex.synchronize do
+          @function_breakpoints = arguments.breakpoints
+        end
+
+        # All Function breakpoints are considered valid
+        arguments.breakpoints.map do
+          DSP::Breakpoint.new.from_h!(
+            'verified' => true
+          )
+        end
+      end
+
+      # Returns all of the line breakpoints for a given file.
+      #
+      # @param file_path [String] Absolute path to the file.
+      # @return [Array<Integer>] All of the line breakpoints. Returns empty array if there no breakpoints.
+      def line_breakpoints(file_path)
+        return [] if @source_breakpoints[canonical_file_path(file_path)].nil?
+
+        @source_breakpoints[canonical_file_path(file_path)].map(&:line)
+      end
+
+      # Returns all of the function names that should break on.
+      #
+      # @return [Array<String>] All of the function names that the debugger should break on
+      def function_breakpoint_names
+        result = @function_breakpoints.map(&:name)
+        # Also add the debug::break function which mimics puppet-debug behaviour
+        # https://github.com/nwops/puppet-debug#usage
+        result << 'debug::break'
+      end
+
+      private
+
+      # Returns unique, canonical name for a file path, regardless of Operating System.
+      #
+      # @param file_path [String] The path to canonicalise.
+      # @return [String] All of the function names that the debugger should break on.
+      # @private
+      def canonical_file_path(file_path)
+        # This could be a little dangerous. The paths that come from the editor are URIs, and may or may not always
+        # represent their actual filename on disk e.g. case-insensitive file systems. So a quick and dirty way to
+        # reconcile this is just to always use lowercase file paths. While this works ok on Windows (NTFS or FAT)
+        # other operating systems, could, in theory have two manifests being debugged that only differ by case. This
+        # is not recommend as it breaks cross platform editing, but it's still possible
+        file_path.downcase
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module PuppetDebugServer
+  module DebugSession
+    # Manages the flags used to control the flow of puppet and Debugger during a debug session.
+    class FlowControl
+      # What mode the debug session is running in
+      # @see PuppetDebugServer::DebugSession::PuppetSessionRunMode
+      # @return [PuppetDebugServer::DebugSession::PuppetSessionRunMode]
+      attr_reader :run_mode
+
+      # @param debug_session [PuppetDebugServer::PuppetDebugSession] The debug session to manage the flow for.
+      def initialize(debug_session)
+        @debug_session = debug_session
+
+        @flag_mutex = Mutex.new
+        @flags = {
+          start_puppet: false,
+          puppet_started: false,
+          session_paused: false,
+          client_completed_configuration: false,
+          session_setup: false,
+          terminate: false,
+          suppress_log_messages: false
+        }
+
+        @run_mode = PuppetDebugServer::DebugSession::PuppetSessionRunMode.new
+      end
+
+      # Returns which flags are set.
+      #
+      # Available flags
+      # :start_puppet                       Indicates the main thread can start running Puppet and begin the debug session
+      # :puppet_started                     Indicates the main thread has started running puppet and debug session is now active
+      # :session_paused                     Indicates that the debug session has hit a breakpoint and is currently paused
+      # :client_completed_configuration     The debug client has completed it's configuration
+      # :session_setup                      This debug session has been setup ready to start
+      # :terminate                          Indicates that all threads and wait processes should terminate
+      # :suppress_log_messages              Indicates that Puppet log messages should not be sent to the client
+      #
+      # @param flag_name [Symbol] The name of the flag
+      # @return [Boolean] Whether the flag is set
+      def flag?(flag_name)
+        result = false
+        @flag_mutex.synchronize do
+          result = @flags[flag_name]
+        end
+        result.nil? ? false : result
+      end
+
+      # Asserts a flag is set
+      #
+      # @param flag_name [Symbol] The name of the flag
+      def assert_flag(flag_name)
+        @flag_mutex.synchronize do
+          @flags[flag_name] = true
+          PuppetDebugServer.log_message(:debug, "Asserting flag #{flag_name} is true")
+          # Any custom logic for when flags are asserted
+          # rubocop:disable Style/MultipleComparison, Style/SoleNestedConditional This is faster and doesn't require creation of an array
+          if flag_name == :client_completed_configuration || flag_name == :session_setup
+            # If the client_completed_configuration and session_setup flag are asserted but the session isn't active yet
+            # assert the flag start_puppet so puppet can start in the main thread.
+            if !@flags[:puppet_started] && @flags[:client_completed_configuration] && @flags[:session_setup]
+              PuppetDebugServer.log_message(:debug, 'Asserting flag start_puppet is true')
+              @flags[:start_puppet] = true
+            end
+          end
+          @terminate_flag = true if flag_name == :terminate
+        end
+      end
+      # rubocop:enable Style/MultipleComparison, Style/SoleNestedConditional
+
+      # Removes/unasserts a flag
+      #
+      # @param flag_name [Symbol] The name of the flag
+      def unassert_flag(flag_name)
+        return if flag_name == :terminate # Can never unset the terminate flag
+
+        @flag_mutex.synchronize do
+          @flags[flag_name] = false
+          PuppetDebugServer.log_message(:debug, "Unasserting flag #{flag_name} is true")
+        end
+      end
+
+      # The terminate flag will be queried quite often during spin-wait cycles and it's basically immutable (i.e. Once set it can not be unset).
+      # So to help speed up access just treat it as a normal boolean. This can also stop any deadlocks.
+      #
+      # @return [Boolean] Whether the debug session should be terminating.
+      def terminate?
+        @terminate_flag
+      end
+
+      # Whether the debug session has started.
+      #
+      # @return [Boolean] Returns true if the debug session has started.
+      def session_active?
+        flag?(:puppet_started)
+      end
+
+      # Whether the debug session is paused due to breakpoints.
+      #
+      # @return [Boolean] Returns true if the debug session is paused.
+      def session_paused?
+        flag?(:session_paused)
+      end
+
+      # Raises a stopped event to the Debug Client and waits for the debug session to continue.
+      #
+      # @param reason [String] The reason for the event. Values: 'step', 'breakpoint', 'exception', 'pause', 'entry', 'goto', 'function breakpoint', 'data breakpoint'.
+      # @param description [String] The full reason for the event, e.g. 'Paused on exception'. This string is shown in the UI as is and must be translated.
+      # @param text [String] Additional information. E.g. if reason is 'exception', text contains the exception name. This string is shown in the UI.
+      # @param session_state [Hash] Additional information about the puppet state when the event is raised. See PuppetSessionState::Saved.
+      def raise_stopped_event_and_wait(reason, description, text, session_state)
+        # Signal a stop event
+        assert_flag(:session_paused)
+
+        # Save the state so when the client queries us, we can respond.
+        @debug_session.puppet_session_state.saved.update!(session_state)
+
+        @debug_session.send_stopped_event(
+          reason,
+          'description' => description,
+          'text' => text,
+          'threadId' => @debug_session.puppet_thread_id
+        )
+
+        # Spin-wait for the session to be unpaused...
+        # TODO - Could be better. Semaphore maybe?
+        sleep(0.5) while flag?(:session_paused) && !terminate?
+      end
+
+      # Continues a paused debug session
+      def continue!
+        run_mode.run!
+        @debug_session.puppet_session_state.saved.clear!
+        unassert_flag(:session_paused)
+      end
+
+      # Next steps through a paused debug session
+      def next!
+        run_mode.next!(@debug_session.puppet_session_state.saved.pops_depth_level)
+        @debug_session.puppet_session_state.saved.clear!
+        unassert_flag(:session_paused)
+      end
+
+      # Steps into a paused debug session
+      def step_in!
+        run_mode.step_in!
+        @debug_session.puppet_session_state.saved.clear!
+        unassert_flag(:session_paused)
+      end
+
+      # Steps out of a paused debug session
+      def step_out!
+        run_mode.step_out!(@debug_session.puppet_session_state.saved.pops_depth_level)
+        @debug_session.puppet_session_state.saved.clear!
+        unassert_flag(:session_paused)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module PuppetDebugServer
+  module DebugSession
+    # Implements the hooks within the debug session.
+    #
+    # @todo The following hooks are not implemented
+    # :hook_after_compile
+    #   Fires after a catalog compilation is succesfully completed
+    #   Arguments:
+    #     Puppet::Resource::Catalog - Resultant compiled catalog
+    #
+    # :hook_before_parser_function_reset
+    #   Fires before the Puppet::Parser::Functions is reset, destroying the existing list of loaded functions
+    #   Arguments:
+    #     Puppet::Parser::Functions - Instance of Puppet::Parser::Functions
+    #
+    class HookHandlers
+      # List of Puppet POPS classes that the Source Breakpoints will NOT trigger on
+      EXCLUDED_CLASSES = %w[BlockExpression HostClassDefinition].freeze
+
+      # @param debug_session [PuppetDebugServer::PuppetDebugSession] The debug session to manage the hooks for.
+      def initialize(debug_session)
+        @debug_session = debug_session
+
+        @debug_session.hook_manager.add_hook(:hook_after_parser_function_reset, :debug_session) { |args| on_hook_after_parser_function_reset(args) }
+        @debug_session.hook_manager.add_hook(:hook_after_pops_evaluate, :debug_session)         { |args| on_hook_after_pops_evaluate(args) }
+        @debug_session.hook_manager.add_hook(:hook_before_apply_exit, :debug_session)           { |args| on_hook_before_apply_exit(args) }
+        @debug_session.hook_manager.add_hook(:hook_before_compile, :debug_session)              { |args| on_hook_before_compile(args) }
+        @debug_session.hook_manager.add_hook(:hook_before_pops_evaluate, :debug_session)        { |args| on_hook_before_pops_evaluate(args) }
+        @debug_session.hook_manager.add_hook(:hook_breakpoint, :debug_session)                  { |args| on_hook_breakpoint(args) }
+        @debug_session.hook_manager.add_hook(:hook_exception, :debug_session)                   { |args| on_hook_exception(args) }
+        @debug_session.hook_manager.add_hook(:hook_function_breakpoint, :debug_session)         { |args| on_hook_function_breakpoint(args) }
+        @debug_session.hook_manager.add_hook(:hook_log_message, :debug_session)                 { |args| on_hook_log_message(args) }
+        @debug_session.hook_manager.add_hook(:hook_step_breakpoint, :debug_session)             { |args| on_hook_step_breakpoint(args) }
+      end
+
+      #  Fires after the Puppet::Parser::Functions class is reset
+      #  Arguments:
+      #    Puppet::Parser::Functions - Instance of Puppet::Parser::Functions
+      def on_hook_after_parser_function_reset(args)
+        func_object = args[0]
+
+        # This mimics the break function from puppet-debugger
+        # https://github.com/nwops/puppet-debug#usage
+        func_object.newfunction(:'debug::break', 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
+
+      # Fires after an item in the AST is evaluated
+      # Arguments:
+      #   The Pops object about to be evaluated
+      #   The scope of the Pops object
+      def on_hook_after_pops_evaluate(_args)
+        # If the debug session is paused no need to process
+        return if @debug_session.flow_control.session_paused?
+
+        @debug_session.puppet_session_state.actual.decrement_pops_depth
+      end
+
+      # Fires before the Puppet::Apply application tries to call Kernel#exit.
+      # Arguments:
+      #   Integer - Exit Code
+      def on_hook_before_apply_exit(args)
+        option = args[0]
+
+        @debug_session.send_exited_event(option)
+        @debug_session.send_output_event(
+          'category' => 'console',
+          'output' => "puppet exited with #{option}"
+        )
+
+        @debug_session.flow_control.unassert_flag(:puppet_started)
+        @debug_session.close
+
+        # Wait up to 30 seconds for the client to disconnect and stop the debug session
+        # Anymore than that and we force the debug session to stop.
+        sleep(30)
+        @debug_session.force_terminate
+      end
+
+      # Fires before a catalog compilation is attempted
+      # Arguments:
+      #   Puppet::Parser::Compiler - Current compiler in use
+      def on_hook_before_compile(args)
+        @debug_session.puppet_session_state.actual.update_compiler(args[0])
+
+        # Spin-wait for the configurationDone message from the client before we continue compilation
+        return if @debug_session.flow_control.flag?(:client_completed_configuration)
+
+        sleep(0.5) until @debug_session.flow_control.flag?(:client_completed_configuration)
+      end
+
+      #   Fires before an item in the AST is evaluated during a catalog compilation
+      #   Arguments:
+      #     The Pops object about to be evaluated
+      #     The scope of the Pops object
+      def on_hook_before_pops_evaluate(args)
+        # If the debug session is paused no need to process
+        return if @debug_session.flow_control.session_paused?
+
+        @debug_session.puppet_session_state.actual.increment_pops_depth
+
+        target = args[1]
+        # Ignore this if there is no positioning information available
+        return unless target.is_a?(Puppet::Pops::Model::Positioned)
+
+        target_loc = @debug_session.get_location_from_pops_object(target)
+
+        # 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_loc.file.nil? || target_loc.file.empty?
+
+        target_classname = @debug_session.get_puppet_class_name(target)
+        ast_classname = get_ast_class_name(target)
+
+        # Break if we hit a specific puppet function
+        if target_classname == 'CallNamedFunctionExpression' && @debug_session.breakpoints.function_breakpoint_names.include?(target.functor_expr.value)
+          # Re-raise the hook as a breakpoint
+          @debug_session.execute_hook(:hook_function_breakpoint, [target.functor_expr.value, ast_classname] + args)
+          return
+        end
+
+        # Check for Source based breakpoints
+        unless target_loc.length.zero? || EXCLUDED_CLASSES.include?(target_classname)
+          line_breakpoints = @debug_session.breakpoints.line_breakpoints(target_loc.file)
+
+          # Calculate the start and end lines of the target
+          target_start_line = target_loc.line
+          target_end_line   = @debug_session.line_for_offset(target, target_loc.offset + target_loc.length)
+
+          # TODO: What about Hit and Conditional BreakPoints?
+          bp = line_breakpoints.find_index { |bp_line| bp_line >= target_start_line && bp_line <= target_end_line }
+          unless bp.nil?
+            # Re-raise the hook as a breakpoint
+            @debug_session.execute_hook(:hook_breakpoint, [ast_classname, ''] + args)
+            return
+          end
+        end
+
+        # Break if we are stepping
+        case @debug_session.flow_control.run_mode.mode
+        when :stepin
+          # Stepping-in is basically break on everything
+          # Re-raise the hook as a step breakpoint
+          @debug_session.execute_hook(:hook_step_breakpoint, [ast_classname, ''] + args)
+        when :next
+          # Next will break on anything at this Pop depth or shallower than this Pop depth. Re-raise the hook as a step breakpoint
+          depth = @debug_session.flow_control.run_mode.options[:pops_depth_level] || -1
+          if @debug_session.puppet_session_state.actual.pops_depth_level <= depth # rubocop:disable Style/IfUnlessModifier
+            @debug_session.execute_hook(:hook_step_breakpoint, [ast_classname, ''] + args)
+          end
+        when :stepout
+          # Stepping-Out will break on anything shallower than this Pop depth. Re-raise the hook as a step breakpoint
+          depth = @debug_session.flow_control.run_mode.options[:pops_depth_level] || -1
+          if @debug_session.puppet_session_state.actual.pops_depth_level < depth # rubocop:disable Style/IfUnlessModifier
+            @debug_session.execute_hook(:hook_step_breakpoint, [ast_classname, ''] + args)
+          end
+        end
+        nil
+      end
+
+      # Fires when a source/line breakpoint is hit
+      # Arguments:
+      #   String - Breakpoint display text
+      #   String - Breakpoint full text
+      #   Object - self where the breakpoint was hit
+      #   Object[] - optional objects
+      def on_hook_breakpoint(args)
+        process_breakpoint_hook('breakpoint', args)
+      end
+
+      # Fires when an unhandled exception is hit during puppet apply
+      # Arguments:
+      #   Error - The exception information
+      def on_hook_exception(args)
+        # If the debug session is paused, can't raise a new exception
+        return if @debug_session.flow_control.session_paused?
+
+        error_detail = args[0]
+
+        @debug_session.flow_control.raise_stopped_event_and_wait(
+          'exception',
+          'Compilation Exception',
+          error_detail.basic_message,
+          session_exception: error_detail,
+          puppet_stacktrace: Puppet::Pops::PuppetStack.stacktrace_from_backtrace(error_detail)
+        )
+      end
+
+      # Fires when a function breakpoint is hit
+      # Arguments:
+      #   String - Breakpoint display text
+      #   String - Breakpoint full text
+      #   Object - self where the function breakpoint was hit
+      #   Object[] - optional objects
+      def on_hook_function_breakpoint(args)
+        process_breakpoint_hook('function breakpoint', args)
+      end
+
+      # Fires when a message is sent to the puppet logger
+      # Arguments:
+      #   Message - The message being sent to the log
+      def on_hook_log_message(args)
+        return if @debug_session.flow_control.flag?(:suppress_log_messages)
+
+        msg = args[0]
+        str = msg.respond_to?(:multiline) ? msg.multiline : msg.to_s
+        str = "#{msg.source}: #{str}" unless msg.source == 'Puppet'
+
+        level = msg.level.to_s.capitalize
+
+        category = 'stderr'
+        category = 'stdout' if msg.level == :notice || msg.level == :info || msg.level == :debug
+
+        @debug_session.send_output_event(
+          'category' => category,
+          'output' => "#{level}: #{str}\n"
+        )
+      end
+
+      # Fires when a function breakpoint is hit
+      # Arguments:
+      #   String - Breakpoint display text
+      #   String - Breakpoint full text
+      #   Object - self where the step breakpoint was hit
+      #   Object[] - optional objects
+      def on_hook_step_breakpoint(args)
+        process_breakpoint_hook('step', args)
+      end
+
+      private
+
+      # Raises a stop event and waits for the debug session to continue for a given breakpoint type.
+      #
+      # @param reason [String] The type of breakpoint that was hit
+      # @param args [Array<Object>] An array of arguments for the breakpoint
+      # @private
+      def process_breakpoint_hook(reason, args)
+        # If the debug session is paused no need to process
+        return if @debug_session.flow_control.session_paused?
+
+        break_display_text = args[0] # TODO: REALLY don't like all this magic array stuff. Real Object? Hash?
+        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 = @debug_session.puppet_session_state.actual.pops_depth_level
+        end
+
+        break_description = break_display_text if break_description.empty?
+        # Due to a modification to the way stack traces are treated in Puppet 6.11.0, the stack
+        # now includes entries for files in Line 0, which doesn't exist. These indicate that a file
+        # has started to be processed/parsed/compiled. So we just ignore them
+        # See https://tickets.puppetlabs.com/browse/PUP-10150 for more infomation
+        stack_trace = Puppet::Pops::PuppetStack.stacktrace.reject { |item| item[1].zero? }
+        # Due to https://github.com/puppetlabs/puppet/commit/0f96dd918b6184261bc2219e5e68e246ffbeac10
+        # Prior to Puppet 4.8.0, stacktrace is in reverse order
+        stack_trace.reverse! if Gem::Version.new(Puppet.version) < Gem::Version.new('4.8.0')
+
+        @debug_session.flow_control.raise_stopped_event_and_wait(
+          reason,
+          break_display_text,
+          break_description,
+          pops_target: pops_target_object,
+          scope: scope_object,
+          pops_depth_level: pops_depth_level,
+          puppet_stacktrace: stack_trace
+        )
+      end
+
+      # Retrieves the name of a Puppet AST object for Puppet 5+ and Puppet 4.x.
+      #
+      # @param obj [Object] The Puppet POPS object.
+      # @return [String] Then class name of the object
+      # @private
+      def get_ast_class_name(obj)
+        # Puppet 5 has PCore Types
+        return obj._pcore_type.name if obj.respond_to?(:_pcore_type)
+
+        # .. otherwise revert to Pops classname
+        obj.class.to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PuppetDebugServer
+  module DebugSession
+    # The run mode and configuration for a Debug Session.
+    class PuppetSessionRunMode
+      # The run mode fo the debug session. Either run, stepin, next, or stepout
+      # @return [Symbol]
+      attr_accessor :mode
+
+      # Any options associated with the current mode.
+      # @option options [Integer] :pops_depth_level The depth of the AST object where the mode was initiated from.
+      # @return [Hash]
+      attr_accessor :options
+
+      # @param mode See mode. Default is run
+      # @param options See options
+      def initialize(mode = :run, options = {})
+        raise "Invalid mode #{mode}" unless %i[run stepin next stepout].include?(mode)
+
+        @mode = mode
+        @options = options
+
+        @run_mode_mutex = Mutex.new
+      end
+
+      # Configures the run_mode for "continue until a breakpoint is hit.
+      def run!
+        @run_mode_mutex.synchronize do
+          @mode = :run
+          @options = {}
+        end
+      end
+
+      # Configures the run_mode for "next"-ing through a debug session.
+      # @param pops_depth_level [Integer] The depth of the AST object where the next command was initiated from.
+      def next!(pops_depth_level)
+        @run_mode_mutex.synchronize do
+          @mode = :next
+          @options = {
+            pops_depth_level: pops_depth_level
+          }
+        end
+      end
+
+      # Configures the run_mode for "stepping in" a debug session.
+      def step_in!
+        @run_mode_mutex.synchronize do
+          @mode = :stepin
+          @options = {}
+        end
+      end
+
+      # Configures the run_mode for "stepping out" a debug session.
+      # @param pops_depth_level [Integer] The depth of the AST object  where the step put command was initiated from.
+      def step_out!(pops_depth_level)
+        @run_mode_mutex.synchronize do
+          @mode = :stepout
+          @options = {
+            pops_depth_level: pops_depth_level
+          }
+        end
+      end
+    end
+  end
+end