0N/A<!
DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 0N/A <
title>Request Processing in Apache 2.0</
title>
0N/A <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 0N/A <
body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 0N/A vlink="#000080" alink="#FF0000">
0N/A <
h1>Request Processing in Apache 2.0</
h1>
0N/A <
p>Warning - this is a first (fast) draft that needs further
2362N/A <
p>Several changes in Apache 2.0 affect the internal request
2362N/A processing mechanics. Module authors need to be aware of these
2362N/A changes so they may take advantage of the optimizations and
0N/A security enhancements.</
p>
0N/A <
p>The first major change is to the subrequest and redirect
0N/A mechanisms. There were a number of different code paths in
0N/A Apache 1.3 to attempt to optimize subrequest or redirect
0N/A behavior. As patches were introduced to 2.0, these
0N/A optimizations (and the server behavior) were quickly broken due
0N/A to this duplication of code. All duplicate code has been folded
0N/A back into <
code>ap_process_internal_request()</
code> to prevent
4124N/A the code from falling out of sync again.</
p>
0N/A <
p>This means that much of the existing code was 'unoptimized'.
0N/A It is the Apache HTTP Project's first goal to create a robust
0N/A and correct implementation of the HTTP server RFC. Additional
0N/A goals include security, scalability and optimization. New
0N/A methods were sought to optimize the server (beyond the
0N/A performance of Apache 1.3) without introducing fragile or
0N/A <
h2>The Request Processing Cycle</
h2>
0N/A <
p>All requests pass through
0N/A including subrequests and redirects. If a module doesn't pass
0N/A generated requests through this code, the author is cautioned
0N/A that the module may be broken by future changes to request
0N/A <
p>To streamline requests, the module author can take advantage
0N/A of the hooks offered to drop out of the request cycle early, or
0N/A to bypass core Apache hooks which are irrelevant (and costly in
0N/A <
h2>The Request Parsing Phase</
h2>
0N/A <
h3>Unescapes the URL</
h3>
0N/A <
p>The request's parsed_uri path is unescaped, once and only
0N/A once, at the beginning of internal request processing.</
p>
0N/A <
p>This step is bypassed if the proxyreq flag is set, or the
0N/A control of this one-time unescape operation, either failing to
0N/A unescape or multiply unescaping the URL leads to security
0N/A <
h3>Strips Parent and This Elements from the URI</
h3>
0N/A <
p>All <
code>/../</
code> and <
code>/./</
code> elements are
0N/A removed by <
code>ap_getparents()</
code>. This helps to ensure
0N/A the path is (nearly) absolute before the request processing
0N/A <
p>This step cannot be bypassed.</
p>
0N/A <
h3>Initial URI Location Walk</
h3>
0N/A <
p>Every request is subject to an
0N/A <
code>ap_location_walk()</
code> call. This ensures that
0N/A <Location > sections are consistently enforced for all
0N/A requests. If the request is an internal redirect or a
0N/A sub-request, it may borrow some or all of the processing from
0N/A the previous or parent request's ap_location_walk, so this step
0N/A is generally very efficient after processing the main
0N/A <
h3>Hook: translate_name</
h3>
0N/A <
p>Modules can determine the file name, or alter the given URI
0N/A in this step. For example, mod_vhost_alias will translate the
0N/A URI's path into the configured virtual host, mod_alias will
0N/A translate the path to an alias path, and if the request falls
0N/A back on the core, the DocumentRoot is prepended to the request
0N/A <
p>If all modules DECLINE this phase, an error 500 is returned
0N/A to the browser, and a "couldn't translate name" error is logged
0N/A <
h3>Hook: map_to_storage</
h3>
0N/A <
p>After the file or correct URI was determined, the
0N/A appropriate per-dir configurations are merged together. For
0N/A example, mod_proxy compares and merges the appropriate
0N/A <Proxy > sections. If the URI is nothing more than a
0N/A local (non-proxy) TRACE request, the core handles the request
0N/A and returns DONE. If no module answers this hook with OK or
0N/A DONE, the core will run the request filename against the
0N/A <Directory > and <Files > sections. If the request
0N/A 'filename' isn't an absolute, legal filename, a note is set for
0N/A later termination.</
p>
0N/A <
h3>Initial URI Location Walk</
h3>
0N/A <
p>Every request is hardened by a second
0N/A <
code>ap_location_walk()</
code> call. This reassures that a
0N/A translated request is still subjected to the configured
0N/A <Location > sections. The request again borrows some or
0N/A all of the processing from its previous location_walk above,
0N/A so this step is almost always very efficient unless the
0N/A translated URI mapped to a substantially different path or
0N/A <
h3>Hook: header_parser</
h3>
0N/A <
p>The main request then parses the client's headers. This
0N/A prepares the remaining request processing steps to better serve
0N/A the client's request.</
p>
0N/A <
h2>The Security Phase</
h2>
0N/A <
p>Needs Documentation. Code is;</
p>
0N/A switch (ap_satisfies(r)) {
0N/A case SATISFY_NOSPEC:
0N/A if ((access_status = ap_run_access_checker(r)) != 0) {
0N/A return decl_die(access_status, "check access", r);
0N/A if (ap_some_auth_required(r)) {
0N/A if (((access_status = ap_run_check_user_id(r)) != 0) || !ap_auth_type(r)) {
0N/A return decl_die(access_status, ap_auth_type(r)
0N/A ? "check user. No user file?"
0N/A : "perform authentication. AuthType not set!", r);
0N/A if (((access_status = ap_run_auth_checker(r)) != 0) || !ap_auth_type(r)) {
0N/A return decl_die(access_status, ap_auth_type(r)
0N/A ? "check access. No groups file?"
0N/A : "perform authentication. AuthType not set!", r);
0N/A if (((access_status = ap_run_access_checker(r)) != 0) || !ap_auth_type(r)) {
0N/A if (!ap_some_auth_required(r)) {
0N/A return decl_die(access_status, ap_auth_type(r)
0N/A : "perform authentication. AuthType not set!", r);
0N/A if (((access_status = ap_run_check_user_id(r)) != 0) || !ap_auth_type(r)) {
0N/A return decl_die(access_status, ap_auth_type(r)
0N/A ? "check user. No user file?"
0N/A : "perform authentication. AuthType not set!", r);
0N/A if (((access_status = ap_run_auth_checker(r)) != 0) || !ap_auth_type(r)) {
0N/A return decl_die(access_status, ap_auth_type(r)
0N/A ? "check access. No groups file?"
0N/A : "perform authentication. AuthType not set!", r);
0N/A <
h2>The Preparation Phase</
h2>
0N/A <
h3>Hook: type_checker</
h3>
0N/A <
p>The modules have an opportunity to test the URI or filename
0N/A against the target resource, and set mime information for the
0N/A request. Both mod_mime and mod_mime_magic use this phase to
0N/A compare the file name or contents against the administrator's
0N/A configuration and set the content type, language, character set
0N/A and request handler. Some modules may set up their filters or
0N/A other request handling parameters at this time.</
p>
0N/A <
p>If all modules DECLINE this phase, an error 500 is returned
0N/A to the browser, and a "couldn't find types" error is logged
0N/A <
h3>Hook: fixups</
h3>
0N/A <
p>Many modules are 'trounced' by some phase above. The fixups
0N/A phase is used by modules to 'reassert' their ownership or force
0N/A the request's fields to their appropriate values. It isn't
0N/A always the cleanest mechanism, but occasionally it's the only
0N/A <
h2>The Handler Phase</
h2>
0N/A <
p>This phase is <
strong><
em>not</
em></
strong> part of the
0N/A processing in <
code>ap_process_request_internal()</
code>. Many
0N/A modules prepare one or more subrequests prior to creating any
0N/A content at all. After the core, or a module calls
0N/A <
code>ap_process_request_internal()</
code> it then calls
0N/A <
code>ap_invoke_handler()</
code> to generate the request.</
p>
0N/A <
h3>Hook: insert_filter</
h3>
0N/A <
p>Modules that transform the content in some way can insert
0N/A their values and override existing filters, such that if the
0N/A user configured a more advanced filter out-of-order, then the
0N/A module can move its order as need be. There is no result code,
0N/A so actions in this hook better be trusted to always succeed.</
p>
0N/A <
h3>Hook: handler</
h3>
0N/A <
p>The module finally has a chance to serve the request in its
0N/A handler hook. Note that not every prepared request is sent to
0N/A the handler hook. Many modules, such as mod_autoindex, will
0N/A create subrequests for a given URI, and then never serve the
0N/A subrequest, but simply lists it for the user. Remember not to
0N/A put required teardown from the hooks above into this module,
0N/A but register pool cleanups against the request pool to free
0N/A resources as required.</
p>