Class: PhusionPassenger::AbstractRequestHandler

Inherits:

Object
PhusionPassenger::AbstractRequestHandler

Includes:: DebugLogging, Utils

Defined in:: lib/phusion_passenger/abstract_request_handler.rb

Overview

The request handler is the layer which connects Apache with the underlying application’s request dispatcher (i.e. either Rails’s Dispatcher class or Rack). The request handler’s job is to process incoming HTTP requests using the currently loaded Ruby on Rails application. HTTP requests are forwarded to the request handler by the web server. HTTP responses generated by the RoR application are forwarded to the web server, which, in turn, sends the response back to the HTTP client.

AbstractRequestHandler is an abstract base class for easing the implementation of request handlers for Rails and Rack.

Design decisions

Some design decisions are made because we want to decrease system administrator maintenance overhead. These decisions are documented in this section.

Owner pipes

Because only the web server communicates directly with a request handler, we want the request handler to exit if the web server has also exited. This is implemented by using a so-called _owner pipe_. The writable part of the pipe will be passed to the web server* via a Unix socket, and the web server will own that part of the pipe, while AbstractRequestHandler owns the readable part of the pipe. AbstractRequestHandler will continuously check whether the other side of the pipe has been closed. If so, then it knows that the web server has exited, and so the request handler will exit as well. This works even if the web server gets killed by SIGKILL.

It might also be passed to the ApplicationPoolServerExecutable, if the web server’s using ApplicationPoolServer instead of StandardApplicationPool.

Request format

Incoming “HTTP requests” are not true HTTP requests, i.e. their binary representation do not conform to RFC 2616. Instead, the request format is based on CGI, and is similar to that of SCGI.

The format consists of 3 parts:

A 32-bit big-endian integer, containing the size of the transformed headers.
The transformed HTTP headers.
The verbatim (untransformed) HTTP request body.

HTTP headers are transformed to a format that satisfies the following grammar:

headers ::= header*
header ::= name NUL value NUL
name ::= notnull+
value ::= notnull+
notnull ::= "\x01" | "\x02" | "\x02" | ... | "\xFF"
NUL = "\x00"

The web server transforms the HTTP request to the aforementioned format, and sends it to the request handler.

Direct Known Subclasses

ClassicRails::RequestHandler, Rack::RequestHandler

Constant Summary collapse

HARD_TERMINATION_SIGNAL = Signal which will cause the Rails application to exit immediately.

"SIGTERM"

SOFT_TERMINATION_SIGNAL = Signal which will cause the Rails application to exit as soon as it’s done processing a request.

"SIGUSR1"

BACKLOG_SIZE =

MAX_HEADER_SIZE =

128 * 1024

IGNORE = String constants which exist to relieve Ruby’s garbage collector.

'IGNORE'

DEFAULT = :nodoc:

'DEFAULT'

X_POWERED_BY = :nodoc:

'X-Powered-By'

REQUEST_METHOD = :nodoc:

'REQUEST_METHOD'

PING = :nodoc:

'PING'

PASSENGER_CONNECT_PASSWORD = :nodoc:

"PASSENGER_CONNECT_PASSWORD"

OBJECT_SPACE_SUPPORTS_LIVE_OBJECTS = :nodoc:

ObjectSpace.respond_to?(:live_objects)

OBJECT_SPACE_SUPPORTS_ALLOCATED_OBJECTS =

ObjectSpace.respond_to?(:allocated_objects)

OBJECT_SPACE_SUPPORTS_COUNT_OBJECTS =

ObjectSpace.respond_to?(:count_objects)

GC_SUPPORTS_TIME =

GC.respond_to?(:time)

GC_SUPPORTS_CLEAR_STATS =

GC.respond_to?(:clear_stats)

Instance Attribute Summary collapse

#connect_password ⇒ Object

A password with which clients must authenticate.
#iterations ⇒ Object readonly

The number of times the main loop has iterated so far.
#memory_limit ⇒ Object

Specifies the maximum allowed memory usage, in MB.
#processed_requests ⇒ Object readonly

Number of requests processed so far.
#server_sockets ⇒ Object readonly

A hash containing all server sockets that this request handler listens on.
#soft_termination_linger_time ⇒ Object

If a soft termination signal was received, then the main loop will quit the given amount of seconds after the last time a connection was accepted.

Instance Method Summary collapse

#cleanup ⇒ Object

Clean up temporary stuff created by the request handler.
#initialize(owner_pipe, options = {}) ⇒ AbstractRequestHandler constructor

Create a new RequestHandler with the given owner pipe.
#main_loop ⇒ Object

