megrez 0.1.0

data/lib/megrez/session/messages.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Megrez
+  class Session
+    private
+
+    def cancel_request(request_id)
+      message = @lock.synchronize do
+        next unless @pending.delete(request_id)
+        next if @closing
+
+        sequence = next_sequence
+        @ignored_responses[request_id] = true
+        @ignored_responses[sequence] = true
+        @ignored_responses.shift while @ignored_responses.length > MAX_PENDING * 2
+        {seq: sequence, type: "request", command: "cancel", arguments: {requestId: request_id}}
+      end
+      @transport.write(message) if message
+    rescue Error => error
+      record_error(error)
+    end
+
+    def next_sequence
+      @sequence += 1
+      @sequence = 1 if @sequence > 0x7fff_ffff
+      @sequence
+    end
+
+    def enqueue(message, error)
+      return if @lock.synchronize { @closing }
+
+      return process_message(message, error) if error || message["type"] == "response"
+
+      @inbound << [message, error]
+    rescue StandardError => failure
+      record_error(failure)
+    end
+
+    def dispatch_messages
+      loop do
+        item = @inbound.pop
+        break if item.equal?(STOP)
+
+        done = Queue.new
+        begin
+          @dispatch.call do
+            begin
+              next if @lock.synchronize { @closing }
+
+              process_message(*item)
+            rescue StandardError => error
+              record_error(error)
+            ensure
+              done << true
+            end
+          end
+          done.pop
+        rescue StandardError => error
+          record_error(error)
+        end
+      end
+    end
+
+    def process_message(message, error)
+      return fail_connection(error) if error
+
+      Protocol.validate_message(message)
+      case message["type"]
+      when "response" then process_response(message)
+      when "event" then process_event(message)
+      when "request" then process_reverse_request(message)
+      end
+    end
+
+    def process_response(message)
+      ignored = false
+      pending = @lock.synchronize do
+        request_sequence = message["request_seq"]
+        if @ignored_responses.delete(request_sequence)
+          ignored = true
+          next
+        end
+        @pending.delete(request_sequence)
+      end
+      return if ignored
+      return record_error(Error.new("unsolicited DAP response")) unless pending
+      return pending.future.fulfill(error: Error.new("mismatched DAP response command")) if message["command"] != pending.command
+
+      unless message["success"]
+        text = message["message"] || "debug adapter rejected #{pending.command}"
+        body = message["body"]&.then { |value| Protocol.deep_freeze(value.dup) }
+        return pending.future.fulfill(error: AdapterError.new(pending.command, text, body))
+      end
+
+      body = message.fetch("body", {})
+      value = pending.validate ? pending.validate.call(body) : body
+      pending.future.fulfill(value)
+    rescue StandardError => error
+      pending&.future&.fulfill(error: error)
+    end
+
+    def process_event(message)
+      key = event_key(message["event"])
+      body = Protocol.deep_freeze(message.fetch("body", {}).dup)
+      handlers = @lock.synchronize do
+        case key
+        when :stopped
+          @generation += 1
+          @state = :stopped
+        when :continued
+          @state = :running
+        when :terminated, :exited
+          @generation += 1
+          @state = :terminated
+          @ended = true
+        end
+        (@handlers[key] || []).dup
+      end
+      handlers.each do |handler|
+        handler.call(body)
+      rescue StandardError => error
+        record_error(error)
+      end
+    end
+
+    def process_reverse_request(message)
+      command = message["command"]
+      handler = @lock.synchronize { @request_handlers[command] }
+      raise AdapterError.new(command, "unsupported adapter request: #{command}") unless handler
+
+      result = handler.call(Protocol.deep_freeze(message.fetch("arguments", {}).dup)) || {}
+      Protocol.object(result, "adapter request result")
+      Protocol.validate_outbound(result)
+      send_response(message, success: true, body: result)
+    rescue StandardError => error
+      record_error(error)
+      send_response(message, success: false, message: error.message.scrub.byteslice(0, 4096).scrub(""))
+    end
+
+    def send_response(request, success:, body: nil, message: nil)
+      response = @lock.synchronize do
+        next if @closing
+
+        value = {seq: next_sequence, type: "response", request_seq: request["seq"],
+                 success: success, command: request["command"]}
+        value[:body] = body if body
+        value[:message] = message if message
+        value
+      end
+      @transport.write(response) if response
+    rescue Error => error
+      record_error(error)
+    end
+
+    def fail_connection(error)
+      pending = @lock.synchronize do
+        next [] if @closing
+
+        @state = :terminated
+        @ended = true
+        @generation += 1
+        values = @pending.values.map(&:future)
+        @pending.clear
+        values
+      end
+      record_error(error)
+      pending.each { |future| future.fulfill(error: error) }
+    end
+
+    def record_error(error)
+      prefix = error.is_a?(Error) ? "" : "#{error.class}: "
+      message = "#{prefix}#{error.message}".scrub.byteslice(0, 4096).scrub("")
+      bounded = error.is_a?(Error) && error.message.bytesize <= 4096 ? error : Error.new(message)
+      @lock.synchronize do
+        @errors << bounded
+        @errors.shift if @errors.length > MAX_ERRORS
+      end
+      bounded
+    end
+
+    def event_key(event)
+      event.to_s.gsub(/([a-z\d])([A-Z])/, '\\1_\\2').downcase.to_sym
+    end
+  end
+end

