megrez 0.1.0

data/lib/megrez/testing/fake_adapter.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Megrez
+  module Testing
+    class FakeAdapter
+      DEFAULT_CAPABILITIES = {
+        "supportsConfigurationDoneRequest" => true,
+        "supportsConditionalBreakpoints" => true,
+        "supportsLogPoints" => true,
+        "supportsSetVariable" => true,
+        "supportsSetExpression" => true,
+        "supportsCompletionsRequest" => true,
+        "supportsCancelRequest" => true
+      }.freeze
+
+      attr_reader :messages
+
+      def self.command
+        root = File.expand_path("../..", __dir__)
+        [RbConfig.ruby, "-I#{root}", "-rmegrez/testing", "-e", "Megrez::Testing::FakeAdapter.run_stdio"]
+      end
+
+      def self.run_stdio = new.serve(STDIN, STDOUT)
+
+      def initialize(responses: {}, capabilities: DEFAULT_CAPABILITIES, variable_count: 3)
+        raise ArgumentError, "responses must be a Hash" unless responses.is_a?(Hash)
+        raise ArgumentError, "capabilities must be a Hash" unless capabilities.is_a?(Hash)
+        raise ArgumentError, "variable_count must be nonnegative" unless variable_count.is_a?(Integer) && variable_count >= 0
+
+        @responses = responses.transform_keys(&:to_s)
+        @capabilities = capabilities
+        @variable_count = variable_count
+        @messages = []
+        @sequence = 0
+        @lock = Mutex.new
+        @sinks = []
+      end
+
+      def transport(&receive) = FakeTransport.new(self, &receive)
+
+      def attach(&sink)
+        @lock.synchronize { @sinks << sink }
+        sink
+      end
+
+      def detach(sink) = @lock.synchronize { @sinks.delete(sink) }
+
+      def emit(event, body = {})
+        message = event_message(event, body)
+        @lock.synchronize { @sinks.dup }.each { |sink| sink.call([message]) }
+        message
+      end
+
+      def request_client(command, arguments = {})
+        message = {
+          "seq" => sequence,
+          "type" => "request",
+          "command" => command.to_s,
+          "arguments" => arguments
+        }
+        @lock.synchronize { @sinks.dup }.each { |sink| sink.call([message]) }
+        message
+      end
+
+      def dispatch(message)
+        Protocol.validate_message(message)
+        @lock.synchronize { @messages << Protocol.deep_freeze(message.dup) }
+        return [] unless message["type"] == "request"
+        return [] if message["command"] == "never"
+
+        override = @responses[message["command"]]
+        return Array(override.call(message["arguments"] || {}, message)) if override.respond_to?(:call)
+        return [response(message, override)] if @responses.key?(message["command"])
+
+        result, events = response_for(message)
+        [response(message, result), *events]
+      rescue AdapterError => error
+        [response(message, {}, success: false, message: error.message)]
+      end
+
+      def serve(input, output = input)
+        input.binmode
+        output.binmode
+        output.sync = true
+        while (message = Transport.read_message(input))
+          dispatch(message).each { |item| output.write(Transport.frame(item)) }
+        end
+      rescue IOError, Errno::EPIPE
+        nil
+      end
+
+      private
+
+      def response_for(message)
+        arguments = message["arguments"] || {}
+        case message["command"]
+        when "initialize"
+          [@capabilities, []]
+        when "launch", "attach"
+          [{}, [event_message("initialized")]]
+        when "configurationDone"
+          [{}, [stopped_event]]
+        when "setBreakpoints"
+          values = arguments.fetch("breakpoints", []).each_with_index.map do |breakpoint, index|
+            {
+              "id" => index + 1,
+              "verified" => true,
+              "source" => arguments["source"],
+              "line" => breakpoint["line"],
+              "column" => breakpoint["column"]
+            }.compact
+          end
+          [{"breakpoints" => values}, []]
+        when "setFunctionBreakpoints", "setDataBreakpoints"
+          values = arguments.fetch("breakpoints", []).each_index.map { |index| {"id" => index + 1, "verified" => true} }
+          [{"breakpoints" => values}, []]
+        when "setExceptionBreakpoints"
+          values = arguments.fetch("filters", []).each_index.map { |index| {"id" => index + 1, "verified" => true} }
+          [{"breakpoints" => values}, []]
+        when "threads"
+          [{"threads" => [{"id" => 1, "name" => "main"}]}, []]
+        when "stackTrace"
+          [{"stackFrames" => [{"id" => 10, "name" => "main", "source" => {"path" => "app.rb"}, "line" => 1, "column" => 1}], "totalFrames" => 1}, []]
+        when "scopes"
+          [{"scopes" => [{"name" => "Locals", "variablesReference" => 1, "expensive" => false}]}, []]
+        when "variables"
+          values = Array.new(@variable_count) do |index|
+            {"name" => "value#{index}", "value" => index.to_s, "type" => "Integer", "variablesReference" => 0}
+          end
+          [{"variables" => values}, []]
+        when "evaluate"
+          [{"result" => "42", "type" => "Integer", "variablesReference" => 0}, []]
+        when "setVariable", "setExpression"
+          [{"value" => arguments.fetch("value"), "type" => "String", "variablesReference" => 0}, []]
+        when "completions"
+          [{"targets" => [{"label" => "value", "text" => "value", "start" => 0, "length" => arguments.fetch("column", 0)}]}, []]
+        when "source"
+          [{"content" => "puts :ok\n", "mimeType" => "text/x-ruby"}, []]
+        when "continue"
+          [{"allThreadsContinued" => !arguments["singleThread"]}, [event_message("continued", "threadId" => arguments["threadId"], "allThreadsContinued" => !arguments["singleThread"])] ]
+        when "next", "stepIn", "stepOut", "restartFrame"
+          [{}, [event_message("continued", "threadId" => arguments["threadId"] || 1), stopped_event]]
+        when "restart"
+          [{}, [event_message("continued", "threadId" => 1), stopped_event]]
+        when "pause"
+          [{}, [stopped_event]]
+        when "terminate"
+          [{}, [event_message("terminated")]]
+        when "disconnect"
+          [{}, [event_message("terminated")]]
+        else
+          [@responses.fetch(message["command"], {}), []]
+        end
+      end
+
+      def response(request, body, success: true, message: nil)
+        value = {
+          "seq" => sequence,
+          "type" => "response",
+          "request_seq" => request["seq"],
+          "success" => success,
+          "command" => request["command"],
+          "body" => body
+        }
+        value["message"] = message if message
+        value
+      end
+
+      def stopped_event = event_message("stopped", "reason" => "breakpoint", "threadId" => 1, "allThreadsStopped" => true)
+
+      def event_message(event, body = {})
+        {"seq" => sequence, "type" => "event", "event" => event, "body" => body}
+      end
+
+      def sequence = @lock.synchronize { @sequence += 1 }
+    end
+  end
+end