Enter the request handler’s main loop.
#main_loop_running? ⇒ Boolean

Check whether the main loop’s currently running.
#soft_shutdown ⇒ Object

Remove this request handler from the application pool so that no new connections will come in.
#start_main_loop_thread ⇒ Object

Start the main loop in a new thread.

Methods included from Utils

process_is_alive?

Methods included from DebugLogging

_log_device, debug, error, included, log_file=, log_level=, stderr_evaluator=, trace, warn

Constructor Details

#initialize(owner_pipe, options = {}) ⇒ `AbstractRequestHandler`

Create a new RequestHandler with the given owner pipe. owner_pipe must be the readable part of a pipe IO object.

Additionally, the following options may be given:

memory_limit: Used to set the memory_limit attribute.
detach_key
connect_password
pool_account_username
pool_account_password_base64

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 170

def initialize(owner_pipe, options = {})
	@server_sockets = {}
	
	if should_use_unix_sockets?
		@main_socket_address, @main_socket = create_unix_socket_on_filesystem
		@server_sockets[:main] = [@main_socket_address, 'unix', @main_socket]
	else
		@main_socket_address, @main_socket = create_tcp_socket
		@server_sockets[:main] = [@main_socket_address, 'tcp', @main_socket]
	end
	
	@http_socket_address, @http_socket = create_tcp_socket
	@server_sockets[:http] = [@http_socket_address, 'tcp', @http_socket]
	
	@owner_pipe = owner_pipe
	@options = options
	@previous_signal_handlers = {}
	@main_loop_generation  = 0
	@main_loop_thread_lock = Mutex.new
	@main_loop_thread_cond = ConditionVariable.new
	@memory_limit          = options["memory_limit"] || 0
	@connect_password      = options["connect_password"]
	@detach_key            = options["detach_key"]
	@pool_account_username = options["pool_account_username"]
	if options["pool_account_password_base64"]
		@pool_account_password = options["pool_account_password_base64"].unpack('m').first
	end
	@analytics_logger      = options["analytics_logger"]
	@iterations         = 0
	@processed_requests = 0
	@soft_termination_linger_time = 3
	@main_loop_running  = false
	@passenger_header   = determine_passenger_header
	
	@debugger = @options["debugger"]
	if @debugger
		@server_sockets[:ruby_debug_cmd] = ["127.0.0.1:#{Debugger.cmd_port}", 'tcp']
		@server_sockets[:ruby_debug_ctrl] = ["127.0.0.1:#{Debugger.ctrl_port}", 'tcp']
	end
	
	#############
end

Instance Attribute Details

#connect_password ⇒ `Object`

A password with which clients must authenticate. Default is unauthenticated.



159
160
161

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 159

def connect_password
  @connect_password
end

#iterations ⇒ `Object` (readonly)

The number of times the main loop has iterated so far. Mostly useful for unit test assertions.



147
148
149

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 147

def iterations
  @iterations
end

#memory_limit ⇒ `Object`

Specifies the maximum allowed memory usage, in MB. If after having processed a request AbstractRequestHandler detects that memory usage has risen above this limit, then it will gracefully exit (that is, exit after having processed all pending requests).

A value of 0 (the default) indicates that there’s no limit.



143
144
145

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 143

def memory_limit
  @memory_limit
end

#processed_requests ⇒ `Object` (readonly)

Number of requests processed so far. This includes requests that raised exceptions.



151
152
153

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 151

def processed_requests
  @processed_requests
end

#server_sockets ⇒ `Object` (readonly)

A hash containing all server sockets that this request handler listens on. The hash is in the form of:

{
   name1 => [socket_address1, socket_type1, socket1],
   name2 => [socket_address2, socket_type2, socket2],
   ...
}

name is a Symbol. socket_addressx is the address of the socket, socket_typex is the socket’s type (either ‘unix’ or ‘tcp’) and socketx is the actual socket IO objec. There’s guaranteed to be at least one server socket, namely one with the name :main.



135
136
137

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 135

def server_sockets
  @server_sockets
end

#soft_termination_linger_time ⇒ `Object`

If a soft termination signal was received, then the main loop will quit the given amount of seconds after the last time a connection was accepted. Defaults to 3 seconds.



156
157
158

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 156

def soft_termination_linger_time
  @soft_termination_linger_time
end

Instance Method Details

#cleanup ⇒ `Object`

Clean up temporary stuff created by the request handler.

If the main loop was started by #main_loop, then this method may only be called after the main loop has exited.

If the main loop was started by #start_main_loop_thread, then this method may be called at any time, and it will stop the main loop thread.

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 220

