FooBarWidget-daemon_controller 0.1.0

data/README.rdoc

@@ -0,0 +1,41 @@
+= Introduction
+
+daemon_controller is a library for implementing daemon management capabilities.
+
+Suppose that you have a Ruby on Rails application which uses the Sphinx search
+server [1] for full-text searching capbilities. In order to search the index,
+the search daemon (searchd) must be running. Furthermore, you're using the Riddle
+library [2] for interfacing with the search daemon.
+
+You can write this in your application:
+
+  require 'daemon_controller'
+  require 'riddle'
+  
+  controller = DaemonController.new(
+     :identifier    => 'Sphinx search daemon',
+     :start_command => 'searchd -c config/sphinx.conf',
+     :ping_command  => proc { Riddle::Client.new('localhost', 1234) },
+     :pid_file      => 'tmp/pids/sphinx.pid',
+     :log_file      => 'log/sphinx.log'
+  )
+  client = controller.connect do
+     Riddle::Client.new('localhost', 1234)
+  end
+  client.query("some search query...")
+
+controller.connect will start the Sphinx search daemon if it isn't already
+started. Then, it will connect to the Sphinx search daemon by running the
+given block.
+
+Basically you just tell the library how to start the daemon, how to check
+whether it's responding to connections, and which PID file and log file it
+uses. daemon_controller will automatically take care of things like:
+
+ * concurrency control, e.g. to ensure that no two processes will try to start
+   the Sphinx search daemon at the same time.
+ * error handling: if 'searchd' failed to start, then its error message will
+   be propagated into the exception that will be thrown. This makes it much
+   easier to handle daemon startup errors in your application. This can also
+   allow the system administrator to see the error message directly in your
+   application, instead of having to consult the daemon's log file.

data/daemon_controller.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name = "daemon_controller"
+  s.version = "0.1.0"
+  s.date = "2008-08-21"
+  s.summary = "A library for implementing daemon management capabilities"
+  s.email = "hongli@phusion.nl"
+  s.homepage = "http://github.com/FooBarWidget/daemon_controller/tree/master"
+  s.description = "A library for implementing daemon management capabilities."
+  s.has_rdoc = false
+  s.authors = ["Hongli Lai"]
+  
+  s.files = [
+      "README.rdoc", "LICENSE.txt", "daemon_controller.gemspec",
+      "lib/daemon_controller.rb",
+      "spec/daemon_controller_spec.rb",
+      "spec/echo_server.rb"
+  ]
+end

data/lib/daemon_controller.rb

