Class
PhusionPassenger::AbstractRequestHandler

In: | lib/phusion_passenger/abstract_request_handler.rb
Parent: | Object

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.

Methods

- cleanup
- main_loop
- main_loop_running?
- new
- soft_shutdown
- start_main_loop_thread

Included Modules

- DebugLogging
- Utils

Constants

HARD_TERMINATION_SIGNAL | = | "SIGTERM"
| Signal which will cause the Rails application to exit immediately.
SOFT_TERMINATION_SIGNAL | = | "SIGUSR1"
| Signal which will cause the Rails application to exit as soon as it‘s done processing a request.
BACKLOG_SIZE | = | 500
MAX_HEADER_SIZE | = | 128 * 1024
OBJECT_SPACE_SUPPORTS_LIVE_OBJECTS | = | 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)

Attributes

[RW] | connect_password | A password with which clients must authenticate. Default is unauthenticated.
[R] | iterations | The number of times the main loop has iterated so far. Mostly useful for unit test assertions.
[RW] | memory_limit | 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.
[R] | processed_requests | Number of requests processed so far. This includes requests that raised exceptions.

[R]

server_sockets

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+.

[RW] | soft_termination_linger_time | 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.

Public Class methods
new(owner_pipe, options = {})

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

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 170
    170:         def initialize(owner_pipe, options = {})
    171:                 @server_sockets = {}
    172:
    173:                 if should_use_unix_sockets?
    174:                         @main_socket_address, @main_socket = create_unix_socket_on_filesystem
    175:                         @server_sockets[:main] = [@main_socket_address, 'unix', @main_socket]
    176:                 else
    177:                         @main_socket_address, @main_socket = create_tcp_socket
    178:                         @server_sockets[:main] = [@main_socket_address, 'tcp', @main_socket]
    179:                 end
    180:
    181:                 @http_socket_address, @http_socket = create_tcp_socket
    182:                 @server_sockets[:http] = [@http_socket_address, 'tcp', @http_socket]
    183:
    184:                 @owner_pipe = owner_pipe
    185:                 @options = options
    186:                 @previous_signal_handlers = {}
    187:                 @main_loop_generation  = 0
    188:                 @main_loop_thread_lock = Mutex.new
    189:                 @main_loop_thread_cond = ConditionVariable.new
    190:                 @memory_limit          = options["memory_limit"] || 0
    191:                 @connect_password      = options["connect_password"]
    192:                 @detach_key            = options["detach_key"]
    193:                 @pool_account_username = options["pool_account_username"]
    194:                 if options["pool_account_password_base64"]
    195:                         @pool_account_password = options["pool_account_password_base64"].unpack('m').first
    196:                 end
    197:                 @analytics_logger      = options["analytics_logger"]
    198:                 @iterations         = 0
    199:                 @processed_requests = 0
    200:                 @soft_termination_linger_time = 3
    201:                 @main_loop_running  = false
    202:                 @passenger_header   = determine_passenger_header
    203:
    204:                 @debugger = @options["debugger"]
    205:                 if @debugger
    206:                         @server_sockets[:ruby_debug_cmd] = ["127.0.0.1:#{Debugger.cmd_port}", 'tcp']
    207:                         @server_sockets[:ruby_debug_ctrl] = ["127.0.0.1:#{Debugger.ctrl_port}", 'tcp']
    208:                 end
    209:
    210:                 #############
    211:         end

Public Instance methods
cleanup()

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.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 220
    220:         def cleanup
    221:                 if @main_loop_thread
    222:                         @main_loop_thread_lock.synchronize do
    223:                                 @graceful_termination_pipe[1].close rescue nil
    224:                         end
    225:                         @main_loop_thread.join
    226:                 end
    227:                 @server_sockets.each_value do |value|
    228:                         address, type, socket = value
    229:                         socket.close rescue nil
    230:                         if type == 'unix'
    231:                                 File.unlink(address) rescue nil
    232:                         end
    233:                 end
    234:                 @owner_pipe.close rescue nil
    235:         end

main_loop()

