daemon_controller 0.2.2

data/lib/daemon_controller/lock_file.rb

@@ -0,0 +1,126 @@
+# daemon_controller, library for robust daemon management
+# Copyright (c) 2008 Phusion
+# 
+# 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.
+
+require 'fcntl'
+
+class DaemonController
+
+# A lock file is a synchronization mechanism, like a Mutex, but it also allows
+# inter-process synchronization (as opposed to only inter-thread synchronization
+# within a single process).
+#
+# Processes can obtain either a shared lock or an exclusive lock. It's possible
+# for multiple processes to obtain a shared lock on a file as long as no
+# exclusive lock has been obtained by a process. If a process has obtained an
+# exclusive lock, then no other processes can lock the file, whether they're
+# trying to obtain a shared lock or an exclusive lock.
+#
+# Note that on JRuby, LockFile can only guarantee synchronization between
+# threads if the different threads use the same LockFile object. Specifying the
+# same filename is not enough.
+class LockFile
+	class AlreadyLocked < StandardError
+	end
+	
+	# Create a LockFile object. The lock file is initially not locked.
+	#
+	# +filename+ may point to a nonexistant file. In that case, the lock
+	# file will not be created until one's trying to obtain a lock.
+	#
+	# Note that LockFile will use this exact filename. So if +filename+
+	# is a relative filename, then the actual lock file that will be used
+	# depends on the current working directory.
+	def initialize(filename)
+		@filename = filename
+	end
+	
+	# Obtain an exclusive lock on the lock file, yield the given block,
+	# then unlock the lockfile. If the lock file was already locked (whether
+	# shared or exclusively) by another process/thread then this method will
+	# block until the lock file has been unlocked.
+	#
+	# The lock file *must* be writable, otherwise an Errno::EACCESS
+	# exception will be raised.
+	def exclusive_lock
+		File.open(@filename, '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
+	
+	# Obtain an exclusive lock on the lock file, yield the given block,
+	# then unlock the lockfile. If the lock file was already exclusively
+	# locked by another process/thread then this method will
+	# block until the exclusive lock has been released. This method will not
+	# block if only shared locks have been obtained.
+	#
+	# The lock file *must* be writable, otherwise an Errno::EACCESS
+	# exception will be raised.
+	def shared_lock
+		File.open(@filename, '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
+	
+	# Try to obtain a shared lock on the lock file, similar to #shared_lock.
+	# But unlike #shared_lock, this method will raise AlreadyLocked if
+	# no lock can be obtained, instead of blocking.
+	#
+	# If a lock can be obtained, then the given block will be yielded.
+	def try_shared_lock
+		File.open(@filename, 'w') do |f|
+			if Fcntl.const_defined? :F_SETFD
+				f.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
+			end
+			if f.flock(File::LOCK_SH | File::LOCK_NB)
+				yield
+			else
+				raise AlreadyLocked
+			end
+		end
+	end
+	
+	# Try to obtain an exclusive lock on the lock file, similar to #exclusive_lock.
+	# But unlike #exclusive_lock, this method will raise AlreadyLocked if
+	# no lock can be obtained, instead of blocking.
+	#
+	# If a lock can be obtained, then the given block will be yielded.
+	def try_exclusive_lock
+		File.open(@filename, 'w') do |f|
+			if Fcntl.const_defined? :F_SETFD
+				f.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
+			end
+			if f.flock(File::LOCK_EX | File::LOCK_NB)
+				yield
+			else
+				raise AlreadyLocked
+			end
+		end
+	end
+end # class LockFile
+end # class DaemonController

data/spec/daemon_controller_spec.rb

@@ -0,0 +1,288 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "test_helper"))
+require 'daemon_controller'
+require 'benchmark'
+require 'socket'
+
+describe DaemonController, "#start" do
+	before :each do
+		new_controller
+	end
+	
+	include TestHelper
+	
+	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('spec/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?('spec/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('spec/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
+			min_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
+		begin
+			lambda { @controller.start }.should raise_error(DaemonController::StartTimeout)
+			(min_start_timeout .. max_start_timeout).should === end_time - start_time
+		ensure
+			@controller.stop
+		end
+	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
+		begin
+			lambda { @controller.start }.should raise_error(DaemonController::StartTimeout)
+		ensure
+			# It's possible that because of a racing condition, the PID
+			# file doesn't get deleted before the next test is run. So
+			# here we ensure that the PID file is gone.
+			File.unlink("spec/echo_server.pid") rescue nil
+		end
+	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 $$ > spec/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 TestHelper
+	
+	before :each do
+		new_controller
+	end
+	
+	after :each do
+		@controller.stop
+	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.should_not be_running
+		(0.3 .. 0.6).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 TestHelper
+	
+	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
+
+describe DaemonController do
+	include TestHelper
+	
+	specify "if the ping command is a block that raises Errno::ECONNREFUSED, then that's " <<
+	        "an indication that the daemon cannot be connected to" do
+		new_controller(:ping_command => lambda do
+			raise Errno::ECONNREFUSED, "dummy"
+		end)
+		@controller.send(:run_ping_command).should be_false
+	end
+	
+	specify "if the ping command is a block that returns an object that responds to #close, " <<
+	        "then the close method will be called on that object" do
+		server = TCPServer.new('localhost', 8278)
+		begin
+			socket = nil
+			new_controller(:ping_command => lambda do
+				socket = TCPSocket.new('localhost', 8278)
+			end)
+			@controller.send(:run_ping_command)
+			socket.should be_closed
+		ensure
+			server.close
+		end
+	end
+	
+	specify "if the ping command is a block that returns an object that responds to #close, " <<
+	        "and #close raises an exception, then that exception is ignored" do
+		server = TCPServer.new('localhost', 8278)
+		begin
+			o = Object.new
+			o.should_receive(:close).and_return do
+				raise StandardError, "foo"
+			end
+			new_controller(:ping_command => lambda do
+				o
+			end)
+			lambda { @controller.send(:run_ping_command) }.should_not raise_error(StandardError)
+		ensure
+			server.close
+		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('127.0.0.1', 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)