rubbos/app/httpd-2.0.64/docs/manual/developer/request.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Request Processing in Apache 2.0 - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.0</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Request Processing in Apache 2.0</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English">&nbsp;en&nbsp;</a></p>
  22 </div>
  23
  24     <div class="warning"><h3>Warning</h3>
  25       <p>Warning - this is a first (fast) draft that needs further
  26       revision!</p>
  27     </div>
  28
  29     <p>Several changes in Apache 2.0 affect the internal request
  30     processing mechanics. Module authors need to be aware of these
  31     changes so they may take advantage of the optimizations and
  32     security enhancements.</p>
  33
  34     <p>The first major change is to the subrequest and redirect
  35     mechanisms. There were a number of different code paths in
  36     Apache 1.3 to attempt to optimize subrequest or redirect
  37     behavior. As patches were introduced to 2.0, these
  38     optimizations (and the server behavior) were quickly broken due
  39     to this duplication of code. All duplicate code has been folded
  40     back into <code>ap_process_request_internal()</code> to prevent
  41     the code from falling out of sync again.</p>
  42
  43     <p>This means that much of the existing code was 'unoptimized'.
  44     It is the Apache HTTP Project's first goal to create a robust
  45     and correct implementation of the HTTP server RFC. Additional
  46     goals include security, scalability and optimization. New
  47     methods were sought to optimize the server (beyond the
  48     performance of Apache 1.3) without introducing fragile or
  49     insecure code.</p>
  50 </div>
  51 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#processing">The Request Processing Cycle</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#parsing">The Request Parsing Phase</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#security">The Security Phase</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#preparation">The Preparation Phase</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#handler">The Handler Phase</a></li>
  56 </ul></div>
  57 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  58 <div class="section">
  59 <h2><a name="processing" id="processing">The Request Processing Cycle</a></h2>
  60     <p>All requests pass through <code>ap_process_request_internal()</code>
  61     in <code>request.c</code>, including subrequests and redirects. If a module
  62     doesn't pass generated requests through this code, the author is cautioned
  63     that the module may be broken by future changes to request
  64     processing.</p>
  65
  66     <p>To streamline requests, the module author can take advantage
  67     of the hooks offered to drop out of the request cycle early, or
  68     to bypass core Apache hooks which are irrelevant (and costly in
  69     terms of CPU.)</p>
  70 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  71 <div class="section">
  72 <h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2>
  73     <h3><a name="unescape" id="unescape">Unescapes the URL</a></h3>
  74       <p>The request's <code>parsed_uri</code> path is unescaped, once and only
  75       once, at the beginning of internal request processing.</p>
  76
  77       <p>This step is bypassed if the proxyreq flag is set, or the
  78       <code>parsed_uri.path</code> element is unset. The module has no further
  79       control of this one-time unescape operation, either failing to
  80       unescape or multiply unescaping the URL leads to security
  81       reprecussions.</p>
  82
  83
  84     <h3><a name="strip" id="strip">Strips Parent and This Elements from the
  85     URI</a></h3>
  86       <p>All <code>/../</code> and <code>/./</code> elements are
  87       removed by <code>ap_getparents()</code>. This helps to ensure
  88       the path is (nearly) absolute before the request processing
  89       continues.</p>
  90
  91       <p>This step cannot be bypassed.</p>
  92
  93
  94     <h3><a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</a></h3>
  95       <p>Every request is subject to an
  96       <code>ap_location_walk()</code> call. This ensures that
  97       <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> sections
  98       are consistently enforced for all requests. If the request is an internal
  99       redirect or a sub-request, it may borrow some or all of the processing
 100       from the previous or parent request's ap_location_walk, so this step
 101       is generally very efficient after processing the main request.</p>
 102
 103
 104     <h3><a name="translate_name" id="translate_name">translate_name</a></h3>
 105       <p>Modules can determine the file name, or alter the given URI
 106       in this step. For example, <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> will
 107       translate the URI's path into the configured virtual host,
 108       <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> will translate the path to an alias path,
 109       and if the request falls back on the core, the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is prepended to the request resource.</p>
 110
 111       <p>If all modules <code>DECLINE</code> this phase, an error 500 is
 112       returned to the browser, and a "couldn't translate name" error is logged
 113       automatically.</p>
 114
 115
 116     <h3><a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</a></h3>
 117       <p>After the file or correct URI was determined, the
 118       appropriate per-dir configurations are merged together. For
 119       example, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> compares and merges the appropriate
 120       <code class="directive"><a href="../mod/mod_proxy.html#proxy">&lt;Proxy&gt;</a></code> sections.
 121       If the URI is nothing more than a local (non-proxy) <code>TRACE</code>
 122       request, the core handles the request and returns <code>DONE</code>.
 123       If no module answers this hook with <code>OK</code> or <code>DONE</code>,
 124       the core will run the request filename against the <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> and <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code> sections. If the request
 125       'filename' isn't an absolute, legal filename, a note is set for
 126       later termination.</p>
 127
 128
 129     <h3><a name="location-walk" id="location-walk">URI Location Walk</a></h3>
 130       <p>Every request is hardened by a second
 131       <code>ap_location_walk()</code> call. This reassures that a
 132       translated request is still subjected to the configured
 133       <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> sections.
 134       The request again borrows some or all of the processing from its previous
 135       <code>location_walk</code> above, so this step is almost always very
 136       efficient unless the translated URI mapped to a substantially different
 137       path or Virtual Host.</p>
 138
 139
 140     <h3><a name="header_parser" id="header_parser">Hook: header_parser</a></h3>
 141       <p>The main request then parses the client's headers. This
 142       prepares the remaining request processing steps to better serve
 143       the client's request.</p>
 144
 145 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 146 <div class="section">
 147 <h2><a name="security" id="security">The Security Phase</a></h2>
 148     <p>Needs Documentation. Code is:</p>
 149
 150     <div class="example"><pre>
 151 switch (ap_satisfies(r)) {
 152 case SATISFY_ALL:
 153 case SATISFY_NOSPEC:
 154     if ((access_status = ap_run_access_checker(r)) != 0) {
 155         return decl_die(access_status, "check access", r);
 156     }
 157
 158     if (ap_some_auth_required(r)) {
 159         if (((access_status = ap_run_check_user_id(r)) != 0)
 160             || !ap_auth_type(r)) {
 161             return decl_die(access_status, ap_auth_type(r)
 162                           ? "check user.  No user file?"
 163                           : "perform authentication. AuthType not set!",
 164                           r);
 165         }
 166
 167         if (((access_status = ap_run_auth_checker(r)) != 0)
 168             || !ap_auth_type(r)) {
 169             return decl_die(access_status, ap_auth_type(r)
 170                           ? "check access.  No groups file?"
 171                           : "perform authentication. AuthType not set!",
 172                           r);
 173         }
 174     }
 175     break;
 176
 177 case SATISFY_ANY:
 178     if (((access_status = ap_run_access_checker(r)) != 0)) {
 179         if (!ap_some_auth_required(r)) {
 180             return decl_die(access_status, "check access", r);
 181         }
 182
 183         if (((access_status = ap_run_check_user_id(r)) != 0)
 184             || !ap_auth_type(r)) {
 185             return decl_die(access_status, ap_auth_type(r)
 186                           ? "check user.  No user file?"
 187                           : "perform authentication. AuthType not set!",
 188                           r);
 189         }
 190
 191         if (((access_status = ap_run_auth_checker(r)) != 0)
 192             || !ap_auth_type(r)) {
 193             return decl_die(access_status, ap_auth_type(r)
 194                           ? "check access.  No groups file?"
 195                           : "perform authentication. AuthType not set!",
 196                           r);
 197         }
 198     }
 199     break;
 200 }</pre></div>
 201 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 202 <div class="section">
 203 <h2><a name="preparation" id="preparation">The Preparation Phase</a></h2>
 204     <h3><a name="type_checker" id="type_checker">Hook: type_checker</a></h3>
 205       <p>The modules have an opportunity to test the URI or filename
 206       against the target resource, and set mime information for the
 207       request. Both <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> and
 208       <code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code> use this phase to compare the file
 209       name or contents against the administrator's configuration and set the
 210       content type, language, character set and request handler. Some modules
 211       may set up their filters or other request handling parameters at this
 212       time.</p>
 213
 214       <p>If all modules <code>DECLINE</code> this phase, an error 500 is
 215       returned to the browser, and a "couldn't find types" error is logged
 216       automatically.</p>
 217
 218
 219     <h3><a name="fixups" id="fixups">Hook: fixups</a></h3>
 220       <p>Many modules are 'trounced' by some phase above. The fixups
 221       phase is used by modules to 'reassert' their ownership or force
 222       the request's fields to their appropriate values. It isn't
 223       always the cleanest mechanism, but occasionally it's the only
 224       option.</p>
 225
 226 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 227 <div class="section">
 228 <h2><a name="handler" id="handler">The Handler Phase</a></h2>
 229     <p>This phase is <strong>not</strong> part of the processing in
 230     <code>ap_process_request_internal()</code>. Many
 231     modules prepare one or more subrequests prior to creating any
 232     content at all. After the core, or a module calls
 233     <code>ap_process_request_internal()</code> it then calls
 234     <code>ap_invoke_handler()</code> to generate the request.</p>
 235
 236     <h3><a name="insert_filter" id="insert_filter">Hook: insert_filter</a></h3>
 237       <p>Modules that transform the content in some way can insert
 238       their values and override existing filters, such that if the
 239       user configured a more advanced filter out-of-order, then the
 240       module can move its order as need be.  There is no result code,
 241       so actions in this hook better be trusted to always succeed.</p>
 242
 243
 244     <h3><a name="hook_handler" id="hook_handler">Hook: handler</a></h3>
 245       <p>The module finally has a chance to serve the request in its
 246       handler hook. Note that not every prepared request is sent to
 247       the handler hook. Many modules, such as <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>,
 248       will create subrequests for a given URI, and then never serve the
 249       subrequest, but simply lists it for the user. Remember not to
 250       put required teardown from the hooks above into this module,
 251       but register pool cleanups against the request pool to free
 252       resources as required.</p>
 253
 254 </div></div>
 255 <div class="bottomlang">
 256 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English">&nbsp;en&nbsp;</a></p>
 257 </div><div id="footer">
 258 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 259 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 260 </body></html>