granicus.if.org Git - apache/blob - docs/manual/developer/request.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="request.xml.meta">
  24 <parentdocument href="./">Developer Documentation</parentdocument>
  25
  26 <title>Request Processing in the Apache HTTP Server 2.x</title>
  27
  28 <summary>
  29     <note type="warning"><title>Warning</title>
  30       <p>Warning - this is a first (fast) draft that needs further
  31       revision!</p>
  32     </note>
  33
  34     <p>Several changes in 2.0 and above affect the internal request
  35     processing mechanics. Module authors need to be aware of these
  36     changes so they may take advantage of the optimizations and
  37     security enhancements.</p>
  38
  39     <p>The first major change is to the subrequest and redirect
  40     mechanisms. There were a number of different code paths in
  41     the Apache HTTP Server 1.3 to attempt to optimize subrequest
  42     or redirect behavior. As patches were introduced to 2.0, these
  43     optimizations (and the server behavior) were quickly broken due
  44     to this duplication of code. All duplicate code has been folded
  45     back into <code>ap_process_request_internal()</code> to prevent
  46     the code from falling out of sync again.</p>
  47
  48     <p>This means that much of the existing code was 'unoptimized'.
  49     It is the Apache HTTP Project's first goal to create a robust
  50     and correct implementation of the HTTP server RFC. Additional
  51     goals include security, scalability and optimization. New
  52     methods were sought to optimize the server (beyond the
  53     performance of 1.3) without introducing fragile or
  54     insecure code.</p>
  55 </summary>
  56
  57 <section id="processing"><title>The Request Processing Cycle</title>
  58     <p>All requests pass through <code>ap_process_request_internal()</code>
  59     in <code>request.c</code>, including subrequests and redirects. If a module
  60     doesn't pass generated requests through this code, the author is cautioned
  61     that the module may be broken by future changes to request
  62     processing.</p>
  63
  64     <p>To streamline requests, the module author can take advantage
  65     of the hooks offered to drop out of the request cycle early, or
  66     to bypass core hooks which are irrelevant (and costly in
  67     terms of CPU.)</p>
  68 </section>
  69
  70 <section id="parsing"><title>The Request Parsing Phase</title>
  71     <section id="unescape"><title>Unescapes the URL</title>
  72       <p>The request's <code>parsed_uri</code> path is unescaped, once and only
  73       once, at the beginning of internal request processing.</p>
  74
  75       <p>This step is bypassed if the proxyreq flag is set, or the
  76       <code>parsed_uri.path</code> element is unset. The module has no further
  77       control of this one-time unescape operation, either failing to
  78       unescape or multiply unescaping the URL leads to security
  79       repercussions.</p>
  80     </section>
  81
  82     <section id="strip"><title>Strips Parent and This Elements from the
  83     URI</title>
  84       <p>All <code>/../</code> and <code>/./</code> elements are
  85       removed by <code>ap_getparents()</code>. This helps to ensure
  86       the path is (nearly) absolute before the request processing
  87       continues.</p>
  88
  89       <p>This step cannot be bypassed.</p>
  90     </section>
  91
  92     <section id="inital-location-walk"><title>Initial URI Location Walk</title>
  93       <p>Every request is subject to an
  94       <code>ap_location_walk()</code> call. This ensures that
  95       <directive type="section" module="core">Location</directive> sections
  96       are consistently enforced for all requests. If the request is an internal
  97       redirect or a sub-request, it may borrow some or all of the processing
  98       from the previous or parent request's ap_location_walk, so this step
  99       is generally very efficient after processing the main request.</p>
 100     </section>
 101
 102     <section id="translate_name"><title>translate_name</title>
 103       <p>Modules can determine the file name, or alter the given URI
 104       in this step. For example, <module>mod_vhost_alias</module> will
 105       translate the URI's path into the configured virtual host,
 106       <module>mod_alias</module> will translate the path to an alias path,
 107       and if the request falls back on the core, the <directive module="core"
 108       >DocumentRoot</directive> is prepended to the request resource.</p>
 109
 110       <p>If all modules <code>DECLINE</code> this phase, an error 500 is
 111       returned to the browser, and a "couldn't translate name" error is logged
 112       automatically.</p>
 113     </section>
 114
 115     <section id="map_to_storage"><title>Hook: map_to_storage</title>
 116       <p>After the file or correct URI was determined, the
 117       appropriate per-dir configurations are merged together. For
 118       example, <module>mod_proxy</module> compares and merges the appropriate
 119       <directive module="mod_proxy" type="section">Proxy</directive> sections.
 120       If the URI is nothing more than a local (non-proxy) <code>TRACE</code>
 121       request, the core handles the request and returns <code>DONE</code>.
 122       If no module answers this hook with <code>OK</code> or <code>DONE</code>,
 123       the core will run the request filename against the <directive
 124       module="core" type="section">Directory</directive> and <directive
 125       module="core" type="section">Files</directive> sections. If the request
 126       'filename' isn't an absolute, legal filename, a note is set for
 127       later termination.</p>
 128     </section>
 129
 130     <section id="location-walk"><title>URI Location Walk</title>
 131       <p>Every request is hardened by a second
 132       <code>ap_location_walk()</code> call. This reassures that a
 133       translated request is still subjected to the configured
 134       <directive module="core" type="section">Location</directive> sections.
 135       The request again borrows some or all of the processing from its previous
 136       <code>location_walk</code> above, so this step is almost always very
 137       efficient unless the translated URI mapped to a substantially different
 138       path or Virtual Host.</p>
 139     </section>
 140
 141     <section id="header_parser"><title>Hook: header_parser</title>
 142       <p>The main request then parses the client's headers. This
 143       prepares the remaining request processing steps to better serve
 144       the client's request.</p>
 145     </section>
 146 </section>
 147
 148 <section id="security"><title>The Security Phase</title>
 149     <p>Needs Documentation. Code is:</p>
 150
 151     <highlight language="c">
 152         if ((access_status = ap_run_access_checker(r)) != 0) {
 153             return decl_die(access_status, "check access", r);
 154         }
 155
 156         if ((access_status = ap_run_check_user_id(r)) != 0) {
 157             return decl_die(access_status, "check user", r);
 158         }
 159
 160         if ((access_status = ap_run_auth_checker(r)) != 0) {
 161             return decl_die(access_status, "check authorization", r);
 162         }
 163     </highlight>
 164 </section>
 165
 166 <section id="preparation"><title>The Preparation Phase</title>
 167     <section id="type_checker"><title>Hook: type_checker</title>
 168       <p>The modules have an opportunity to test the URI or filename
 169       against the target resource, and set mime information for the
 170       request. Both <module>mod_mime</module> and
 171       <module>mod_mime_magic</module> use this phase to compare the file
 172       name or contents against the administrator's configuration and set the
 173       content type, language, character set and request handler. Some modules
 174       may set up their filters or other request handling parameters at this
 175       time.</p>
 176
 177       <p>If all modules <code>DECLINE</code> this phase, an error 500 is
 178       returned to the browser, and a "couldn't find types" error is logged
 179       automatically.</p>
 180     </section>
 181
 182     <section id="fixups"><title>Hook: fixups</title>
 183       <p>Many modules are 'trounced' by some phase above. The fixups
 184       phase is used by modules to 'reassert' their ownership or force
 185       the request's fields to their appropriate values. It isn't
 186       always the cleanest mechanism, but occasionally it's the only
 187       option.</p>
 188     </section>
 189 </section>
 190
 191 <section id="handler"><title>The Handler Phase</title>
 192     <p>This phase is <strong>not</strong> part of the processing in
 193     <code>ap_process_request_internal()</code>. Many
 194     modules prepare one or more subrequests prior to creating any
 195     content at all. After the core, or a module calls
 196     <code>ap_process_request_internal()</code> it then calls
 197     <code>ap_invoke_handler()</code> to generate the request.</p>
 198
 199     <section id="insert_filter"><title>Hook: insert_filter</title>
 200       <p>Modules that transform the content in some way can insert
 201       their values and override existing filters, such that if the
 202       user configured a more advanced filter out-of-order, then the
 203       module can move its order as need be.  There is no result code,
 204       so actions in this hook better be trusted to always succeed.</p>
 205     </section>
 206
 207     <section id="hook_handler"><title>Hook: handler</title>
 208       <p>The module finally has a chance to serve the request in its
 209       handler hook. Note that not every prepared request is sent to
 210       the handler hook. Many modules, such as <module>mod_autoindex</module>,
 211       will create subrequests for a given URI, and then never serve the
 212       subrequest, but simply lists it for the user. Remember not to
 213       put required teardown from the hooks above into this module,
 214       but register pool cleanups against the request pool to free
 215       resources as required.</p>
 216     </section>
 217 </section>
 218 </manualpage>
 219