live_console 0.1.0 → 0.2.0

data/bin/udscat

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+# This is a client for the unix domain socket version of LiveConsole.  It just
+# talks to the socket.  It has been included so that you don't have to track
+# down a version of netcat that does this.
+
+require 'socket'
+
+socket_path = ARGV.first
+if socket_path.nil?
+	$stderr.puts "You must supply a path to the socket you want to connect to."
+	exit 1
+end
+
+client = UNIXSocket.new socket_path
+
+$stdin.sync = $stdout.sync = client.sync = true
+
+read_thread =
+	Thread.new {
+		loop {
+			begin
+				Thread.pass
+				$stdout.write client.read_nonblock(1024)
+			rescue Errno::EAGAIN, Errno::EINTR => e
+				IO.select [client], [], [], 1
+			rescue Errno::EOFError, Errno::EPIPE => e
+				# nothing
+			end
+		}
+	}
+
+Thread.new {
+	loop {
+		begin 
+			l = $stdin.read_nonblock(1024)
+		rescue Errno::EAGAIN
+			retry
+		end
+
+		begin
+			client.print l if IO.select [], [client], [], 1
+		rescue Errno::EPIPE => e
+			$stderr.puts "Other end closed."
+			exit 0
+		end
+	}
+}
+
+trap('INT') { exit 0 }
+loop { sleep 1 }

data/doc/README

@@ -2,15 +2,16 @@
 
 == Summary
 
-LiveConsole is a library for providing IRB over a TCP connection .  If you add
-it to your application, you can run arbitrary code against your application.
+LiveConsole is a library for providing IRB over a TCP connection or a Unix
+Domain Socket.  If you add it to your application, you can run arbitrary code
+against your application.
 For example, you can:
 	* Inspect the state of a running application
 	* Change the state of the application
 	* Patch code on the fly, without a restart.
-	* Let anyone on the net 0wn you if you bind to anything other than
-	  localhost.  :)
-It's useful as a diagnostic tool, a debugging tool, and a way to impress your friends or get those Lisp guys off your back.  You know the ones.  
+	* Let anyone on the net 0wn you if you bind to a public interface. :)
+It's useful as a diagnostic tool, a debugging tool, and a way to impress your
+friends or get those Lisp guys off your back.  You know the ones I mean.
 
 == Stern Security Warning.  Grrr.
 
@@ -35,14 +36,32 @@ LiveConsole is very easy to use in your own app:
 	require 'rubygems'
 	require 'live_console'
 
-	lc = LiveConsole.new 1337	# Creates a LiveConsole on port 1337
-	# We're not yet listening on the port.  We need to start it up:
-	lc.run				# Starts the LiveConsole thread
+	# Create a LiveConsole using TCP on port 1337
+	lc = LiveConsole.new :socket, :port => 1337
+	# We're not yet accepting connections.  We need to start it up:
+	lc.start            # Starts the LiveConsole thread
 	# At this point, users can connect and get an IRB prompt.
-	lc.stop				# Kills the LiveConsole thread
+	lc.stop             # Kills the LiveConsole thread
 	# Now, no one can connect.
 
-Have a look at doc/lc_example.rb for a brief example of how to use LiveConsole.
+	# Create a LiveConsole using a Unix socket in /tmp/live-console.sock
+	lc = LiveConsole.new :unix_socket, :path => '/tmp/live-console.sock'
+	# As above:
+	lc.start
+	lc.stop
+
+	# Have a LiveConsole run code in a binding other than the top-level:
+	lc = LiveConsole.new :unix_socket, :path => '/tmp/live-console.sock'
+	                     :bind => binding
+	lc.start
+	# That will start IRB in the current binding.  There is also an accessor:
+	lc.bind = binding
+	# Of course, you must restart before IRB will see the new binding:
+	lc.restart
+
+Have a look at doc/lc_example.rb or doc/lc_unix_example.rb for brief examples
+of how to use LiveConsole.
+
 Try just running it:
 
 	$ ruby doc/lc_example.rb 4000 test
@@ -50,30 +69,54 @@ Try just running it:
 	$ netcat localhost 4000
 	irb(main):001:0> puts 'Wow, magic!'
 
+	$ ruby doc/lc_unix_example.rb /tmp/live-console.sock
+	# Then, in a different shell:
+	$ udscat /tmp/live-console.sock
+	irb(main):001:0> puts 'Words cannot describe the joy I feel.'
+
 You can get creative about it, only starting LiveConsole when there's an
 unhandled exception in your server, and then calling LiveConsole#stop when
 you've diagnosed and fixed whatever the problem was.
 
