ladybug 0.0.1.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 19fccf01c424b4f35e62b84e6d7aaf3978e0253d
+  data.tar.gz: 5a12abd7a1eb3148e9fd067675ffacb4012f4dd4
+SHA512:
+  metadata.gz: 481c6763053abdaea1057eba44c38003bc8475010a9684a02c82e5f5e55b217b960f93f29250c19a6cd5306aca4aac8bc6f644c1cd709e86017355a09504f3ac
+  data.tar.gz: 61f3f7a14e828a8192a21836f8f9325ebba844a091390b46e3540673476d8492db06f68f1bf70fa420ee9755beb22308276cdb1aa34abe5356a5dad8190c2f96

data/README.md

@@ -0,0 +1 @@
+# Ladybug

data/lib/ladybug/debugger.rb

@@ -0,0 +1,156 @@
+# A simple debugger using set_trace_func
+# Allows for external control while in a breakpoint
+
+module Ladybug
+  class Debugger
+    def initialize
+      @breakpoints = []
+
+      @to_main_thread = Queue.new
+      @from_main_thread = Queue.new
+
+      @on_pause = -> {}
+      @on_resume = -> {}
+    end
+
+    def start
+      RubyVM::InstructionSequence.compile_option = {
+        trace_instruction: true
+      }
+
+      set_trace_func trace_func
+    end
+
+    def on_pause(&block)
+      @on_pause = block
+    end
+
+    def on_resume(&block)
+      @on_resume = block
+    end
+
+    def resume
+      @to_main_thread.push({ command: 'continue' })
+    end
+
+    def step_over
+      @to_main_thread.push({ command: 'step_over' })
+    end
+
+    def evaluate(expression)
+      @to_main_thread.push({
+        command: 'eval',
+        arguments: {
+          expression: expression
+        }
+      })
+
+      # Block on eval, returns result
+      @from_main_thread.pop
+    end
+
+    # returns a breakpoint ID
+    def set_breakpoint(filename:, line_number:)
+      breakpoint = {
+        filename: filename,
+        line_number: line_number,
+        id: "filename:#{line_number}"
+      }
+
+      @breakpoints.push(breakpoint)
+
+      breakpoint[:id]
+    end
+
+    def remove_breakpoint(breakpoint_id)
+      filename, line_number = breakpoint_id.split(":")
+      line_number = line_number.to_i
+
+      @breakpoints.delete_if { |bp| bp[:id] == breakpoint_id }
+    end
+
+    private
+
+    def trace_func
+      @step_over_file = nil
+
+      proc { |event, filename, line_number, id, binding, klass, *rest|
+        # This check is called a lot so perhaps worth making faster,
+        # but might not matter much with small number of breakpoints in practice
+        breakpoint_hit = @breakpoints.find do |bp|
+          bp[:filename] == filename && bp[:line_number] == line_number
+        end
+
+        break_on_step_over = (@step_over_file == filename)
+
+        if breakpoint_hit || break_on_step_over
+          local_variables =
+            binding.local_variables.each_with_object({}) do |lvar, hash|
+              hash[lvar] = binding.local_variable_get(lvar)
+            end
+
+          instance_variables =
+            binding.eval("instance_variables").each_with_object({}) do |ivar, hash|
+              hash[ivar] = binding.eval("instance_variable_get(:#{ivar})")
+            end
+
+          pause_info = {
+            breakpoint_id: breakpoint_hit ? breakpoint_hit[:id] : nil,
+            label: Kernel.caller_locations.first.base_label,
+            local_variables: local_variables,
+            instance_variables: instance_variables,
+            filename: filename,
+            line_number: line_number
+            # call_frames: []
+
+            # Call frames are pretty complicated...
+            # call_frames: Kernel.caller_locations.first(3).map do |call_frame|
+            #   {
+            #     callFrameId: SecureRandom.uuid,
+            #     functionName: call_frame.base_label,
+            #     scopeChain: [
+            #       {
+            #         type: "local",
+            #         startLocation: ,
+            #         endLocation:
+            #       }
+            #     ],
+            #     url: "#{"http://rails.com"}/#{filename}",
+            #     this:
+            #   }
+            # end
+          }
+
+          @on_pause.call(pause_info)
+
+          loop do
+            # block until we get a command from the debugger thread
+            message = @to_main_thread.pop
+
+            case message[:command]
+            when 'continue'
+              @step_over_file = nil
+              break
+            when 'step_over'
+              # todo: does "step over" really mean break in the same file,
+              # or is there are a deeper meaning
+              @step_over_file = filename
+              break
+            when 'eval'
+              evaluated =
+                begin
+                  binding.eval(message[:arguments][:expression])
+                rescue
+                  nil
+                end
+              @from_main_thread.push(evaluated)
+            end
+          end
+
+          # Notify the debugger thread that we've resumed
+          @on_resume.call({})
+        end
+      }
+    end
+  end
+end