@@ -0,0 +1,525 @@
+# Basic functionality for a single, local, external daemon:
+# - starting daemon
+#   * must be concurrency-safe!
+#   * must be able to report startup errors!
+#   * returns when daemon is fully operational
+# - stopping daemon
+#   * must be concurrency-safe!
+#   * returns when daemon has exited
+# - querying the status of a daemon
+#   * querying the status of a daemon (i.e. whether it's running)
+# - connect to a daemon, and start it if it isn't already running
+#   * must be a single atomic action
+
+require 'tempfile'
+require 'fcntl'
+
+class DaemonController
+	class Error < StandardError
+	end
+	class TimeoutError < Error
+	end
+	class AlreadyStarted < Error
+	end
+	class StartError < Error
+	end
+	class StartTimeout < TimeoutError
+	end
+	class StopError < Error
+	end
+	class StopTimeout < TimeoutError
+	end
+	class ConnectError < Error
+	end
+
+	# Create a new DaemonController object.
+	#
+	# === Mandatory options
+	#
+	# [:identifier]
+	#  A human-readable, unique name for this daemon, e.g. "Sphinx search server".
+	#  This identifier will be used in some error messages. On some platforms, it will
+	#  be used for concurrency control: on such platforms, no two DaemonController
+	#  objects will operate on the same identifier on the same time.
+	#  
+	# [:start_command]
+	#  The command to start the daemon. This must be a a String, e.g.
+	#  "mongrel_rails start -e production".
+	#  
+	# [:ping_command]
+	#  The ping command is used to check whether the daemon can be connected to.
+	#  It is also used to ensure that #start only returns when the daemon can be
+	#  connected to.
+	#  
+	#  The value may be a command string. This command must exit with an exit code of
+	#  0 if the daemon can be successfully connected to, or exit with a non-0 exit
+	#  code on failure.
+	#  
+	#  The value may also be a Proc, which returns an expression that evaluates to
+	#  true (indicating that the daemon can be connected to) or false (failure).
+	#  
+	# [:pid_file]
+	#  The PID file that the daemon will write to. Used to check whether the daemon
+	#  is running.
+	#  
+	# [:log_file]
+	#  The log file that the daemon will write to. It will be consulted to see
+	#  whether the daemon has printed any error messages during startup.
+	#
+	# === Optional options
+	# [:stop_command]
+	#  A command to stop the daemon with, e.g. "/etc/rc.d/nginx stop". If no stop
+	#  command is given (i.e. +nil+), then DaemonController will stop the daemon
+	#  by killing the PID written in the PID file.
+	#  
+	#  The default value is +nil+.
+	#  
+	# [:start_timeout]
+	#  The maximum amount of time, in seconds, that #start may take to start
+	#  the daemon. Since #start also waits until the daemon can be connected to,
+	#  that wait time is counted as well. If the daemon does not start in time,
+	#  then #start will raise an exception.
+	#  
+	#  The default value is 15.
+	#  
+	# [:stop_timeout]
+	#  The maximum amount of time, in seconds, that #stop may take to stop
+	#  the daemon. Since #stop also waits until the daemon is no longer running,
+	#  that wait time is counted as well. If the daemon does not stop in time,
+	#  then #stop will raise an exception.
+	#  
+	#  The default value is 15.
+	#  
+	# [:log_file_activity_timeout]
+	#  Once a daemon has gone into the background, it will become difficult to
+	#  know for certain whether it is still initializing or whether it has
+	#  failed and exited, until it has written its PID file. It's 99.9% probable
+	#  that the daemon has terminated with an if its start timeout has expired,
+	#  not many system administrators want to wait 15 seconds (the default start
+	#  timeout) to be notified of whether the daemon has terminated with an error.
+	#  
+	#  An alternative way to check whether the daemon has terminated with an error,
+	#  is by checking whether its log file has been recently updated. If, after the
+	#  daemon has started, the log file hasn't been updated for the amount of seconds
+	#  given by the :log_file_activity_timeout option, then the daemon is assumed to
+	#  have terminated with an error.
+	#  
+	#  The default value is 7.
+	def initialize(options)
+		[:identifier, :start_command, :ping_command, :pid_file, :log_file].each do |option|
+			if !options.has_key?(option)
+				raise ArgumentError, "The ':#{option}' option is mandatory."
+			end
+		end
+		@identifier = options[:identifier]
+		@start_command = options[:start_command]
+		@stop_command = options[:stop_command]
+		@ping_command = options[:ping_command]
+		@ping_interval = options[:ping_interval] || 0.1
+		@pid_file = options[:pid_file]
+		@log_file = options[:log_file]
+		@start_timeout = options[:start_timeout] || 15
+		@stop_timeout = options[:stop_timeout] || 15
+		@log_file_activity_timeout = options[:log_file_activity_timeout] || 7
+		@lock_file = determine_lock_file(@identifier, @pid_file)
+	end
+	
+	# Start the daemon and wait until it can be pinged.
+	#
+	# Raises:
+	# - AlreadyStarted - the daemon is already running.
+	# - StartError - the start command failed.
+	# - StartTimeout - the daemon did not start in time. This could also
+	#   mean that the daemon failed after it has gone into the background.
+	def start
+		exclusive_lock do
+			start_without_locking
+		end
+	end
+	
+	# Connect to the daemon by running the given block, which contains the
+	# connection logic. If the daemon isn't already running, then it will be
+	# started.
+	#
+	# The block must return nil or raise Errno::ECONNREFUSED, Errno::ENETUNREACH,
+	# or Errno::ETIMEDOUT to indicate that the daemon cannot be connected to.
+	# It must return non-nil if the daemon can be connected to.
+	# Upon successful connection, the return value of the block will
+	# be returned by #connect.
+	#
+	# Note that the block may be called multiple times.
+	#
+	# Raises:
+	# - StartError - an attempt to start the daemon was made, but the start
+	#   command failed with an error.
+	# - StartTimeout - an attempt to start the daemon was made, but the daemon
+	#   did not start in time, or it failed after it has gone into the background.
+	# - ConnectError - the daemon wasn't already running, but we couldn't connect
+	#   to the daemon even after starting it.
+	def connect
+		connection = nil
+		shared_lock do
+			begin
+				connection = yield
+			rescue Errno::ECONNREFUSED, Errno::ENETUNREACH, Errno::ETIMEDOUT
+				connection = nil
+			end
+		end
+		if connection.nil?
+			exclusive_lock do
+				if !daemon_is_running?
+					start_without_locking
+				end
+				begin
+					connection = yield
+				rescue Errno::ECONNREFUSED, Errno::ENETUNREACH, Errno::ETIMEDOUT
+					connection = nil
+				end
+				if connection.nil?
+					# Daemon is running but we couldn't connect to it. Possible
+					# reasons:
+					# - The daemon froze.
+					# - Bizarre security restrictions.
+					# - There's a bug in the yielded code.
+					raise ConnectError, "Cannot connect to the daemon"
+				else
+					return connection
+				end
+			end
+		else
+			return connection
+		end
+	end
+	
+	# Stop the daemon and wait until it has exited.
+	#
+	# Raises:
+	# - StopError - the stop command failed.
+	# - StopTimeout - the daemon didn't stop in time.
+	def stop
+		exclusive_lock do
+			begin
+				Timeout.timeout(@stop_timeout) do
+					kill_daemon
+					wait_until do
+						!daemon_is_running?
+					end
+				end
+			rescue Timeout::Error
+				raise StopTimeout, "Daemon '#{@identifier}' did not exit in time"
+			end
+		end
+	end
+	
+	# Returns the daemon's PID, as reported by its PID file.
+	# This method doesn't check whether the daemon's actually running.
+	# Use #running? if you want to check whether it's actually running.
+	#
+	# Raises SystemCallError or IOError if something went wrong during
+	# reading of the PID file.
+	def pid
+		shared_lock do
+			return read_pid_file
+		end
+	end
+	
+	# Checks whether the daemon is still running. This is done by reading
+	# the PID file and then checking whether there is a process with that
+	# PID.
+	#
+	# Raises SystemCallError or IOError if something went wrong during
+	# reading of the PID file.
+	def running?
+		shared_lock do
+			return daemon_is_running?
+		end
+	end
+
+private
+	def exclusive_lock
+		File.open(@lock_file, 'w') do |f|
+			if Fcntl.const_defined? :F_SETFD
+				f.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
+			end
+			f.flock(File::LOCK_EX)
+			yield
+		end
+	end
+	
+	def shared_lock
+		File.open(@lock_file, 'w') do |f|
+			if Fcntl.const_defined? :F_SETFD
+				f.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
+			end
+			f.flock(File::LOCK_SH)
+			yield
+		end
+	end
+	
+	def start_without_locking
+		if daemon_is_running?
+			raise AlreadyStarted, "Daemon '#{@identifier}' is already started"
+		end
+		save_log_file_information
+		delete_pid_file
+		begin
+			started = false
+			Timeout.timeout(@start_timeout) do
+				done = false
+				spawn_daemon
+				record_activity
+				
+				# We wait until the PID file is available and until
+				# the daemon responds to pings, but we wait no longer
+				# than @start_timeout seconds in total (including daemon
+				# spawn time).
+				# Furthermore, if the log file hasn't changed for
+				# @log_file_activity_timeout seconds, and the PID file
+				# still isn't available or the daemon still doesn't
+				# respond to pings, then assume that the daemon has
+				# terminated with an error.
+				wait_until do
+					if log_file_has_changed?
+						record_activity
+					elsif no_activity?(@log_file_activity_timeout)
+						raise Timeout::Error, "Daemon seems to have exited"
+					end
+					pid_file_available?
+				end
+				wait_until(@ping_interval) do
+					if log_file_has_changed?
+						record_activity
+					elsif no_activity?(@log_file_activity_timeout)
+						raise Timeout::Error, "Daemon seems to have exited"
+					end
+					run_ping_command || !daemon_is_running?
+				end
+				started = run_ping_command
+			end
+			result = started
+		rescue Timeout::Error
+			start_timed_out
+			if pid_file_available?
+				kill_daemon_with_signal
+			end
+			result = :timeout
+		end
+		if !result
+			raise StartError, differences_in_log_file
+		elsif result == :timeout
+			raise StartTimeout, differences_in_log_file
+		else
+			return true
+		end
+	end
+	
+	def spawn_daemon
+		run_command(@start_command)
+	end
+	
+	def kill_daemon
+		if @stop_command
+			begin
+				run_command(@stop_command)
+			rescue StartError => e
+				raise StopError, e.message
+			end
+		else
+			kill_daemon_with_signal
+		end
+	end
+	
+	def kill_daemon_with_signal
+		Process.kill('SIGTERM', read_pid_file)
+	rescue Errno::ESRCH, Errno::ENOENT
+	end
+	
+	def daemon_is_running?
+		begin
+			pid = read_pid_file
+		rescue Errno::ENOENT
+			# The PID file may not exist, or another thread/process
+			# executing #running? may have just deleted the PID file.
+			# So we catch this error.
+			pid = nil
+		end
+		if pid.nil?
+			return false
+		elsif check_pid(pid)
+			return true
+		else
+			delete_pid_file
+			return false
+		end
+	end
+	
+	def read_pid_file
+		return File.read(@pid_file).strip.to_i
+	end
+	
+	def delete_pid_file
+		File.unlink(@pid_file)
+	rescue Errno::EPERM, Errno::EACCES, Errno::ENOENT # ignore
+	end
+	
+	def check_pid(pid)
+		Process.kill(0, pid)
+		return true
+	rescue Errno::ESRCH
+		return false
+	rescue Errno::EPERM
+		# We didn't have permission to kill the process. Either the process
+		# is owned by someone else, or the system has draconian security
+		# settings and we aren't allowed to kill *any* process. Assume that
+		# the process is running.
+		return true
+	end
+	
+	def wait_until(sleep_interval = 0.1)
+		while !yield
+			sleep(sleep_interval)
+		end
+	end
+	
+	def wait_until_pid_file_is_available_or_log_file_has_changed
+		while !(pid_file_available? || log_file_has_changed?)
+			sleep 0.1
+		end
+		return pid_file_is_available?
+	end
+	
+	def wait_until_daemon_responds_to_ping_or_has_exited_or_log_file_has_changed
+		while !(run_ping_command || !daemon_is_running? || log_file_has_changed?)
+			sleep(@ping_interval)
+		end
+		return run_ping_command
+	end
+	
+	def record_activity
+		@last_activity_time = Time.now
+	end
+	
+	# Check whether there has been no recorded activity in the past +seconds+ seconds.
+	def no_activity?(seconds)
+		return Time.now - @last_activity_time > seconds
+	end
+	
+	def pid_file_available?
+		return File.exist?(@pid_file) && File.stat(@pid_file).size != 0
+	end
+	
+	# This method does nothing and only serves as a hook for the unit test.
+	def start_timed_out
+	end
+	
+	def save_log_file_information
+		@original_log_file_stat = File.stat(@log_file) rescue nil
+		@current_log_file_stat = @original_log_file_stat
+	end
+	
+	def log_file_has_changed?
+		if @current_log_file_stat
+			stat = File.stat(@log_file) rescue nil
+			if stat
+				result = @current_log_file_stat.mtime != stat.mtime ||
+				         @current_log_file_stat.size  != stat.size
+				@current_log_file_stat = stat
+				return result
+			else
+				return true
+			end
+		else
+			return false
+		end
+	end
+	
+	def differences_in_log_file
+		if @original_log_file_stat
+			File.open(@log_file, 'r') do |f|
+				f.seek(@original_log_file_stat.size, IO::SEEK_SET)
+				return f.read.strip
+			end
+		else
+			return nil
+		end
+	rescue Errno::ENOENT
+		return nil
+	end
+	
+	def determine_lock_file(identifier, pid_file)
+		return File.expand_path(pid_file + ".lock")
+	end
+	
+	def self.fork_supported?
+		return RUBY_PLATFORM != "java" && RUBY_PLATFORM !~ /win32/
+	end
+	
+	def run_command(command)
+		# Create tempfile for storing the command's output.
+		tempfile = Tempfile.new('daemon-output')
+		tempfile_path = tempfile.path
+		File.chmod(0666, tempfile_path)
+		tempfile.close
+		
+		if self.class.fork_supported?
+			pid = safe_fork do
+				STDIN.reopen("/dev/null", "r")
+				STDOUT.reopen(tempfile_path, "w")
+				STDERR.reopen(tempfile_path, "w")
+				exec(command)
+			end
+			begin
+				Process.waitpid(pid) rescue nil
+			rescue Timeout::Error
+				# If the daemon doesn't fork into the background
+				# in time, then kill it.
+				Process.kill('SIGTERM', pid) rescue nil
+				begin
+					Timeout.timeout(5) do
+						Process.waitpid(pid) rescue nil
+					end
+				rescue Timeout::Error
+					Process.kill('SIGKILL', pid)
+					Process.waitpid(pid) rescue nil
+				end
+				raise
+			end
+			if $?.exitstatus != 0
+				raise StartError, File.read(tempfile_path).strip
+			end
+		else
+			if !system("#{command} >\"#{tempfile_path}\" 2>\"#{tempfile_path}\"")
+				raise StartError, File.read(tempfile_path).strip
+			end
+		end
+	ensure
+		File.unlink(tempfile_path) rescue nil
+	end
+	
+	def run_ping_command
+		if @ping_command.respond_to?(:call)
+			return @ping_command.call
+		else
+			return system(@ping_command)
+		end
+	end
+	
+	def safe_fork
+		pid = fork
+		if pid.nil?
+			begin
+				yield
+			rescue Exception => e
+				message = "*** Exception #{e.class} " <<
+					"(#{e}) (process #{$$}):\n" <<
+					"\tfrom " << e.backtrace.join("\n\tfrom ")
+				STDERR.write(e)
+				STDERR.flush
+			ensure
+				exit!
+			end
+		else
+			return pid
+		end
+	end
+end

