megrez 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85a6c24732dbeeb7c806452f4d963df6c0e1d4aa33faa2b45961aeb27c737f03
+  data.tar.gz: b742be2cdcd1d743185f2fa3f3eabf0224f1bc94f00f08ea6eaaf35631ac5eb6
+SHA512:
+  metadata.gz: 6e1fe32a3fea8f74156ec480ec0fe60c43098b7c5748a3896e6dc13436416d06a4822f87e82b8ecac82698f6b5166c16e2ae01bcb5a1ec331eed586d7e1feed0
+  data.tar.gz: 456406256f220f0a3faecb88d8ea49acc07dd15284a3bc1c8e90e2e74888a688798a084609012e2794f833c54826b15239cca1bf22099b30390095be57409f5b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-16
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# Megrez
+
+Megrez is a pure Ruby Debug Adapter Protocol (DAP) client. It owns adapter
+transport, protocol validation, session state, breakpoints, execution control,
+and lazy variable expansion without depending on an editor or UI toolkit.
+
+## Installation
+
+```ruby
+gem "megrez"
+```
+
+## Usage
+
+```ruby
+require "megrez"
+
+session = Megrez::Session.stdio(command: ["path/to/debug-adapter", "--stdio"])
+session.on(:stopped) { |event| puts "stopped: #{event.fetch("reason")}" }
+initialized = Queue.new
+session.on(:initialized) { initialized << true }
+session.start(adapter_id: "my-adapter")
+launch = session.launch("program" => File.expand_path("app.rb"))
+initialized.pop
+session.set_breakpoints("app.rb", [
+  Megrez::SourceBreakpoint.new(
+    line: 12, column: nil, condition: nil, hit_condition: nil,
+    log_message: nil
+  )
+]).await(timeout: 5)
+session.configuration_done.await(timeout: 5)
+launch.await(timeout: 5)
+```
+
+Requests return `Megrez::Future`; call `await(timeout:)` where a blocking
+result is needed. Cancelling a future sends the DAP `cancel` request and
+rejects the local wait. Event callbacks are delivered in adapter arrival order.
+
+TCP adapters are supported with `Megrez::Session.tcp(host:, port:)`. Adapter
+reverse requests such as `runInTerminal` and `startDebugging` can be handled
+with `on_request`:
+
+```ruby
+session.on_request("startDebugging") { |arguments| start_child(arguments) }
+```
+
+Register reverse-request handlers before `start`; Megrez advertises only the
+requests that have handlers.
+
+Values returned as `variables_reference` embed the current stop generation.
+Passing a value from an earlier stop to `variables` or `set_variable` raises
+`Megrez::Error` instead of querying stale adapter state.
+
+## Conformance
+
+The bundled fake adapter is exercised by default. Set
+`MEGREZ_ADAPTERS=ruby` to additionally run the installed `rdbg` conformance
+scenario.
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rbs -I sig -r stringio validate
+BUDGET=1 bundle exec rake bench
+gem build --strict megrez.gemspec
+```
+
+Adapters are external programs and should be treated as untrusted input.
+Megrez does not invoke a shell, caps frame/header/pending-request sizes, and
+bounds retained stderr and callback errors. TCP is unencrypted; use it only on
+a trusted interface or inside a secure tunnel.
+
+## License
+
+Megrez is available under the MIT License.

data/docs/adr/000-template.md

@@ -0,0 +1,16 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its constraints.
+
+## Decision
+
+Describe the durable boundary or architecture choice.
+
+## Consequences
+
+Describe the important trade-offs and when to revisit the decision.

data/docs/adr/001-generation-safe-references.md

@@ -0,0 +1,20 @@
+# ADR 001: Encode stop generations in variable references
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+DAP variable references are valid only while execution remains stopped. An
+adapter may reuse the same integer after the next stop, so retaining only a
+set of seen integers cannot reliably identify stale UI state.
+
+## Decision
+
+Expose zero unchanged and encode the current stop generation with every
+positive adapter reference. Decode and verify it before sending requests.
+
+## Consequences
+
+References remain integers and stale values are rejected deterministically.
+They are opaque handles; callers must not interpret their numeric value.

data/docs/adr/README.md

@@ -0,0 +1,3 @@
+# Architecture decision records
+
+These records document Megrez's durable boundaries.

data/lib/megrez/future.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Megrez
+  class Future
+    class Subscription
+      def initialize(&detach) = @detach = detach
+
+      def detach
+        callback, @detach = @detach, nil
+        callback&.call
+      end
+    end
+
+    attr_reader :id, :callback_errors
+
+    def initialize(id, on_error: nil, &cancel)
+      @id = id
+      @cancel_callback = cancel
+      @on_error = on_error
+      @lock = Mutex.new
+      @ready = ConditionVariable.new
+      @callbacks = []
+      @callback_errors = []
+    end
+
+    def fulfill(value = nil, error: nil)
+      callbacks = @lock.synchronize do
+        return if @done
+
+        @value = value
+        @error = error
+        @done = true
+        @ready.broadcast
+        saved, @callbacks = @callbacks, []
+        saved
+      end
+      callbacks.each { |callback| invoke(callback, @value, @error) }
+      self
+    end
+
+    def then(&callback)
+      raise ArgumentError, "callback required" unless callback
+
+      ready = @lock.synchronize do
+        @callbacks << callback unless @done
+        @done
+      end
+      invoke(callback, @value, @error) if ready
+      self
+    end
+
+    def on_complete(&callback)
+      raise ArgumentError, "callback required" unless callback
+
+      self.then(&callback)
+      Subscription.new { @lock.synchronize { @callbacks.delete(callback) } }
+    end
+
+    def done? = @lock.synchronize { !!@done }
+
+    def await(timeout: nil)
+      valid = timeout.nil? || (timeout.is_a?(Numeric) && timeout.finite? && timeout >= 0)
+      raise ArgumentError, "timeout must be finite and nonnegative" unless valid
+
+      deadline = timeout && Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @lock.synchronize do
+        until @done
+          remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Timeout, "DAP request #{@id} timed out" if remaining && remaining <= 0
+
+          @ready.wait(@lock, remaining)
+        end
+        raise @error if @error
+
+        @value
+      end
+    rescue Timeout
+      cancel
+      raise
+    end
+
+    def cancel
+      callback = @lock.synchronize do
+        return false if @done || @cancelling
+
+        @cancelling = true
+        @cancel_callback
+      end
+      invoke(->(*) { callback.call(@id) }, nil, nil) if callback
+      fulfill(error: Cancelled.new("DAP request #{@id} cancelled"))
+      true
+    end
+
+    private
+
+    def invoke(callback, value, error)
+      callback.call(value, error)
+    rescue StandardError => callback_error
+      bounded = Error.new("#{callback_error.class}: #{callback_error.message}".scrub.byteslice(0, 2048).scrub(""))
+      @lock.synchronize do
+        @callback_errors << bounded
+        @callback_errors.shift if @callback_errors.length > 32
+      end
+      begin
+        @on_error&.call(bounded)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/megrez/protocol.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Megrez
+  module Protocol
+    MAX_COLLECTION = 100_000
+    MAX_DEPTH = 64
+
+    module_function
+
+    def validate_message(message)
+      raise Error, "DAP message must be an object" unless message.is_a?(Hash)
+
+      uint(message["seq"], "DAP seq", positive: true)
+      case message["type"]
+      when "request" then validate_request(message)
+      when "response" then validate_response(message)
+      when "event" then validate_event(message)
+      else raise Error, "invalid DAP message type"
+      end
+      message
+    end
+
+    def validate_outbound(value)
+      validate_json(value, 0)
+      value
+    end
+
+    def validate_request(message)
+      string(message["command"], "DAP command", empty: false, max: 256)
+      validate_json(object(message["arguments"], "DAP request arguments"), 0) if message.key?("arguments")
+      forbidden = %w[request_seq success event]
+      raise Error, "invalid DAP request fields" if forbidden.any? { |key| message.key?(key) }
+    end
+
+    def validate_response(message)
+      uint(message["request_seq"], "DAP request_seq", positive: true)
+      boolean(message["success"], "DAP response success")
+      string(message["command"], "DAP response command", empty: false, max: 256)
+      string(message["message"], "DAP response message", max: 4096) if message.key?("message")
+      validate_json(object(message["body"], "DAP response body"), 0) if message.key?("body")
+      raise Error, "invalid DAP response fields" if message.key?("event")
+    end
+
+    def validate_event(message)
+      string(message["event"], "DAP event", empty: false, max: 256)
+      validate_json(object(message["body"], "DAP event body"), 0) if message.key?("body")
+      forbidden = %w[request_seq success command]
+      raise Error, "invalid DAP event fields" if forbidden.any? { |key| message.key?(key) }
+    end
+
+    def validate_json(value, depth)
+      raise Error, "DAP value is nested too deeply" if depth > MAX_DEPTH
+
+      case value
+      when nil, true, false, Integer, String
+        string(value, "DAP string") if value.is_a?(String)
+      when Float
+        raise Error, "DAP number must be finite" unless value.finite?
+      when Array
+        collection(value, "DAP array").each { |item| validate_json(item, depth + 1) }
+      when Hash
+        value.each do |key, item|
+          raise Error, "DAP object keys must be strings or symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+
+          string(key.to_s, "DAP object key", empty: false, max: 1024)
+          validate_json(item, depth + 1)
+        end
+      else
+        raise Error, "unsupported DAP value: #{value.class}"
+      end
+    end
+
+    def object(value, name)
+      raise Error, "#{name} must be an object" unless value.is_a?(Hash)
+
+      value
+    end
+
+    def collection(value, name)
+      raise Error, "#{name} must be an array" unless value.is_a?(Array)
+      raise Error, "#{name} has too many elements" if value.length > MAX_COLLECTION
+
+      value
+    end
+
+    def string(value, name, empty: true, max: 1 << 20)
+      valid = value.is_a?(String) && value.encoding != Encoding::BINARY && value.valid_encoding? && !value.include?("\0")
+      valid &&= !value.empty? unless empty
+      valid &&= value.bytesize <= max
+      raise Error, "#{name} must be a valid UTF-8 string" unless valid
+
+      value
+    end
+
+    def integer(value, name)
+      raise Error, "#{name} must be an integer" unless value.is_a?(Integer)
+
+      value
+    end
+
+    def uint(value, name, positive: false)
+      integer(value, name)
+      minimum = positive ? 1 : 0
+      raise Error, "#{name} must be at least #{minimum}" if value < minimum
+
+      value
+    end
+
+    def boolean(value, name)
+      raise Error, "#{name} must be boolean" unless value == true || value == false
+
+      value
+    end
+
+    def optional_string(value, name, **options)
+      value.nil? ? nil : string(value, name, **options)
+    end
+
+    def optional_uint(value, name)
+      value.nil? ? nil : uint(value, name)
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each { |key, item| deep_freeze(key); deep_freeze(item) }
+      when Array
+        value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+  end
+end

data/lib/megrez/results.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Megrez
+  module Results
+    module_function
+
+    def capabilities(body)
+      Protocol.deep_freeze(Protocol.object(body, "initialize response").dup)
+    end
+
+    def breakpoints(body)
+      array(body, "breakpoints").map do |value|
+        value = Protocol.object(value, "breakpoint")
+        Breakpoint.new(
+          id: optional_integer(value["id"], "breakpoint id"),
+          verified: Protocol.boolean(value["verified"], "breakpoint verified"),
+          source: source(value["source"]),
+          line: optional_uint(value["line"], "breakpoint line"),
+          column: optional_uint(value["column"], "breakpoint column"),
+          message: Protocol.optional_string(value["message"], "breakpoint message")
+        )
+      end.freeze
+    end
+
+    def threads(body)
+      array(body, "threads").map do |value|
+        value = Protocol.object(value, "thread")
+        ThreadInfo.new(
+          id: Protocol.integer(value["id"], "thread id"),
+          name: Protocol.string(value["name"], "thread name")
+        )
+      end.freeze
+    end
+
+    def stack_frames(body)
+      array(body, "stackFrames").map do |value|
+        value = Protocol.object(value, "stack frame")
+        StackFrame.new(
+          id: Protocol.integer(value["id"], "stack frame id"),
+          name: Protocol.string(value["name"], "stack frame name"),
+          source: source(value["source"]),
+          line: Protocol.uint(value["line"], "stack frame line"),
+          column: Protocol.uint(value["column"], "stack frame column"),
+          presentation_hint: Protocol.optional_string(value["presentationHint"], "stack frame presentationHint")
+        )
+      end.freeze
+    end
+
+    def scopes(body, generation)
+      array(body, "scopes").map do |value|
+        value = Protocol.object(value, "scope")
+        Scope.new(
+          name: Protocol.string(value["name"], "scope name"),
+          variables_reference: encode_reference(value["variablesReference"], generation),
+          expensive: Protocol.boolean(value["expensive"], "scope expensive"),
+          presentation_hint: Protocol.optional_string(value["presentationHint"], "scope presentationHint")
+        )
+      end.freeze
+    end
+
+    def variables(body, generation)
+      array(body, "variables").map { |value| variable(value, generation) }.freeze
+    end
+
+    def set_variable(body, generation, name)
+      value = Protocol.object(body, "setVariable response").merge("name" => name)
+      variable(value, generation)
+    end
+
+    def evaluate(body, generation, expression)
+      value = Protocol.object(body, "evaluate response").merge(
+        "name" => expression,
+        "value" => body["result"]
+      )
+      variable(value, generation)
+    end
+
+    def completions(body)
+      array(body, "targets").map do |value|
+        value = Protocol.object(value, "completion target")
+        Protocol.string(value["label"], "completion label")
+        %w[text sortText type].each do |key|
+          Protocol.optional_string(value[key], "completion #{key}") if value.key?(key)
+        end
+        %w[start length selectionStart selectionLength].each do |key|
+          Protocol.optional_uint(value[key], "completion #{key}") if value.key?(key)
+        end
+        Protocol.deep_freeze(value.dup)
+      end.freeze
+    end
+
+    def source_content(body)
+      body = Protocol.object(body, "source response")
+      Protocol.string(body["content"], "source content")
+      Protocol.optional_string(body["mimeType"], "source mimeType") if body.key?("mimeType")
+      Protocol.deep_freeze(body.dup)
+    end
+
+    def body(body)
+      Protocol.deep_freeze(Protocol.object(body, "DAP response body").dup)
+    end
+
+    def encode_reference(value, generation)
+      value = Protocol.uint(value, "variablesReference")
+      return 0 if value.zero?
+      raise Error, "variablesReference is too large" if value > 0x7fff_ffff
+
+      (generation << 32) | value
+    end
+
+    def decode_reference(value, generation)
+      value = Protocol.uint(value, "variables reference")
+      raise Error, "variables reference is not expandable" if value.zero?
+
+      encoded_generation = value >> 32
+      raise Error, "stale variables reference" unless encoded_generation == generation
+
+      value & 0xffff_ffff
+    end
+
+    def variable(value, generation)
+      value = Protocol.object(value, "variable")
+      Variable.new(
+        name: Protocol.string(value["name"], "variable name"),
+        value: Protocol.string(value["value"], "variable value"),
+        type: Protocol.optional_string(value["type"], "variable type"),
+        variables_reference: encode_reference(value.fetch("variablesReference", 0), generation),
+        named_count: optional_uint(value["namedVariables"], "variable namedVariables"),
+        indexed_count: optional_uint(value["indexedVariables"], "variable indexedVariables"),
+        memory_reference: Protocol.optional_string(value["memoryReference"], "variable memoryReference")
+      )
+    end
+
+    def source(value)
+      return nil if value.nil?
+
+      value = Protocol.object(value, "source").dup
+      Protocol.optional_string(value["name"], "source name") if value.key?("name")
+      Protocol.optional_string(value["path"], "source path") if value.key?("path")
+      Protocol.optional_uint(value["sourceReference"], "source reference") if value.key?("sourceReference")
+      Protocol.deep_freeze(value)
+    end
+
+    def array(body, key)
+      body = Protocol.object(body, "DAP response body")
+      Protocol.collection(body[key], key)
+    end
+
+    def optional_uint(value, name) = value.nil? ? nil : Protocol.uint(value, name)
+    def optional_integer(value, name) = value.nil? ? nil : Protocol.integer(value, name)
+  end
+end

data/lib/megrez/session/inspection.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Megrez
+  class Session
+    def threads
+      send_request("threads", {}, states: %i[configuring running stopped]) { |body| Results.threads(body) }
+    end
+
+    def stack_trace(thread_id, start: 0, levels: 20)
+      thread_id = Protocol.integer(thread_id, "thread id")
+      start = Protocol.uint(start, "stack start")
+      levels = Protocol.uint(levels, "stack levels")
+      send_request(
+        "stackTrace",
+        {threadId: thread_id, startFrame: start, levels: levels},
+        states: [:stopped]
+      ) { |body| Results.stack_frames(body) }
+    end
+
+    def scopes(frame_id)
+      frame_id = Protocol.integer(frame_id, "frame id")
+      stopped_generation = generation
+      send_request("scopes", {frameId: frame_id}, states: [:stopped]) do |body|
+        ensure_generation(stopped_generation)
+        Results.scopes(body, stopped_generation)
+      end
+    end
+
+    def variables(reference, start: nil, count: nil, filter: nil)
+      stopped_generation = generation
+      arguments = {variablesReference: Results.decode_reference(reference, stopped_generation)}
+      arguments[:start] = Protocol.uint(start, "variable start") unless start.nil?
+      arguments[:count] = Protocol.uint(count, "variable count") unless count.nil?
+      arguments[:filter] = variable_filter(filter) unless filter.nil?
+      send_request("variables", arguments, states: [:stopped]) do |body|
+        ensure_generation(stopped_generation)
+        Results.variables(body, stopped_generation)
+      end
+    end
+
+    def set_variable(reference, name, value)
+      stopped_generation = generation
+      reference = Results.decode_reference(reference, stopped_generation)
+      name = Protocol.string(name, "variable name")
+      value = Protocol.string(value, "variable value")
+      send_request(
+        "setVariable",
+        {variablesReference: reference, name: name, value: value},
+        states: [:stopped]
+      ) do |body|
+        ensure_generation(stopped_generation)
+        Results.set_variable(body, stopped_generation, name)
+      end
+    end
+
+    def set_expression(expression, value, frame_id: nil)
+      stopped_generation = generation
+      expression = Protocol.string(expression, "expression", empty: false)
+      value = Protocol.string(value, "expression value")
+      arguments = {expression: expression, value: value}
+      arguments[:frameId] = Protocol.integer(frame_id, "frame id") unless frame_id.nil?
+      send_request("setExpression", arguments, states: [:stopped]) do |body|
+        ensure_generation(stopped_generation)
+        Results.set_variable(body, stopped_generation, expression)
+      end
+    end
+
+    def evaluate(expression, frame_id: nil, context: "repl")
+      stopped_generation = generation
+      expression = Protocol.string(expression, "expression")
+      context = Protocol.string(context, "evaluation context", empty: false)
+      arguments = {expression: expression, context: context}
+      arguments[:frameId] = Protocol.integer(frame_id, "frame id") unless frame_id.nil?
+      send_request("evaluate", arguments, states: [:stopped]) do |body|
+        ensure_generation(stopped_generation)
+        Results.evaluate(body, stopped_generation, expression)
+      end
+    end
+
+    def completions(text, column, frame_id: nil)
+      text = Protocol.string(text, "completion text")
+      column = Protocol.uint(column, "completion column")
+      arguments = {text: text, column: column}
+      arguments[:frameId] = Protocol.integer(frame_id, "frame id") unless frame_id.nil?
+      send_request("completions", arguments, states: [:stopped]) { |body| Results.completions(body) }
+    end
+
+    def source(reference)
+      reference = Protocol.uint(reference, "source reference")
+      send_request("source", {sourceReference: reference}, states: %i[configuring running stopped]) do |body|
+        Results.source_content(body)
+      end
+    end
+
+    private
+
+    def variable_filter(value)
+      value = value.to_s
+      raise ArgumentError, "filter must be indexed or named" unless %w[indexed named].include?(value)
+
+      value
+    end
+
+    def ensure_generation(expected)
+      raise Error, "debuggee resumed while request was pending" unless generation == expected && state == :stopped
+    end
+  end
+end