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.
Abstract namespace Unix sockets
AbstractRequestHandler listens on a Unix socket for incoming requests. If possible, AbstractRequestHandler 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, AbstractRequestHandler will automatically fallback to using regular Unix socket files.
It is possible to force AbstractRequestHandler 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. 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:
- 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 | = | 50 |
MAX_HEADER_SIZE | = | 128 * 1024 |
PASSENGER_VERSION | = | determine_passenger_version |
PASSENGER_HEADER | = | determine_passenger_header |
[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? |
Create a new RequestHandler with the given owner pipe. owner_pipe must be the readable part of a pipe IO object.
[ show source ]
# File lib/passenger/abstract_request_handler.rb, line 120 120: def initialize(owner_pipe) 121: if abstract_namespace_sockets_allowed? 122: @using_abstract_namespace = create_unix_socket_on_abstract_namespace 123: else 124: @using_abstract_namespace = false 125: end 126: if !@using_abstract_namespace 127: create_unix_socket_on_filesystem 128: end 129: @socket.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC) 130: @owner_pipe = owner_pipe 131: @previous_signal_handlers = {} 132: end
Clean up temporary stuff created by the request handler. This method should be called after the main loop has exited.
[ show source ]
# File lib/passenger/abstract_request_handler.rb, line 136 136: def cleanup 137: @socket.close rescue nil 138: @owner_pipe.close rescue nil 139: if !using_abstract_namespace? 140: File.unlink(@socket_name) rescue nil 141: end 142: end
Enter the request handler‘s main loop.
[ show source ]
# File lib/passenger/abstract_request_handler.rb, line 150 150: def main_loop 151: reset_signal_handlers 152: begin 153: done = false 154: while !done 155: client = accept_connection 156: if client.nil? 157: break 158: end 159: trap SOFT_TERMINATION_SIGNAL do 160: done = true 161: end 162: begin 163: headers, input = parse_request(client) 164: if headers 165: process_request(headers, input, client) 166: end 167: rescue IOError, SocketError, SystemCallError => e 168: print_exception("Passenger RequestHandler", e) 169: ensure 170: client.close rescue nil 171: end 172: trap SOFT_TERMINATION_SIGNAL, DEFAULT 173: end 174: rescue EOFError 175: # Exit main loop. 176: rescue Interrupt 177: # Exit main loop. 178: rescue SignalException => signal 179: if signal.message != HARD_TERMINATION_SIGNAL && 180: signal.message != SOFT_TERMINATION_SIGNAL 181: raise 182: end 183: ensure 184: revert_signal_handlers 185: end 186: end
Returns whether socket_name refers to an abstract namespace Unix socket.
[ show source ]
# File lib/passenger/abstract_request_handler.rb, line 145 145: def using_abstract_namespace? 146: return @using_abstract_namespace 147: end