data/spec/daemon_controller_spec.rb

@@ -0,0 +1,300 @@
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+Dir.chdir(File.dirname(__FILE__))
+require 'daemon_controller'
+require 'benchmark'
+require 'socket'
+
+# A thread which doesn't execute its block until the
+# 'go!' method has been called.
+class WaitingThread < Thread
+	def initialize
+		super do
+			@mutex = Mutex.new
+			@cond = ConditionVariable.new
+			@go = false
+			@mutex.synchronize do
+				while !@go
+					@cond.wait(@mutex)
+				end
+			end
+			yield
+		end
+	end
+	
+	def go!
+		@mutex.synchronize do
+			@go = true
+			@cond.broadcast
+		end
+	end
+end
+
+module TestHelpers
+	def new_controller(options = {})
+		start_command = './echo_server.rb -l echo_server.log -P echo_server.pid'
+		if options[:wait1]
+			start_command << " --wait1 #{options[:wait1]}"
+		end
+		if options[:wait2]
+			start_command << " --wait2 #{options[:wait2]}"
+		end
+		if options[:stop_time]
+			start_command << " --stop-time #{options[:stop_time]}"
+		end
+		if options[:crash_before_bind]
+			start_command << " --crash-before-bind"
+		end
+		new_options = {
+			:identifier    => 'My Test Daemon',
+			:start_command => start_command,
+			:ping_command  => proc do
+				begin
+					TCPSocket.new('localhost', 3230)
+					true
+				rescue SystemCallError
+					false
+				end
+			end,
+			:pid_file      => 'echo_server.pid',
+			:log_file      => 'echo_server.log',
+			:start_timeout => 3,
+			:stop_timeout  => 3
+		}.merge(options)
+		@controller = DaemonController.new(new_options)
+	end
+	
+	def write_file(filename, contents)
+		File.open(filename, 'w') do |f|
+			f.write(contents)
+		end
+	end
+	
+	def exec_is_slow?
+		return RUBY_PLATFORM == "java"
+	end
+end
+
+describe DaemonController, "#start" do
+	before :each do
+		new_controller
+	end
+	
+	include TestHelpers
+	
+	it "works" do
+		@controller.start
+		@controller.stop
+	end
+	
+	it "raises AlreadyStarted if the daemon is already running" do
+		@controller.should_receive(:daemon_is_running?).and_return(true)
+		lambda { @controller.start }.should raise_error(DaemonController::AlreadyStarted)
+	end
+	
+	it "deletes existing PID file before starting the daemon" do
+		write_file('echo_server.pid', '1234')
+		@controller.should_receive(:daemon_is_running?).and_return(false)
+		@controller.should_receive(:spawn_daemon)
+		@controller.should_receive(:pid_file_available?).and_return(true)
+		@controller.should_receive(:run_ping_command).at_least(:once).and_return(true)
+		@controller.start
+		File.exist?('echo_server.pid').should be_false
+	end
+	
+	it "blocks until the daemon has written to its PID file" do
+		thread = WaitingThread.new do
+			sleep 0.15
+			write_file('echo_server.pid', '1234')
+		end
+		@controller.should_receive(:daemon_is_running?).and_return(false)
+		@controller.should_receive(:spawn_daemon).and_return do
+			thread.go!
+		end
+		@controller.should_receive(:run_ping_command).at_least(:once).and_return(true)
+		begin
+			result = Benchmark.measure do
+				@controller.start
+			end
+			(0.15 .. 0.30).should === result.real
+		ensure
+			thread.join
+		end
+	end
+	
+	it "blocks until the daemon can be pinged" do
+		ping_ok = false
+		running = false
+		thread = WaitingThread.new do
+			sleep 0.15
+			ping_ok = true
+		end
+		@controller.should_receive(:daemon_is_running?).at_least(:once).and_return do
+			running
+		end
+		@controller.should_receive(:spawn_daemon).and_return do
+			thread.go!
+			running = true
+		end
+		@controller.should_receive(:pid_file_available?).and_return(true)
+		@controller.should_receive(:run_ping_command).at_least(:once).and_return do
+			ping_ok
+		end
+		begin
+			result = Benchmark.measure do
+				@controller.start
+			end
+			(0.15 .. 0.30).should === result.real
+		ensure
+			thread.join
+		end
+	end
+	
+	it "raises StartTimeout if the daemon doesn't start in time" do
+		if exec_is_slow?
+			start_timeout = 4
+			min_start_timeout = 0
+			max_start_timeout = 6
+		else
+			start_timeout = 0.15
+			max_start_timeout = 0.30
+		end
+		new_controller(:start_command => 'sleep 2', :start_timeout => start_timeout)
+		start_time = Time.now
+		end_time = nil
+		@controller.should_receive(:start_timed_out).and_return do
+			end_time = Time.now
+		end
+		lambda { @controller.start }.should raise_error(DaemonController::StartTimeout)
+		(min_start_timeout .. max_start_timeout).should === end_time - start_time
+	end
+	
+	it "kills the daemon with a signal if the daemon doesn't start in time and there's a PID file" do
+		new_controller(:wait2 => 3, :start_timeout => 1)
+		pid = nil
+		@controller.should_receive(:start_timed_out).and_return do
+			@controller.send(:wait_until) do
+				@controller.send(:pid_file_available?)
+			end
+			pid = @controller.send(:read_pid_file)
+		end
+		lambda { @controller.start }.should raise_error(DaemonController::StartTimeout)
+	end
+	
+	if DaemonController.send(:fork_supported?)
+		it "kills the daemon if it doesn't start in time and hasn't " <<
+		   "forked yet, on platforms where Ruby supports fork()" do
+			new_controller(:start_command => '(echo $$ > echo_server.pid && sleep 5)',
+				:start_timeout => 0.3)
+			lambda { @controller.start }.should raise_error(DaemonController::StartTimeout)
+		end
+	end
+	
+	it "raises an error if the daemon exits with an error before forking" do
+		new_controller(:start_command => 'false')
+		lambda { @controller.start }.should raise_error(DaemonController::Error)
+	end
+	
+	it "raises an error if the daemon exits with an error after forking" do
+		new_controller(:crash_before_bind => true, :log_file_activity_timeout => 0.2)
+		lambda { @controller.start }.should raise_error(DaemonController::Error)
+	end
+	
+	specify "the daemon's error output before forking is made available in the exception" do
+		new_controller(:start_command => '(echo hello world; false)')
+		begin
+			@controller.start
+		rescue DaemonController::Error => e
+			e.message.should == "hello world"
+		end
+	end
+	
+	specify "the daemon's error output after forking is made available in the exception" do
+		new_controller(:crash_before_bind => true, :log_file_activity_timeout => 0.1)
+		begin
+			@controller.start
+			violated
+		rescue DaemonController::StartTimeout => e
+			e.message.should =~ /crashing, as instructed/
+		end
+	end
+end
+
+describe DaemonController, "#stop" do
+	include TestHelpers
+	
+	before :each do
+		new_controller
+	end
+	
+	it "raises no exception if the daemon is not running" do
+		@controller.stop
+	end
+	
+	it "waits until the daemon is no longer running" do
+		new_controller(:stop_time => 0.3)
+		@controller.start
+		result = Benchmark.measure do
+			@controller.stop
+		end
+		@controller.running?.should be_false
+		(0.3 .. 0.5).should === result.real
+	end
+	
+	it "raises StopTimeout if the daemon does not stop in time" do
+		new_controller(:stop_time => 0.3, :stop_timeout => 0.1)
+		@controller.start
+		begin
+			lambda { @controller.stop }.should raise_error(DaemonController::StopTimeout)
+		ensure
+			new_controller.stop
+		end
+	end
+	
+	describe "if stop command was given" do
+		it "raises StopError if the stop command exits with an error" do
+			new_controller(:stop_command => '(echo hello world; false)')
+			begin
+				begin
+					@controller.stop
+					violated
+				rescue DaemonController::StopError => e
+					e.message.should == 'hello world'
+				end
+			ensure
+				new_controller.stop
+			end 
+		end
+		
+		it "makes the stop command's error message available in the exception" do
+		end
+	end
+end
+
+describe DaemonController, "#connect" do
+	include TestHelpers
+	
+	before :each do
+		new_controller
+	end
+	
+	it "starts the daemon if it isn't already running" do
+		socket = @controller.connect do
+			TCPSocket.new('localhost', 3230)
+		end
+		socket.close
+		@controller.stop
+	end
+	
+	it "connects to the existing daemon if it's already running" do
+		@controller.start
+		begin
+			socket = @controller.connect do
+				TCPSocket.new('localhost', 3230)
+			end
+			socket.close
+		ensure
+			@controller.stop
+		end
+	end
+end
+

