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.

Design decisions

Some design decisions are made because we want to decrease system administrator maintenance overhead. These decisions are documented in this section.

Abstract namespace Unix sockets

RequestHandler listens on a Unix socket for incoming requests. If possible, RequestHandler will try to create a Unix socket on the _abstract namespace_, instead of on the filesystem. If the RoR application crashes (segfault), or if it gets killed by SIGKILL, or if the system loses power, then there will be no stale socket files left on the filesystem. Unfortunately, abstract namespace Unix sockets are only supported by Linux. On systems that do not support abstract namespace Unix sockets, RequestHandler will automatically fallback to using regular Unix socket files.

It is possible to force RequestHandler to use regular Unix socket files by setting the environment variable PASSENGER_NO_ABSTRACT_NAMESPACE_SOCKETS to 1.

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 owned by the web server. RequestHandler 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:

  • 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
Included Modules
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 = 50
MAX_HEADER_SIZE = 128 * 1024
X_POWERED_BY = 'X-Powered-By'
NINJA_PATCHING_LOCK = Mutex.new
PASSENGER_VERSION = $1
PASSENGER_HEADER = "Phusion Passenger (mod_rails) #{PASSENGER_VERSION}"
Attributes
[R] socket_name The name of the socket on which the request handler accepts new connections. This is either a Unix socket filename, or the name for an abstract namespace Unix socket.

If socket_name refers to an abstract namespace Unix socket, then the name does not contain a leading null byte.

See also using_abstract_namespace?

Public Class methods
new(owner_pipe)

Create a new RequestHandler with the given owner pipe. owner_pipe must be the readable part of a pipe IO object.

     # File lib/passenger/request_handler.rb, line 124
124:         def initialize(owner_pipe)
125:                 if ENV['PASSENGER_NO_ABSTRACT_NAMESPACE_SOCKETS'].blank?
126:                         @using_abstract_namespace = create_unix_socket_on_abstract_namespace
127:                 else
128:                         @using_abstract_namespace = false
129:                 end
130:                 if !@using_abstract_namespace
131:                         create_unix_socket_on_filesystem
132:                 end
133:                 @owner_pipe = owner_pipe
134:                 @previous_signal_handlers = {}
135:                 
136:                 NINJA_PATCHING_LOCK.synchronize do
137:                         if !@@ninja_patched_action_controller && defined?(::ActionController::Base) \
138:                         && ::ActionController::Base.private_method_defined?(:perform_action)
139:                                 @@ninja_patched_action_controller = true
140:                                 ::ActionController::Base.class_eval do
141:                                         alias passenger_orig_perform_action perform_action
142:                                         
143:                                         def perform_action(*whatever)
144:                                                 headers[X_POWERED_BY] = PASSENGER_HEADER
145:                                                 passenger_orig_perform_action(*whatever)
146:                                         end
147:                                 end
148:                         end
149:                 end
150:         end
Public Instance methods
cleanup()

Clean up temporary stuff created by the request handler. This method should be called after the main loop has exited.

     # File lib/passenger/request_handler.rb, line 154
154:         def cleanup
155:                 @socket.close rescue nil
156:                 @owner_pipe.close rescue nil
157:                 if !using_abstract_namespace?
158:                         File.unlink(@socket_name) rescue nil
159:                 end
160:         end
main_loop()

Enter the request handler‘s main loop.

     # File lib/passenger/request_handler.rb, line 168
168:         def main_loop
169:                 reset_signal_handlers
170:                 begin
171:                         done = false
172:                         while !done
173:                                 client = accept_connection
174:                                 if client.nil?
175:                                         break
176:                                 end
177:                                 trap SOFT_TERMINATION_SIGNAL do
178:                                         done = true
179:                                 end
180:                                 process_request(client)
181:                                 trap SOFT_TERMINATION_SIGNAL, DEFAULT
182:                         end
183:                 rescue EOFError
184:                         # Exit main loop.
185:                 rescue Interrupt
186:                         # Exit main loop.
187:                 rescue SignalException => signal
188:                         if signal.message != HARD_TERMINATION_SIGNAL &&
189:                            signal.message != SOFT_TERMINATION_SIGNAL
190:                                 raise
191:                         end
192:                 ensure
193:                         revert_signal_handlers
194:                 end
195:         end
perform_action(*whatever)
     # File lib/passenger/request_handler.rb, line 143
143:                                         def perform_action(*whatever)
144:                                                 headers[X_POWERED_BY] = PASSENGER_HEADER
145:                                                 passenger_orig_perform_action(*whatever)
146:                                         end
using_abstract_namespace?()

Returns whether socket_name refers to an abstract namespace Unix socket.

     # File lib/passenger/request_handler.rb, line 163
163:         def using_abstract_namespace?
164:                 return @using_abstract_namespace
165:         end