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 | = | 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) |
[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. |
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
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
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
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
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
[ 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