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
- start_main_loop_thread

Included Modules

- 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 | = | 100
MAX_HEADER_SIZE | = | 128 * 1024
PASSENGER_VERSION | = | determine_passenger_version
PASSENGER_HEADER | = | determine_passenger_header

Attributes

[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] | socket_name | 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.
[R] | socket_type | The type of socket that #socket_name refers to. At the moment, the value is always ‘unix’, which indicates a Unix domain socket.

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.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 132
    132:         def initialize(owner_pipe, options = {})
    133:                 if should_use_unix_sockets?
    134:                         create_unix_socket_on_filesystem
    135:                 else
    136:                         create_tcp_socket
    137:                 end
    138:                 @socket.close_on_exec!
    139:                 @owner_pipe = owner_pipe
    140:                 @previous_signal_handlers = {}
    141:                 @main_loop_thread_lock = Mutex.new
    142:                 @main_loop_thread_cond = ConditionVariable.new
    143:                 @memory_limit = options["memory_limit"] || 0
    144:                 @iterations = 0
    145:                 @processed_requests = 0
    146:         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 155
    155:         def cleanup
    156:                 if @main_loop_thread
    157:                         @main_loop_thread.raise(Interrupt.new("Cleaning up"))
    158:                         @main_loop_thread.join
    159:                 end
    160:                 @socket.close rescue nil
    161:                 @owner_pipe.close rescue nil
    162:                 File.unlink(@socket_name) rescue nil
    163:         end

main_loop()

Enter the request handler‘s main loop.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 171
    171:         def main_loop
    172:                 reset_signal_handlers
    173:                 begin
    174:                         @graceful_termination_pipe = IO.pipe
    175:                         @graceful_termination_pipe[0].close_on_exec!
    176:                         @graceful_termination_pipe[1].close_on_exec!
    177:
    178:                         @main_loop_thread_lock.synchronize do
    179:                                 @main_loop_running = true
    180:                                 @main_loop_thread_cond.broadcast
    181:                         end
    182:
    183:                         install_useful_signal_handlers
    184:
    185:                         while true
    186:                                 @iterations += 1
    187:                                 client = accept_connection
    188:                                 if client.nil?
    189:                                         break
    190:                                 end
    191:                                 begin
    192:                                         headers, input = parse_request(client)
    193:                                         if headers
    194:                                                 if headers[REQUEST_METHOD] == PING
    195:                                                         process_ping(headers, input, client)
    196:                                                 else
    197:                                                         process_request(headers, input, client)
    198:                                                 end
    199:                                         end
    200:                                 rescue IOError, SocketError, SystemCallError => e
    201:                                         print_exception("Passenger RequestHandler", e)
    202:                                 ensure
    203:                                         # 'input' is the same as 'client' so we don't
    204:                                         # need to close that.
    205:                                         client.close rescue nil
    206:                                 end
    207:                                 @processed_requests += 1
    208:                         end
    209:                 rescue EOFError
    210:                         # Exit main loop.
    211:                 rescue Interrupt
    212:                         # Exit main loop.
    213:                 rescue SignalException => signal
    214:                         if signal.message != HARD_TERMINATION_SIGNAL &&
    215:                            signal.message != SOFT_TERMINATION_SIGNAL
    216:                                 raise
    217:                         end
    218:                 ensure
    219:                         @graceful_termination_pipe[0].close rescue nil
    220:                         @graceful_termination_pipe[1].close rescue nil
    221:                         revert_signal_handlers
    222:                         @main_loop_thread_lock.synchronize do
    223:                                 @main_loop_running = false
    224:                                 @main_loop_thread_cond.broadcast
    225:                         end
    226:                 end
    227:         end

main_loop_running?()

Check whether the main loop‘s currently running.

[ show source ]

         # File lib/phusion_passenger/abstract_request_handler.rb, line 166
    166:         def main_loop_running?
    167:                 return @main_loop_running
    168:         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 230
    230:         def start_main_loop_thread
    231:                 @main_loop_thread = Thread.new do
    232:                         main_loop
    233:                 end
    234:                 @main_loop_thread_lock.synchronize do
    235:                         while !@main_loop_running
    236:                                 @main_loop_thread_cond.wait(@main_loop_thread_lock)
    237:                         end
    238:                 end
    239:         end