passenger 1.0.1

data/lib/passenger/abstract_server.rb

@@ -0,0 +1,308 @@
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (C) 2008  Phusion
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation; version 2 of the License.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along
+#  with this program; if not, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require 'socket'
+require 'timeout'
+require 'passenger/message_channel'
+require 'passenger/utils'
+module Passenger
+
+# An abstract base class for a server, with the following properties:
+#
+# - The server has exactly one client, and is connected to that client at all times. The server will
+#   quit when the connection closes.
+# - The server's main loop may be run in a child process (and so is asynchronous from the main process).
+# - One can communicate with the server through discrete messages (as opposed to byte streams).
+# - The server can pass file descriptors (IO objects) back to the client.
+#
+# A message is just an ordered list of strings. The first element in the message is the _message name_.
+#
+# The server will also reset all signal handlers (in the child process). 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 < Passenger::AbstractServer
+#     def initialize
+#        super()
+#        define_message_handler(:hello, :handle_hello)
+#     end
+#
+#     def hello(first_name, last_name)
+#        send_to_server('hello', first_name, last_name)
+#        reply, pointless_number = recv_from_server
+#        puts "The server said: #{reply}"
+#        puts "In addition, it sent this pointless number: #{pointless_number}"
+#     end
+#
+#  private
+#     def handle_hello(first_name, last_name)
+#        send_to_client("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
+	SERVER_TERMINATION_SIGNAL = "SIGTERM"
+
+	# 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
+	
+	def initialize
+		@done = false
+		@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 !@parent_channel.nil?
+			raise ServerAlreadyStarted, "Server is already started"
+		end
+	
+		@parent_socket, @child_socket = UNIXSocket.pair
+		before_fork
+		@pid = fork do
+			begin
+				STDOUT.sync = true
+				STDERR.sync = true
+				@parent_socket.close
+				NativeSupport.close_all_file_descriptors([0, 1, 2, @child_socket.fileno])
+				start_synchronously(@child_socket)
+			rescue Interrupt
+				# Do nothing.
+			rescue SignalException => signal
+				if signal.message == SERVER_TERMINATION_SIGNAL
+					# Do nothing.
+				else
+					print_exception(self.class.to_s, signal)
+				end
+			rescue Exception => e
+				print_exception(self.class.to_s, e)
+			ensure
+				exit!
+			end
+		end
+		@child_socket.close
+		@parent_channel = MessageChannel.new(@parent_socket)
+	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.
+	#
+	# _socket_ is the socket that the server should listen on. The server main
+	# loop will end if the socket has been closed.
+	#
+	# All hooks will be called, except before_fork().
+	def start_synchronously(socket)
+		@child_socket = socket
+		@child_channel = MessageChannel.new(socket)
+		begin
+			reset_signal_handlers
+			initialize_server
+			begin
+				main_loop
+			ensure
+				finalize_server
+			end
+		ensure
+			revert_signal_handlers
+		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 @parent_channel.nil?
+			raise ServerNotStarted, "Server is not started"
+		end
+		
+		@parent_socket.close
+		@parent_channel = nil
+		
+		# Wait at most 5 seconds for server to exit. If it doesn't do that,
+		# we kill it. If that doesn't work either, we kill it forcefully with
+		# SIGKILL.
+		begin
+			Timeout::timeout(3) do
+				Process.waitpid(@pid) rescue nil
+			end
+		rescue Timeout::Error
+			Process.kill(SERVER_TERMINATION_SIGNAL, @pid) rescue nil
+			begin
+				Timeout::timeout(3) do
+					Process.waitpid(@pid) rescue nil
+				end
+			rescue Timeout::Error
+				Process.kill('SIGKILL', @pid) rescue nil
+				Process.waitpid(@pid, Process::WNOHANG) rescue nil
+			end
+		end
+	end
+	
+	# Return the PID of the started server. This is only valid if start() has been called.
+	def server_pid
+		return @pid
+	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
+	
+	# Return the communication channel with the server. This is a MessageChannel
+	# object.
+	#
+	# Raises ServerNotStarted if the server hasn't been started yet.
+	#
+	# This method may only be called in the parent process, and not
+	# in the started server process.
+	def server
+		if @parent_channel.nil?
+			raise ServerNotStarted, "Server hasn't been started yet. Please call start() first."
+		end
+		return @parent_channel
+	end
+	
+	# Return the communication channel with the client (i.e. the parent process
+	# that started the server). This is a MessageChannel object.
+	def client
+		return @child_channel
+	end
+	
+	# Tell the main loop to stop as soon as possible.
+	def quit_main
+		@done = true
+	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.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
+	
+	# The server's main loop. This is called in the child process.
+	# The main loop's main function is to read messages from the socket,
+	# and letting registered message handlers handle each message.
+	# Use define_message_handler() to register a message handler.
+	#
+	# If an unknown message is encountered, UnknownMessage will be raised.
+	def main_loop
+		channel = MessageChannel.new(@child_socket)
+		while !@done
+			begin
+				name, *args = channel.read
+				if name.nil?
+					@done = true
+				elsif @message_handlers.has_key?(name)
+					__send__(@message_handlers[name], *args)
+				else
+					raise UnknownMessage, "Unknown message '#{name}' received."
+				end
+			rescue Interrupt
+				@done = true
+			rescue SignalException => signal
+				if signal.message == SERVER_TERMINATION_SIGNAL
+					@done = true
+				else
+					raise
+				end
+			end
+		end
+	end
+end
+
+end # module Passenger

