pete-live_console 0.2.1

data/Rakefile

@@ -0,0 +1,91 @@
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'lib/live_console_config'
+require 'fileutils'
+
+$: << "#{File.dirname(__FILE__)}/lib"
+
+spec = Gem::Specification.new { |s|
+	s.name = LiveConsoleConfig::PkgName
+	s.version = LiveConsoleConfig::Version
+	s.author = LiveConsoleConfig::Authors
+	s.email = LiveConsoleConfig::Email
+	s.homepage = LiveConsoleConfig::URL
+	s.rubyforge_project = LiveConsoleConfig::Project
+
+	s.platform = Gem::Platform::RUBY
+
+	s.files = Dir["{lib,doc,bin,ext}/**/*"].delete_if {|f| 
+		/\/rdoc(\/|$)/i.match f
+	} + %w(Rakefile)
+	s.require_path = 'lib'
+	s.has_rdoc = true
+	s.extra_rdoc_files = Dir['doc/*'].select(&File.method(:file?))
+	s.extensions << 'ext/extconf.rb' if File.exist? 'ext/extconf.rb'
+	Dir['bin/*'].map(&File.method(:basename)).map(&s.executables.method(:<<))
+
+	s.summary =	'A library to support adding an irb console to your ' \
+		'running application.'
+	%w().each &s.method(:add_dependency)
+}
+
+Rake::RDocTask.new(:doc) { |t|
+	t.main = 'doc/README'
+	t.rdoc_files.include 'lib/**/*.rb', 'doc/*', 'bin/*', 'ext/**/*.c', 
+		'ext/**/*.rb'
+	t.options << '-S' << '-N'
+	t.rdoc_dir = 'doc/rdoc'
+}
+
+Rake::GemPackageTask.new(spec) { |pkg|
+	pkg.need_tar_bz2 = true
+}
+
+desc "Builds and installs the gem for #{spec.name}"
+task(:install => :package) { 
+	g = "pkg/#{spec.name}-#{spec.version}.gem"
+	system "sudo gem install -l #{g}"
+}
+
+desc "Runs IRB, automatically require()ing #{spec.name}."
+task(:irb) {
+	exec "irb -Ilib -r#{spec.name}"
+}
+
+desc "Cleans up the pkg directory."
+task(:clean) {
+	FileUtils.rm_rf 'pkg'
+}
+
+
+desc "Generates a static gemspec file; useful for github."
+task(:static_gemspec) {
+	# This whole thing is hacky.
+	spec.validate
+	spec_attrs = %w(
+		platform author email files require_path has_rdoc extra_rdoc_files
+		extensions executables name summary homepage
+	).map { |attr|
+		"\ts.#{attr} = #{spec.send(attr).inspect}\n"
+	}.join << 
+		"\ts.version = #{spec.version.to_s.inspect}\n" <<
+		spec.dependencies.map { |dep|
+			"\ts.add_dependency #{dep.inspect}\n"
+		}.join
+
+	File.open("#{spec.name}.gemspec", 'w') { |f|
+		f.print <<-EOGEMSPEC
+# This is a static gempsec automatically generated by rake.  It's better to
+# edit the Rakefile than this file.  It is kept in the repository for the
+# benefit of github.
+
+spec = Gem::Specification.new { |s|
+#{spec_attrs}}
+if __FILE__ == $0
+	Gem::Builder.new(spec).build 
+else
+	spec
+end
+		EOGEMSPEC
+	}
+}

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/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2007 Peter Elmore (pete.elmore at gmail.com)
+
+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/doc/README

@@ -0,0 +1,127 @@
+= LiveConsole
+
+== Summary
+
+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 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.
+
+Have a look at the bugs section.  It should be pretty apparent that incorrect
+use of this library could create a large security hole, especially before
+authentication is implemented.
+
+== Installation
+
+You can install via rubygems,
+
+  gem install live_console
+
+or plain old setup.rb:
+
+  ruby setup.rb install
+
+== How to use LiveConsole
+
+LiveConsole is very easy to use in your own app:
+
+	require 'rubygems'
+	require 'live_console'
+
+	# 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
+	# Now, no one can connect.
+
+	# 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
+	# Then, in a different shell:
+	$ 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.  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.
+
+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 odd
+software that also monkey-patches IRB, so they are likely to be there.  Bug
+reports and patches gratefully accepted.
+
+== Credits
+
+Pete Elmore -- (pete.elmore(a)gmail.com)
+
+== Home page
+
+http://debu.gs/live-console

data/doc/lc_example.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'live_console'
+
+print <<-EOF
+This is a demo program for LiveConsole.  It starts a LiveConsole on the
+specified port, and you can connect to it by using netcat or telnet to connect
+to the specified port.  
+	Usage:
+		#{$0} [port_number [value_for_$x]]
+The default port is 3333, and $x is set by default to nil.  Run this program,
+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 :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 { 
+	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/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

@@ -0,0 +1,227 @@
+# LiveConsole
+# Pete Elmore (pete.elmore@gmail.com), 2007-10-18
+# debu.gs/live-console
+# See doc/LICENSE.
+
+require 'irb'
+require 'irb/frame'
+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 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 :io_method, :io, :thread, :bind
+	private :io_method=, :io=, :thread=
+	
+	# call-seq:
+	#	# 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(: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#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 {
+				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
+			}
+		}
+		thread
+	end
+
+	# Ends the running thread, if it exists.  Returns true if a thread was
+	# running, false otherwise.
+	def stop
+		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
+			Thread.new &r # Leaks a thread, but works.
+		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
+# weird I/O method and re-starting IRB from time to time.  
+module IRB
+	@inited = false
+
+	ARGV = []
+
+	# Overridden a la FXIrb to accomodate our needs.
+	def IRB.start_with_io(io, bind, &block)
+		unless @inited
+			setup '/dev/null'
+			IRB.parse_opts
+			IRB.load_modules
+			@inited = true
+		end
+
+		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
+		@CONF[:PROMPT_MODE] = :INF_RUBY
+
+		catch(:IRB_EXIT) { 
+			begin
+				irb.eval_input
+			rescue StandardError => e
+				irb.print([e.to_s, e.backtrace].flatten.join("\n") + "\n")
+				retry
+			end
+		}
+		irb.print "\n"
+	end
+
+	class Context
+		# Fix an IRB bug; it ignores your output method.
+		def output *args
+			@output_method.print *args
+		end
+	end
+
+	class Irb
+		# Fix an IRB bug; it ignores your output method.
+		def printf(*args)
+			context.output(sprintf(*args))
+		end
+
+		# Fix an IRB bug; it ignores your output method.
+		def print(*args)
+			context.output *args
+		end
+	end
+end
+
+# 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
+		output.print @prompt
+		output.flush
+		@line[@line_no += 1] = input.gets
+		# @io.flush	# Not sure this is needed.
+		@line[@line_no]
+	end
+
+	# Returns the user input history.
+	def lines
+		@line.dup
+	end
+
+	def print(*a)
+		output.print *a
+	end
+
+	def file_name
+		input.inspect
+	end
+
+	def eof?
+		input.eof?
+	end
+
+	def close
+		input.close
+		output.close if @output
+	end
+end

