From bf0e37b3cf8288779d63e67459bc261b13a13ca3 Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Thu, 9 Dec 2004 17:20:00 +0000 Subject: [PATCH] Added preliminary remote breakpoint support git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@102 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- railties/Rakefile | 13 +- railties/bin/breakpointing | 2 + railties/environments/development.rb | 9 + railties/fresh_rakefile | 1 + railties/lib/binding_of_caller.rb | 81 +++++ railties/lib/breakpoint.rb | 512 +++++++++++++++++++++++++++ railties/lib/breakpoint_client.rb | 134 +++++++ railties/lib/webrick_server.rb | 18 - 8 files changed, 750 insertions(+), 20 deletions(-) create mode 100644 railties/bin/breakpointing create mode 100644 railties/lib/binding_of_caller.rb create mode 100755 railties/lib/breakpoint.rb create mode 100644 railties/lib/breakpoint_client.rb diff --git a/railties/Rakefile b/railties/Rakefile index bfea6da8e3..79042c325d 100644 --- a/railties/Rakefile +++ b/railties/Rakefile @@ -21,7 +21,8 @@ TEST_DIRS = %w( fixtures unit functional mocks mocks/development mocks/testing LOG_FILES = %w( apache.log development.log test.log production.log ) HTML_FILES = %w( 404.html 500.html index.html ) -SCRIPT_FILES = %w( generate ) +SCRIPT_FILES = %w( generate breakpoint_client envcon ) +BIN_FILES = %w( breakpointing envcon ) GENERATORS = %w( controller mailer model scaffold ) VENDOR_LIBS = %w( actionpack activerecord actionmailer railties ) @@ -96,7 +97,7 @@ end desc "Make copies of all the default content of ties" task :copy_ties_content => [ :copy_rootfiles, :copy_dispatches, :copy_html_files, :copy_abstract_application, - :copy_configs, :copy_generators, :copy_test_helpers, :copy_docs_in_public, + :copy_configs, :copy_generators, :copy_binfiles, :copy_test_helpers, :copy_docs_in_public, :copy_app_doc_readme ] task :copy_dispatches do @@ -150,6 +151,14 @@ task :copy_generators do end end +task :copy_binfiles do + BIN_FILES.each do |file| + dest_file = File.join(PKG_DESTINATION, 'script', file) + cp File.join('bin', file), dest_file + chmod 0755, dest_file + end +end + task :copy_rootfiles do cp "fresh_rakefile", "#{PKG_DESTINATION}/Rakefile" cp "README", "#{PKG_DESTINATION}/README" diff --git a/railties/bin/breakpointing b/railties/bin/breakpointing new file mode 100644 index 0000000000..77a561bdef --- /dev/null +++ b/railties/bin/breakpointing @@ -0,0 +1,2 @@ +#!/usr/local/bin/ruby +require 'breakpoint_client' diff --git a/railties/environments/development.rb b/railties/environments/development.rb index b2119a9700..ab4d3b9979 100644 --- a/railties/environments/development.rb +++ b/railties/environments/development.rb @@ -1,3 +1,12 @@ ActionController::Base.consider_all_requests_local = true ActionController::Base.reload_dependencies = true ActiveRecord::Base.reload_associations = true + +require 'breakpoint' +require 'irb/completion' +# Change the port (default: 42531) here in case you are +# on shared hosting. Note that you should set up a SSH +# tunnel when you want to connect from a different +# computer over the internet. See the documentation of +# Breakpoint.activate_drb for how to do that. +Breakpoint.activate_drb('druby://localhost:42531') \ No newline at end of file diff --git a/railties/fresh_rakefile b/railties/fresh_rakefile index ae50a21665..4de647169c 100755 --- a/railties/fresh_rakefile +++ b/railties/fresh_rakefile @@ -43,6 +43,7 @@ Rake::RDocTask.new("apidoc") { |rdoc| rdoc.title = "Rails Framework Documentation" rdoc.options << '--line-numbers --inline-source' rdoc.rdoc_files.include('README') + rdoc.rdoc_files.include('lib/breakpoint.rb') rdoc.rdoc_files.include('vendor/railties/CHANGELOG') rdoc.rdoc_files.include('vendor/railties/MIT-LICENSE') rdoc.rdoc_files.include('vendor/activerecord/README') diff --git a/railties/lib/binding_of_caller.rb b/railties/lib/binding_of_caller.rb new file mode 100644 index 0000000000..64b945158c --- /dev/null +++ b/railties/lib/binding_of_caller.rb @@ -0,0 +1,81 @@ +begin + require 'simplecc' +rescue LoadError + def Continuation.create(*args, &block) + cc = nil; result = callcc {|c| cc = c; block.call(cc) if block and args.empty?} + result ||= args + return *[cc, *result] + end +end + +# This method returns the binding of the method that called your +# method. It will raise an Exception when you're not inside a method. +# +# It's used like this: +# def inc_counter(amount = 1) +# Binding.of_caller do |binding| +# # Create a lambda that will increase the variable 'counter' +# # in the caller of this method when called. +# inc = eval("lambda { |arg| counter += arg }", binding) +# # We can refer to amount from inside this block safely. +# inc.call(amount) +# end +# # No other statements can go here. Put them inside the block. +# end +# counter = 0 +# 2.times { inc_counter } +# counter # => 2 +# +# Binding.of_caller must be the last statement in the method. +# This means that you will have to put everything you want to +# do after the call to Binding.of_caller into the block of it. +# This should be no problem however, because Ruby has closures. +# If you don't do this an Exception will be raised. Because of +# the way that Binding.of_caller is implemented it has to be +# done this way. +def Binding.of_caller(&block) + old_critical = Thread.critical + Thread.critical = true + count = 0 + cc, result, error, extra_data = Continuation.create(nil, nil) + error.call if error + + tracer = lambda do |*args| + type, context, extra_data = args[0], args[4], args + if type == "return" + count += 1 + # First this method and then calling one will return -- + # the trace event of the second event gets the context + # of the method which called the method that called this + # method. + if count == 2 + # It would be nice if we could restore the trace_func + # that was set before we swapped in our own one, but + # this is impossible without overloading set_trace_func + # in current Ruby. + set_trace_func(nil) + cc.call(eval("binding", context), nil, extra_data) + end + elsif type == "line" then + nil + elsif type == "c-return" and extra_data[3] == :set_trace_func then + nil + else + set_trace_func(nil) + error_msg = "Binding.of_caller used in non-method context or " + + "trailing statements of method using it aren't in the block." + cc.call(nil, lambda { raise(ArgumentError, error_msg) }, nil) + end + end + + unless result + set_trace_func(tracer) + return nil + else + Thread.critical = old_critical + case block.arity + when 1 then yield(result) + else yield(result, extra_data) + end + end +end diff --git a/railties/lib/breakpoint.rb b/railties/lib/breakpoint.rb new file mode 100755 index 0000000000..ab8a5be5a1 --- /dev/null +++ b/railties/lib/breakpoint.rb @@ -0,0 +1,512 @@ +# The Breakpoint library provides the convenience of +# being able to inspect and modify state, diagnose +# bugs all via IRB by simply setting breakpoints in +# your applications by the call of a method. +# +# This library was written and is supported by me, +# Florian Gross. I can be reached at flgr@ccan.de +# and enjoy getting feedback about my libraries. +# +# The whole library (including breakpoint_client.rb +# and binding_of_caller.rb) is licensed under the +# same license that Ruby uses. (Which is currently +# either the GNU General Public License or a custom +# one that allows for commercial usage.) If you for +# some good reason need to use this under another +# license please contact me. + +require 'irb' +require 'binding_of_caller' +require 'drb' +require 'drb/acl' + +module Breakpoint + extend self + + # This will pop up an interactive ruby session at a + # pre-defined break point in a Ruby application. In + # this session you can examine the environment of + # the break point. + # + # You can get a list of variables in the context using + # local_variables via +local_variables+. You can then + # examine their values by typing their names. + # + # You can have a look at the call stack via +caller+. + # + # The source code around the location where the breakpoint + # was executed can be examined via +source_lines+. Its + # argument specifies how much lines of context to display. + # The default amount of context is 5 lines. Note that + # the call to +source_lines+ can raise an exception when + # it isn't able to read in the source code. + # + # breakpoints can also return a value. They will execute + # a supplied block for getting a default return value. + # A custom value can be returned from the session by doing + # +throw(:debug_return, value)+. + # + # You can also give names to break points which will be + # used in the message that is displayed upon execution + # of them. + # + # Here's a sample of how breakpoints should be placed: + # + # class Person + # def initialize(name, age) + # @name, @age = name, age + # breakpoint("Person#initialize") + # end + # + # attr_reader :age + # def name + # breakpoint("Person#name") { @name } + # end + # end + # + # person = Person.new("Random Person", 23) + # puts "Name: #{person.name}" + # + # And here is a sample debug session: + # + # Executing break point "Person#initialize" at file.rb:4 in `initialize' + # irb(#):001:0> local_variables + # => ["name", "age", "_", "__"] + # irb(#):002:0> [name, age] + # => ["Random Person", 23] + # irb(#):003:0> [@name, @age] + # => ["Random Person", 23] + # irb(#):004:0> self + # => # + # irb(#):005:0> @age += 1; self + # => # + # irb(#):006:0> exit + # Executing break point "Person#name" at file.rb:9 in `name' + # irb(#):001:0> throw(:debug_return, "Overriden name") + # Name: Overriden name + # + # Breakpoint sessions will automatically have a few + # convenience methods available. See Breakpoint::CommandBundle + # for a list of them. + # + # Breakpoints can also be used remotely over sockets. + # This is implemented by running part of the IRB session + # in the application and part of it in a special client. + # You have to call Breakpoint.activate_drb to enable + # support for remote breakpoints and then run + # breakpoint_client.rb which is distributed with this + # library. See the documentation of Breakpoint.activate_drb + # for details. + def breakpoint(id = nil, context = nil, &block) + callstack = caller + callstack.slice!(0, 3) if callstack.first["breakpoint"] + file, line, method = *callstack.first.match(/^(.+?):(\d+)(?::in `(.*?)')?/).captures + + message = "Executing break point " + (id ? "#{id.inspect} " : "") + + "at #{file}:#{line}" + (method ? " in `#{method}'" : "") + + if context then + return handle_breakpoint(context, message, file, line, &block) + end + + Binding.of_caller do |binding_context| + handle_breakpoint(binding_context, message, file, line, &block) + end + end + + module CommandBundle + # Proxy to a Breakpoint client. Lets you directly execute code + # in the context of the client. + class Client + def initialize(eval_handler) # :nodoc: + @eval_handler = eval_handler + end + + instance_methods.each do |method| + next if method[/^__.+__$/] + undef_method method + end + + # Executes the specified code at the client. + def eval(code) + @eval_handler.call(code) + end + + # Will execute the specified statement at the client. + def method_missing(method, *args) + if args.empty? + result = eval("#{method}") + else + result = eval("#{method}(*Marshal.load(#{Marshal.dump(args).inspect}))") + end + + unless [true, false, nil].include?(result) + result.extend(DRbUndumped) rescue nil + end + + return result + end + end + + # Returns the source code surrounding the location where the + # breakpoint was issued. + def source_lines(context = 5, return_line_numbers = false) + lines = File.readlines(@__bp_file).map { |line| line.chomp } + + break_line = @__bp_line + start_line = [break_line - context, 1].max + end_line = break_line + context + + result = lines[(start_line - 1) .. (end_line - 1)] + + if return_line_numbers then + return [start_line, break_line, result] + else + return result + end + end + + # Lets an object that will forward method calls to the breakpoint + # client. This is useful for outputting longer things at the client + # and so on. You can for example do these things: + # + # client.puts "Hello" # outputs "Hello" at client console + # # outputs "Hello" into the file temp.txt at the client + # client.File.open("temp.txt", "w") { |f| f.puts "Hello" } + def client() + if Breakpoint.use_drb? then + Client.new(Breakpoint.drb_service.eval_handler) + else + Client.new(lambda { |code| eval(code, TOPLEVEL_BINDING) }) + end + end + end + + def handle_breakpoint(context, message, file = "", line = "", &block) # :nodoc: + catch(:debug_return) do |value| + eval(%{ + @__bp_file = #{file.inspect} + @__bp_line = #{line} + extend Breakpoint::CommandBundle + extend DRbUndumped + }, context) rescue nil + + if not use_drb? then + puts message + IRB.start(nil, IRB::WorkSpace.new(context)) + else + @drb_service.add_breakpoint(context, message) + end + + block.call if block + end + end + + # These exceptions will be raised on failed asserts + # if Breakpoint.asserts_cause_exceptions is set to + # true. + class FailedAssertError < RuntimeError + end + + # This asserts that the block evaluates to true. + # If it doesn't evaluate to true a breakpoint will + # automatically be created at that execution point. + # + # You can disable assert checking in production + # code by setting Breakpoint.optimize_asserts to + # true. (It will still be enabled when Ruby is run + # via the -d argument.) + # + # Example: + # person_name = "Foobar" + # assert { not person_name.nil? } + # + # Note: If you want to use this method from an + # unit test, you will have to call it by its full + # name, Breakpoint.assert. + def assert(context = nil, &condition) + return if Breakpoint.optimize_asserts and not $DEBUG + return if yield + + callstack = caller + callstack.slice!(0, 3) if callstack.first["assert"] + file, line, method = *callstack.first.match(/^(.+?):(\d+)(?::in `(.*?)')?/).captures + + message = "Assert failed at #{file}:#{line}#{" in `#{method}'" if method}." + + if Breakpoint.asserts_cause_exceptions and not $DEBUG then + raise(Breakpoint::FailedAssertError, message) + end + + message += " Executing implicit breakpoint." + + if context then + return handle_breakpoint(context, message, file, line) + end + + Binding.of_caller do |context| + handle_breakpoint(context, message, file, line) + end + end + + # Whether asserts should be ignored if not in debug mode. + # Debug mode can be enabled by running ruby with the -d + # switch or by setting $DEBUG to true. + attr_accessor :optimize_asserts + self.optimize_asserts = false + + # Whether an Exception should be raised on failed asserts + # in non-$DEBUG code or not. By default this is disabled. + attr_accessor :asserts_cause_exceptions + self.asserts_cause_exceptions = false + @use_drb = false + + attr_reader :drb_service # :nodoc: + + class DRbService # :nodoc: + include DRbUndumped + + def initialize + @handler = @eval_handler = @collision_handler = nil + + IRB.instance_eval { @CONF[:RC] = true } + IRB.run_config + end + + def collision + sleep(0.5) until @collision_handler + + @collision_handler.call + end + + def ping; end + + def add_breakpoint(context, message) + workspace = IRB::WorkSpace.new(context) + workspace.extend(DRbUndumped) + + sleep(0.5) until @handler + + @handler.call(workspace, message) + end + + def register_handler(&block) + @handler = block + end + + def unregister_handler + @handler = nil + end + + attr_reader :eval_handler + + def register_eval_handler(&block) + @eval_handler = block + end + + def unregister_eval_handler + @eval_handler = lambda { } + end + + def register_collision_handler(&block) + @collision_handler = block + end + + def unregister_collision_handler + @collision_handler = lambda { } + end + end + + # Will run Breakpoint in DRb mode. This will spawn a server + # that can be attached to via the breakpoint-client command + # whenever a breakpoint is executed. This is useful when you + # are debugging CGI applications or other applications where + # you can't access debug sessions via the standard input and + # output of your application. + # + # You can specify an URI where the DRb server will run at. + # This way you can specify the port the server runs on. The + # default URI is druby://localhost:42531. + # + # Please note that breakpoints will be skipped silently in + # case the DRb server can not spawned. (This can happen if + # the port is already used by another instance of your + # application on CGI or another application.) + # + # Also note that by default this will only allow access + # from localhost. You can however specify a list of + # allowed hosts or nil (to allow access from everywhere). + # But that will still not protect you from somebody + # reading the data as it goes through the net. + # + # A good approach for getting security and remote access + # is setting up an SSH tunnel between the DRb service + # and the client. This is usually done like this: + # + # $ ssh -L20000:127.0.0.1:20000 -R10000:127.0.0.1:10000 example.com + # (This will connect port 20000 at the client side to port + # 20000 at the server side, and port 10000 at the server + # side to port 10000 at the client side.) + # + # After that do this on the server side: (the code being debugged) + # Breakpoint.activate_drb("druby://127.0.0.1:20000", "localhost") + # + # And at the client side: + # ruby breakpoint_client.rb -c druby://127.0.0.1:10000 -s druby://127.0.0.1:20000 + # + # Running through such a SSH proxy will also let you use + # breakpoint.rb in case you are behind a firewall. + # + # Detailed information about running DRb through firewalls is + # available at http://www.rubygarden.org/ruby?DrbTutorial + def activate_drb(uri = 'druby://localhost:42531', + allowed_hosts = ['localhost', '127.0.0.1', '::1']) + + return false if @use_drb + + if allowed_hosts then + acl = ["deny", "all"] + + Array(allowed_hosts).each do |host| + acl += ["allow", host] + end + + DRb.install_acl(ACL.new(acl)) + end + + @use_drb = true + @drb_service = DRbService.new + did_collision = false + begin + DRb.start_service(uri, @drb_service) + rescue Errno::EADDRINUSE + # The port is already occupied by another + # Breakpoint service. We will try to tell + # the old service that we want its port. + # It will then forward that request to the + # user and retry. + unless did_collision then + DRbObject.new(nil, uri).collision + did_collision = true + end + sleep(10) + retry + end + + return true + end + + # Returns true when Breakpoints are used over DRb. + # Breakpoint.activate_drb causes this to be true. + def use_drb? + @use_drb == true + end +end + +module IRB # :nodoc: + class << self; remove_method :start; end + def self.start(ap_path = nil, main_context = nil, workspace = nil) + $0 = File::basename(ap_path, ".rb") if ap_path + + # suppress some warnings about redefined constants + old_verbose, $VERBOSE = $VERBOSE, nil + IRB.setup(ap_path) + $VERBOSE = old_verbose + + if @CONF[:SCRIPT] then + irb = Irb.new(main_context, @CONF[:SCRIPT]) + else + irb = Irb.new(main_context) + end + + if workspace then + irb.context.workspace = workspace + end + + @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC] + @CONF[:MAIN_CONTEXT] = irb.context + + old_sigint = trap("SIGINT") do + irb.signal_handle + end + + catch(:IRB_EXIT) do + irb.eval_input + end + ensure + trap("SIGINT", old_sigint) + end + + class << self + alias :old_CurrentContext :CurrentContext + remove_method :CurrentContext + end + def IRB.CurrentContext + if old_CurrentContext.nil? and Breakpoint.use_drb? then + result = Object.new + def result.last_value; end + return result + else + old_CurrentContext + end + end + + class Context + alias :old_evaluate :evaluate + def evaluate(line, line_no) + if line.chomp == "exit" then + exit + else + old_evaluate(line, line_no) + end + end + end + + class WorkSpace + alias :old_evaluate :evaluate + + def evaluate(*args) + if Breakpoint.use_drb? then + result = old_evaluate(*args) + if args[0] != :no_proxy and + not [true, false, nil].include?(result) + then + result.extend(DRbUndumped) rescue nil + end + return result + else + old_evaluate(*args) + end + end + end + + module InputCompletor + def self.eval(code, context, *more) + # Big hack, this assumes that InputCompletor + # will only call eval() when it wants code + # to be executed in the IRB context. + IRB.conf[:MAIN_CONTEXT].workspace.evaluate(:no_proxy, code, *more) + end + end +end + +module DRb # :nodoc: + class DRbObject + undef :inspect + undef :clone + end +end + +# See Breakpoint.breakpoint +def breakpoint(id = nil, &block) + Binding.of_caller do |context| + Breakpoint.breakpoint(id, context, &block) + end +end + +# See Breakpoint.assert +def assert(&block) + Binding.of_caller do |context| + Breakpoint.assert(context, &block) + end +end diff --git a/railties/lib/breakpoint_client.rb b/railties/lib/breakpoint_client.rb new file mode 100644 index 0000000000..d36b347d46 --- /dev/null +++ b/railties/lib/breakpoint_client.rb @@ -0,0 +1,134 @@ +require 'breakpoint' +require 'optparse' + +options = { + :ClientURI => nil, + :ServerURI => "druby://localhost:42531", + :RetryDelay => 10 +} + +ARGV.options do |opts| + script_name = File.basename($0) + opts.banner = [ + "Usage: ruby #{script_name} [options] [server uri]", + "", + "This tool lets you connect to a breakpoint service ", + "which was started via Breakpoint.activate_drb.", + "", + "The server uri defaults to druby://localhost:42531" + ].join("\n") + + opts.separator "" + + opts.on("-c", "--client-uri=uri", + "Run the client on the specified uri.", + "This can be used to specify the port", + "that the client uses to allow for back", + "connections from the server.", + "Default: Find a good URI automatically.", + "Example: -c druby://localhost:12345" + ) { |options[:ClientURI]| } + + opts.on("-s", "--server-uri=uri", + "Connect to the server specified at the", + "specified uri.", + "Default: druby://localhost:42531" + ) { |options[:ServerURI]| } + + opts.on("-R", "--retry-delay=delay", Integer, + "Automatically try to reconnect to the", + "server after delay seconds when the", + "connection failed or timed out.", + "A value of 0 disables automatical", + "reconnecting completely.", + "Default: 10" + ) { |options[:RetryDelay]| } + + opts.separator "" + + opts.on("-h", "--help", + "Show this help message." + ) { puts opts; exit } + + opts.parse! +end + +options[:ServerURI] = ARGV[0] if ARGV[0] + +DRb.start_service(options[:ClientURI]) + +begin + service = DRbObject.new(nil, options[:ServerURI]) + + begin + service.register_eval_handler do |code| + result = eval(code, TOPLEVEL_BINDING) + result.extend(DRb::DRbUndumped) rescue nil + result + end + + service.register_collision_handler do + msg = [ + " *** Breakpoint service collision ***", + " Another Breakpoint service tried to use the", + " port already occupied by this one. It will", + " keep waiting until this Breakpoint service", + " is shut down.", + " ", + " If you are using the Breakpoint library for", + " debugging a Rails or other CGI application", + " this likely means that this Breakpoint", + " session belongs to an earlier, outdated", + " request and should be shut down via 'exit'." + ].join("\n") + + if RUBY_PLATFORM["win"] then + # This sucks. Sorry, I'm not doing this because + # I like funky message boxes -- I need to do this + # because on Windows I have no way of displaying + # my notification via puts() when gets() is still + # being performed on STDIN. I have not found a + # better solution. + begin + require 'tk' + root = TkRoot.new { withdraw } + Tk.messageBox('message' => msg, 'type' => 'ok') + root.destroy + rescue Exception + puts "", msg, "" + end + else + puts "", msg, "" + end + end + + service.register_handler do |workspace, message| + puts message + IRB.start(nil, nil, workspace) + end + + loop do + begin + service.ping + rescue DRb::DRbConnError => error + puts "Server exited. Exiting..." + exit! + end + + sleep(0.5) + end + ensure + service.unregister_handler + end +rescue Exception => error + if options[:RetryDelay] > 0 then + puts "No connection to breakpoint service at #{options[:ServerURI]}:", + " (#{error})", + " Reconnecting in #{options[:RetryDelay]} seconds..." + + sleep options[:RetryDelay] + retry + else + raise + end +end diff --git a/railties/lib/webrick_server.rb b/railties/lib/webrick_server.rb index 248378cb57..885610d9a0 100644 --- a/railties/lib/webrick_server.rb +++ b/railties/lib/webrick_server.rb @@ -4,24 +4,6 @@ require 'webrick' require 'cgi' require 'stringio' -begin - require 'dev-utils/debug' - require 'irb/completion' - - module DevUtils::Debug - alias_method :breakpoint_without_io, :breakpoint unless method_defined?(:breakpoint_without_io) - - def breakpoint(name = nil, context = nil, &block) - $new_stdin, $new_stdout = $stdin, $stdout - $stdin, $stdout = $old_stdin, $old_stdout - breakpoint_without_io(name, context, &block) - $stdin, $stdout = $new_stdin, $new_stdout - end - end -rescue LoadError - # dev utils not available -end - include WEBrick class DispatchServlet < WEBrick::HTTPServlet::AbstractServlet