data/spec/echo_server.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+# A simple echo server, used by the unit test.
+require 'socket'
+require 'optparse'
+
+options = {
+	:port => 3230,
+	:chdir => "/",
+	:log_file => "/dev/null",
+	:wait1 => 0,
+	:wait2 => 0,
+	:stop_time => 0
+}
+parser = OptionParser.new do |opts|
+	opts.banner = "Usage: echo_server.rb [options]"
+	opts.separator ""
+	
+	opts.separator "Options:"
+	opts.on("-p", "--port PORT", Integer, "Port to use. Default: 3230") do |value|
+		options[:port] = value
+	end
+	opts.on("-C", "--change-dir DIR", String, "Change working directory. Default: /") do |value|
+		options[:chdir] = value
+	end
+	opts.on("-l", "--log-file FILENAME", String, "Log file to use. Default: /dev/null") do |value|
+		options[:log_file] = value
+	end
+	opts.on("-P", "--pid-file FILENAME", String, "Pid file to use.") do |value|
+		options[:pid_file] = File.expand_path(value)
+	end
+	opts.on("--wait1 SECONDS", Float, "Wait a few seconds before writing pid file.") do |value|
+		options[:wait1] = value
+	end
+	opts.on("--wait2 SECONDS", Float, "Wait a few seconds before binding server socket.") do |value|
+		options[:wait2] = value
+	end
+	opts.on("--stop-time SECONDS", Float, "Wait a few seconds before exiting.") do |value|
+		options[:stop_time] = value
+	end
+	opts.on("--crash-before-bind", "Whether the daemon should crash before binding the server socket.") do
+		options[:crash_before_bind] = true
+	end
+end
+begin
+	parser.parse!
+rescue OptionParser::ParseError => e
+	puts e
+	puts
+	puts "Please see '--help' for valid options."
+	exit 1
+end
+
+if options[:pid_file]
+	if File.exist?(options[:pid_file])
+		STDERR.puts "*** ERROR: pid file #{options[:pid_file]} exists."
+		exit 1
+	end
+end
+
+pid = fork do
+	Process.setsid
+	fork do
+		STDIN.reopen("/dev/null", 'r')
+		STDOUT.reopen(options[:log_file], 'a')
+		STDERR.reopen(options[:log_file], 'a')
+		STDOUT.sync = true
+		STDERR.sync = true
+		Dir.chdir(options[:chdir])
+		File.umask(0)
+		
+		if options[:pid_file]
+			sleep(options[:wait1])
+			File.open(options[:pid_file], 'w') do |f|
+				f.write(Process.pid)
+			end
+			at_exit do
+				File.unlink(options[:pid_file]) rescue nil
+			end
+		end
+		
+		sleep(options[:wait2])
+		if options[:crash_before_bind]
+			puts "#{Time.now}: crashing, as instructed."
+			exit 2
+		end
+		
+		server = TCPServer.new('localhost', options[:port])
+		begin
+			puts "*** #{Time.now}: echo server started"
+			while (client = server.accept)
+				puts "#{Time.now}: new client"
+				begin
+					while (line = client.readline)
+						puts "#{Time.now}: client sent: #{line.strip}"
+						client.puts(line)
+					end
+				rescue EOFError
+				ensure
+					puts "#{Time.now}: connection closed"
+					client.close rescue nil
+				end
+			end
+		rescue SignalException
+			exit 2
+		rescue => e
+			puts e.to_s
+			puts "    " << e.backtrace.join("\n    ")
+			exit 3
+		ensure
+			puts "*** #{Time.now}: echo server exiting..."
+			sleep(options[:stop_time])
+			puts "*** #{Time.now}: echo server exited"
+		end
+	end
+end
+Process.waitpid(pid)

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: FooBarWidget-daemon_controller
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Hongli Lai
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-21 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A library for implementing daemon management capabilities.
+email: hongli@phusion.nl
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- LICENSE.txt
+- daemon_controller.gemspec
+- lib/daemon_controller.rb
+- spec/daemon_controller_spec.rb
+- spec/echo_server.rb
+has_rdoc: false
+homepage: http://github.com/FooBarWidget/daemon_controller/tree/master
+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 for implementing daemon management capabilities
+test_files: []
+