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.
| 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_HEADER | = | determine_passenger_header |
| [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. |
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 136
136: def initialize(owner_pipe, options = {})
137: if should_use_unix_sockets?
138: create_unix_socket_on_filesystem
139: else
140: create_tcp_socket
141: end
142: @socket.close_on_exec!
143: @owner_pipe = owner_pipe
144: @previous_signal_handlers = {}
145: @main_loop_generation = 0
146: @main_loop_thread_lock = Mutex.new
147: @main_loop_thread_cond = ConditionVariable.new
148: @memory_limit = options["memory_limit"] || 0
149: @iterations = 0
150: @processed_requests = 0
151: @main_loop_running = false
152: end
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 161
161: def cleanup
162: if @main_loop_thread
163: @main_loop_thread_lock.synchronize do
164: @graceful_termination_pipe[1].close rescue nil
165: end
166: @main_loop_thread.join
167: end
168: @socket.close rescue nil
169: @owner_pipe.close rescue nil
170: File.unlink(@socket_name) rescue nil
171: end
Enter the request handler‘s main loop.
[ show source ]
# File lib/phusion_passenger/abstract_request_handler.rb, line 179
179: def main_loop
180: reset_signal_handlers
181: begin
182: @graceful_termination_pipe = IO.pipe
183: @graceful_termination_pipe[0].close_on_exec!
184: @graceful_termination_pipe[1].close_on_exec!
185:
186: @main_loop_thread_lock.synchronize do
187: @main_loop_generation += 1
188: @main_loop_running = true
189: @main_loop_thread_cond.broadcast
190: end
191:
192: install_useful_signal_handlers
193:
194: while true
195: @iterations += 1
196: client = accept_connection
197: if client.nil?
198: break
199: end
200: begin
201: headers, input = parse_request(client)
202: if headers
203: if headers[REQUEST_METHOD] == PING
204: process_ping(headers, input, client)
205: else
206: process_request(headers, input, client)
207: end
208: end
209: rescue IOError, SocketError, SystemCallError => e
210: print_exception("Passenger RequestHandler", e)
211: ensure
212: # 'input' is the same as 'client' so we don't
213: # need to close that.
214: # The 'close_write' here prevents forked child
215: # processes from unintentionally keeping the
216: # connection open.
217: client.close_write rescue nil
218: client.close rescue nil
219: end
220: @processed_requests += 1
221: end
222: rescue EOFError
223: # Exit main loop.
224: rescue Interrupt
225: # Exit main loop.
226: rescue SignalException => signal
227: if signal.message != HARD_TERMINATION_SIGNAL &&
228: signal.message != SOFT_TERMINATION_SIGNAL
229: raise
230: end
231: ensure
232: revert_signal_handlers
233: @main_loop_thread_lock.synchronize do
234: @graceful_termination_pipe[0].close rescue nil
235: @graceful_termination_pipe[1].close rescue nil
236: @main_loop_generation += 1
237: @main_loop_running = false
238: @main_loop_thread_cond.broadcast
239: end
240: end
241: end
Check whether the main loop‘s currently running.
[ show source ]
# File lib/phusion_passenger/abstract_request_handler.rb, line 174
174: def main_loop_running?
175: return @main_loop_running
176: end
[ show source ]
# File lib/phusion_passenger/abstract_request_handler.rb, line 244
244: def start_main_loop_thread
245: current_generation = @main_loop_generation
246: @main_loop_thread = Thread.new do
247: main_loop
248: end
249: @main_loop_thread_lock.synchronize do
250: while @main_loop_generation == current_generation
251: @main_loop_thread_cond.wait(@main_loop_thread_lock)
252: end
253: end
254: end