passenger_dudemeister 3.0.1

data/lib/phusion_passenger/abstract_server.rb

@@ -0,0 +1,372 @@
+# encoding: binary
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (c) 2010 Phusion
+#
+#  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
+#
+#  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 'socket'
+require 'phusion_passenger/message_channel'
+require 'phusion_passenger/utils'
+require 'phusion_passenger/utils/tmpdir'
+require 'phusion_passenger/native_support'
+
+module PhusionPassenger
+
+# An abstract base class for a server that has the following properties:
+#
+# - The server listens on a password protected Unix socket.
+# - The server is multithreaded and handles one client per thread.
+# - The server is owned by one or more processes. If all processes close their
+#   reference to the server, then the server will quit.
+# - The server's main loop may be run in a child process (and so is asynchronous
+#   from the parent process).
+# - One can communicate with the server through discrete MessageChannel messages,
+#   as opposed to byte streams.
+# - The server can pass file descriptors (IO objects) back to the client.
+#
+# The server will also reset all signal handlers. That is, it will respond to
+# all signals in the default manner. The only exception is SIGHUP, which is
+# ignored. One may define additional signal handlers using define_signal_handler().
+#
+# Before an AbstractServer can be used, it must first be started by calling start().
+# When it is no longer needed, stop() should be called.
+#
+# Here's an example on using AbstractServer:
+#
+#  class MyServer < PhusionPassenger::AbstractServer
+#     def initialize
+#        super()
+#        define_message_handler(:hello, :handle_hello)
+#     end
+#     
+#     def hello(first_name, last_name)
+#        connect do |channel|
+#           channel.write('hello', first_name, last_name)
+#           reply, pointless_number = channel.read
+#           puts "The server said: #{reply}"
+#           puts "In addition, it sent this pointless number: #{pointless_number}"
+#        end
+#     end
+#  
+#  private
+#     def handle_hello(channel, first_name, last_name)
+#        channel.write("Hello #{first_name} #{last_name}, how are you?", 1234)
+#     end
+#  end
+#  
+#  server = MyServer.new
+#  server.start
+#  server.hello("Joe", "Dalton")
+#  server.stop
+class AbstractServer
+	include Utils
+
+	# Raised when the server receives a message with an unknown message name.
+	class UnknownMessage < StandardError
+	end
+	
+	# Raised when a command is invoked that requires that the server is
+	# not already started.
+	class ServerAlreadyStarted < StandardError
+	end
+	
+	# Raised when a command is invoked that requires that the server is
+	# already started.
+	class ServerNotStarted < StandardError
+	end
+	
+	# This exception means that the server process exited unexpectedly.
+	class ServerError < StandardError
+	end
+	
+	class InvalidPassword < StandardError
+	end
+	
+	attr_reader :password
+	attr_accessor :ignore_password_errors
+	
+	# The maximum time that this AbstractServer may be idle. Used by
+	# AbstractServerCollection to determine when this object should
+	# be cleaned up. nil or 0 indicate that this object should never
+	# be idle cleaned.
+	attr_accessor :max_idle_time
+	
+	# Used by AbstractServerCollection to remember when this AbstractServer
+	# should be idle cleaned.
+	attr_accessor :next_cleaning_time
+	
+	def initialize(socket_filename = nil, password = nil)
+		@socket_filename = socket_filename
+		@password = password
+		@socket_filename ||= "#{passenger_tmpdir}/spawn-server/socket.#{Process.pid}.#{object_id}"
+		@password ||= generate_random_id(:base64)
+		
+		@message_handlers = {}
+		@signal_handlers = {}
+		@orig_signal_handlers = {}
+	end
+	
+	# Start the server. This method does not block since the server runs
+	# asynchronously from the current process.
+	#
+	# You may only call this method if the server is not already started.
+	# Otherwise, a ServerAlreadyStarted will be raised.
+	#
+	# Derived classes may raise additional exceptions.
+	def start
+		if started?
+			raise ServerAlreadyStarted, "Server is already started"
+		end
+		
+		a, b = UNIXSocket.pair
+		File.unlink(@socket_filename) rescue nil
+		server_socket = UNIXServer.new(@socket_filename)
+		File.chmod(0700, @socket_filename)
+		
+		before_fork
+		@pid = fork
+		if @pid.nil?
+			has_exception = false
+			begin
+				STDOUT.sync = true
+				STDERR.sync = true
+				a.close
+				
+				# During Passenger's early days, we used to close file descriptors based
+				# on a white list of file descriptors. That proved to be way too fragile:
+				# too many file descriptors are being left open even though they shouldn't
+				# be. So now we close file descriptors based on a black list.
+				#
+				# Note that STDIN, STDOUT and STDERR may be temporarily set to
+				# different file descriptors than 0, 1 and 2, e.g. in unit tests.
+				# We don't want to close these either.
+				file_descriptors_to_leave_open = [0, 1, 2,
+					b.fileno, server_socket.fileno,
+					fileno_of(STDIN), fileno_of(STDOUT), fileno_of(STDERR)
+				].compact.uniq
+				NativeSupport.close_all_file_descriptors(file_descriptors_to_leave_open)
+				# In addition to closing the file descriptors, one must also close
+				# the associated IO objects. This is to prevent IO.close from
+				# double-closing already closed file descriptors.
+				close_all_io_objects_for_fds(file_descriptors_to_leave_open)
+				
+				# At this point, RubyGems might have open file handles for which
+				# the associated file descriptors have just been closed. This can
+				# result in mysterious 'EBADFD' errors. So we force RubyGems to
+				# clear all open file handles.
+				Gem.clear_paths
+				
+				# Reseed pseudo-random number generator for security reasons.
+				srand
+				
+				start_synchronously(@socket_filename, @password, server_socket, b)
+			rescue Interrupt
+				# Do nothing.
+				has_exception = true
+			rescue Exception => e
+				has_exception = true
+				print_exception(self.class.to_s, e)
+			ensure
+				exit!(has_exception ? 1 : 0)
+			end
+		end
+		server_socket.close
+		b.close
+		@owner_socket = a
+	end
+	
+	# Start the server, but in the current process instead of in a child process.
+	# This method blocks until the server's main loop has ended.
+	#
+	# All hooks will be called, except before_fork().
+	def start_synchronously(socket_filename, password, server_socket, owner_socket)
+		@owner_socket = owner_socket
+		begin
+			reset_signal_handlers
+			initialize_server
+			begin
+				server_main_loop(password, server_socket)
+			ensure
+				finalize_server
+			end
+		rescue Interrupt
+			# Do nothing
+		ensure
+			@owner_socket = nil
+			revert_signal_handlers
+			File.unlink(socket_filename) rescue nil
+			server_socket.close
+		end
+	end
+	
+	# Stop the server. The server will quit as soon as possible. This method waits
+	# until the server has been stopped.
+	#
+	# When calling this method, the server must already be started. If not, a
+	# ServerNotStarted will be raised.
+	def stop
+		if !started?
+			raise ServerNotStarted, "Server is not started"
+		end
+		
+		begin
+			@owner_socket.write("x")
+		rescue Errno::EPIPE
+		end
+		@owner_socket.close
+		@owner_socket = nil
+		File.unlink(@socket_filename) rescue nil
+		
+		# Wait at most 4 seconds for server to exit. If it doesn't do that,
+		# we kill it forcefully with SIGKILL.
+		if !Process.timed_waitpid(@pid, 4)
+			Process.kill('SIGKILL', @pid) rescue nil
+			Process.timed_waitpid(@pid, 1)
+		end
+	end
+	
+	# Return whether the server has been started.
+	def started?
+		return !!@owner_socket
+	end
+	
+	# Return the PID of the started server. This is only valid if #start has been called.
+	def server_pid
+		return @pid
+	end
+	
+	# Connects to the server and yields a channel for communication.
+	# The first message's name must match a handler name. The connection can only
+	# be used for a single handler cycle; after the handler is done, the connection
+	# will be closed.
+	#
+	#   server.connect do |channel|
+	#      channel.write("a message")
+	#      ...
+	#   end
+	#
+	# Raises: SystemCallError, IOError, SocketError
+	def connect
+		channel = MessageChannel.new(UNIXSocket.new(@socket_filename))
+		begin
+			channel.write_scalar(@password)
+			yield channel
+		ensure
+			channel.close
+		end
+	end
+
+protected
+	# A hook which is called when the server is being started, just before forking a new process.
+	# The default implementation does nothing, this method is supposed to be overrided by child classes.
+	def before_fork
+	end
+	
+	# A hook which is called when the server is being started. This is called in the child process,
+	# before the main loop is entered.
+	# The default implementation does nothing, this method is supposed to be overrided by child classes.
+	def initialize_server
+	end
+	
+	# A hook which is called when the server is being stopped. This is called in the child process,
+	# after the main loop has been left.
+	# The default implementation does nothing, this method is supposed to be overrided by child classes.
+	def finalize_server
+	end
+	
+	# Define a handler for a message. _message_name_ is the name of the message to handle,
+	# and _handler_ is the name of a method to be called (this may either be a String or a Symbol).
+	#
+	# A message is just a list of strings, and so _handler_ will be called with the message as its
+	# arguments, excluding the first element. See also the example in the class description.
+	def define_message_handler(message_name, handler)
+		@message_handlers[message_name.to_s] = handler
+	end
+	
+	# Define a handler for a signal.
+	def define_signal_handler(signal, handler)
+		@signal_handlers[signal.to_s] = handler
+	end
+	
+	def fileno_of(io)
+		return io.fileno
+	rescue
+		return nil
+	end
+
+private
+	# Reset all signal handlers to default. This is called in the child process,
+	# before entering the main loop.
+	def reset_signal_handlers
+		Signal.list_trappable.each_key do |signal|
+			begin
+				@orig_signal_handlers[signal] = trap(signal, 'DEFAULT')
+			rescue ArgumentError
+				# Signal cannot be trapped; ignore it.
+			end
+		end
+		@signal_handlers.each_pair do |signal, handler|
+			trap(signal) do
+				__send__(handler)
+			end
+		end
+		trap('HUP', 'IGNORE')
+	end
+	
+	def revert_signal_handlers
+		@orig_signal_handlers.each_pair do |signal, handler|
+			trap(signal, handler)
+		end
+		@orig_signal_handlers.clear
+	end
+	
+	def server_main_loop(password, server_socket)
+		while true
+			ios = select([@owner_socket, server_socket]).first
+			if ios.include?(server_socket)
+				client_socket = server_socket.accept
+				begin
+					client = MessageChannel.new(client_socket)
+					
+					client_password = client.read_scalar
+					if client_password != password
+						next
+					end
+					
+					name, *args = client.read
+					if name
+						if @message_handlers.has_key?(name)
+							__send__(@message_handlers[name], client, *args)
+						else
+							raise UnknownMessage, "Unknown message '#{name}' received."
+						end
+					end
+				ensure
+					client_socket.close
+				end
+			else
+				break
+			end
+		end
+	end
+end
+
+end # module PhusionPassenger