data/lib/ladybug/middleware.rb

@@ -0,0 +1,245 @@
+require 'faye/websocket'
+require 'json'
+require 'thread'
+require 'pathname'
+
+require 'ladybug/script_repository'
+require 'ladybug/debugger'
+require 'ladybug/object_manager'
+
+# A Rack middleware that accepts a websocket connection from the Chrome
+# Devtools UI and responds to requests, interacting with Ladybug::Debugger
+module Ladybug
+  class Middleware
+    def initialize(app)
+      @app = app
+      @scripts = {}
+
+      @script_repository = ScriptRepository.new
+      @debugger = Debugger.new
+      @object_manager = ObjectManager.new
+    end
+
+    def call(env)
+      puts "Debug in Chrome: chrome-devtools://devtools/bundled/inspector.html?ws=#{env['HTTP_HOST']}"
+
+      # For now, all websocket connections are assumed to be a debug connection
+      if Faye::WebSocket.websocket?(env)
+        ws = create_websocket(env)
+
+        # Return async Rack response
+        ws.rack_response
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def create_websocket(env)
+      ws = Faye::WebSocket.new(env)
+
+      ws.on :message do |event|
+        # The WebSockets library silently swallows errors.
+        # Insert our own error handling for debugging purposes.
+
+        begin
+          data = JSON.parse(event.data)
+
+          if data["method"] == "Page.getResourceTree"
+            result = {
+              frameTree: {
+                frame: {
+                  id: "123",
+                  loaderId: "123",
+                  mimeType: "text/plain",
+                  securityOrigin: "http://localhost",
+                  url: "http://localhost"
+                },
+                resources: @script_repository.all.map do |script|
+                  {
+                    mimeType: "text/plain",
+                    type: "Script",
+                    contentSize: script.size,
+                    lastModified: script.last_modified_time.to_i,
+                    url: script.virtual_url
+                  }
+                end
+              }
+            }
+          elsif data["method"] == "Page.getResourceContent"
+            result = {
+              base64Encoded: false,
+              content: "hello world"
+            }
+          elsif data["method"] == "Debugger.getScriptSource"
+            script_id = data["params"]["scriptId"]
+            path = @script_repository.find(id: script_id).path
+            result = {
+              scriptSource: File.new(path, "r").read
+            }
+          elsif data["method"] == "Debugger.getPossibleBreakpoints"
+            # Just echo back the location the browser requested
+            result = { locations: [ data["params"]["start"] ] }
+          elsif data["method"] == "Debugger.setBreakpointByUrl"
+            # Chrome gives us a virtual URL;
+            # we need an absolute path to the file to match the API for set_trace_func
+            script = @script_repository.find(virtual_url: data["params"]["url"])
+
+            # DevTools gives us 0-indexed line numbers but
+            # ruby uses 1-indexed line numbers
+            line_number = data["params"]["lineNumber"]
+            ruby_line_number = line_number + 1
+
+            puts "setting breakpoint on #{script.path}:#{ruby_line_number}"
+
+            breakpoint_id = @debugger.set_breakpoint(
+              filename: script.absolute_path,
+              line_number: ruby_line_number
+            )
+
+            result = {
+              breakpointId: breakpoint_id,
+              locations: [
+                {
+                  scriptId: script.id,
+                  lineNumber: line_number,
+                  columnNumber: data["params"]["columnNumber"],
+                }
+              ]
+            }
+          elsif data["method"] == "Debugger.resume"
+            # Synchronously just ack the command;
+            # we'll async hear back from the main thread when execution resumes
+            @debugger.resume
+            result = {}
+          elsif data["method"] == "Debugger.stepOver"
+            # Synchronously just ack the command;
+            # we'll async hear back from the main thread when execution resumes
+            @debugger.step_over
+            result = {}
+          elsif data["method"] == "Debugger.evaluateOnCallFrame"
+            evaluated = @debugger.evaluate(data["params"]["expression"])
+            result = {
+              result: @object_manager.serialize(evaluated)
+            }
+          elsif data["method"] == "Debugger.removeBreakpoint"
+            @debugger.remove_breakpoint(data["params"]["breakpointId"])
+            result = {}
+          elsif data["method"] == "Runtime.getProperties"
+            object = @object_manager.find(data["params"]["objectId"])
+
+            result = {
+              result: @object_manager.get_properties(object)
+            }
+          else
+            result = {}
+          end
+
+          response = {
+            id: data["id"],
+            result: result
+          }
+
+          ws.send(response.to_json)
+
+          # After we send a resource tree response, we need to send these
+          # messages as well to get the files to show up
+          if data["method"] == "Page.getResourceTree"
+            @script_repository.all.each do |script|
+              message = {
+                method: "Debugger.scriptParsed",
+                params: {
+                  scriptId: script.id,
+                  url: script.virtual_url,
+                  startLine: 0,
+                  startColumn: 0,
+                  endLine: 100, #todo: really populate
+                  endColumn: 100
+                }
+              }.to_json
+
+              ws.send(message)
+            end
+          end
+        rescue => e
+          puts e.message
+          puts e.backtrace
+
+          raise e
+        end
+      end
+
+      ws.on :close do |event|
+        p [:close, event.code, event.reason]
+        ws = nil
+      end
+
+      # Spawn a thread to handle messages from the main thread
+      # and notify the client.
+
+      @debugger.on_pause do |info|
+        # Generate an object representing this scope
+        # (this is here not in the debugger because the debugger
+        #  shouldn't need to know about the requirement for a virtual object)
+        virtual_scope_object =
+          info[:local_variables].merge(info[:instance_variables])
+
+        # Register the virtual object to give it an ID and hold a ref to it
+        object_id = @object_manager.register(virtual_scope_object)
+
+        script = @script_repository.find(absolute_path: info[:filename])
+
+        location = {
+          scriptId: script.id,
+          lineNumber: info[:line_number] - 1,
+          columnNumber: 0
+        }
+
+        msg_to_client = {
+          method: "Debugger.paused",
+          params: {
+            callFrames: [
+              {
+                location: location,
+                callFrameId: SecureRandom.uuid,
+                functionName: info[:label],
+                scopeChain: [
+                  {
+                    type: "local",
+                    startLocation: location,
+                    endLocation: location,
+                    object: {
+                      className: "Object",
+                      description: "Object",
+                      type: "object",
+                      objectId: object_id
+                    }
+                  }
+                ],
+                url: script.virtual_url
+              }
+            ],
+            hitBreakpoints: info[:breakpoint_id] ? [info[:breakpoint_id]] : [],
+            reason: "other"
+          }
+        }
+
+        ws.send(msg_to_client.to_json)
+      end
+
+      @debugger.on_resume do
+        msg_to_client = {
+          method: "Debugger.resumed",
+          params: {}
+        }
+
+        ws.send(msg_to_client.to_json)
+      end
+
+      @debugger.start
+
+      ws
+    end
+  end
+end