data/lib/megrez/testing/fake_transport.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Megrez
+  module Testing
+    class FakeTransport < Transport
+      STOP = Object.new.freeze
+      private_constant :STOP
+
+      attr_reader :stderr_lines, :pid
+
+      def initialize(adapter, &receive)
+        @adapter = adapter
+        @receive = receive
+        @stderr_lines = []
+        @pid = Process.pid
+        @lock = Mutex.new
+        @write_lock = Mutex.new
+        @responses = Queue.new
+        @alive = true
+        @sink = @adapter.attach { |messages| enqueue(messages) }
+        @reader = Thread.new { read }
+        @reader.report_on_exception = false
+      end
+
+      def listen(&receive)
+        raise ArgumentError, "receiver required" unless receive
+        raise Error, "debug adapter transport is already listening" if @receive
+
+        @receive = receive
+        self
+      end
+
+      def write(message)
+        message = wire(message)
+        responses = @write_lock.synchronize do
+          raise Error, "debug adapter write failed: closed transport" unless alive?
+
+          @adapter.dispatch(message)
+        end
+        enqueue(responses)
+        nil
+      end
+
+      def alive? = @lock.synchronize { @alive }
+
+      def close
+        reader = @lock.synchronize do
+          if @alive
+            @alive = false
+            @responses << STOP
+          end
+          @reader
+        end
+        @adapter.detach(@sink)
+        return if reader == Thread.current
+
+        reader.kill unless reader.join(1)
+        reader.join
+        nil
+      end
+
+      private
+
+      def wire(message)
+        frame = Transport.frame(message)
+        Transport.read_message(StringIO.new(frame))
+      end
+
+      def enqueue(messages)
+        values = messages.map { |message| wire(message) }
+        @lock.synchronize do
+          return unless @alive
+
+          values.each { |message| @responses << message }
+        end
+      end
+
+      def read
+        loop do
+          message = @responses.pop
+          break if message.equal?(STOP)
+
+          @receive.call(message, nil)
+        end
+      rescue StandardError => error
+        @receive.call(nil, error) if alive?
+      ensure
+        @lock.synchronize { @alive = false }
+      end
+    end
+  end
+end