data/lib/phusion_passenger/abstract_server_collection.rb

@@ -0,0 +1,335 @@
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (c) 2010 Phusion
+#
+#  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
+#
+#  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 'phusion_passenger/utils'
+
+module PhusionPassenger
+
+# This class maintains a collection of AbstractServer objects. One can add new
+# AbstractServer objects, or look up existing ones via a key.
+# AbstractServerCollection also automatically takes care of cleaning up
+# AbstractServers that have been idle for too long.
+#
+# This class exists because both SpawnManager and ClassicRails::FrameworkSpawner need this kind
+# of functionality. SpawnManager maintains a collection of ClassicRails::FrameworkSpawner
+# and ClassicRails::ApplicationSpawner objects, while ClassicRails::FrameworkSpawner maintains a
+# collection of ClassicRails::ApplicationSpawner objects.
+#
+# This class is thread-safe as long as the specified thread-safety rules are followed.
+class AbstractServerCollection
+	attr_reader :next_cleaning_time
+	
+	include Utils
+	
+	def initialize
+		@collection = {}
+		@lock = Mutex.new
+		@cleanup_lock = Mutex.new
+		@cond = ConditionVariable.new
+		@done = false
+		
+		# The next time the cleaner thread should check for idle servers.
+		# The value may be nil, in which case the value will be calculated
+		# at the end of the #synchronized block.
+		#
+		# Invariant:
+		#    if value is not nil:
+		#       There exists an s in @collection with s.next_cleaning_time == value.
+		#       for all s in @collection:
+		#          if eligable_for_cleanup?(s):
+		#             s.next_cleaning_time <= value
+		@next_cleaning_time = Time.now + 60 * 60
+		@next_cleaning_time_changed = false
+		
+		@cleaner_thread = Thread.new do
+			begin
+				@lock.synchronize do
+					cleaner_thread_main
+				end
+			rescue Exception => e
+				print_exception(self.class.to_s, e)
+			end
+		end
+	end
+	
+	# Acquire the lock for this AbstractServerCollection object, and run
+	# the code within the block. The entire block will be a single atomic
+	# operation.
+	def synchronize
+		@lock.synchronize do
+			@in_synchronize_block = true
+			begin
+				yield
+			ensure
+				if @next_cleaning_time.nil?
+					@collection.each_value do |server|
+						if @next_cleaning_time.nil? ||
+						   (eligable_for_cleanup?(server) &&
+						    server.next_cleaning_time < @next_cleaning_time
+						   )
+							@next_cleaning_time = server.next_cleaning_time
+						end
+					end
+					if @next_cleaning_time.nil?
+						# There are no servers in the collection with an idle timeout.
+						@next_cleaning_time = Time.now + 60 * 60
+					end
+					@next_cleaning_time_changed = true
+				end
+				if @next_cleaning_time_changed
+					@next_cleaning_time_changed = false
+					@cond.signal
+				end
+				@in_synchronize_block = false
+			end
+		end
+	end
+	
+	# Lookup and returns an AbstractServer with the given key.
+	#
+	# If there is no AbstractSerer associated with the given key, then the given
+	# block will be called. That block must return an AbstractServer object. Then,
+	# that object will be stored in the collection, and returned.
+	#
+	# The block must set the 'max_idle_time' attribute on the AbstractServer.
+	# AbstractServerCollection's idle cleaning interval will be adapted to accomodate
+	# with this. Changing the value outside this block is not guaranteed to have any
+	# effect on the idle cleaning interval.
+	# A max_idle_time value of nil or 0 means the AbstractServer will never be idle cleaned.
+	#
+	# If the block raises an exception, then the collection will not be modified,
+	# and the exception will be propagated.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def lookup_or_add(key)
+		raise ArgumentError, "cleanup() has already been called." if @done
+		must_be_in_synchronize_block
+		server = @collection[key]
+		if server
+			register_activity(server)
+			return server
+		else
+			server = yield
+			if !server.respond_to?(:start)
+				raise TypeError, "The block didn't return a valid AbstractServer object."
+			end
+			if eligable_for_cleanup?(server)
+				server.next_cleaning_time = Time.now + server.max_idle_time
+				if @next_cleaning_time && server.next_cleaning_time < @next_cleaning_time
+					@next_cleaning_time = server.next_cleaning_time
+					@next_cleaning_time_changed = true
+				end
+			end
+			@collection[key] = server
+			return server
+		end
+	end
+	
+	# Checks whether there's an AbstractServer object associated with the given key.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def has_key?(key)
+		must_be_in_synchronize_block
+		return @collection.has_key?(key)
+	end
+	
+	# Checks whether the collection is empty.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def empty?
+		must_be_in_synchronize_block
+		return @collection.empty?
+	end
+	
+	# Deletes from the collection the AbstractServer that's associated with the
+	# given key. If no such AbstractServer exists, nothing will happen.
+	#
+	# If the AbstractServer is started, then it will be stopped before deletion.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def delete(key)
+		raise ArgumentError, "cleanup() has already been called." if @done
+		must_be_in_synchronize_block
+		server = @collection[key]
+		if server
+			if server.started?
+				server.stop
+			end
+			@collection.delete(key)
+			if server.next_cleaning_time == @next_cleaning_time
+				@next_cleaning_time = nil
+			end
+		end
+	end
+	
+	# Notify this AbstractServerCollection that +server+ has performed an activity.
+	# This AbstractServerCollection will update the idle information associated with +server+
+	# accordingly.
+	#
+	# lookup_or_add already automatically updates idle information, so you only need to
+	# call this method if the time at which the server has performed an activity is
+	# not close to the time at which lookup_or_add had been called.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def register_activity(server)
+		must_be_in_synchronize_block
+		if eligable_for_cleanup?(server)
+			if server.next_cleaning_time == @next_cleaning_time
+				@next_cleaning_time = nil
+			end
+			server.next_cleaning_time = Time.now + server.max_idle_time
+		end
+	end
+	
+	# Tell the cleaner thread to check the collection as soon as possible, instead
+	# of sleeping until the next scheduled cleaning time.
+	#
+	# Precondition: this method must NOT be called within a #synchronize block.
+	def check_idle_servers!
+		must_not_be_in_synchronize_block
+		@lock.synchronize do
+			@next_cleaning_time = Time.now - 60 * 60
+			@cond.signal
+		end
+	end
+	
+	# Iterate over all AbstractServer objects.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def each
+		must_be_in_synchronize_block
+		each_pair do |key, server|
+			yield server
+		end
+	end
+	
+	# Iterate over all keys and associated AbstractServer objects.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def each_pair
+		raise ArgumentError, "cleanup() has already been called." if @done
+		must_be_in_synchronize_block
+		@collection.each_pair do |key, server|
+			yield(key, server)
+		end
+	end
+	
+	# Delete all AbstractServers from the collection. Each AbstractServer will be
+	# stopped, if necessary.
+	#
+	# Precondition: this method must be called within a #synchronize block.
+	def clear
+		must_be_in_synchronize_block
+		@collection.each_value do |server|
+			if server.started?
+				server.stop
+			end
+		end
+		@collection.clear
+		@next_cleaning_time = nil
+	end
+	
+	# Cleanup all resources used by this AbstractServerCollection. All AbstractServers
+	# from the collection will be deleted. Each AbstractServer will be stopped, if
+	# necessary. The background thread which removes idle AbstractServers will be stopped.
+	#
+	# After calling this method, this AbstractServerCollection object will become
+	# unusable.
+	#
+	# Precondition: this method must *NOT* be called within a #synchronize block.
+	def cleanup
+		must_not_be_in_synchronize_block
+		@cleanup_lock.synchronize do
+			return if @done
+			@lock.synchronize do
+				@done = true
+				@cond.signal
+			end
+			@cleaner_thread.join
+			synchronize do
+				clear
+			end
+		end
+	end
+
+private
+	def cleaner_thread_main
+		while !@done
+			current_time = Time.now
+			# We add a 0.2 seconds delay to the sleep time because system
+			# timers are not entirely accurate.
+			sleep_time = (@next_cleaning_time - current_time).to_f + 0.2
+			if sleep_time > 0 && @cond.timed_wait(@lock, sleep_time)
+				next
+			else
+				keys_to_delete = nil
+				@next_cleaning_time = nil
+				@collection.each_pair do |key, server|
+					if eligable_for_cleanup?(server)
+						# Cleanup this server if its idle timeout has expired.
+						if server.next_cleaning_time <= current_time
+							keys_to_delete ||= []
+							keys_to_delete << key
+							if server.started?
+								server.stop
+							end
+						# If not, then calculate the next cleaning time because
+						# we're iterating the collection anyway.
+						elsif @next_cleaning_time.nil? ||
+						      server.next_cleaning_time < @next_cleaning_time
+							@next_cleaning_time = server.next_cleaning_time
+						end
+					end
+				end
+				if keys_to_delete
+					keys_to_delete.each do |key|
+						@collection.delete(key)
+					end
+				end
+				if @next_cleaning_time.nil?
+					# There are no servers in the collection with an idle timeout.
+					@next_cleaning_time = Time.now + 60 * 60
+				end
+			end
+		end
+	end
+	
+	# Checks whether the given server is eligible for being idle cleaned.
+	def eligable_for_cleanup?(server)
+		return server.max_idle_time && server.max_idle_time != 0
+	end
+	
+	def must_be_in_synchronize_block
+		if !@in_synchronize_block
+			raise RuntimeError, "This method may only be called within a #synchronize block!"
+		end
+	end
+	
+	def must_not_be_in_synchronize_block
+		if @in_synchronize_block
+			raise RuntimeError, "This method may NOT be called within a #synchronize block!"
+		end
+	end
+end
+
+end # module PhusionPassenger