data/lib/ladybug/object_manager.rb

@@ -0,0 +1,139 @@
+module Ladybug
+  # This class:
+  #
+  # * serializes objects for display in the Chrome UI
+  # * maintains references to all objects for which it has given out IDs for;
+  #   this ensures they don't get GC'd and can be dereferenced later by ID.
+  #
+  # TODO: Handle Chrome's "release" APIs to enable releasing references
+  #       at some point and avoid too much memory growth
+
+  class ObjectManager
+    def initialize
+      @objects = {}
+    end
+
+    # Given an ID, return the object from our registry
+    def find(id)
+      @objects[id]
+    end
+
+    # Given an object, register it in our internal state and
+    # return an ID for it
+    def register(object)
+      object_id = SecureRandom.uuid
+      @objects[object_id] = object
+      object_id
+    end
+
+    # Convert a Ruby object to a hash representing a Chrome RemoteObject
+    # https://chromedevtools.github.io/devtools-protocol/tot/Runtime#type-RemoteObject
+    def serialize(object)
+      case object
+      when String
+        {
+          type: "string",
+          value: object,
+          description: object
+        }
+      when Numeric
+        {
+          type: "number",
+          value: object,
+          description: object.to_s
+        }
+      when TrueClass, FalseClass
+        {
+          type: "boolean",
+          value: object,
+          description: object.to_s
+        }
+      when Symbol
+        {
+          type: "symbol",
+          value: object,
+          description: object.to_s
+        }
+      when Array
+        result = {
+          type: "object",
+          className: object.class.to_s,
+          description: "Array(#{object.length})",
+          objectId: register(object),
+          subtype: "array"
+        }
+
+        result.merge!(
+          preview: result.merge(
+            overflow: false,
+            properties: get_properties(object)
+          )
+        )
+
+        result
+      when nil
+        {
+          type: "object",
+          subtype: "null",
+          value: nil
+        }
+      else
+        {
+          type: "object",
+          className: object.class.to_s,
+          description: object.to_s,
+          objectId: register(object)
+        }
+      end
+    end
+
+    # Ruby objects don't have properties like JS objects do,
+    # so we need to figure out the best properties to show for non-primitives.
+    #
+    # We first give the object a chance to tell us its debug properties,
+    # then we fall back to handling a bunch of common cases,
+    # then finally we give up and just serialize its instance variables.
+    def get_properties(object)
+      if object.respond_to?(:chrome_debug_properties)
+        get_properties(object.chrome_debug_properties)
+      elsif object.is_a? Hash
+        object.
+          map do |key, value|
+            kv = {
+              name: key,
+              value: serialize(value)
+            }
+
+            kv
+          end.
+          reject { |property| property[:value].nil? }
+      elsif object.is_a? Array
+        object.map.with_index do |element, index|
+          {
+            name: index.to_s,
+            value: serialize(element)
+          }
+        end
+
+      # TODO: This section is too magical,
+      # better to let users just define their own chrome_debug_properties
+      # and then add an optional Rails plugin to the gem which
+      # monkey patches rails classes.
+      elsif object.respond_to?(:to_a)
+        get_properties(object.to_a)
+      elsif object.respond_to?(:attributes)
+        get_properties(object.attributes)
+      elsif object.respond_to?(:to_hash)
+        get_properties(object.to_hash)
+      elsif object.respond_to?(:to_h)
+        get_properties(object.to_h)
+      else
+        ivar_hash = object.instance_variables.each_with_object({}) do |ivar, hash|
+          hash[ivar] = object.instance_variable_get(ivar)
+        end
+
+        get_properties(ivar_hash)
+      end
+    end
+  end
+end