data/lib/megrez/testing.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "stringio"
+require_relative "../megrez"
+require_relative "testing/fake_adapter"
+require_relative "testing/fake_transport"

data/lib/megrez/transport/framing.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Megrez
+  class Transport
+    def self.read_message(io)
+      headers = {}
+      bytes = 0
+      loop do
+        line = io.gets("\r\n", MAX_HEADER_LINE + 1)
+        return nil if line.nil? && headers.empty?
+        valid = line && line.end_with?("\r\n") && line.bytesize <= MAX_HEADER_LINE
+        raise Error, "truncated or oversized DAP header" unless valid
+        break if line == "\r\n"
+
+        bytes += line.bytesize
+        raise Error, "oversized DAP headers" if bytes > MAX_HEADERS
+        raise Error, "non-ASCII DAP header" unless line.ascii_only?
+
+        key, value = line.strip.split(":", 2)
+        raise Error, "invalid DAP header" unless value && key.match?(/\A[A-Za-z][A-Za-z0-9-]*\z/)
+
+        key = key.downcase
+        raise Error, "duplicate DAP header" if headers.key?(key)
+
+        headers[key] = value.strip
+      end
+
+      raw_length = headers["content-length"]
+      raise Error, "missing or invalid Content-Length" unless raw_length&.match?(/\A\d+\z/)
+
+      length = Integer(raw_length, 10)
+      raise Error, "oversized DAP message" unless length.between?(1, MAX_MESSAGE)
+
+      charset = headers["content-type"]&.match(/charset\s*=\s*"?([^;"\s]+)/i)&.[](1)
+      raise Error, "unsupported DAP character encoding" if charset && !%w[utf-8 utf8].include?(charset.downcase)
+
+      body = io.read(length)
+      raise Error, "truncated DAP body" unless body && body.bytesize == length
+
+      body.force_encoding(Encoding::UTF_8)
+      raise Error, "invalid DAP UTF-8 body" unless body.valid_encoding?
+
+      Protocol.validate_message(JSON.parse(body))
+    rescue JSON::ParserError => error
+      raise Error, "invalid DAP JSON: #{error.message.byteslice(0, 256)}"
+    end
+
+    def self.frame(message)
+      raise Error, "DAP message must be an object" unless message.is_a?(Hash)
+
+      normalized = JSON.parse(JSON.generate(message))
+      Protocol.validate_message(normalized)
+      body = JSON.generate(normalized).b
+      raise Error, "oversized DAP message" unless body.bytesize.between?(1, MAX_MESSAGE)
+
+      "Content-Length: #{body.bytesize}\r\n\r\n".b + body
+    rescue JSON::GeneratorError, JSON::NestingError => error
+      raise Error, "invalid DAP JSON: #{error.message.byteslice(0, 256)}"
+    end
+  end
+end