+Additionally, if you want to run LiveConsole on a server, but run netcat
+locally, you can use SSH port forwarding to avoid having to open LiveConsole
+to the world:  
+
+	ssh -L4000:localhost:4000 you@server
+
+Then, locally, you can do 
+
+	netcat localhost 4000
+
+and get the remote LiveConsole.  man ssh for more details.  Of course, this
+only works for the TCP socket mode.
+
 == Bugs
 
 LiveConsole lacks many of the niceties of IRB on the console, like Readline
 support.
 
 Typing exit, hitting ^D, or sending signals (like INT or STOP) doesn't work.
-Just exit the program you used to connect to it.
+Just exit the program you used to connect to it.  This has more to do with the
+program you use to connect to the socket.
+
+For TCP connections, there is no authentication support yet, although it is
+planned for the near future.  This creates a security risk:  anyone that can
+connect to the socket can run arbitrary Ruby code as the user who owns the
+process.  In fact, even binding to localhost can be a security issue if you're
+on a box with any untrusted users.  If there's a chance you don't know what
+you're doing, avoid using this library.  The Unix Domain Socket version is more
+secure, as you can control access via filesystem permissions.
 
-There is no authentication support yet, although it is planned for the near
-future.  This creates a security risk:  anyone that can connect to the socket
-can run arbitrary Ruby code as the user who owns the process.  In fact, even
-binding to localhost can be a security issue if you're on a box with any
-untrusted users.  If there's a chance you don't know what you're doing, avoid
-using this library.
+Only one client can connect at a time.  I don't think anyone needs multiple LC
+connections to serve multiple instances of IRB to various clients, but if you
+need it, let me know.
 
 The README contains a slur against Lisp guys.  Please stop hitting me with that PDP-10 manual.  I love your language and the lambda tattoo on your chest.  
 
-Other than that, LiveConsole doesn't have any known bugs, but it is alpha
-software, so they are likely to be there.  Bug reports and patches gratefully
-accepted.
+Other than that, LiveConsole doesn't have any known bugs, but it is odd
+software that also monkey-patches IRB, so they are likely to be there.  Bug
+reports and patches gratefully accepted.
 
 == Credits
 

data/doc/lc_example.rb

@@ -14,14 +14,18 @@ and then in a different terminal, connect to it via netcat or telnet.  You can
 check that the value of $x is exactly what you set it to, and that you're
 working inside this process, but there's not much to do inside the example
 script.  :)
+
 EOF
 
 port = ARGV.first.to_i
 port = port.zero? ? 3333 : port
 $x = ARGV[1]
 
