granicus.if.org Git - apache/blob - 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 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>Request Processing in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body id="manual-page"><div id="page-header">
  19 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  20 <p class="apache">Apache HTTP Server Version 2.5</p>
  21 <img alt="" src="../images/feather.png" /></div>
  22 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  23 <div id="path">
  24 <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.5</a> &gt; <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Request Processing in the Apache HTTP Server 2.x</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English">&nbsp;en&nbsp;</a></p>
  27 </div>
  28
  29     <div class="warning"><h3>Warning</h3>
  30       <p>Warning - this is a first (fast) draft that needs further
  31       revision!</p>
  32     </div>
  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 </div>
  56 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#processing">The Request Processing Cycle</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#parsing">The Request Parsing Phase</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#security">The Security Phase</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#preparation">The Preparation Phase</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#handler">The Handler Phase</a></li>
  61 </ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  62 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  63 <div class="section">
  64 <h2><a name="processing" id="processing">The Request Processing Cycle</a></h2>
  65     <p>All requests pass through <code>ap_process_request_internal()</code>
  66     in <code>server/request.c</code>, including subrequests and redirects. If a module
  67     doesn't pass generated requests through this code, the author is cautioned
  68     that the module may be broken by future changes to request
  69     processing.</p>
  70
  71     <p>To streamline requests, the module author can take advantage
  72     of the <a href="./modguide.html#hooking">hooks offered</a> to drop
  73     out of the request cycle early, or to bypass core hooks which are
  74     irrelevant (and costly in terms of CPU.)</p>
  75 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  76 <div class="section">
  77 <h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2>
  78     <h3><a name="unescape" id="unescape">Unescapes the URL</a></h3>
  79       <p>The request's <code>parsed_uri</code> path is unescaped, once and only
  80       once, at the beginning of internal request processing.</p>
  81
  82       <p>This step is bypassed if the proxyreq flag is set, or the
  83       <code>parsed_uri.path</code> element is unset. The module has no further
  84       control of this one-time unescape operation, either failing to
  85       unescape or multiply unescaping the URL leads to security
  86       repercussions.</p>
  87
  88
  89     <h3><a name="strip" id="strip">Strips Parent and This Elements from the
  90     URI</a></h3>
  91       <p>All <code>/../</code> and <code>/./</code> elements are
  92       removed by <code>ap_getparents()</code>. This helps to ensure
  93       the path is (nearly) absolute before the request processing
  94       continues.</p>
  95
  96       <p>This step cannot be bypassed.</p>
  97
  98
  99     <h3><a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</a></h3>
 100       <p>Every request is subject to an
 101       <code>ap_location_walk()</code> call. This ensures that
 102       <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> sections
 103       are consistently enforced for all requests. If the request is an internal
 104       redirect or a sub-request, it may borrow some or all of the processing
 105       from the previous or parent request's ap_location_walk, so this step
 106       is generally very efficient after processing the main request.</p>
 107
 108
 109     <h3><a name="translate_name" id="translate_name">translate_name</a></h3>
 110       <p>Modules can determine the file name, or alter the given URI
 111       in this step. For example, <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> will
 112       translate the URI's path into the configured virtual host,
 113       <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> will translate the path to an alias path,
 114       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>
 115
 116       <p>If all modules <code>DECLINE</code> this phase, an error 500 is
 117       returned to the browser, and a "couldn't translate name" error is logged
 118       automatically.</p>
 119
 120
 121     <h3><a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</a></h3>
 122       <p>After the file or correct URI was determined, the
 123       appropriate per-dir configurations are merged together. For
 124       example, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> compares and merges the appropriate
 125       <code class="directive"><a href="../mod/mod_proxy.html#proxy">&lt;Proxy&gt;</a></code> sections.
 126       If the URI is nothing more than a local (non-proxy) <code>TRACE</code>
 127       request, the core handles the request and returns <code>DONE</code>.
 128       If no module answers this hook with <code>OK</code> or <code>DONE</code>,
 129       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
 130       'filename' isn't an absolute, legal filename, a note is set for
 131       later termination.</p>
 132
 133
 134     <h3><a name="location-walk" id="location-walk">URI Location Walk</a></h3>
 135       <p>Every request is hardened by a second
 136       <code>ap_location_walk()</code> call. This reassures that a
 137       translated request is still subjected to the configured
 138       <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> sections.
 139       The request again borrows some or all of the processing from its previous
 140       <code>location_walk</code> above, so this step is almost always very
 141       efficient unless the translated URI mapped to a substantially different
 142       path or Virtual Host.</p>
 143
 144
 145     <h3><a name="header_parser" id="header_parser">Hook: header_parser</a></h3>
 146       <p>The main request then parses the client's headers. This
 147       prepares the remaining request processing steps to better serve
 148       the client's request.</p>
 149
 150 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 151 <div class="section">
 152 <h2><a name="security" id="security">The Security Phase</a></h2>
 153     <p>Needs Documentation. Code is:</p>
 154
 155     <pre class="prettyprint lang-c">if ((access_status = ap_run_access_checker(r)) != 0) {
 156     return decl_die(access_status, "check access", r);
 157 }
 158
 159 if ((access_status = ap_run_check_user_id(r)) != 0) {
 160     return decl_die(access_status, "check user", r);
 161 }
 162
 163 if ((access_status = ap_run_auth_checker(r)) != 0) {
 164     return decl_die(access_status, "check authorization", r);
 165 }</pre>
 166
 167 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 168 <div class="section">
 169 <h2><a name="preparation" id="preparation">The Preparation Phase</a></h2>
 170     <h3><a name="type_checker" id="type_checker">Hook: type_checker</a></h3>
 171       <p>The modules have an opportunity to test the URI or filename
 172       against the target resource, and set mime information for the
 173       request. Both <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> and
 174       <code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code> use this phase to compare the file
 175       name or contents against the administrator's configuration and set the
 176       content type, language, character set and request handler. Some modules
 177       may set up their filters or other request handling parameters at this
 178       time.</p>
 179
 180       <p>If all modules <code>DECLINE</code> this phase, an error 500 is
 181       returned to the browser, and a "couldn't find types" error is logged
 182       automatically.</p>
 183
 184
 185     <h3><a name="fixups" id="fixups">Hook: fixups</a></h3>
 186       <p>Many modules are 'trounced' by some phase above. The fixups
 187       phase is used by modules to 'reassert' their ownership or force
 188       the request's fields to their appropriate values. It isn't
 189       always the cleanest mechanism, but occasionally it's the only
 190       option.</p>
 191
 192 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 193 <div class="section">
 194 <h2><a name="handler" id="handler">The Handler Phase</a></h2>
 195     <p>This phase is <strong>not</strong> part of the processing in
 196     <code>ap_process_request_internal()</code>. Many
 197     modules prepare one or more subrequests prior to creating any
 198     content at all. After the core, or a module calls
 199     <code>ap_process_request_internal()</code> it then calls
 200     <code>ap_invoke_handler()</code> to generate the request.</p>
 201
 202     <h3><a name="insert_filter" id="insert_filter">Hook: insert_filter</a></h3>
 203       <p>Modules that transform the content in some way can insert
 204       their values and override existing filters, such that if the
 205       user configured a more advanced filter out-of-order, then the
 206       module can move its order as need be.  There is no result code,
 207       so actions in this hook better be trusted to always succeed.</p>
 208
 209
 210     <h3><a name="hook_handler" id="hook_handler">Hook: handler</a></h3>
 211       <p>The module finally has a chance to serve the request in its
 212       handler hook. Note that not every prepared request is sent to
 213       the handler hook. Many modules, such as <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>,
 214       will create subrequests for a given URI, and then never serve the
 215       subrequest, but simply lists it for the user. Remember not to
 216       put required teardown from the hooks above into this module,
 217       but register pool cleanups against the request pool to free
 218       resources as required.</p>
 219
 220 </div></div>
 221 <div class="bottomlang">
 222 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English">&nbsp;en&nbsp;</a></p>
 223 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 224 <script type="text/javascript"><!--//--><![CDATA[//><!--
 225 var comments_shortname = 'httpd';
 226 var comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/request.html';
 227 (function(w, d) {
 228     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 229         d.write('<div id="comments_thread"><\/div>');
 230         var s = d.createElement('script');
 231         s.type = 'text/javascript';
 232         s.async = true;
 233         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 234         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 235     }
 236     else {
 237         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 238     }
 239 })(window, document);
 240 //--><!]]></script></div><div id="footer">
 241 <p class="apache">Copyright 2016 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>
 242 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 243 if (typeof(prettyPrint) !== 'undefined') {
 244     prettyPrint();
 245 }
 246 //--><!]]></script>
 247 </body></html>