Request Processing in Apache 2.0

Available Languages: en

- -

Warning

Warning - this is a first (fast) draft that needs further - revision!

- -

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.

- -

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 ap_process_request_internal() to prevent - the code from falling out of sync again.

- -

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.

The Request Processing Cycle
The Request Parsing Phase
The Security Phase
The Preparation Phase
The Handler Phase

The Request Processing Cycle

All requests pass through ap_process_request_internal() - 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.

- -

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.)

The Request Parsing Phase

Unescapes the URL

The request's parsed_uri path is unescaped, once and only - once, at the beginning of internal request processing.

- -

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.

- - -

Strips Parent and This Elements from the - URI

All /../ and /./ elements are - removed by ap_getparents(). This helps to ensure - the path is (nearly) absolute before the request processing - continues.

- -

This step cannot be bypassed.

- - -

Initial URI Location Walk

Every request is subject to an - ap_location_walk() 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.

- - -

translate_name

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.

- -

If all modules DECLINE this phase, an error 500 is - returned to the browser, and a "couldn't translate name" error is logged - automatically.

- - -

Hook: map_to_storage

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.

- - -

URI Location Walk

Every request is hardened by a second - ap_location_walk() 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 its 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.

- - -

Hook: header_parser

The main request then parses the client's headers. This - prepares the remaining request processing steps to better serve - the client's request.

- -

The Security Phase

Needs Documentation. Code is:

- -

-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)) {
-        if (!ap_some_auth_required(r)) {
-            return decl_die(access_status, "check access", 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;
-}

The Preparation Phase

Hook: type_checker

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.

- -

If all modules DECLINE this phase, an error 500 is - returned to the browser, and a "couldn't find types" error is logged - automatically.

- - -

Hook: fixups

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.

- -

The Handler Phase

This phase is not part of the processing in - ap_process_request_internal(). Many - modules prepare one or more subrequests prior to creating any - content at all. After the core, or a module calls - ap_process_request_internal() it then calls - ap_invoke_handler() to generate the request.

- -

Hook: insert_filter

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 its order as need be. There is no result code, - so actions in this hook better be trusted to always succeed.

- - -

Hook: handler

The module finally has a chance to serve the request in its - 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.

- -