def cleanup
	if @main_loop_thread
		@main_loop_thread_lock.synchronize do
			@graceful_termination_pipe[1].close rescue nil
		end
		@main_loop_thread.join
	end
	@server_sockets.each_value do |value|
		address, type, socket = value
		socket.close rescue nil
		if type == 'unix'
			File.unlink(address) rescue nil
		end
	end
	@owner_pipe.close rescue nil
end

#main_loop ⇒ `Object`

Enter the request handler’s main loop.

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 243

def main_loop
	debug("Entering request handler main loop")
	reset_signal_handlers
	begin
		@graceful_termination_pipe = IO.pipe
		@graceful_termination_pipe[0].close_on_exec!
		@graceful_termination_pipe[1].close_on_exec!
		
		@main_loop_thread_lock.synchronize do
			@main_loop_generation += 1
			@main_loop_running = true
			@main_loop_thread_cond.broadcast
			
			@select_timeout = nil
			
			@selectable_sockets = []
			@server_sockets.each_value do |value|
				socket = value[2]
				@selectable_sockets << socket if socket
			end
			@selectable_sockets << @owner_pipe
			@selectable_sockets << @graceful_termination_pipe[0]
		end
		
		install_useful_signal_handlers
		socket_wrapper = Utils::UnseekableSocket.new
		channel        = MessageChannel.new
		buffer         = ''
		
		while true
			@iterations += 1
			if !accept_and_process_next_request(socket_wrapper, channel, buffer)
				trace(2, "Request handler main loop exited normally")
				break
			end
			@processed_requests += 1
		end
	rescue EOFError
		# Exit main loop.
		trace(2, "Request handler main loop interrupted by EOFError exception")
	rescue Interrupt
		# Exit main loop.
		trace(2, "Request handler main loop interrupted by Interrupt exception")
	rescue SignalException => signal
		trace(2, "Request handler main loop interrupted by SignalException")
		if signal.message != HARD_TERMINATION_SIGNAL &&
		   signal.message != SOFT_TERMINATION_SIGNAL
			raise
		end
	rescue Exception => e
		trace(2, "Request handler main loop interrupted by #{e.class} exception")
		raise
	ensure
		debug("Exiting request handler main loop")
		revert_signal_handlers
		@main_loop_thread_lock.synchronize do
			@graceful_termination_pipe[1].close rescue nil
			@graceful_termination_pipe[0].close rescue nil
			@selectable_sockets = []
			@main_loop_generation += 1
			@main_loop_running = false
			@main_loop_thread_cond.broadcast
		end
	end
end

#main_loop_running? ⇒ `Boolean`

Check whether the main loop’s currently running.

Returns:

(Boolean)



238
239
240

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 238

def main_loop_running?
	return @main_loop_running
end

#soft_shutdown ⇒ `Object`

Remove this request handler from the application pool so that no new connections will come in. Then make the main loop quit a few seconds after the last time a connection came in. This all is to ensure that no connections come in while we’re shutting down.

May only be called while the main loop is running. May be called from any thread.

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 333

def soft_shutdown
	@select_timeout = @soft_termination_linger_time
	@graceful_termination_pipe[1].close rescue nil
	if @detach_key && @pool_account_username && @pool_account_password
		client = MessageClient.new(@pool_account_username, @pool_account_password)
		begin
			client.detach(@detach_key)
		ensure
			client.close
		end
	end
end

#start_main_loop_thread ⇒ `Object`

Start the main loop in a new thread. This thread will be stopped by #cleanup.

# File 'lib/phusion_passenger/abstract_request_handler.rb', line 310

def start_main_loop_thread
	current_generation = @main_loop_generation
	@main_loop_thread = Thread.new do
		begin
			main_loop
		rescue Exception => e
			print_exception(self.class, e)
		end
	end
	@main_loop_thread_lock.synchronize do
		while @main_loop_generation == current_generation
			@main_loop_thread_cond.wait(@main_loop_thread_lock)
		end
	end
end

Class: PhusionPassenger::AbstractRequestHandler

Overview

Design decisions

Owner pipes

Request format

Direct Known Subclasses

Constant Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils

Methods included from DebugLogging

Constructor Details

#initialize(owner_pipe, options = {}) ⇒ AbstractRequestHandler

Instance Attribute Details

#connect_password ⇒ Object

#iterations ⇒ Object (readonly)

#memory_limit ⇒ Object

#processed_requests ⇒ Object (readonly)

#server_sockets ⇒ Object (readonly)

#soft_termination_linger_time ⇒ Object