Enter the request handler‘s main loop.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 243
    243:         def main_loop
    244:                 debug("Entering request handler main loop")
    245:                 reset_signal_handlers
    246:                 begin
    247:                         @graceful_termination_pipe = IO.pipe
    248:                         @graceful_termination_pipe[0].close_on_exec!
    249:                         @graceful_termination_pipe[1].close_on_exec!
    250:
    251:                         @main_loop_thread_lock.synchronize do
    252:                                 @main_loop_generation += 1
    253:                                 @main_loop_running = true
    254:                                 @main_loop_thread_cond.broadcast
    255:
    256:                                 @select_timeout = nil
    257:
    258:                                 @selectable_sockets = []
    259:                                 @server_sockets.each_value do |value|
    260:                                         socket = value[2]
    261:                                         @selectable_sockets << socket if socket
    262:                                 end
    263:                                 @selectable_sockets << @owner_pipe
    264:                                 @selectable_sockets << @graceful_termination_pipe[0]
    265:                         end
    266:
    267:                         install_useful_signal_handlers
    268:                         socket_wrapper = Utils::UnseekableSocket.new
    269:                         channel        = MessageChannel.new
    270:                         buffer         = ''
    271:
    272:                         while true
    273:                                 @iterations += 1
    274:                                 if !accept_and_process_next_request(socket_wrapper, channel, buffer)
    275:                                         trace(2, "Request handler main loop exited normally")
    276:                                         break
    277:                                 end
    278:                                 @processed_requests += 1
    279:                         end
    280:                 rescue EOFError
    281:                         # Exit main loop.
    282:                         trace(2, "Request handler main loop interrupted by EOFError exception")
    283:                 rescue Interrupt
    284:                         # Exit main loop.
    285:                         trace(2, "Request handler main loop interrupted by Interrupt exception")
    286:                 rescue SignalException => signal
    287:                         trace(2, "Request handler main loop interrupted by SignalException")
    288:                         if signal.message != HARD_TERMINATION_SIGNAL &&
    289:                            signal.message != SOFT_TERMINATION_SIGNAL
    290:                                 raise
    291:                         end
    292:                 rescue Exception => e
    293:                         trace(2, "Request handler main loop interrupted by #{e.class} exception")
    294:                         raise
    295:                 ensure
    296:                         debug("Exiting request handler main loop")
    297:                         revert_signal_handlers
    298:                         @main_loop_thread_lock.synchronize do
    299:                                 @graceful_termination_pipe[1].close rescue nil
    300:                                 @graceful_termination_pipe[0].close rescue nil
    301:                                 @selectable_sockets = []
    302:                                 @main_loop_generation += 1
    303:                                 @main_loop_running = false
    304:                                 @main_loop_thread_cond.broadcast
    305:                         end
    306:                 end
    307:         end

main_loop_running?()

Check whether the main loop‘s currently running.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 238
    238:         def main_loop_running?
    239:                 return @main_loop_running
    240:         end

soft_shutdown()

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.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 333
    333:         def soft_shutdown
    334:                 @select_timeout = @soft_termination_linger_time
    335:                 @graceful_termination_pipe[1].close rescue nil
    336:                 if @detach_key && @pool_account_username && @pool_account_password
    337:                         client = MessageClient.new(@pool_account_username, @pool_account_password)
    338:                         begin
    339:                                 client.detach(@detach_key)
    340:                         ensure
    341:                                 client.close
    342:                         end
    343:                 end
    344:         end

start_main_loop_thread()

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

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 310
    310:         def start_main_loop_thread
    311:                 current_generation = @main_loop_generation
    312:                 @main_loop_thread = Thread.new do
    313:                         begin
    314:                                 main_loop
    315:                         rescue Exception => e
    316:                                 print_exception(self.class, e)
    317:                         end
    318:                 end
    319:                 @main_loop_thread_lock.synchronize do
    320:                         while @main_loop_generation == current_generation
    321:                                 @main_loop_thread_cond.wait(@main_loop_thread_lock)
    322:                         end
    323:                 end
    324:         end