canopus 0.4.0 → 0.5.0

data/lib/canopus/debug/configuration.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "kochab"
+require_relative "../error"
+require_relative "../settings"
+
+module Canopus
+  module Debug
+    class Configuration
+      RELATIVE_PATH = File.join(".canopus", "launch.jsonc")
+      MAX_BYTES = 1_048_576
+      MAX_CONFIGURATIONS = 128
+      MAX_DEPTH = 20
+      MAX_COLLECTION_SIZE = 1_024
+      MAX_STRING_BYTES = 65_536
+      MAX_EXPANDED_STRING_BYTES = 1_048_576
+      MAX_TOTAL_EXPANDED_BYTES = 1_048_576
+      MAX_ENVIRONMENT_ENTRY_BYTES = 1_048_576
+      MAX_ENVIRONMENT_BYTES = 1_048_576
+      VARIABLE = /\$\{([^{}]+)\}/
+
+      attr_reader :root, :configurations
+
+      def initialize(root:, settings: Settings.new, environment: ENV)
+        @root = canonical_root(root)
+        @settings = settings
+        @environment = snapshot_environment(environment)
+        @configurations = load_configurations
+      end
+
+      def resolve(configuration, file: nil, line_number: nil, selected_text: nil)
+        source = configuration.is_a?(String) ? @configurations.find { |item| item["name"] == configuration } :
+          @configurations.find { |item| item.equal?(configuration) }
+        raise Error, "unknown debug configuration" unless source
+        resolved = expand_value(source, context(file, line_number, selected_text), [MAX_TOTAL_EXPANDED_BYTES])
+        %w[program cwd].each do |key|
+          resolved[key] = project_path(resolved[key], key) if resolved.key?(key)
+        end
+        freeze_value(resolved)
+      end
+
+      def adapter(type, file: nil, line_number: nil, selected_text: nil)
+        raise Error, "debug adapter type must be a string" unless type.is_a?(String)
+        options = @settings["debug_adapters"]
+        options = options[type] if options.is_a?(Hash)
+        raise Error, "no debug adapter configured for #{type}" unless options
+        freeze_value(expand_value(options, context(file, line_number, selected_text), [MAX_TOTAL_EXPANDED_BYTES]))
+      end
+
+      private
+
+      def canonical_root(root)
+        path = File.realpath(root)
+        raise Error, "debug workspace root must be a directory" unless File.directory?(path)
+        path.freeze
+      rescue SystemCallError, TypeError => error
+        raise Error, "invalid debug workspace root: #{error.message}"
+      end
+
+      def load_configurations
+        path = File.join(@root, RELATIVE_PATH)
+        unless File.exist?(path)
+          raise Error, "debug configuration path is a broken symlink" if File.symlink?(path)
+          return fallback_configurations
+        end
+        real_path = File.realpath(path)
+        raise Error, "debug configuration is outside the workspace" unless inside_root?(real_path)
+        raise Error, "debug configuration must be a regular file" unless File.file?(real_path)
+        raise Error, "debug configuration exceeds 1 MiB" if File.size(real_path) > MAX_BYTES
+        source = File.binread(real_path, MAX_BYTES + 1).force_encoding(Encoding::UTF_8)
+        raise Error, "debug configuration must be valid UTF-8" unless source.valid_encoding?
+        raise Error, "debug configuration exceeds 1 MiB" if source.bytesize > MAX_BYTES
+        document = Kochab.parse(source)
+        raise Error, "invalid debug configuration: #{RELATIVE_PATH}" unless document.valid?
+        root = document.value
+        raise Error, "debug configuration must be an object" unless root.is_a?(Hash) && root.keys.all? { |key| key.is_a?(String) }
+        entries = root.fetch("configurations", [])
+        unless entries.is_a?(Array) && entries.length <= MAX_CONFIGURATIONS
+          raise Error, "configurations must be an array of at most #{MAX_CONFIGURATIONS} items"
+        end
+        entries = entries.map { |entry| validate_configuration(entry) }
+        names = entries.map { |entry| entry["name"] }
+        raise Error, "debug configuration names must be unique" unless names.uniq.length == names.length
+        entries.empty? ? fallback_configurations : entries.freeze
+      rescue SystemCallError => error
+        raise Error, "cannot read debug configuration: #{error.message}"
+      end
+
+      def validate_configuration(entry)
+        raise Error, "each debug configuration must be an object" unless entry.is_a?(Hash)
+        validate_json(entry)
+        bounded_identifier(entry["name"], "debug configuration name", 256)
+        type = bounded_identifier(entry["type"], "debug configuration type", 128)
+        raise Error, "invalid debug configuration type" unless type.match?(/\A[A-Za-z0-9_.-]+\z/)
+        raise Error, "debug request must be launch or attach" unless %w[launch attach].include?(entry["request"])
+        %w[program cwd].each do |key|
+          raise Error, "debug #{key} must be a string" if entry.key?(key) && !entry[key].is_a?(String)
+        end
+        if entry.key?("args") && !(entry["args"].is_a?(Array) && entry["args"].length <= 256 && entry["args"].all? { |arg| arg.is_a?(String) })
+          raise Error, "debug args must be an array of at most 256 strings"
+        end
+        if entry.key?("env") && !(entry["env"].is_a?(Hash) && entry["env"].length <= 256 &&
+          entry["env"].all? { |key, value| key.is_a?(String) && (value.nil? || value.is_a?(String)) })
+          raise Error, "debug env must be an object of at most 256 string values"
+        end
+        freeze_value(entry)
+      end
+
+      def validate_json(value, depth = 0)
+        raise Error, "debug configuration is nested too deeply" if depth > MAX_DEPTH
+        case value
+        when Hash
+          raise Error, "debug object has too many properties" if value.length > MAX_COLLECTION_SIZE
+          value.each do |key, child|
+            bounded_identifier(key, "debug option name", 256)
+            validate_json(child, depth + 1)
+          end
+        when Array
+          raise Error, "debug array has too many items" if value.length > MAX_COLLECTION_SIZE
+          value.each { |child| validate_json(child, depth + 1) }
+        when String
+          valid_string!(value, "debug string", MAX_STRING_BYTES)
+        when Integer, TrueClass, FalseClass, NilClass
+          nil
+        when Float
+          raise Error, "debug numbers must be finite" unless value.finite?
+        else
+          raise Error, "unsupported debug value"
+        end
+      end
+
+      def bounded_identifier(value, label, maximum)
+        valid_string!(value, label, maximum)
+        unless value == value.strip && !value.empty? && !value.match?(/[\x00-\x1f\x7f]/)
+          raise Error, "invalid #{label}"
+        end
+        value
+      end
+
+      def valid_string!(value, label, maximum)
+        unless value.is_a?(String) && value.valid_encoding? &&
+          (value.encoding == Encoding::UTF_8 || value.ascii_only?) &&
+          value.bytesize <= maximum && !value.include?("\0")
+          raise Error, "invalid #{label}"
+        end
+      end
+
+      def context(file, line_number, selected_text)
+        {"file" => file && project_path(file, "file"), "lineNumber" => line_number,
+         "selectedText" => selected_text}
+      end
+
+      def expand_value(value, variables, budget)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.dup, expand_value(child, variables, budget)] }
+        when Array
+          value.map { |child| expand_value(child, variables, budget) }
+        when String
+          expand_string(value, variables, budget)
+        else
+          value
+        end
+      end
+
+      def expand_string(value, variables, budget)
+        expanded = +""
+        cursor = 0
+        remaining = MAX_EXPANDED_STRING_BYTES
+        while (match = VARIABLE.match(value, cursor))
+          marker = value.index("${", cursor)
+          raise Error, "malformed debug variable" unless marker == match.begin(0)
+          remaining = append_expanded!(expanded, value[cursor...marker], budget, remaining)
+          name = match[1]
+          replacement = if name == "workspaceFolder"
+            @root
+          elsif variables.key?(name)
+            variable(name, variables[name])
+          elsif name.start_with?("env:")
+            environment_variable(name.delete_prefix("env:"))
+          else
+            raise Error, "unknown debug variable: #{name}"
+          end
+          remaining = append_expanded!(expanded, replacement, budget, remaining)
+          cursor = match.end(0)
+        end
+        raise Error, "malformed debug variable" if value.index("${", cursor)
+        append_expanded!(expanded, value[cursor..] || "", budget, remaining)
+        expanded
+      end
+
+      def append_expanded!(output, value, budget, remaining)
+        bytes = value.bytesize
+        if bytes > remaining || bytes > budget[0]
+          raise Error, "expanded debug data exceeds 1 MiB"
+        end
+        output << value
+        budget[0] -= bytes
+        remaining - bytes
+      end
+
+      def variable(name, value)
+        raise Error, "debug variable #{name} is unavailable" if value.nil?
+        if name == "lineNumber"
+          raise Error, "lineNumber must be a positive integer" unless value.is_a?(Integer) && value.positive? && value <= 2_147_483_647
+          return value.to_s
+        end
+        valid_string!(value, name, MAX_EXPANDED_STRING_BYTES)
+        value
+      end
+
+      def environment_variable(name)
+        raise Error, "invalid environment variable name" unless name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+        raise Error, "environment variable #{name} is unavailable" unless @environment.key?(name)
+        valid_string!(@environment[name], "environment variable #{name}", MAX_EXPANDED_STRING_BYTES)
+        @environment[name]
+      end
+
+      def project_path(value, label)
+        valid_string!(value, label, MAX_EXPANDED_STRING_BYTES)
+        raise Error, "debug #{label} must not be empty" if value.empty?
+        path = File.expand_path(value, @root)
+        if File.exist?(path)
+          path = File.realpath(path)
+        else
+          ancestor, suffix = path, []
+          until File.exist?(ancestor) || File.dirname(ancestor) == ancestor
+            suffix.unshift(File.basename(ancestor))
+            ancestor = File.dirname(ancestor)
+          end
+          path = File.join(File.realpath(ancestor), *suffix) if File.exist?(ancestor)
+        end
+        raise Error, "debug #{label} is outside the workspace" unless inside_root?(path)
+        cursor = path
+        until cursor == @root
+          if File.symlink?(cursor)
+            raise Error, "debug #{label} is outside the workspace" unless inside_root?(File.realpath(cursor))
+          end
+          cursor = File.dirname(cursor)
+        end
+        raise Error, "debug cwd must be a directory" if label == "cwd" && File.exist?(path) && !File.directory?(path)
+        raise Error, "debug program must not be a directory" if label == "program" && File.directory?(path)
+        path
+      rescue SystemCallError => error
+        raise Error, "invalid debug #{label}: #{error.message}"
+      end
+
+      def inside_root?(path)
+        path == @root || path.start_with?(@root.end_with?(File::SEPARATOR) ? @root : "#{@root}#{File::SEPARATOR}")
+      end
+
+      def snapshot_environment(environment)
+        raise Error, "debug environment must provide string pairs" unless environment.respond_to?(:each_pair)
+        pairs, total = [], 0
+        environment.each_pair do |key, value|
+          raise Error, "debug environment has too many entries" if pairs.length >= 4_096
+          valid = key.is_a?(String) && value.is_a?(String) && key.valid_encoding? && value.valid_encoding? &&
+            (key.encoding == Encoding::UTF_8 || key.ascii_only?) &&
+            (value.encoding == Encoding::UTF_8 || value.ascii_only?) &&
+            key.bytesize.between?(1, 256) && value.bytesize <= MAX_ENVIRONMENT_ENTRY_BYTES &&
+            !key.include?("\0") && !value.include?("\0")
+          raise Error, "invalid debug environment entry" unless valid
+          total += key.bytesize + value.bytesize
+          raise Error, "debug environment exceeds 1 MiB" if total > MAX_ENVIRONMENT_BYTES
+          pairs << [key, value]
+        end
+        pairs.to_h do |key, value|
+          [key.dup.freeze, value.dup.freeze]
+        end.freeze
+      end
+
+      def fallback_configurations
+        rakefile = %w[Rakefile rakefile].find do |name|
+          path = File.join(@root, name)
+          File.file?(path) && inside_root?(File.realpath(path))
+        end
+        return [].freeze unless rakefile
+        [freeze_value({"name" => "Run tests", "type" => "ruby", "request" => "launch",
+          "program" => "${workspaceFolder}/bin/rake", "args" => ["test"], "cwd" => "${workspaceFolder}"})].freeze
+      rescue SystemCallError
+        [].freeze
+      end
+
+      def freeze_value(value)
+        value.each { |key, child| key.freeze; freeze_value(child) } if value.is_a?(Hash)
+        value.each { |child| freeze_value(child) } if value.is_a?(Array)
+        value.freeze
+      end
+    end
+  end
+end

