Parent

Object

Included Modules

  • Utils

Class Index [+]

Quicksearch

PhusionPassenger::AbstractRequestHandler

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.

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:

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.

Constants

HARD_TERMINATION_SIGNAL

Signal which will cause the Rails application to exit immediately.

SOFT_TERMINATION_SIGNAL

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

BACKLOG_SIZE
MAX_HEADER_SIZE
PASSENGER_HEADER

Attributes

socket_name[R]

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.

socket_type[R]

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

memory_limit[RW]

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.

iterations[R]

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

processed_requests[R]

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

Public Class Methods

new(owner_pipe, options = {}) click to toggle source

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: 

     # File lib/phusion_passenger/abstract_request_handler.rb, line 137
137:         def initialize(owner_pipe, options = {})
138:                 if should_use_unix_sockets?
139:                         create_unix_socket_on_filesystem
140:                 else
141:                         create_tcp_socket
142:                 end
143:                 @socket.close_on_exec!
144:                 @owner_pipe = owner_pipe
145:                 @previous_signal_handlers = {}
146:                 @main_loop_generation  = 0
147:                 @main_loop_thread_lock = Mutex.new
148:                 @main_loop_thread_cond = ConditionVariable.new
149:                 @memory_limit = options["memory_limit"] || 0
150:                 @iterations = 0
151:                 @processed_requests = 0
152:                 @main_loop_running = false
153:         end

Private Class Methods

determine_passenger_header() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 464
464:         def self.determine_passenger_header
465:                 header = "Phusion Passenger (mod_rails/mod_rack) #{VERSION_STRING}"
466:                 if File.exist?("#{File.dirname(__FILE__)}/../../enterprisey.txt") ||
467:                    File.exist?("/etc/passenger_enterprisey.txt")
468:                         header << ", Enterprise Edition"
469:                 end
470:                 return header
471:         end

Public Instance Methods

cleanup() click to toggle source

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 162
162:         def cleanup
163:                 if @main_loop_thread
164:                         @main_loop_thread_lock.synchronize do
165:                                 @graceful_termination_pipe[1].close rescue nil
166:                         end
167:                         @main_loop_thread.join
168:                 end
169:                 @socket.close rescue nil
170:                 @owner_pipe.close rescue nil
171:                 File.unlink(@socket_name) rescue nil
172:         end
main_loop() click to toggle source

Enter the request handler’s main loop. 

     # File lib/phusion_passenger/abstract_request_handler.rb, line 180
180:         def main_loop
181:                 reset_signal_handlers
182:                 begin
183:                         @graceful_termination_pipe = IO.pipe
184:                         @graceful_termination_pipe[0].close_on_exec!
185:                         @graceful_termination_pipe[1].close_on_exec!
186:                         
187:                         @main_loop_thread_lock.synchronize do
188:                                 @main_loop_generation += 1
189:                                 @main_loop_running = true
190:                                 @main_loop_thread_cond.broadcast
191:                         end
192:                         
193:                         install_useful_signal_handlers
194:                         
195:                         while true
196:                                 @iterations += 1
197:                                 client = accept_connection
198:                                 if client.nil?
199:                                         break
200:                                 end
201:                                 begin
202:                                         headers, input = parse_request(client)
203:                                         if headers
204:                                                 if headers[REQUEST_METHOD] == PING
205:                                                         process_ping(headers, input, client)
206:                                                 else
207:                                                         process_request(headers, input, client)
208:                                                 end
209:                                         end
210:                                 rescue IOError, SocketError, SystemCallError => e
211:                                         print_exception("Passenger RequestHandler", e)
212:                                 ensure
213:                                         # 'input' is the same as 'client' so we don't
214:                                         # need to close that.
215:                                         # The 'close_write' here prevents forked child
216:                                         # processes from unintentionally keeping the
217:                                         # connection open.
218:                                         client.close_write rescue nil
219:                                         client.close rescue nil
220:                                 end
221:                                 @processed_requests += 1
222:                         end
223:                 rescue EOFError
224:                         # Exit main loop.
225:                 rescue Interrupt
226:                         # Exit main loop.
227:                 rescue SignalException => signal
228:                         if signal.message != HARD_TERMINATION_SIGNAL &&
229:                            signal.message != SOFT_TERMINATION_SIGNAL
230:                                 raise
231:                         end
232:                 ensure
233:                         revert_signal_handlers
234:                         @main_loop_thread_lock.synchronize do
235:                                 @graceful_termination_pipe[0].close rescue nil
236:                                 @graceful_termination_pipe[1].close rescue nil
237:                                 @main_loop_generation += 1
238:                                 @main_loop_running = false
239:                                 @main_loop_thread_cond.broadcast
240:                         end
241:                 end
242:         end
main_loop_running?() click to toggle source

Check whether the main loop’s currently running. 

     # File lib/phusion_passenger/abstract_request_handler.rb, line 175