-lc = LiveConsole.new port
-lc.run
+lc = LiveConsole.new :socket, :port => port, :bind => binding
+lc.start
+
+puts "My PID is #{Process.pid}, " \
+	"I'm running on port #{port}, and $x = #{$x.inspect}"
 
 oldx = $x
 loop { 

data/doc/lc_unix_example.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'live_console'
+
+default_path = "/tmp/lc_example_#{Process.uid}.sock"
+
+print <<-EOF
+This is a demo program for LiveConsole.  It starts a LiveConsole at the
+specified path, and you can connect to it by using netcat or telnet to connect
+to the specified port.  
+	Usage:
+		#{$0} [path_to_socket [value_for_$x]]
+The default path is #{default_path}, and $x is set by default to nil.  
+Run this program, and then in a different terminal, connect to it via
+the supplied udscat program or the BSD version of netcat.
+EOF
+
+path = ARGV.first
+path = path.nil? ? default_path : path
+$x = ARGV[1]
+
+lc = LiveConsole.new :unix_socket, :path => path, :bind => binding
+lc.start
+
+puts "My PID is #{Process.pid}, " \
+	"I'm running on #{path}, and $x = #{$x.inspect}"
+
+oldx = $x
+loop { 
+	if $x != oldx
+		puts "The time is now #{Time.now.strftime('%R:%S')}.",
+			"The value of $x changed from #{oldx.inspect} to #{$x.inspect}."
+		oldx = $x
+	end
+	sleep 1
+}

data/lib/live_console/io_methods/socket_io.rb

@@ -0,0 +1,27 @@
+class LiveConsole::IOMethods::SocketIO
+	DefaultOpts = {
+		:host => '127.0.0.1',
+	}.freeze
+	RequiredOpts = DefaultOpts.keys + [:port]
+
+	include LiveConsole::IOMethods::IOMethod
+
+	def start
+		@server ||= TCPServer.new host, port
+
+		begin
+			self.raw_input = self.raw_output = server.accept_nonblock
+			return true
+		rescue Errno::EAGAIN, Errno::ECONNABORTED, Errno::EPROTO,
+			   Errno::EINTR => e
+			select
+			retry
+		end
+	end
+
+	def stop
+		select
+		raw_input.close rescue nil
+	end
+
+end

data/lib/live_console/io_methods/unix_socket_io.rb

@@ -0,0 +1,31 @@
+require 'socket'
+
+class LiveConsole::IOMethods::UnixSocketIO
+	DefaultOpts = {
+		:mode => 0600,
+		:uid => Process.uid,
+		:gid => Process.gid,
+	}
+	RequiredOpts = DefaultOpts.keys + [:path]
+
+	include LiveConsole::IOMethods::IOMethod
+
+	def start
+		@server ||= UNIXServer.new path
+		
+		begin
+			self.raw_input = self.raw_output = server.accept_nonblock
+			raw_input.sync = true
+			return true
+		rescue Errno::EAGAIN, Errno::ECONNABORTED, Errno::EPROTO,
+			   Errno::EINTR => e
+			select
+			retry
+		end
+	end
+
+	def stop
+		select
+		raw_input.close
+	end
+end

data/lib/live_console/io_methods.rb

@@ -0,0 +1,53 @@
+module LiveConsole::IOMethods
+	List = []
+
+	Dir[File.join(File.dirname(__FILE__), 'io_methods', '*.rb')].each { |entry|
+		fname = entry.sub /\.rb$/, ''
+		classname = File.basename(entry, '.rb').capitalize.
+			gsub(/_(\w)/) { $1.upcase }.sub(/io$/i, 'IO').to_sym
+		mname = File.basename(fname).sub(/_io$/, '').to_sym
+
+		autoload classname, fname
+		List << mname
+
+		define_method(mname) {
+			const_get classname
+		}
+	}
+	List.freeze
+
+	extend self
+
+	module IOMethod
+		def initialize(opts)
+			self.opts = self.class::DefaultOpts.merge opts
+			unless missing_opts.empty?
+				raise ArgumentError, "Missing opts for " \
+					"#{self.class.name}:  #{missing_opts.inspect}"
+			end
+		end
+
+		def missing_opts
+			self.class::RequiredOpts - opts.keys
+		end
+
+		def self.included(other)
+			other.instance_eval {
+				readers = [:opts, :raw_input, :raw_output]
+				attr_accessor *readers
+				private *readers.map { |r| (r.to_s + '=').to_sym }
+
+				other::RequiredOpts.each { |opt| 
+					define_method(opt) { opts[opt] } 
+				}
+			}
+		end
+
+		def select
+			IO.select [server], [], [], 1 if server
+		end
+
+		private
+		attr_accessor :server
+	end
+end

data/lib/live_console.rb

@@ -5,73 +5,119 @@
 
 require 'irb'
 require 'socket'
+require 'live_console_config'
 
 # LiveConsole provides a socket that can be connected to via netcat or telnet
 # to use to connect to an IRB session inside a running process.  It creates a
-# thread that listens on the specified address/port, and presents connecting
-# clients with an IRB shell.  Using this, you can execute code on a running
-# instance of a Ruby process to inspect the state or even patch code on the
-# fly.  There is currently no readline support.
+# thread that listens on the specified address/port or Unix Domain Socket path,
+# and presents connecting clients with an IRB shell.  Using this, you can
+# execute code on a running instance of a Ruby process to inspect the state or
+# even patch code on the fly.  There is currently no readline support.
 class LiveConsole
 	include Socket::Constants
+	autoload :IOMethods, 'live_console/io_methods'
 
-	attr_accessor :tcp_server, :lc_thread
-	private :tcp_server=, :lc_thread=
+	attr_accessor :io_method, :io, :thread, :bind
+	private :io_method=, :io=, :thread=
 	
 	# call-seq:
-	#	# Bind a LiveConsole to localhost:3030:
-	# 	LiveConsole.new 3030
+	#	# Bind a LiveConsole to localhost:3030 (only allow clients on this 
+	#	# machine to connect):
+	#	LiveConsole.new :socket, :port => 3030
 	#	# Accept connections from anywhere on port 3030.  Ridiculously insecure:
-	# 	LiveConsole.new(3030, 'Your.IP.address')
+	#	LiveConsole.new(:socket, :port => 3030, :host => '0.0.0.0')
+	#	# Use a Unix Domain Socket (which is more secure) instead:
+	#	LiveConsole.new(:unix_socket, :path => '/tmp/my_liveconsole.sock',
+	#	                :mode => 0600, :uid => Process.uid, :gid => Process.gid)
+	#	# By default, the mode is 0600, and the uid and gid are those of the 
+	#	# current process.  These three options are for the file's permissions.
+	#	# You can also supply a binding for IRB's toplevel:
+	#	LiveConsole.new(:unix_socket, 
+	#		:path => "/tmp/live_console_#{Process.pid}.sock", :bind => binding)
 	#
-	# Creates a new LiveConsole.  You must next call LiveConsole#run when you
-	# want to spawn the thread to accept connections and run the console.
-	def initialize(listen_port, listen_addr = '127.0.0.1')
-		self.tcp_server = TCPServer.new listen_addr, listen_port
-	end
-
-	# LiveConsole#run spawns a thread to listen for, accept, and provide an IRB
-	# console to new connections.  If a thread is already running, this method
-	# simply returns false; otherwise, it returns the new thread.
-	def run
-		return false if lc_thread
-		self.lc_thread = Thread.new { 
+	# Creates a new LiveConsole.  You must next call LiveConsole#start when you
+	# want to spawn the thread to accept connections and start the console.
+	def initialize(io_method, opts = {})
+		self.io_method = io_method.to_sym
+		self.bind = opts.delete :bind
+		unless IOMethods::List.include?(self.io_method)
+			raise ArgumentError, "Unknown IO method: #{io_method}" 
+		end
+
+		init_io opts
+	end
+
+	# LiveConsole#start spawns a thread to listen for, accept, and provide an
+	# IRB console to new connections.  If a thread is already running, this
+	# method simply returns false; otherwise, it returns the new thread.
+	def start
+		if thread 
+			if thread.alive?
+				return false
+			else
+				thread.join
+				self.thread = nil
+			end
+		end
+
+		self.thread = Thread.new { 
 			loop {
-				socket = nil
-				begin
-					Thread.pass
-					socket = tcp_server.accept_nonblock
-					io = SocketIOMethod.new(socket)
-					IRB.start_with_io(io)
-				rescue Errno::EAGAIN, Errno::ECONNABORTED, Errno::EPROTO,
-					   Errno::EINTR
-					socket.close rescue nil
-					IO.select([tcp_server], [], [], 1)
-
-					retry
+				Thread.pass
+				if io.start
+					irb_io = GenericIOMethod.new io.raw_input, io.raw_output
+					begin
+						IRB.start_with_io(irb_io, bind)
+					rescue Errno::EPIPE => e
+						io.stop
+					end
 				end
 			}
 		}
-		lc_thread
+		thread
 	end
 
 	# Ends the running thread, if it exists.  Returns true if a thread was
 	# running, false otherwise.
 	def stop
-		if lc_thread
-			lc_thread.exit
-			self.lc_thread = nil
+		if thread
+			if thread == Thread.current
+				self.thread = nil
+				Thread.current.exit!
+			end
+
+			thread.exit
+			if thread.join(0.1).nil?
+				thread.exit!
+			end
+			self.thread = nil
 			true
 		else
 			false
 		end
 	end
 
+	# Restarts.  Useful for binding changes.  Return value is the same as for 
+	# LiveConsole#start.
+	def restart
+		r = lambda { stop; start }
+		if thread == Thread.current # An odd case.
+			Thread.new &r
+		else
+			r.call
+		end
+	end
+
+	private
+
 	def init_irb
 		return if @@irb_inited_already
 		IRB.setup nil
 		@@irb_inited_already = true
 	end
+
+	def init_io opts
+		self.io = IOMethods.send(io_method).new opts
+	end
 end
 
 # We need to make a couple of changes to the IRB module to account for using a
@@ -80,7 +126,7 @@ module IRB
 	@inited = false
 
 	# Overridden a la FXIrb to accomodate our needs.
-	def IRB.start_with_io(io, &block)
+	def IRB.start_with_io(io, bind, &block)
 		unless @inited
 			setup '/dev/null'
 			IRB.parse_opts
@@ -88,7 +134,9 @@ module IRB
 			@inited = true
 		end
 
-		irb = Irb.new(nil, io, io)
+		bind ||= IRB::Frame.top(1)
+		ws = IRB::WorkSpace.new(bind)
+		irb = Irb.new(ws, io, io)
 
 		@CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC]
 		@CONF[:MAIN_CONTEXT] = irb.context
@@ -102,7 +150,7 @@ module IRB
 				retry
 			end
 		}
