--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Request Processing in Apache 2.0</TITLE>
+</HEAD>
+
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+<BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+>
+
+<!--#include virtual="header.html" -->
+
+<h1>Request Processing in Apache 2.0</h1>
+
+<p>Warning - this is a first (fast) draft that needs further revision!</p>
+
+<p>Several changes in Apache 2.0 affect the internal request processing
+ mechanics. Module authors need to be aware of these changes so they
+ may take advantage of the optimizations and security enhancements.</p>
+
+<p>The first major change is to the subrequest and redirect mechanisms.
+ There were a number of different code paths in Apache 1.3 to attempt
+ to optimize subrequest or redirect behavior. As patches were introduced
+ to 2.0, these optimizations (and the server behavior) were quickly broken
+ due to this duplication of code. All duplicate code has been folded
+ back into <code>ap_process_internal_request()</code> to prevent the
+ code from falling out of sync again.</p>
+
+<p>This means that much of the existing code was 'unoptimized'. It is
+ the Apache HTTP Project's first goal to create a robust and correct
+ implementation of the HTTP server RFC. Additional goals include
+ security, scalability and optimization. New methods were sought to
+ optimize the server (beyond the performance of Apache 1.3) without
+ introducing fragile or insecure code.</p>
+
+<h2>The Request Processing Cycle</h2>
+
+<p>All requests pass through <code>ap_process_request_internal()</code>
+ in request.c, including subrequests and redirects. If a module doesn't
+ pass generated requests through this code, the author is cautioned that
+ the module may be broken by future changes to request processing.</p>
+
+<p>To streamline requests, the module author can take advantage of the
+ hooks offered to drop out of the request cycle early, or to bypass
+ core Apache hooks which are irrelevant (and costly in terms of CPU.)</p>
+
+<h2>The Request Parsing Phase</h3>
+
+<h3>Unescapes the URL</h3>
+
+<p>The request's parsed_uri path is unescaped, once and only once, at the
+ beginning of internal request processing.</p>
+
+<p>This step is bypassed if the proxyreq flag is set, or the parsed_uri.path
+ element is unset. The module has no further control of this one-time
+ unescape operation, either failing to unescape or multiply unescaping
+ the URL leads to security reprecussions.</p>
+
+<h3>Strips Parent and This Elements from the URI</h3>
+
+<p>All <code>/../</code> and <code>/./</code> elements are removed by
+ <code>ap_getparents()</code>. This helps to ensure the path is (nearly)
+ absolute before the request processing continues.</p>
+
+<p>This step cannot be bypassed.</p>
+
+<h3>Initial URI Location Walk</h3>
+
+<p>Every request is subject to an <code>ap_location_walk()</code> call.
+ This ensures that <Location > sections are consistently enforced for
+ all requests. If the request is an internal redirect or a sub-request,
+ it may borrow some or all of the processing from the previous or parent
+ request's ap_location_walk, so this step is generally very efficient
+ after processing the main request.</p>
+
+<h3>Hook: translate_name</h3>
+
+<p>Modules can determine the file name, or alter the given URI in this step.
+ For example, mod_vhost_alias will translate the URI's path into the
+ configured virtual host, mod_alias will translate the path to an alias
+ path, and if the request falls back on the core, the DocumentRoot is
+ prepended to the request resource.
+
+<p>If all modules DECLINE this phase, an error 500 is returned to the browser,
+ and a "couldn't translate name" error is logged automatically.</p>
+
+<h3>Hook: map_to_storage</h3>
+
+<p>After the file or correct URI was determined, the appropriate per-dir
+ configurations are merged together. For example, mod_proxy compares
+ and merges the appropriate <Proxy > sections. If the URI is nothing
+ more than a local (non-proxy) TRACE request, the core handles the
+ request and returns DONE. If no module answers this hook with OK or
+ DONE, the core will run the request filename against the <Directory >
+ and <Files > sections. If the request 'filename' isn't an absolute,
+ legal filename, a note is set for later termination.</p>
+
+<h3>Initial URI Location Walk</h3>
+
+<p>Every request is hardened by a second <code>ap_location_walk()</code>
+ call. This reassures that a translated request is still subjected to
+ the configured <Location > sections. The request again borrows
+ some or all of the processing from it's previous location_walk above,
+ so this step is almost always very efficient unless the translated URI
+ mapped to a substantially different path or Virtual Host.</p>
+
+<h3>Hook: header_parser</h3>
+
+<p>The main request then parses the client's headers. This prepares
+the remaining request processing steps to better serve the client's
+request.</p>
+
+<h2>The Security Phase</h3>
+
+<p>Needs Documentation. Code is;</p>
+<pre>
+ switch (ap_satisfies(r)) {
+ case SATISFY_ALL:
+ case SATISFY_NOSPEC:
+ if ((access_status = ap_run_access_checker(r)) != 0) {
+ return decl_die(access_status, "check access", r);
+ }
+ if (ap_some_auth_required(r)) {
+ if (((access_status = ap_run_check_user_id(r)) != 0) || !ap_auth_type(r)) {
+ return decl_die(access_status, ap_auth_type(r)
+ ? "check user. No user file?"
+ : "perform authentication. AuthType not set!", r);
+ }
+ if (((access_status = ap_run_auth_checker(r)) != 0) || !ap_auth_type(r)) {
+ return decl_die(access_status, ap_auth_type(r)
+ ? "check access. No groups file?"
+ : "perform authentication. AuthType not set!", r);
+ }
+ }
+ break;
+ case SATISFY_ANY:
+ if (((access_status = ap_run_access_checker(r)) != 0) || !ap_auth_type(r)) {
+ if (!ap_some_auth_required(r)) {
+ return decl_die(access_status, ap_auth_type(r)
+ ? "check access"
+ : "perform authentication. AuthType not set!", r);
+ }
+ if (((access_status = ap_run_check_user_id(r)) != 0) || !ap_auth_type(r)) {
+ return decl_die(access_status, ap_auth_type(r)
+ ? "check user. No user file?"
+ : "perform authentication. AuthType not set!", r);
+ }
+ if (((access_status = ap_run_auth_checker(r)) != 0) || !ap_auth_type(r)) {
+ return decl_die(access_status, ap_auth_type(r)
+ ? "check access. No groups file?"
+ : "perform authentication. AuthType not set!", r);
+ }
+ }
+ break;
+ }
+</pre>
+<h2>The Preparation Phase</h2>
+
+<h3>Hook: type_checker</h3>
+
+<p>The modules have an opportunity to test the URI or filename against
+ the target resource, and set mime information for the request. Both
+ mod_mime and mod_mime_magic use this phase to compare the file name
+ or contents against the administrator's configuration and set the
+ content type, language, character set and request handler. Some
+ modules may set up their filters or other request handling parameters
+ at this time.</p>
+
+<p>If all modules DECLINE this phase, an error 500 is returned to the browser,
+ and a "couldn't find types" error is logged automatically.</p>
+
+<h3>Hook: fixups</h3>
+
+<p>Many modules are 'trounced' by some phase above. The fixups phase is
+ used by modules to 'reassert' their ownership or force the request's
+ fields to their appropriate values. It isn't always the cleanest
+ mechanism, but occasionally it's the only option.</p>
+
+<h3>Hook: insert_filter</h3>
+
+<p>Modules that transform the content in some way can insert their values
+ and override existing filters, such that if the user configured a more
+ advanced filter out-of-order, then the module can move it's order as
+ need be.
+
+<h2>The Handler Phase</h2>
+
+<p>This phase is <strong><em>not</em></strong> part of the processing in
+ <code>ap_process_request_internal()</code>. Many modules prepare one
+ or more subrequests prior to creating any content at all. After the
+ core, or a module calls <code>ap_process_request_internal()</code> it
+ then calls <code>ap_invoke_handler()</code> to generate the request.</p>
+
+<h3>Hook: handler</h3>
+
+<p>The module finally has a chance to serve the request in it's handler
+ hook. Note that not every prepared request is sent to the handler
+ hook. Many modules, such as mod_autoindex, will create subrequests
+ for a given URI, and then never serve the subrequest, but simply
+ lists it for the user. Remember not to put required teardown from
+ the hooks above into this module, but register pool cleanups against
+ the request pool to free resources as required.</p>
+
+<!--#include virtual="footer.html" -->
+
+</body>
+</html>
+
+
+
+
+
projects / thirdparty / apache / httpd.git / commitdiff
