Parent

Class/Module 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

BACKLOG_SIZE
GC_SUPPORTS_CLEAR_STATS
GC_SUPPORTS_TIME
HARD_TERMINATION_SIGNAL

Signal which will cause the Rails application to exit immediately.

MAX_HEADER_SIZE
OBJECT_SPACE_SUPPORTS_ALLOCATED_OBJECTS
OBJECT_SPACE_SUPPORTS_COUNT_OBJECTS
OBJECT_SPACE_SUPPORTS_LIVE_OBJECTS
SOFT_TERMINATION_SIGNAL

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

Attributes

connect_password[RW]

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

iterations[R]

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

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.

processed_requests[R]

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

server_sockets[R]

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.

soft_termination_linger_time[RW]

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 = {}) 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 169
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(options["spawn_ipaddress"])
                @server_sockets[:main] = [@main_socket_address, 'tcp', @main_socket]
        end
        
        @http_socket_address, @http_socket = create_tcp_socket(options["spawn_ipaddress"])
        @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

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 219
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() click to toggle source

Enter the request handler's main loop.

# File lib/phusion_passenger/abstract_request_handler.rb, line 242
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?() click to toggle source

Check whether the main loop's currently running.

# File lib/phusion_passenger/abstract_request_handler.rb, line 237
def main_loop_running?
        return @main_loop_running
end
soft_shutdown() click to toggle source

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 332
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() 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 309
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

[Validate]

Generated with the Darkfish Rdoc Generator 2.