-		print "\n"
+		irb.print "\n"
 	end
 
 	class Context
@@ -125,32 +173,52 @@ module IRB
 	end
 end
 
-# The SocketIOMethod is a class that wraps I/O over a socket for IRB.
-class SocketIOMethod < IRB::StdioInputMethod
-	def initialize(socket)
-		@socket = socket
+# The GenericIOMethod is a class that wraps I/O for IRB.
+class GenericIOMethod < IRB::StdioInputMethod
+	# call-seq:
+	# 	GenericIOMethod.new io
+	# 	GenericIOMethod.new input, output
+	#
+	# Creates a GenericIOMethod, using either a single object for both input
+	# and output, or one object for input and another for output.
+	def initialize(input, output = nil)
+		@input, @output = input, output
 		@line = []
 		@line_no = 0
 	end
 
+	attr_reader :input
+	def output
+		@output || input
+	end
+
 	def gets
-		@socket.print @prompt
-		@socket.flush
-		@line[@line_no += 1] = @socket.gets
-		@socket.flush
+		output.print @prompt
+		output.flush
+		@line[@line_no += 1] = input.gets
+		# @io.flush	# Not sure this is needed.
 		@line[@line_no]
 	end
 
-	# These just pass through to the socket.
-	%w(eof? close).each { |mname|
-		define_method(mname) { || @socket.send mname }
-	}
+	# Returns the user input history.
+	def lines
+		@line.dup
+	end
 
 	def print(*a)