data/lib/megrez/session/requests.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Megrez
+  class Session
+    def launch(configuration)
+      transition_request("launch", configuration, from: :initialized, to: :configuring) { |body| Results.body(body) }
+    end
+
+    def attach(configuration)
+      transition_request("attach", configuration, from: :initialized, to: :configuring) { |body| Results.body(body) }
+    end
+
+    def configuration_done
+      transition_request("configurationDone", {}, from: :configuring, to: :running) { |body| Results.body(body) }
+    end
+
+    def disconnect(terminate: false, restart: false)
+      Protocol.boolean(terminate, "terminate")
+      Protocol.boolean(restart, "restart")
+      future = transition_request(
+        "disconnect",
+        {terminateDebuggee: terminate, restart: restart},
+        from: %i[initialized configuring running stopped],
+        to: :terminated
+      ) { |body| Results.body(body) }
+      future.then { |_value, _error| close }
+    end
+
+    def set_breakpoints(source_path, breakpoints)
+      source_path = Protocol.string(source_path, "source path", empty: false)
+      breakpoints = Protocol.collection(breakpoints, "source breakpoints").map do |breakpoint|
+        source_breakpoint(breakpoint)
+      end
+      send_request(
+        "setBreakpoints",
+        {source: {path: source_path}, breakpoints: breakpoints},
+        states: %i[configuring stopped running]
+      ) { |body| Results.breakpoints(body) }
+    end
+
+    def set_function_breakpoints(names)
+      values = Protocol.collection(names, "function breakpoint names").map do |name|
+        {name: Protocol.string(name, "function breakpoint name", empty: false)}
+      end
+      breakpoint_request("setFunctionBreakpoints", breakpoints: values)
+    end
+
+    def set_exception_breakpoints(filters, options: [])
+      filters = Protocol.collection(filters, "exception filters").map do |filter|
+        Protocol.string(filter, "exception filter", empty: false)
+      end
+      options = object_array(options, "exception options")
+      breakpoint_request("setExceptionBreakpoints", filters: filters, filterOptions: options)
+    end
+
+    def set_data_breakpoints(descriptors)
+      values = object_array(descriptors, "data breakpoints")
+      values.each do |descriptor|
+        Protocol.string(descriptor["dataId"] || descriptor[:dataId], "data breakpoint dataId", empty: false)
+      end
+      breakpoint_request("setDataBreakpoints", breakpoints: values)
+    end
+
+    def continue(thread_id, all: false)
+      Protocol.boolean(all, "all")
+      execution_request("continue", thread_id, singleThread: !all)
+    end
+
+    def step_over(thread_id, granularity: :statement)
+      execution_request("next", thread_id, granularity: granularity_value(granularity))
+    end
+
+    def step_in(thread_id, target_id: nil)
+      arguments = {}
+      arguments[:targetId] = Protocol.integer(target_id, "step target id") unless target_id.nil?
+      execution_request("stepIn", thread_id, **arguments)
+    end
+
+    def step_out(thread_id) = execution_request("stepOut", thread_id)
+
+    def pause(thread_id)
+      thread_id = Protocol.integer(thread_id, "thread id")
+      send_request("pause", {threadId: thread_id}, states: [:running]) { |body| Results.body(body) }
+    end
+
+    def restart_frame(frame_id)
+      frame_id = Protocol.integer(frame_id, "frame id")
+      transition_request("restartFrame", {frameId: frame_id}, from: :stopped, to: :running) do |body|
+        Results.body(body)
+      end
+    end
+
+    def restart(arguments = {})
+      transition_request("restart", arguments, from: %i[running stopped], to: :running) { |body| Results.body(body) }
+    end
+
+    def terminate
+      send_request("terminate", {}, states: %i[configuring running stopped]) { |body| Results.body(body) }
+    end
+
+    private
+
+    def breakpoint_request(command, arguments)
+      send_request(command, arguments, states: %i[configuring stopped running]) { |body| Results.breakpoints(body) }
+    end
+
+    def execution_request(command, thread_id, **arguments)
+      thread_id = Protocol.integer(thread_id, "thread id")
+      transition_request(command, {threadId: thread_id, **arguments}, from: :stopped, to: :running) do |body|
+        Results.body(body)
+      end
+    end
+
+    def source_breakpoint(value)
+      raise Error, "source breakpoint must be a SourceBreakpoint" unless value.is_a?(SourceBreakpoint)
+
+      result = {line: Protocol.uint(value.line, "breakpoint line")}
+      result[:column] = Protocol.uint(value.column, "breakpoint column") unless value.column.nil?
+      {
+        condition: value.condition,
+        hitCondition: value.hit_condition,
+        logMessage: value.log_message
+      }.each do |key, text|
+        result[key] = Protocol.string(text, "breakpoint #{key}") unless text.nil?
+      end
+      result
+    end
+
+    def object_array(values, name)
+      Protocol.collection(values, name).map do |value|
+        Protocol.validate_outbound(Protocol.object(value, name))
+      end
+    end
+
+    def granularity_value(value)
+      value = value.to_s
+      raise ArgumentError, "granularity must be statement, line, or instruction" unless %w[statement line instruction].include?(value)
+
+      value
+    end
+
+  end
+end