data/lib/passenger/application.rb

@@ -0,0 +1,120 @@
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (C) 2008  Phusion
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation; version 2 of the License.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along
+#  with this program; if not, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require 'rubygems'
+require 'passenger/utils'
+module Passenger
+
+# Indicates that there is no Ruby on Rails version installed that satisfies
+# a given Ruby on Rails Gem version specification.
+class VersionNotFound < StandardError
+	attr_reader :gem_version_spec
+	
+	# - +message+: The exception message.
+	# - +gem_version_spec+: The Ruby on Rails Gem version specification that caused this error.
+	def initialize(message, gem_version_spec)
+		super(message)
+		@gem_version_spec = gem_version_spec
+	end
+end
+
+# Represents a single Ruby on Rails application instance.
+class Application
+	# The root directory of this application, i.e. the directory that contains
+	# 'app/', 'public/', etc.
+	attr_reader :app_root
+	
+	# The process ID of this application instance.
+	attr_reader :pid
+	
+	# The name of the Unix socket on which the application instance will accept
+	# new connections.
+	attr_reader :listen_socket_name
+	
+	# The owner pipe of the application instance (an IO object). Please see
+	# RequestHandler for a description of the owner pipe.
+	attr_reader :owner_pipe
+
+	# - Returns the Ruby on Rails version that the application requires.
+	# - Returns <tt>:vendor</tt> if the application has a vendored Rails.
+	# - Returns nil if the application doesn't specify a particular version.
+	# Raises VersionNotFound if the required Rails version is not installed.
+	def self.detect_framework_version(app_root)
+		if File.directory?("#{app_root}/vendor/rails/railties")
+			# NOTE: We must check for 'rails/railties' and not just 'rails'.
+			# Typo's vendor directory contains an empty 'rails' directory.
+			return :vendor
+		end
+		
+		environment_rb = File.read("#{app_root}/config/environment.rb")
+		environment_rb =~ /^[^#]*RAILS_GEM_VERSION\s*=\s*["']([!~<>=]*\s*[\d.]+)["']/
+		gem_version_spec = $1
+		if gem_version_spec.nil?
+			return nil
+		end
+		
+		found_version = Gem.cache.search('rails', gem_version_spec).map do |x|
+			x.version.version
+		end.sort.last
+		if found_version.nil?
+			# If this error was reported before, then the cache might be out of
+			# date because the Rails version may have been installed now.
+			# So we reload the RubyGems cache and try again.
+			Gem.clear_paths
+			found_version = Gem.cache.search('rails', gem_version_spec).map do |x|
+				x.version.version
+			end.sort.last
+		end
+		
+		if found_version.nil?
+			raise VersionNotFound.new("There is no Ruby on Rails version " <<
+				"installed that matches version \"#{gem_version_spec}\"",
+				gem_version_spec)
+		else
+			return found_version
+		end
+	end
+
+	# Creates a new instance of Application. The parameters correspond with the attributes
+	# of the same names. No exceptions will be thrown.
+	def initialize(app_root, pid, listen_socket_name, using_abstract_namespace, owner_pipe)
+		@app_root = app_root
+		@pid = pid
+		@listen_socket_name = listen_socket_name
+		@using_abstract_namespace = using_abstract_namespace
+		@owner_pipe = owner_pipe
+	end
+	
+	# Whether _listen_socket_name_ refers to a Unix socket in the abstract namespace.
+	# In any case, _listen_socket_name_ does *not* contain the leading null byte.
+	#
+	# Note that at the moment, only Linux seems to support abstract namespace Unix
+	# sockets.
+	def using_abstract_namespace?
+		return @using_abstract_namespace
+	end
+	
+	# Close the connection with the application instance. If there are no other
+	# processes that have connections to this application instance, then it will
+	# shutdown as soon as possible.
+	#
+	# See also RequestHandler#owner_pipe.
+	def close
+		@owner_pipe.close rescue nil
+	end
+end
+
+end # module Passenger

data/lib/passenger/application_spawner.rb

@@ -0,0 +1,295 @@
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (C) 2008  Phusion
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation; version 2 of the License.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along
+#  with this program; if not, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require 'rubygems'
+require 'socket'
+require 'etc'
+require 'passenger/abstract_server'
+require 'passenger/application'
+require 'passenger/utils'
+require 'passenger/request_handler'
+
+begin
+	# Preload MySQL if possible. We want to preload it and we need
+	# its exception classes.
+	require 'mysql'
+rescue LoadError
+end
+begin
+	# Preload SQLite 3 if possible. Rails 2.0 apps use it by default.
+	require 'sqlite3'
+rescue LoadError
+end
+
+module Passenger
+
+# An abstract base class for AppInitError and FrameworkInitError. This represents
+# the failure when initializing something.
+class InitializationError < StandardError
+	# The exception that caused initialization to fail. This may be nil.
+	attr_accessor :child_exception
+
+	# Create a new InitializationError. +message+ is the error message,
+	# and +child_exception+ is the exception that caused initialization
+	# to fail.
+	def initialize(message, child_exception = nil)
+		super(message)
+		@child_exception = child_exception
+	end
+end
+
+# Raised when ApplicationSpawner, FrameworkSpawner or SpawnManager was unable
+# spawn a Ruby on Rails application, because the application either threw an
+# exception or called exit.
+#
+# If the +child_exception+ attribute is nil, then it means that the application
+# called exit.
+class AppInitError < InitializationError
+end
+
+# This class is capable of spawns instances of a single Ruby on Rails application.
+# It does so by preloading as much of the application's code as possible, then creating
+# instances of the application using what is already preloaded. This makes it spawning
+# application instances very fast, except for the first spawn.
+#
+# Use multiple instances of ApplicationSpawner if you need to spawn multiple different
+# Ruby on Rails applications.
+#
+# *Note*: ApplicationSpawner may only be started asynchronously with AbstractServer#start.
+# Starting it synchronously with AbstractServer#start_synchronously has not been tested.
+class ApplicationSpawner < AbstractServer
+	include Utils
+	
+	# This exception means that the ApplicationSpawner server process exited unexpectedly.
+	class Error < AbstractServer::ServerError
+	end
+	
+	# The user ID of the root user.
+	ROOT_UID = 0
+	# The group ID of the root user.
+	ROOT_GID = 0
+	
+	# An attribute, used internally. This should not be used outside Passenger.
+	attr_accessor :time
+	# The application root of this spawner.
+	attr_reader :app_root
+
+	# +app_root+ is the root directory of this application, i.e. the directory
+	# that contains 'app/', 'public/', etc. If given an invalid directory,
+	# or a directory that doesn't appear to be a Rails application root directory,
+	# then an ArgumentError will be raised.
+	#
+	# If +lower_privilege+ is true, then ApplicationSpawner will attempt to
+	# switch to the user who owns the application's <tt>config/environment.rb</tt>,
+	# and to the default group of that user.
+	#
+	# If that user doesn't exist on the system, or if that user is root,
+	# then ApplicationSpawner will attempt to switch to the username given by
+	# +lowest_user+ (and to the default group of that user).
+	# If +lowest_user+ doesn't exist either, or if switching user failed
+	# (because the current process does not have the privilege to do so),
+	# then ApplicationSpawner will continue without reporting an error.
+	def initialize(app_root, lower_privilege = true, lowest_user = "nobody")
+		super()
+		begin
+			@app_root = normalize_path(app_root)
+		rescue SystemCallError => e
+			raise ArgumentError, e.message
+		rescue ArgumentError
+			raise
+		end
+		@lower_privilege = lower_privilege
+		@lowest_user = lowest_user
+		self.time = Time.now
+		assert_valid_app_root(@app_root)
+		define_message_handler(:spawn_application, :handle_spawn_application)
+	end
+	
+	# Spawn an instance of the RoR application. When successful, an Application object
+	# will be returned, which represents the spawned RoR application.
+	#
+	# Raises:
+	# - AbstractServer::ServerNotStarted: The ApplicationSpawner server hasn't already been started.
+	# - ApplicationSpawner::Error: The ApplicationSpawner server exited unexpectedly.
+	def spawn_application
+		server.write("spawn_application")
+		pid, socket_name, using_abstract_namespace = server.read
+		if pid.nil?
+			raise IOError, "Connection closed"
+		end
+		owner_pipe = server.recv_io
+		return Application.new(@app_root, pid, socket_name,
+			using_abstract_namespace == "true", owner_pipe)
+	rescue SystemCallError, IOError, SocketError => e
+		raise Error, "The application spawner server exited unexpectedly"
+	end
+	
+	# Overrided from AbstractServer#start.
+	#
+	# May raise these additional exceptions:
+	# - AppInitError: The Ruby on Rails application raised an exception
+	#   or called exit() during startup.
+	# - ApplicationSpawner::Error: The ApplicationSpawner server exited unexpectedly.
+	def start
+		super
+		begin
+			status = server.read[0]
+			if status == 'exception'
+				child_exception = unmarshal_exception(server.read_scalar)
+				stop
+				raise AppInitError.new(
+					"Application '#{@app_root}' raised an exception: " <<
+					"#{child_exception.class} (#{child_exception.message})",
+					child_exception)
+			elsif status == 'exit'
+				stop
+				raise AppInitError.new("Application '#{@app_root}' exited during startup")
+			end
+		rescue IOError, SystemCallError, SocketError
+			stop
+			raise Error, "The application spawner server exited unexpectedly"
+		end
+	end
+
+protected
+	# Overrided method.
+	def before_fork # :nodoc:
+		if GC.copy_on_write_friendly?
+			# Garbage collect now so that the child process doesn't have to
+			# do that (to prevent making pages dirty).
+			GC.start
+		end
+	end
+	
+	# Overrided method.
+	def initialize_server # :nodoc:
+		begin
+			$0 = "Passenger ApplicationSpawner: #{@app_root}"
+			Dir.chdir(@app_root)
+			lower_privilege! if @lower_privilege
+			preload_application
+		rescue StandardError, ScriptError, NoMemoryError => e
+			client.write('exception')
+			client.write_scalar(marshal_exception(e))
+			return
+		rescue SystemExit
+			client.write('exit')
+			raise
+		end
+		client.write('success')
+	end
+	
+private
+	def lower_privilege!
+		stat = File.stat("config/environment.rb")
+		begin
+			if !switch_to_user(stat.uid)
+				switch_to_user(@lowest_user)
+			end
+		rescue Errno::EPERM
+			# No problem if we were unable to switch user.
+		end
+	end
+
+	def switch_to_user(user)
+		begin
+			if user.is_a?(String)
+				pw = Etc.getpwnam(user)
+				uid = pw.uid
+				gid = pw.gid
+			else
+				uid = user
+				gid = Etc.getpwuid(uid).gid
+			end
+		rescue
+			return false
+		end
+		if uid == ROOT_UID
+			return false
+		else
+			Process::Sys.setgid(gid)
+			Process::Sys.setuid(uid)
+			return true
+		end
+	end
+
+	def preload_application
+		Object.const_set(:RAILS_ROOT, @app_root)
+		if defined?(Rails::Initializer)
+			Rails::Initializer.run(:set_load_path)
+		end
+		require 'config/environment'
+		ActionController::Base.page_cache_directory = "#{RAILS_ROOT}/public"
+		if defined?(ActionController::Dispatcher) \
+		   && ActionController::Dispatcher.respond_to?(:error_file_path)
+			ActionController::Dispatcher.error_file_path = "#{RAILS_ROOT}/public"
+		end
+		if !defined?(Dispatcher)
+			require 'dispatcher'
+		end
+		require_dependency 'application'
+		Dir.glob('app/{models,controllers,helpers}/*.rb').each do |file|
+			require_dependency normalize_path(file)
+		end
+	end
+
+	def handle_spawn_application
+		# Double fork to prevent zombie processes.
+		pid = fork do
+			begin
+				pid = fork do
+					begin
+						start_request_handler
+					rescue SignalException => signal
+						if e.message != RequestHandler::HARD_TERMINATION_SIGNAL &&
+						   e.message != RequestHandler::SOFT_TERMINATION_SIGNAL
+							print_exception('application', e)
+						end
+					rescue Exception => e
+						print_exception('application', e)
+					ensure
+						exit!
+					end
+				end
+			rescue Exception => e
+				print_exception(self.class.to_s, e)
+			ensure
+				exit!
+			end
+		end
+		Process.waitpid(pid)
+	end
+	
+	def start_request_handler
+		$0 = "Rails: #{@app_root}"
+		reader, writer = IO.pipe
+		begin
+			handler = RequestHandler.new(reader)
+			client.write(Process.pid, handler.socket_name,
+				handler.using_abstract_namespace?)
+			client.send_io(writer)
+			writer.close
+			client.close
+			handler.main_loop
+		ensure
+			client.close rescue nil
+			writer.close rescue nil
+			handler.cleanup rescue nil
+		end
+	end
+end
+
+end # module Passenger