data/lib/megrez/transport.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+
+module Megrez
+  class Transport
+    MAX_MESSAGE = 32 << 20
+    MAX_HEADER_LINE = 8192
+    MAX_HEADERS = 16_384
+
+    attr_reader :stderr_lines, :pid
+
+    def self.stdio(command:, env: {}, cwd: nil)
+      valid = command.is_a?(Array) && !command.empty? && command.all? do |part|
+        part.is_a?(String) && !part.empty? && !part.include?("\0")
+      end
+      raise ArgumentError, "command must be a nonempty argument array" unless valid
+      raise ArgumentError, "environment must be a string map" unless valid_environment?(env)
+      raise ArgumentError, "cwd must be a path string" unless cwd.nil? || (cwd.is_a?(String) && !cwd.include?("\0"))
+
+      options = cwd ? {chdir: cwd} : {}
+      input, output, error, process = Open3.popen3(env, *command, **options)
+      new(output, input, process: process, stderr: error, closeables: [input, output, error])
+    rescue SystemCallError => error
+      raise Error, "debug adapter spawn failed: #{error.message}"
+    end
+
+    def self.tcp(host:, port:, connect_timeout: 10)
+      valid_host = host.is_a?(String) && !host.empty? && !host.include?("\0")
+      valid_port = port.is_a?(Integer) && port.between?(1, 65_535)
+      valid_timeout = connect_timeout.is_a?(Numeric) && connect_timeout.finite? && connect_timeout.positive?
+      raise ArgumentError, "host must be a nonempty string" unless valid_host
+      raise ArgumentError, "port must be between 1 and 65535" unless valid_port
+      raise ArgumentError, "connect_timeout must be positive and finite" unless valid_timeout
+
+      socket = Socket.tcp(host, port, connect_timeout: connect_timeout)
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+      new(socket, socket, closeables: [socket])
+    rescue SystemCallError, SocketError => error
+      raise Error, "debug adapter connection failed: #{error.message}"
+    end
+
+    def self.valid_environment?(env)
+      env.is_a?(Hash) && env.all? do |key, value|
+        key.is_a?(String) && !key.empty? && !key.include?("\0") && !key.include?("=") &&
+          (value.nil? || (value.is_a?(String) && !value.include?("\0")))
+      end
+    end
+
+    def initialize(input, output, process: nil, stderr: nil, closeables: [])
+      @input = input
+      @output = output
+      @process = process
+      @stderr = stderr
+      @closeables = closeables.uniq
+      @pid = process&.pid
+      @stderr_lines = []
+      @write_lock = Mutex.new
+      @close_lock = Mutex.new
+      @closing = false
+      [@input, @output, @stderr].compact.uniq.each(&:binmode)
+    end
+
+    def listen(&receive)
+      raise ArgumentError, "receiver required" unless receive
+
+      @close_lock.synchronize do
+        raise Error, "debug adapter transport is closed" if @closing
+        raise Error, "debug adapter transport is already listening" if @reader
+
+        @reader = Thread.new { read(receive) }
+        @logger = Thread.new { read_stderr } if @stderr
+        [@reader, @logger].compact.each { |thread| thread.report_on_exception = false }
+      end
+      self
+    end
+
+    def write(message)
+      frame = self.class.frame(message)
+      @write_lock.synchronize do
+        raise Error, "debug adapter write failed: closed transport" unless alive?
+
+        @output.write(frame)
+        @output.flush
+      end
+      nil
+    rescue IOError, SystemCallError => error
+      raise Error, "debug adapter write failed: #{error.message}"
+    end
+
+    def alive?
+      @close_lock.synchronize do
+        !@closing && (@process ? @process.alive? : !@input.closed? && !@output.closed?)
+      end
+    end
+
+    def close
+      threads = @close_lock.synchronize do
+        next if @closing
+
+        @closing = true
+        [@reader, @logger]
+      end
+      return unless threads
+
+      begin
+        begin
+          @output.shutdown(Socket::SHUT_RDWR) if @output.is_a?(BasicSocket)
+        rescue IOError, SystemCallError
+          nil
+        end
+        @output.close unless @output.closed?
+        stop_process
+      ensure
+        @closeables.each do |io|
+          io.close unless io.closed?
+        rescue IOError
+          nil
+        end
+        threads.compact.each do |thread|
+          next if thread == Thread.current
+
+          thread.kill unless thread.join(1)
+          thread.join(1)
+        end
+      end
+      nil
+    end
+
+    private
+
+    def read(receive)
+      while (message = self.class.read_message(@input))
+        receive.call(message, nil)
+      end
+      receive.call(nil, Error.new("debug adapter closed its connection")) unless closing?
+    rescue StandardError => error
+      begin
+        receive.call(nil, error) unless closing?
+      rescue StandardError
+        nil
+      end
+    end
+
+    def read_stderr
+      while (line = @stderr.gets("\n", MAX_HEADER_LINE))
+        @stderr_lines << line.scrub.byteslice(0, MAX_HEADER_LINE).scrub("")
+        @stderr_lines.shift if @stderr_lines.length > 200
+      end
+    rescue IOError
+      nil
+    end
+
+    def closing? = @close_lock.synchronize { @closing }
+
+    def stop_process
+      return unless @process
+      return if @process.join(1)
+
+      Process.kill("TERM", @process.pid)
+      return if @process.join(1)
+
+      Process.kill("KILL", @process.pid)
+      @process.join(1)
+    rescue Errno::ESRCH, Errno::ECHILD
+      nil
+    end
+  end
+end
+
+require_relative "transport/framing"