data/lib/megrez/session.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Megrez
+  class Session
+    MAX_PENDING = 1024
+    MAX_INBOUND = 1024
+    MAX_ERRORS = 100
+    STOP = Object.new.freeze
+    Pending = Struct.new(:future, :command, :validate, keyword_init: true)
+    private_constant :MAX_PENDING, :MAX_INBOUND, :MAX_ERRORS, :STOP, :Pending
+
+    def self.stdio(command:, env: {}, cwd: nil, dispatch: ->(&block) { block.call })
+      new(Transport.stdio(command: command, env: env, cwd: cwd), dispatch: dispatch)
+    end
+
+    def self.tcp(host:, port:, dispatch: ->(&block) { block.call }, connect_timeout: 10)
+      new(Transport.tcp(host: host, port: port, connect_timeout: connect_timeout), dispatch: dispatch)
+    end
+
+    attr_reader :transport
+
+    def initialize(transport, dispatch: ->(&block) { block.call })
+      valid = transport.respond_to?(:listen) && transport.respond_to?(:write) && transport.respond_to?(:close)
+      raise ArgumentError, "transport must support listen, write, and close" unless valid
+      raise ArgumentError, "dispatch must respond to call" unless dispatch.respond_to?(:call)
+
+      @transport = transport
+      @dispatch = dispatch
+      @lock = Mutex.new
+      @pending = {}
+      @ignored_responses = {}
+      @handlers = {}
+      @request_handlers = {}
+      @errors = []
+      @sequence = 0
+      @generation = 0
+      @state = :initialized
+      @started = false
+      @closing = false
+      @ended = false
+      @capabilities = {}.freeze
+      @inbound = SizedQueue.new(MAX_INBOUND)
+      @dispatcher = Thread.new { dispatch_messages }
+      @dispatcher.report_on_exception = false
+      @transport.listen { |message, error| enqueue(message, error) }
+    rescue StandardError
+      close
+      raise
+    end
+
+    def start(adapter_id:, lines_start_at_1: true, columns_start_at_1: true, path_format: "path", timeout: 10)
+      started_now = false
+      adapter_id = Protocol.string(adapter_id, "adapter_id", empty: false, max: 256)
+      Protocol.boolean(lines_start_at_1, "lines_start_at_1")
+      Protocol.boolean(columns_start_at_1, "columns_start_at_1")
+      raise ArgumentError, "path_format must be path or uri" unless %w[path uri].include?(path_format)
+
+      reverse_requests = @lock.synchronize do
+        raise Error, "debug session already started" if @started
+        raise Error, "debug session is closed" if @closing
+
+        @started = true
+        started_now = true
+        @request_handlers.keys
+      end
+      arguments = {
+        clientID: "megrez",
+        clientName: "Megrez",
+        adapterID: adapter_id,
+        linesStartAt1: lines_start_at_1,
+        columnsStartAt1: columns_start_at_1,
+        pathFormat: path_format,
+        supportsVariableType: true,
+        supportsVariablePaging: true,
+        supportsProgressReporting: true,
+        supportsRunInTerminalRequest: reverse_requests.include?("runInTerminal"),
+        supportsStartDebuggingRequest: reverse_requests.include?("startDebugging")
+      }
+      future = send_request("initialize", arguments, states: [:initialized], allow_unstarted: true) do |body|
+        Results.capabilities(body)
+      end
+      value = future.await(timeout: timeout)
+      @lock.synchronize { @capabilities = value }
+      value
+    rescue StandardError
+      close if started_now
+      raise
+    end
+
+    def request(command, arguments = {})
+      send_request(command, arguments, states: %i[initialized configuring running stopped]) { |body| Results.body(body) }
+    end
+
+    def on(event, &handler)
+      raise ArgumentError, "handler required" unless handler
+
+      key = event_key(event)
+      @lock.synchronize { (@handlers[key] ||= []) << handler }
+      handler
+    end
+
+    def on_request(command, &handler)
+      raise ArgumentError, "handler required" unless handler
+
+      command = Protocol.string(command.to_s, "request command", empty: false, max: 256)
+      @lock.synchronize { @request_handlers[command] = handler }
+      handler
+    end
+
+    def capabilities = @lock.synchronize { @capabilities }
+    def state = @lock.synchronize { @state }
+    def generation = @lock.synchronize { @generation }
+    def errors = @lock.synchronize { @errors.dup.freeze }
+
+    def close
+      pending = @lock&.synchronize do
+        next if @closing
+
+        @closing = true
+        @state = :terminated
+        values = @pending.values.map(&:future)
+        @pending.clear
+        values
+      end
+      return nil unless pending
+
+      error = Error.new("debug session closed")
+      pending.each { |future| future.fulfill(error: error) }
+      @inbound&.clear
+      @inbound&.push(STOP)
+      @transport&.close
+      if @dispatcher && @dispatcher != Thread.current
+        @dispatcher.kill unless @dispatcher.join(1)
+        @dispatcher.join
+      end
+      nil
+    end
+
+    private
+
+    def send_request(command, arguments, states:, allow_unstarted: false, &validate)
+      command = Protocol.string(command.to_s, "DAP command", empty: false, max: 256)
+      arguments = Protocol.object(arguments, "DAP request arguments")
+      Protocol.validate_outbound(arguments)
+
+      pending = @lock.synchronize do
+        raise Error, "debug session is closed" if @closing
+        raise Error, "debug session has not started" unless @started || allow_unstarted
+        raise Error, "#{command} is invalid while #{@state}" unless states.include?(@state)
+        raise Error, "too many pending DAP requests" if @pending.length >= MAX_PENDING
+
+        sequence = next_sequence
+        future = Future.new(sequence, on_error: method(:record_error)) { |id| cancel_request(id) }
+        value = Pending.new(future: future, command: command, validate: validate)
+        @pending[sequence] = value
+        [sequence, value]
+      end
+      sequence, value = pending
+      @transport.write(seq: sequence, type: "request", command: command, arguments: arguments)
+      value.future
+    rescue StandardError => error
+      if pending
+        @lock.synchronize { @pending.delete(pending.first) }
+        pending.last.future.fulfill(error: error)
+        pending.last.future
+      else
+        raise
+      end
+    end
+
+    def transition_request(command, arguments, from:, to:, &validate)
+      previous = @lock.synchronize do
+        raise Error, "debug session is closed" if @closing
+        raise Error, "debug session has not started" unless @started
+        raise Error, "#{command} is invalid while #{@state}" unless Array(from).include?(@state)
+
+        old = @state
+        @state = to
+        old
+      end
+      future = send_request(command, arguments, states: [to], &validate)
+      future.then do |_value, error|
+        @lock.synchronize do
+          @state = previous if error && !@closing && !@ended && @state == to
+        end
+      end
+      future
+    rescue StandardError
+      @lock.synchronize do
+        @state = previous if previous && !@closing && !@ended && @state == to
+      end
+      raise
+    end
+
+  end
+end
+
+require_relative "session/messages"
+require_relative "session/requests"
+require_relative "session/inspection"