data/lib/canopus/debug/console.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "set"
+require "zaniah/ui"
+
+module Canopus
+  module Debug
+    class Console
+      ITEM_LIMIT = 1_000
+      TEXT_LIMIT = 4_096
+      PENDING_LIMIT = 16
+      OUTPUT_QUEUE_LIMIT = ITEM_LIMIT
+
+      attr_reader :tree, :entries, :selected_frame
+
+      def initialize(post:, request_frame:)
+        raise ArgumentError, "debug console callbacks must be callable" unless [post, request_frame].all? { |item| item.respond_to?(:call) }
+
+        @post, @request_frame = post, request_frame
+        @generation = @sequence = 0
+        @pending = Set.new
+        @output_lock = Mutex.new
+        @output_generation = 0
+        @output_queue = []
+        @output_flush_pending = false
+        @entries = [].freeze
+        @tree = Zaniah::UI::TreeView.new(nodes, height: 320)
+      end
+
+      def attach(session)
+        reset_requests
+        reset_output(session)
+        @selected_frame = nil
+        @entries = [].freeze
+        refresh
+        self
+      end
+
+      def stopped(session, frame)
+        return false unless @session.equal?(session)
+
+        reset_requests
+        @selected_frame = frame
+        true
+      end
+
+      def continued(session)
+        return false unless @session.equal?(session)
+
+        reset_requests
+        @selected_frame = nil
+        true
+      end
+
+      def clear
+        detach
+        @entries = [].freeze
+        refresh
+        nil
+      end
+
+      def detach
+        reset_requests
+        reset_output(nil)
+        @selected_frame = nil
+        nil
+      end
+
+      def output(session, event)
+        return false unless output_session?(session)
+        rows = output_rows(event)
+        return false if rows.empty?
+
+        schedule = false
+        generation = @output_lock.synchronize do
+          next unless @session.equal?(session)
+
+          room = OUTPUT_QUEUE_LIMIT - @output_queue.length
+          @output_queue.concat(rows.first(room)) if room.positive?
+          unless @output_flush_pending
+            @output_flush_pending = schedule = true
+          end
+          @output_generation
+        end
+        return false unless generation
+
+        @post.call { flush_output(session, generation) } if schedule
+        true
+      end
+
+      def evaluate(expression)
+        expression = checked_expression(expression)
+        raise Error, "debug session is not stopped" unless active?
+        raise Error, "too many pending debug evaluations" if @pending.length >= PENDING_LIMIT
+
+        generation, session, frame = @generation, @session, @selected_frame
+        append("> #{expression}")
+        future = session.evaluate(expression, frame_id: frame.id, context: "repl")
+        @pending.add(future)
+        future.on_complete do |variable, error|
+          @post.call do
+            @pending.delete(future)
+            next unless generation == @generation && @session.equal?(session) && @selected_frame.equal?(frame)
+
+            if error
+              append("Error: #{bounded_text(error.message)}")
+            else
+              append(result_label(variable))
+            end
+          end
+        end
+        future
+      end
+
+      private
+
+      def active? = !!(@session && @selected_frame)
+
+      def nodes
+        return [{id: [:debug_console_status, :empty].freeze, label: "No debug output", value: nil}.freeze] if @entries.empty?
+
+        @entries.map { |entry| {id: [:debug_console, entry[:id]].freeze, label: entry[:label], value: nil}.freeze }.freeze
+      end
+
+      def append(label)
+        append_rows([bounded_text(label)])
+      end
+
+      def append_rows(rows)
+        @sequence += 1
+        added = rows.each_with_index.map do |label, index|
+          {id: @sequence + index, label: bounded_line(label).freeze}.freeze
+        end
+        @sequence += added.length - 1
+        @entries = [*@entries, *added].last(ITEM_LIMIT).freeze
+        refresh
+      end
+
+      def refresh
+        @tree.replace(nodes)
+        @request_frame.call
+      end
+
+      def output_rows(event)
+        return [] unless event.is_a?(Hash)
+
+        output = event["output"] || event[:output]
+        return [] unless output.is_a?(String)
+        output = bounded_output(output)
+        return [] if output.empty?
+
+        category = event["category"] || event[:category]
+        category = bounded_text(category) if category.is_a?(String)
+        source = event["source"] || event[:source]
+        source = source_label(source)
+        line = event["line"] || event[:line]
+        line = nil unless line.is_a?(Integer) && line.between?(1, 0x7fff_ffff)
+        location = source && line ? "#{source}:#{line}" : source
+        prefix = [category, location].compact.reject(&:empty?)
+        prefix = prefix.empty? ? "" : "[#{prefix.join(" ")}] "
+        rows = output.split("\n", -1)
+        rows.pop if output.end_with?("\n")
+        rows[0] = "#{prefix}#{rows[0]}" unless prefix.empty?
+        rows.first(OUTPUT_QUEUE_LIMIT).map { |row| bounded_line(row).freeze }.freeze
+      end
+
+      def source_label(source)
+        return unless source.is_a?(Hash)
+
+        value = source["name"] || source[:name]
+        unless value.is_a?(String) && !value.empty?
+          path = source["path"] || source[:path]
+          return unless path.is_a?(String)
+
+          value = bounded_text(path).tr("\\", "/").split("/").last
+        end
+        value = bounded_text(value).tr("\\", "/")
+        value.include?("/") ? value.split("/").last : value
+      end
+
+      def result_label(variable)
+        value = variable.respond_to?(:value) ? variable.value : nil
+        type = variable.respond_to?(:type) ? variable.type : nil
+        text = bounded_text(value)
+        type = bounded_text(type) if type
+        type && !type.empty? ? "#{text} · #{type}" : text
+      end
+
+      def checked_expression(value)
+        valid = value.is_a?(String) && value.encoding == Encoding::UTF_8 && value.valid_encoding? &&
+          value.bytesize.between?(1, TEXT_LIMIT) && !value.include?("\0") && !value.strip.empty?
+        raise ArgumentError, "invalid debug expression" unless valid
+
+        value.dup.freeze
+      end
+
+      def bounded_text(value)
+        value.to_s.byteslice(0, TEXT_LIMIT).to_s.dup.force_encoding(Encoding::UTF_8).scrub("")
+          .gsub(/[\x00-\x1f\x7f]+/, " ").gsub(/\s+/, " ").strip
+      end
+
+      def bounded_output(value)
+        value.byteslice(0, TEXT_LIMIT).to_s.dup.force_encoding(Encoding::UTF_8).scrub("")
+          .gsub(/\r\n?/, "\n").gsub(/[\x00-\x09\x0b\x0c\x0e-\x1f\x7f]+/, " ")
+      end
+
+      def bounded_line(value)
+        value.to_s.byteslice(0, TEXT_LIMIT).to_s.dup.force_encoding(Encoding::UTF_8).scrub("")
+      end
+
+      def output_session?(session) = @output_lock.synchronize { @session.equal?(session) }
+
+      def flush_output(session, generation)
+        rows = @output_lock.synchronize do
+          next unless generation == @output_generation && @session.equal?(session)
+
+          values, @output_queue = @output_queue, []
+          @output_flush_pending = false
+          values
+        end
+        return false unless rows && !rows.empty?
+
+        append_rows(rows)
+        true
+      end
+
+      def reset_output(session)
+        @output_lock.synchronize do
+          @output_generation += 1
+          @session = session
+          @output_queue = []
+          @output_flush_pending = false
+        end
+      end
+
+      def reset_requests
+        @generation += 1
+        pending, @pending = @pending, Set.new
+        pending.each(&:cancel)
+      end
+    end
+  end
+end