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