live_console 0.1.0

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,84 @@
+= LiveConsole
+
+== 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.
+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.  
+
+== 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'
+
+	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
+	# At this point, users can connect and get an IRB prompt.
+	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.
+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!'
+
+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.
+
+== 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.
+
+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 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.
+
+== Credits
+
+Pete Elmore -- (pete.elmore(a)gmail.com)
+
+== Home page
+
+http://debu.gs/live-console

data/doc/lc_example.rb

@@ -0,0 +1,34 @@
+#!/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 port
+lc.run
+
+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.rb

@@ -0,0 +1,156 @@
+# LiveConsole
+# Pete Elmore (pete.elmore@gmail.com), 2007-10-18
+# debu.gs/live-console
+# See doc/LICENSE.
+
+require 'irb'
+require 'socket'
+
+# 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.
+class LiveConsole
+	include Socket::Constants
+
+	attr_accessor :tcp_server, :lc_thread
+	private :tcp_server=, :lc_thread=
+	
+	# call-seq:
+	#	# Bind a LiveConsole to localhost:3030:
+	# 	LiveConsole.new 3030
+	#	# Accept connections from anywhere on port 3030.  Ridiculously insecure:
+	# 	LiveConsole.new(3030, 'Your.IP.address')
+	#
+	# 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 { 
+			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
+				end
+			}
+		}
+		lc_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
+			true
+		else
+			false
+		end
+	end
+
+	def init_irb
+		return if @@irb_inited_already
+		IRB.setup nil
+		@@irb_inited_already = true
+	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
+
+	# Overridden a la FXIrb to accomodate our needs.
+	def IRB.start_with_io(io, &block)
+		unless @inited
+			setup '/dev/null'
+			IRB.parse_opts
+			IRB.load_modules
+			@inited = true
+		end
+
+		irb = Irb.new(nil, 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
+		}
+		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 SocketIOMethod is a class that wraps I/O over a socket for IRB.
+class SocketIOMethod < IRB::StdioInputMethod
+	def initialize(socket)
+		@socket = socket
+		@line = []
+		@line_no = 0
+	end
+
+	def gets
+		@socket.print @prompt
+		@socket.flush
+		@line[@line_no += 1] = @socket.gets
+		@socket.flush
+		@line[@line_no]
+	end
+
+	# These just pass through to the socket.
+	%w(eof? close).each { |mname|
+		define_method(mname) { || @socket.send mname }
+	}
+
+	def print(*a)
+		@socket.print *a
+	end
+
+	def file_name
+		@socket.inspect
+	end
+end

data/lib/live_console_config.rb

@@ -0,0 +1,8 @@
+# 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.1.0'
+	URL = 'http://debu.gs/live-console'
+end

metadata

@@ -0,0 +1,52 @@
+--- !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: 
+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: []
+
+rdoc_options: []
+
+extra_rdoc_files: 
+- doc/README
+- doc/LICENSE
+- doc/lc_example.rb
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+