Request Processing in the Apache HTTP Server 2.4 - Apache HTTP Server Version 2.4
Modules | Directives | FAQ | Glossary | Sitemap | Report a bug Apache HTTP Server Version 2.4 Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation Request Processing in the Apache HTTP Server 2.4 Available Languages: en This document describes how the Apache HTTP Server processes requests internally, covering the full hook sequence from URI translation through content generation and logging. Module authors should understand these phases to correctly insert their processing at the appropriate point in the cycle.
All requests pass through ap_process_request_internal() in server/request.c , including subrequests and internal redirects. Do not duplicate this logic elsewhere; doing so will break when the request processing API changes. The first major design principle is that all request processing paths (main requests, subrequests, and redirects) share a single code path. Duplicate code was folded back into ap_process_request_internal() in 2.0 to prevent the paths from falling out of sync.
To streamline requests, module authors can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core hooks which are irrelevant (and costly in terms of CPU). Hook Overview The Request Parsing Phase Hook: quick_handler Hook: create_request The Translation Phase Hook: map_to_storage Hook: post_perdir_config Hook: header_parser The Security Phase The Preparation Phase The Handler Phase The Logging Phase Hook: dirwalk_stat Hook Types and Ordering Hook Overview ¶ The complete request processing cycle involves the following hooks, listed in execution order.
Hooks marked with (request.c) are implemented in server/request.c ; others are declared in http_config.h or http_protocol.h and run from the MPM or protocol layer. quick_handler — Short-circuit before the full request cycle (e.g. cache hits) create_request — Initialize request-specific module data pre_translate_name — Manipulate URI before decoding/translation translate_name — Map URI to filesystem path map_to_storage — Merge per-directory config, directory/file walks post_perdir_config — Act on merged per-directory configuration header_parser — Examine client request headers access_checker — Host-based or environment-based access control access_checker_ex — Extended access control with auth bypass capability force_authn — Force authentication even when not otherwise required check_user_id — Authenticate the user (set r->user ) auth_checker — Authorize the authenticated user type_checker — Determine content type, language, encoding fixups — Last chance to adjust request fields before content generation insert_filter — Insert content/protocol filters handler — Generate the response content log_transaction — Log the completed transaction Additionally, the dirwalk_stat hook is called during directory walks to allow modules to emulate or override apr_stat() calls.
The Request Parsing Phase ¶ Before hooks run, the server performs URL normalization: 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 repercussions.
Strips Parent and This Elements from the URI All /../ and /./ elements are removed by ap_getparents() , as well as any trailing /. or /.. element. This helps to ensure the path is (nearly) absolute before the request processing continues. (See RFC 1808 section 4 for further discussion.) 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. Hook: quick_handler ¶ The quick_handler hook runs before any other request processing hooks — before location walks, directory walks, access checking, and authentication. It provides a fast path for modules that can serve content directly from a URI-keyed cache or similar mechanism without needing per-directory configuration.
This hook is declared in http_config.h and called from the MPM/protocol layer, not from ap_process_request_internal() . AP_DECLARE_HOOK(int, quick_handler, (request_rec *r, int lookup_uri)) The lookup_uri parameter is set to 1 when called from ap_sub_req_lookup_uri() , indicating the caller only needs metadata (not actual content delivery). Used by: mod_cache Return OK to indicate the request has been fully handled. Return DECLINED to fall through to normal processing.
Hook: create_request ¶ Called when a new request_rec is created (for main requests, subrequests, and internal redirects). Modules use this hook to initialize per-request module state and set up private data structures attached to the request pool or request notes. AP_DECLARE_HOOK(int, create_request, (request_rec *r)) This is a RUN_ALL hook — all registered modules get a chance to run. Return OK or DECLINED . Used by: mod_http (http_core.c), mod_firehose The Translation Phase ¶ Hook: pre_translate_name Runs before URL decoding happens.
Modules can manipulate the raw URI before it is translated to a filesystem path. This is useful for modules that need to operate on the URI before percent-decoding or normalization. AP_DECLARE_HOOK(int, pre_translate_name, (request_rec *r)) Return DECLINED to let other modules handle the pre-translation, OK if it was handled, DONE if no further transformation should happen on the URI, or an HTTP error status code. Used by: mod_proxy Hook: 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. AP_DECLARE_HOOK(int, translate_name, (request_rec *r)) 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 . AP_DECLARE_HOOK(int, map_to_storage, (request_rec *r)) 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. After map_to_storage , a second ap_location_walk() call hardens the request by re-applying <Location> sections to the translated URI. Hook: post_perdir_config ¶ This hook fires immediately after per-directory configuration has been merged (after both map_to_storage and the second location walk). Modules can use it to act on the fully-merged per-directory configuration before access control runs.
AP_DECLARE_HOOK(int, post_perdir_config, (request_rec *r)) Return OK to allow processing to continue, DECLINED to let later modules decide, or an HTTP error status code to abort. 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. This hook only runs for the initial request (not subrequests). The Security Phase ¶ The security phase in 2.4 uses the provider-based authentication/authorization architecture managed by mod_auth_basic , m
The rest of this page is on the live site.