data/lib/ladybug/script_repository.rb

@@ -0,0 +1,50 @@
+# A repository of the source files for the app.
+# The Chrome Devtools API switches back and forth between different
+# references to a source file; this repository enables lookup by
+# different attributes and conversion between them.
+
+module Ladybug
+  class ScriptRepository
+    # todo: would be nice to dynamically set this to the server name
+    ROOT_URL = "http://localhost"
+
+    # todo: accept path as param?
+    def initialize
+      @scripts = enumerate_scripts
+    end
+
+    def all
+      @scripts
+    end
+
+    def find(args)
+      @scripts.find do |script|
+        args.all? do |key, value|
+          script[key] == value
+        end
+      end
+    end
+
+    private
+
+    # Return a list of Scripts with all attributes populated
+    def enumerate_scripts
+      Dir.glob("**/*").
+        reject { |f| File.directory?(f) }.
+        select { |f| File.extname(f) == ".rb" }.
+        map do |filename|
+          stat = File.stat(filename)
+
+          OpenStruct.new(
+            id: SecureRandom.uuid,
+            path: filename,
+            absolute_path: File.expand_path(filename),
+            virtual_url: "#{ROOT_URL}/#{filename}",
+            size: stat.size,
+            last_modified_time: stat.mtime
+          )
+        end
+    end
+  end
+end
+

data/lib/ladybug.rb

@@ -0,0 +1,4 @@
+module Ladybug
+end
+
+require 'ladybug/middleware'

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: ladybug
+version: !ruby/object:Gem::Version
+  version: 0.0.1.alpha
+platform: ruby
+authors:
+- Geoffrey Litt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Debug Ruby code using Chrome Devtools
+email: gklitt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ladybug.rb
+- lib/ladybug/debugger.rb
+- lib/ladybug/middleware.rb
+- lib/ladybug/object_manager.rb
+- lib/ladybug/script_repository.rb
+homepage: http://rubygems.org/gems/ladybug
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Ladybug
+test_files: []