Class: PhusionPassenger::AbstractRequestHandler

Inherits:
Object
  • Object
show all
Includes:
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

Rack::RequestHandler, Railz::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 = 
100
MAX_HEADER_SIZE = 
128 * 1024
IGNORE =

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

'IGNORE'
DEFAULT =

:nodoc:

'DEFAULT'
NULL =

:nodoc:

"\0"
X_POWERED_BY =

:nodoc:

'X-Powered-By'
REQUEST_METHOD =

:nodoc:

'REQUEST_METHOD'
PING =

:nodoc:

'ping'
PASSENGER_HEADER = 
determine_passenger_header

Instance Attribute Summary collapse

Instance Method Summary collapse

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.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 137

def initialize(owner_pipe, options = {})
	if should_use_unix_sockets?
		create_unix_socket_on_filesystem
	else
		create_tcp_socket
	end
	@socket.close_on_exec!
	@owner_pipe = owner_pipe
	@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
	@iterations = 0
	@processed_requests = 0
	@main_loop_running = false
end

Instance Attribute Details

#iterations ⇒ Object (readonly)

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



126
127
128
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 126

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.



122
123
124
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 122

def memory_limit
  @memory_limit
end

#processed_requests ⇒ Object (readonly)

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



130
131
132
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 130

def processed_requests
  @processed_requests
end

#socket_name ⇒ Object (readonly)

The name of the socket on which the request handler accepts new connections. At this moment, this value is always the filename of a Unix domain socket.

See also #socket_type.



110
111
112
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 110

def socket_name
  @socket_name
end

#socket_type ⇒ Object (readonly)

The type of socket that #socket_name refers to. At the moment, the value is always ‘unix’, which indicates a Unix domain socket.



114
115
116
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 114

def socket_type
  @socket_type
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.



162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 162

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
	@socket.close rescue nil
	@owner_pipe.close rescue nil
	File.unlink(@socket_name) rescue nil
end

#main_loop ⇒ Object

Enter the request handler’s main loop.



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 180

def 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
		end
		
		install_useful_signal_handlers
		
		while true
			@iterations += 1
			client = accept_connection
			if client.nil?
				break
			end
			begin
				headers, input = parse_request(client)
				if headers
					if headers[REQUEST_METHOD] == PING
						process_ping(headers, input, client)
					else
						process_request(headers, input, client)
					end
				end
			rescue IOError, SocketError, SystemCallError => e
				print_exception("Passenger RequestHandler", e)
			ensure
				# 'input' is the same as 'client' so we don't
				# need to close that.
				# The 'close_write' here prevents forked child
				# processes from unintentionally keeping the
				# connection open.
				client.close_write rescue nil
				client.close rescue nil
			end
			@processed_requests += 1
		end
	rescue EOFError
		# Exit main loop.
	rescue Interrupt
		# Exit main loop.
	rescue SignalException => signal
		if signal.message != HARD_TERMINATION_SIGNAL &&
		   signal.message != SOFT_TERMINATION_SIGNAL
			raise
		end
	ensure
		revert_signal_handlers
		@main_loop_thread_lock.synchronize do
			@graceful_termination_pipe[0].close rescue nil
			@graceful_termination_pipe[1].close rescue nil
			@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) 


175
176
177
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 175

def main_loop_running?
	return @main_loop_running
end

#start_main_loop_thread ⇒ Object

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



245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/phusion_passenger/abstract_request_handler.rb', line 245

def start_main_loop_thread
	current_generation = @main_loop_generation
	@main_loop_thread = Thread.new do
		main_loop
	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