175:         def main_loop_running?
176:                 return @main_loop_running
177:         end
start_main_loop_thread() click to toggle source

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

     # File lib/phusion_passenger/abstract_request_handler.rb, line 245
245:         def start_main_loop_thread
246:                 current_generation = @main_loop_generation
247:                 @main_loop_thread = Thread.new do
248:                         main_loop
249:                 end
250:                 @main_loop_thread_lock.synchronize do
251:                         while @main_loop_generation == current_generation
252:                                 @main_loop_thread_cond.wait(@main_loop_thread_lock)
253:                         end
254:                 end
255:         end

Private Instance Methods

accept_connection() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 368
368:         def accept_connection
369:                 ios = select([@socket, @owner_pipe, @graceful_termination_pipe[0]]).first
370:                 if ios.include?(@socket)
371:                         client = @socket.accept
372:                         client.close_on_exec!
373:                         
374:                         # Some people report that sometimes their Ruby (MRI/REE)
375:                         # processes get stuck with 100% CPU usage. Upon further
376:                         # inspection with strace, it turns out that these Ruby
377:                         # processes are continuously calling lseek() on a socket,
378:                         # which of course returns ESPIPE as error. gdb reveals
379:                         # lseek() is called by fwrite(), which in turn is called
380:                         # by rb_fwrite(). The affected socket is the
381:                         # AbstractRequestHandler client socket.
382:                         #
383:                         # I inspected the MRI source code and didn't find
384:                         # anything that would explain this behavior. This makes
385:                         # me think that it's a glibc bug, but that's very
386:                         # unlikely.
387:                         #
388:                         # The rb_fwrite() implementation takes an entirely
389:                         # different code path if I set 'sync' to true: it will
390:                         # skip fwrite() and use write() instead. So here we set
391:                         # 'sync' to true in the hope that this will work around
392:                         # the problem.
393:                         client.sync = true
394:                         
395:                         # We monkeypatch the 'sync=' method to a no-op so that
396:                         # sync mode can't be disabled.
397:                         def client.sync=(value)
398:                         end
399:                         
400:                         # The real input stream is not seekable (calling _seek_
401:                         # or _rewind_ on it will raise an exception). But some
402:                         # frameworks (e.g. Merb) call _rewind_ if the object
403:                         # responds to it. So we simply undefine _seek_ and
404:                         # _rewind_.
405:                         client.instance_eval do
406:                                 undef seek if respond_to?(:seek)
407:                                 undef rewind if respond_to?(:rewind)
408:                         end
409:                         
410:                         # There's no need to set the encoding for Ruby 1.9 because this
411:                         # source file is tagged with 'encoding: binary'.
412:                         
413:                         return client
414:                 else
415:                         # The other end of the owner pipe has been closed, or the
416:                         # graceful termination pipe has been closed. This is our
417:                         # call to gracefully terminate (after having processed all
418:                         # incoming requests).
419:                         return nil
420:                 end
421:         end
create_tcp_socket() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 295
295:         def create_tcp_socket
296:                 # We use "127.0.0.1" as address in order to force
297:                 # TCPv4 instead of TCPv6.
298:                 @socket = TCPServer.new('127.0.0.1', 0)
299:                 @socket.listen(BACKLOG_SIZE)
300:                 @socket_name = "127.0.0.1:#{@socket.addr[1]}"
301:                 @socket_type = "tcp"
302:         end
create_unix_socket_on_filesystem() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 269
269:         def create_unix_socket_on_filesystem
270:                 done = false
271:                 while !done
272:                         begin
273:                                 if defined?(NativeSupport)
274:                                         unix_path_max = NativeSupport::UNIX_PATH_MAX
275:                                 else
276:                                         unix_path_max = 100
277:                                 end
278:                                 @socket_name = "#{passenger_tmpdir}/backends/backend.#{generate_random_id(:base64)}"
279:                                 @socket_name = @socket_name.slice(0, unix_path_max - 1)
280:                                 @socket = UNIXServer.new(@socket_name)
281:                                 @socket.listen(BACKLOG_SIZE)
282:                                 @socket_type = "unix"
283:                                 File.chmod(0600, @socket_name)
284:                                 
285:                                 # The SpawnManager class will set tighter permissions on the
286:                                 # socket later on. See sendSpawnCommand in SpawnManager.h.
287:                                 
288:                                 done = true
289:                         rescue Errno::EADDRINUSE
290:                                 # Do nothing, try again with another name.
291:                         end
292:                 end
293:         end
generate_random_id(method) click to toggle source

Generate a long, cryptographically secure random ID string, which is also a valid filename. 

     # File lib/phusion_passenger/abstract_request_handler.rb, line 449