data/lib/live_console_config.rb

@@ -0,0 +1,9 @@
+# This module houses a pile of informative constants for LiveConsole.
+module LiveConsoleConfig
+	Authors = 'Pete Elmore'
+	Email = 'pete.elmore@gmail.com'
+	PkgName = 'live_console'
+	Version = '0.2.1'
+	URL = 'http://debu.gs/live-console'
+	Project = 'live-console'
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: pete-live_console
+version: !ruby/object:Gem::Version 
+  version: 0.2.1
+platform: ruby
+authors: 
+- Pete Elmore
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-16 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: pete.elmore@gmail.com
+executables: 
+- udscat
+extensions: []
+
+extra_rdoc_files: 
+- doc/LICENSE
+- doc/README
+- doc/lc_example.rb
+- doc/lc_unix_example.rb
+files: 
+- lib/live_console/io_methods/socket_io.rb
+- lib/live_console/io_methods/unix_socket_io.rb
+- lib/live_console/io_methods.rb
+- lib/live_console.rb
+- lib/live_console_config.rb
+- doc/LICENSE
+- doc/README
+- doc/lc_example.rb
+- doc/lc_unix_example.rb
+- bin/udscat
+- Rakefile
+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: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A library to support adding an irb console to your running application.
+test_files: []
+