-		@socket.print *a
+		output.print *a
 	end
 
 	def file_name
-		@socket.inspect
+		input.inspect
+	end
+
+	def eof?
+		input.eof?
+	end
+
+	def close
+		input.close
+		output.close if @output
 	end
 end

data/lib/live_console_config.rb

@@ -3,6 +3,7 @@ module LiveConsoleConfig
 	Authors = 'Pete Elmore'
 	Email = 'pete.elmore@gmail.com'
 	PkgName = 'live_console'
-	Version = '0.1.0'
+	Version = '0.2.0'
 	URL = 'http://debu.gs/live-console'
+	Project = 'live-console'
 end

metadata

@@ -1,52 +1,67 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.4
-specification_version: 1
 name: live_console
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2007-10-19 00:00:00 -07:00
-summary: A library to support adding a console to your running application.
-require_paths: 
-- lib
-email: pete.elmore@gmail.com
-homepage: http://debu.gs/live-console
-rubyforge_project: 
-description: 
-autorequire: live_console
-default_executable: 
-bindir: bin
-has_rdoc: true
-required_ruby_version: !ruby/object:Gem::Version::Requirement 
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      version: 0.0.0
-  version: 
+  version: 0.2.0
 platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
 authors: 
 - Pete Elmore
-files: 
-- doc/LICENSE
-- doc/README
-- doc/lc_example.rb
-- lib/live_console.rb
-- lib/live_console_config.rb
-test_files: []
+autorequire: 
+bindir: bin
+cert_chain: []
 
-rdoc_options: []
+date: 2008-10-15 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: pete.elmore@gmail.com
+executables: 
+- udscat
+extensions: []
 
 extra_rdoc_files: 
-- doc/README
+- doc/lc_example.rb
 - doc/LICENSE
+- doc/README
+- doc/lc_unix_example.rb
+files: 
+- bin/udscat
 - doc/lc_example.rb
-executables: []
-
-extensions: []
+- doc/LICENSE
+- doc/README
+- doc/lc_unix_example.rb
+- lib/live_console_config.rb
+- lib/live_console.rb
+- lib/live_console
+- lib/live_console/io_methods
+- lib/live_console/io_methods/socket_io.rb
+- lib/live_console/io_methods/unix_socket_io.rb
+- lib/live_console/io_methods.rb
+has_rdoc: true
+homepage: http://debu.gs/live-console
+post_install_message: 
+rdoc_options: []
 
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
 requirements: []
 
-dependencies: []
+rubyforge_project: live-console
+rubygems_version: 1.3.0
+signing_key: 
+specification_version: 2
+summary: A library to support adding a console to your running application.
+test_files: []