|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +require "socket" |
| 4 | +require "stringio" |
| 5 | + |
| 6 | +module IRB |
| 7 | + # A request/response server for agent-driven IRB sessions over a Unix socket |
| 8 | + # (experimental). |
| 9 | + # |
| 10 | + # When <tt>binding.agent</tt> is called, the behavior depends on |
| 11 | + # the +IRB_SOCK_PATH+ environment variable: |
| 12 | + # |
| 13 | + # - *Not set* (Phase 1 - discovery): prints instructions explaining how to |
| 14 | + # start a debug session, then calls <tt>exit(0)</tt>. This lets the agent |
| 15 | + # see the instructions before the process terminates. |
| 16 | + # |
| 17 | + # - *Set* (Phase 2 - debug session): starts a Unix socket server at the |
| 18 | + # given path. The server accepts one connection at a time in a loop. Each |
| 19 | + # connection is a single request: the client sends Ruby code (or an IRB |
| 20 | + # command), closes its write end, and reads back the result. The IRB session |
| 21 | + # state persists across requests. Sending +exit+ ends the loop and resumes |
| 22 | + # execution of the host program. |
| 23 | + # |
| 24 | + # == Example agent workflow |
| 25 | + # |
| 26 | + # # 1. Run the app - hits breakpoint, prints instructions, exits: |
| 27 | + # $ ruby app.rb |
| 28 | + # |
| 29 | + # # 2. Re-run in background with a socket path: |
| 30 | + # $ IRB_SOCK_PATH=/tmp/irb-debug.sock ruby app.rb & |
| 31 | + # |
| 32 | + # # 3. Send commands (one per connection): |
| 33 | + # $ ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-debug.sock"); s.puts "ls"; s.close_write; puts s.read; s.close' |
| 34 | + # $ ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-debug.sock"); s.puts "exit"; s.close_write; puts s.read; s.close' |
| 35 | + # |
| 36 | + class RemoteServer |
| 37 | + def initialize(binding_context, sock_path:) |
| 38 | + @binding_context = binding_context |
| 39 | + @sock_path = sock_path |
| 40 | + end |
| 41 | + |
| 42 | + class StringInput < InputMethod |
| 43 | + def initialize(str) |
| 44 | + super() |
| 45 | + @io = StringIO.new(str) |
| 46 | + end |
| 47 | + |
| 48 | + def gets |
| 49 | + @io.gets |
| 50 | + end |
| 51 | + |
| 52 | + def eof? |
| 53 | + @io.eof? |
| 54 | + end |
| 55 | + |
| 56 | + def encoding |
| 57 | + Encoding::UTF_8 |
| 58 | + end |
| 59 | + end |
| 60 | + |
| 61 | + def run |
| 62 | + server = nil |
| 63 | + original_stdout = $stdout |
| 64 | + original_main_context = IRB.conf[:MAIN_CONTEXT] |
| 65 | + original_use_pager = IRB.conf[:USE_PAGER] |
| 66 | + |
| 67 | + begin |
| 68 | + remove_socket_file |
| 69 | + |
| 70 | + server = UNIXServer.new(@sock_path) |
| 71 | + File.chmod(0600, @sock_path) |
| 72 | + |
| 73 | + IRB.conf[:USE_PAGER] = false |
| 74 | + |
| 75 | + binding_irb = create_irb |
| 76 | + IRB.conf[:MAIN_CONTEXT] = binding_irb.context |
| 77 | + |
| 78 | + loop do |
| 79 | + client = server.accept |
| 80 | + begin |
| 81 | + input = client.read |
| 82 | + next if input.nil? || input.empty? |
| 83 | + |
| 84 | + binding_irb.context.io = StringInput.new(input) |
| 85 | + |
| 86 | + not_exited = catch(:IRB_EXIT) do |
| 87 | + begin |
| 88 | + $stdout = client |
| 89 | + binding_irb.eval_input |
| 90 | + ensure |
| 91 | + $stdout = original_stdout |
| 92 | + end |
| 93 | + :not_exited |
| 94 | + end |
| 95 | + |
| 96 | + break unless not_exited == :not_exited |
| 97 | + ensure |
| 98 | + client&.close |
| 99 | + end |
| 100 | + |
| 101 | + end |
| 102 | + ensure |
| 103 | + $stdout = original_stdout |
| 104 | + IRB.conf[:USE_PAGER] = original_use_pager |
| 105 | + # Match Irb#run: restoring MAIN_CONTEXT to nil can crash threaded sessions. |
| 106 | + IRB.conf[:MAIN_CONTEXT] = original_main_context if original_main_context |
| 107 | + server&.close |
| 108 | + remove_socket_file |
| 109 | + end |
| 110 | + end |
| 111 | + |
| 112 | + private |
| 113 | + |
| 114 | + def remove_socket_file |
| 115 | + File.unlink(@sock_path) if File.lstat(@sock_path).socket? |
| 116 | + rescue Errno::ENOENT |
| 117 | + end |
| 118 | + |
| 119 | + def create_irb |
| 120 | + workspace = IRB::WorkSpace.new(@binding_context) |
| 121 | + irb = IRB::Irb.new(workspace, StringInput.new(""), from_binding: true) |
| 122 | + irb.context.irb_path = File.expand_path(@binding_context.source_location[0]) |
| 123 | + irb.context.verbose = false |
| 124 | + irb.context.newline_before_multiline_output = false |
| 125 | + irb |
| 126 | + end |
| 127 | + |
| 128 | + class << self |
| 129 | + def print_instructions(binding_context) |
| 130 | + file, line = binding_context.source_location |
| 131 | + method_name = binding_context.eval("__method__") rescue nil # rubocop:disable Style/RescueModifier |
| 132 | + location = method_name ? "#{file}:#{line} in `#{method_name}`" : "#{file}:#{line}" |
| 133 | + |
| 134 | + $stdout.puts <<~MSG |
| 135 | + ========================================================== |
| 136 | + IRB agent breakpoint hit at #{location} |
| 137 | +
|
| 138 | + No IRB_SOCK_PATH set - exiting without starting a debug session. |
| 139 | +
|
| 140 | + Add breakpoints with: require "irb"; binding.agent |
| 141 | +
|
| 142 | + To debug this breakpoint: |
| 143 | +
|
| 144 | + 1. Run the app in the BACKGROUND with a socket path: |
| 145 | +
|
| 146 | + IRB_SOCK_PATH=/tmp/irb-UNIQUE_ID.sock <your command> & |
| 147 | +
|
| 148 | + The process will block waiting for a connection. |
| 149 | +
|
| 150 | + 2. Wait for the socket file to appear: |
| 151 | +
|
| 152 | + ls /tmp/irb-UNIQUE_ID.sock |
| 153 | +
|
| 154 | + 3. Send commands to the socket with FOREGROUND commands: |
| 155 | +
|
| 156 | + ruby -e 'require "socket"; s = UNIXSocket.new("/tmp/irb-UNIQUE_ID.sock"); s.puts "help"; s.close_write; puts s.read; s.close' |
| 157 | +
|
| 158 | + Each invocation sends one command and prints the result. |
| 159 | + The IRB session persists between invocations. |
| 160 | +
|
| 161 | + Examples: |
| 162 | + ... s.puts "ls"; s.close_write # list methods and variables |
| 163 | + ... s.puts "show_source foo"; s.close_write # see source of a method |
| 164 | + ... s.puts "@name"; s.close_write # inspect a variable |
| 165 | + ... s.puts "exit"; s.close_write # end session, resume app |
| 166 | +
|
| 167 | + ========================================================== |
| 168 | + MSG |
| 169 | + $stdout.flush |
| 170 | + end |
| 171 | + end |
| 172 | + end |
| 173 | +end |
0 commit comments