data/lib/megrez/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Megrez
+  VERSION = "0.1.0"
+end

data/lib/megrez.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "megrez/version"
+
+module Megrez
+  class Error < StandardError; end
+  class Timeout < Error; end
+  class Cancelled < Error; end
+
+  class AdapterError < Error
+    attr_reader :command, :body
+
+    def initialize(command, message, body = nil)
+      @command = command
+      @body = body
+      super(message)
+    end
+  end
+
+  module Value
+    module_function
+
+    def define(*members)
+      return Data.define(*members) if defined?(Data)
+
+      Struct.new(*members) do
+        members.each { |member| undef_method("#{member}=") }
+
+        define_method(:initialize) do |*values, **keywords|
+          if keywords.empty?
+            raise ArgumentError, "wrong number of arguments" unless values.length == self.class.members.length
+
+            super(*values)
+          else
+            raise ArgumentError, "cannot mix positional and keyword arguments" unless values.empty?
+
+            missing = self.class.members - keywords.keys
+            unknown = keywords.keys - self.class.members
+            raise ArgumentError, "missing keyword: #{missing.first.inspect}" unless missing.empty?
+            raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+            super(*self.class.members.map { |member| keywords.fetch(member) })
+          end
+          freeze
+        end
+
+        define_method(:with) do |**changes|
+          return self if changes.empty?
+
+          unknown = changes.keys - self.class.members
+          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+          self.class.new(**to_h.merge(changes))
+        end
+      end
+    end
+  end
+
+  Breakpoint = Value.define(:id, :verified, :source, :line, :column, :message)
+  SourceBreakpoint = Value.define(:line, :column, :condition, :hit_condition, :log_message)
+  StackFrame = Value.define(:id, :name, :source, :line, :column, :presentation_hint)
+  Scope = Value.define(:name, :variables_reference, :expensive, :presentation_hint)
+  Variable = Value.define(:name, :value, :type, :variables_reference,
+    :named_count, :indexed_count, :memory_reference)
+  ThreadInfo = Value.define(:id, :name)
+  private_constant :Value
+end
+
+require_relative "megrez/protocol"
+require_relative "megrez/results"
+require_relative "megrez/future"
+require_relative "megrez/transport"
+require_relative "megrez/session"