449:         def generate_random_id(method)
450:                 case method
451:                 when :base64
452:                         require 'base64' unless defined?(Base64)
453:                         data = Base64.encode64(File.read("/dev/urandom", 64))
454:                         data.gsub!("\n", '')
455:                         data.gsub!("+", '')
456:                         data.gsub!("/", '')
457:                         data.gsub!(/==$/, '')
458:                 when :hex
459:                         data = File.read("/dev/urandom", 64).unpack('H*')[0]
460:                 end
461:                 return data
462:         end
install_useful_signal_handlers() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 322
322:         def install_useful_signal_handlers
323:                 trappable_signals = Signal.list_trappable
324:                 
325:                 trap(SOFT_TERMINATION_SIGNAL) do
326:                         @graceful_termination_pipe[1].close rescue nil
327:                 end if trappable_signals.has_key?(SOFT_TERMINATION_SIGNAL.sub(/^SIG/, ''))
328:                 
329:                 trap('ABRT') do
330:                         raise SignalException, "SIGABRT"
331:                 end if trappable_signals.has_key?('ABRT')
332:                 
333:                 trap('QUIT') do
334:                         if Kernel.respond_to?(:caller_for_all_threads)
335:                                 output = "========== Process #{Process.pid}: backtrace dump ==========\n"
336:                                 caller_for_all_threads.each_pair do |thread, stack|
337:                                         output << ("-" * 60) << "\n"
338:                                         output << "# Thread: #{thread.inspect}, "
339:                                         if thread == Thread.main
340:                                                 output << "[main thread], "
341:                                         end
342:                                         if thread == Thread.current
343:                                                 output << "[current thread], "
344:                                         end
345:                                         output << "alive = #{thread.alive?}\n"
346:                                         output << ("-" * 60) << "\n"
347:                                         output << "    " << stack.join("\n    ")
348:                                         output << "\n\n"
349:                                 end
350:                         else
351:                                 output = "========== Process #{Process.pid}: backtrace dump ==========\n"
352:                                 output << ("-" * 60) << "\n"
353:                                 output << "# Current thread: #{Thread.current.inspect}\n"
354:                                 output << ("-" * 60) << "\n"
355:                                 output << "    " << caller.join("\n    ")
356:                         end
357:                         STDERR.puts(output)
358:                         STDERR.flush
359:                 end if trappable_signals.has_key?('QUIT')
360:         end
parse_request(socket) click to toggle source

Read the next request from the given socket, and return a pair [headers, input_stream]. headers is a Hash containing the request headers, while input_stream is an IO object for reading HTTP POST data.

Returns nil if end-of-stream was encountered. 

     # File lib/phusion_passenger/abstract_request_handler.rb, line 429
429:         def parse_request(socket)
430:                 channel = MessageChannel.new(socket)
431:                 headers_data = channel.read_scalar(MAX_HEADER_SIZE)
432:                 if headers_data.nil?
433:                         return
434:                 end
435:                 headers = Hash[*headers_data.split(NULL)]
436:                 return [headers, socket]
437:         rescue SecurityError => e
438:                 STDERR.puts("*** Passenger RequestHandler: HTTP header size exceeded maximum.")
439:                 STDERR.flush
440:                 print_exception("Passenger RequestHandler", e)
441:         end
process_ping(env, input, output) click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 443
443:         def process_ping(env, input, output)
444:                 output.write("pong")
445:         end
reset_signal_handlers() click to toggle source

Reset signal handlers to their default handler, and install some special handlers for a few signals. The previous signal handlers will be put back by calling revert_signal_handlers. 

     # File lib/phusion_passenger/abstract_request_handler.rb, line 307
307:         def reset_signal_handlers
308:                 Signal.list_trappable.each_key do |signal|
309:                         begin
310:                                 prev_handler = trap(signal, DEFAULT)
311:                                 if prev_handler != DEFAULT
312:                                         @previous_signal_handlers[signal] = prev_handler
313:                                 end
314:                         rescue ArgumentError
315:                                 # Signal cannot be trapped; ignore it.
316:                         end
317:                 end
318:                 trap('HUP', IGNORE)
319:                 PhusionPassenger.call_event(:after_installing_signal_handlers)
320:         end
revert_signal_handlers() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 362
362:         def revert_signal_handlers
363:                 @previous_signal_handlers.each_pair do |signal, handler|
364:                         trap(signal, handler)
365:                 end
366:         end
should_use_unix_sockets?() click to toggle source 
     # File lib/phusion_passenger/abstract_request_handler.rb, line 260
260:         def should_use_unix_sockets?
261:                 # There seems to be a bug in MacOS X w.r.t. Unix sockets.
262:                 # When the Unix socket subsystem is under high stress, a
263:                 # recv()/read() on a Unix socket can return 0 even when EOF is
264:                 # not reached. We work around this by using TCP sockets on
265:                 # MacOS X.
266:                 return RUBY_PLATFORM !~ /darwin/
267:         end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.