request.xml revision c2ce3eebd6de627b8741ee5a3864896ff7baca94
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
6feac653602777107aef73edc90d1865ac4334e1nd Copyright 2003-2005 The Apache Software Foundation or its licensors,
6feac653602777107aef73edc90d1865ac4334e1nd as applicable.
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd Licensed under the Apache License, Version 2.0 (the "License");
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd you may not use this file except in compliance with the License.
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd You may obtain a copy of the License at
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd Unless required by applicable law or agreed to in writing, software
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd distributed under the License is distributed on an "AS IS" BASIS,
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd See the License for the specific language governing permissions and
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd limitations under the License.
c82fca6d3f5608b946f18d37e8710b1d71e3478dnd<parentdocument href="./">Developer Documentation</parentdocument>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Warning - this is a first (fast) draft that needs further
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend revision!</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Several changes in Apache 2.0 affect the internal request
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend processing mechanics. Module authors need to be aware of these
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend changes so they may take advantage of the optimizations and
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend security enhancements.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>The first major change is to the subrequest and redirect
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend mechanisms. There were a number of different code paths in
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend Apache 1.3 to attempt to optimize subrequest or redirect
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend behavior. As patches were introduced to 2.0, these
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend optimizations (and the server behavior) were quickly broken due
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend to this duplication of code. All duplicate code has been folded
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend back into <code>ap_process_internal_request()</code> to prevent
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend the code from falling out of sync again.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>This means that much of the existing code was 'unoptimized'.
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend It is the Apache HTTP Project's first goal to create a robust
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend and correct implementation of the HTTP server RFC. Additional
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend goals include security, scalability and optimization. New
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend methods were sought to optimize the server (beyond the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend performance of Apache 1.3) without introducing fragile or
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend insecure code.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend<section id="processing"><title>The Request Processing Cycle</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>All requests pass through <code>ap_process_request_internal()</code>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend in <code>request.c</code>, including subrequests and redirects. If a module
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend doesn't pass generated requests through this code, the author is cautioned
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend that the module may be broken by future changes to request
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend processing.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>To streamline requests, the module author can take advantage
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend of the hooks offered to drop out of the request cycle early, or
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend to bypass core Apache hooks which are irrelevant (and costly in
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend terms of CPU.)</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend<section id="parsing"><title>The Request Parsing Phase</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>The request's <code>parsed_uri</code> path is unescaped, once and only
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend once, at the beginning of internal request processing.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>This step is bypassed if the proxyreq flag is set, or the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <code>parsed_uri.path</code> element is unset. The module has no further
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend control of this one-time unescape operation, either failing to
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend unescape or multiply unescaping the URL leads to security
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend reprecussions.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="strip"><title>Strips Parent and This Elements from the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend URI</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>All <code>/../</code> and <code>/./</code> elements are
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend removed by <code>ap_getparents()</code>. This helps to ensure
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend the path is (nearly) absolute before the request processing
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend continues.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="inital-location-walk"><title>Initial URI Location Walk</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Every request is subject to an
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <directive type="section" module="core">Location</directive> sections
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend are consistently enforced for all requests. If the request is an internal
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend redirect or a sub-request, it may borrow some or all of the processing
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend from the previous or parent request's ap_location_walk, so this step
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend is generally very efficient after processing the main request.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="translate_name"><title>translate_name</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Modules can determine the file name, or alter the given URI
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend in this step. For example, <module>mod_vhost_alias</module> will
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend translate the URI's path into the configured virtual host,
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <module>mod_alias</module> will translate the path to an alias path,
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend and if the request falls back on the core, the <directive module="core"
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend >DocumentRoot</directive> is prepended to the request resource.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>If all modules <code>DECLINE</code> this phase, an error 500 is
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend returned to the browser, and a "couldn't translate name" error is logged
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend automatically.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="map_to_storage"><title>Hook: map_to_storage</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>After the file or correct URI was determined, the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend appropriate per-dir configurations are merged together. For
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend example, <module>mod_proxy</module> compares and merges the appropriate
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <directive module="mod_proxy" type="section">Proxy</directive> sections.
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend If the URI is nothing more than a local (non-proxy) <code>TRACE</code>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend request, the core handles the request and returns <code>DONE</code>.
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend If no module answers this hook with <code>OK</code> or <code>DONE</code>,
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend the core will run the request filename against the <directive
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend module="core" type="section">Directory</directive> and <directive
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend module="core" type="section">Files</directive> sections. If the request
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend 'filename' isn't an absolute, legal filename, a note is set for
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend later termination.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="location-walk"><title>URI Location Walk</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Every request is hardened by a second
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <code>ap_location_walk()</code> call. This reassures that a
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend translated request is still subjected to the configured
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <directive module="core" type="section">Location</directive> sections.
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend The request again borrows some or all of the processing from its previous
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <code>location_walk</code> above, so this step is almost always very
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend efficient unless the translated URI mapped to a substantially different
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend path or Virtual Host.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="header_parser"><title>Hook: header_parser</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>The main request then parses the client's headers. This
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend prepares the remaining request processing steps to better serve
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend the client's request.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aendswitch (ap_satisfies(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aendcase SATISFY_ALL:
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aendcase SATISFY_NOSPEC:
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if ((access_status = ap_run_access_checker(r)) != 0) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend return decl_die(access_status, "check access", r);
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (ap_some_auth_required(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (((access_status = ap_run_check_user_id(r)) != 0)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend || !ap_auth_type(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend return decl_die(access_status, ap_auth_type(r)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend ? "check user. No user file?"
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend : "perform authentication. AuthType not set!",
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (((access_status = ap_run_auth_checker(r)) != 0)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend || !ap_auth_type(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend return decl_die(access_status, ap_auth_type(r)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend ? "check access. No groups file?"
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend : "perform authentication. AuthType not set!",
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aendcase SATISFY_ANY:
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (((access_status = ap_run_access_checker(r)) != 0)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (!ap_some_auth_required(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend return decl_die(access_status, "check access", r);
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (((access_status = ap_run_check_user_id(r)) != 0)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend || !ap_auth_type(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend return decl_die(access_status, ap_auth_type(r)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend ? "check user. No user file?"
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend : "perform authentication. AuthType not set!",
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend if (((access_status = ap_run_auth_checker(r)) != 0)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend || !ap_auth_type(r)) {
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend return decl_die(access_status, ap_auth_type(r)
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend ? "check access. No groups file?"
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend : "perform authentication. AuthType not set!",
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </example>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend<section id="preparation"><title>The Preparation Phase</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="type_checker"><title>Hook: type_checker</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>The modules have an opportunity to test the URI or filename
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend against the target resource, and set mime information for the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <module>mod_mime_magic</module> use this phase to compare the file
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend name or contents against the administrator's configuration and set the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend content type, language, character set and request handler. Some modules
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend may set up their filters or other request handling parameters at this
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>If all modules <code>DECLINE</code> this phase, an error 500 is
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend returned to the browser, and a "couldn't find types" error is logged
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend automatically.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Many modules are 'trounced' by some phase above. The fixups
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend phase is used by modules to 'reassert' their ownership or force
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend the request's fields to their appropriate values. It isn't
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend always the cleanest mechanism, but occasionally it's the only
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend option.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>This phase is <strong>not</strong> part of the processing in
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend modules prepare one or more subrequests prior to creating any
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend content at all. After the core, or a module calls
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <code>ap_invoke_handler()</code> to generate the request.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <section id="insert_filter"><title>Hook: insert_filter</title>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>Modules that transform the content in some way can insert
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend their values and override existing filters, such that if the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend user configured a more advanced filter out-of-order, then the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend module can move its order as need be. There is no result code,
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend so actions in this hook better be trusted to always succeed.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend <p>The module finally has a chance to serve the request in its
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend handler hook. Note that not every prepared request is sent to
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend the handler hook. Many modules, such as <module>mod_autoindex</module>,
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend will create subrequests for a given URI, and then never serve the
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend subrequest, but simply lists it for the user. Remember not to
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend put required teardown from the hooks above into this module,
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend but register pool cleanups against the request pool to free
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend resources as required.</p>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend </section>
38dd0bd0209a7e29ea44e66bfc3bec8edc03e9aend</manualpage>