From: Rich Bowen Date: Fri, 29 May 2026 17:57:10 +0000 (+0000) Subject: Adds missing hooks to the request handling doc. X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=5c6d0d2d17c9cfe7c4677eb90f343b1c857199f8;p=thirdparty%2Fapache%2Fhttpd.git Adds missing hooks to the request handling doc. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1934756 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/developer/request.xml b/docs/manual/developer/request.xml index 1185b94c6e..a7ef54690d 100644 --- a/docs/manual/developer/request.xml +++ b/docs/manual/developer/request.xml @@ -26,55 +26,91 @@ Request Processing in the Apache HTTP Server 2.x - Warning -

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

- - -

Several changes in 2.0 and above 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 - the Apache HTTP Server 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 1.3) without introducing fragile or - insecure code.

+

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

 -
The Request Processing Cycle -

All requests pass through ap_process_request_internal() - in server/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 hooks which are - irrelevant (and costly in terms of CPU.)

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

+ +
    +
  1. quick_handler — + Short-circuit before the full request cycle (e.g. cache hits)
    2. +
  2. create_request — + Initialize request-specific module data
    3. +
  3. pre_translate_name — + Manipulate URI before decoding/translation
    4. +
  4. translate_name — + Map URI to filesystem path
    5. +
  5. map_to_storage — + Merge per-directory config, directory/file walks
    6. +
  6. post_perdir_config — + Act on merged per-directory configuration
    7. +
  7. header_parser — + Examine client request headers
    8. +
  8. token_checker — + Parse bearer tokens or other auth metadata (trunk)
    9. +
  9. access_checker — + Host-based or environment-based access control
    10. +
  10. access_checker_ex — + Extended access control with auth bypass capability
    11. +
  11. force_authn — + Force authentication even when not otherwise required
    12. +
  12. check_user_id — + Authenticate the user (set r->user)
    13. +
  13. auth_checker — + Authorize the authenticated user
    14. +
  14. type_checker — + Determine content type, language, encoding
    15. +
  15. fixups — + Last chance to adjust request fields before content generation
    16. +
  16. insert_filter — + Insert content/protocol filters
    17. +
  17. handler — + Generate the response content
    18. +
  18. log_transaction — + Log the completed transaction
    19. +
+ +

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 + control of this one-time unescape operation; either failing to unescape or multiply unescaping the URL leads to security repercussions.

@@ -82,7 +118,7 @@
Strips Parent and This Elements from the URI

All /../ and /./ elements are - removed by ap_getparents(), as well as any trailing + 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.)

@@ -90,7 +126,7 @@

This step cannot be bypassed.

-
Initial URI Location Walk +
Initial URI Location Walk

Every request is subject to an ap_location_walk() call. This ensures that Location sections @@ -99,8 +135,71 @@ 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

+
-
translate_name +
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, @@ -108,60 +207,166 @@ 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. - 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:

+
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 ((access_status = ap_run_access_checker(r)) != 0) { - return decl_die(access_status, "check access", r); -} +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.

+
-if ((access_status = ap_run_check_user_id(r)) != 0) { - return decl_die(access_status, "check user", r); -} +
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.

-if ((access_status = ap_run_auth_checker(r)) != 0) { - return decl_die(access_status, "check authorization", r); -} + +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 "new" provider-based + authentication/authorization architecture managed by + mod_auth_basic, mod_authz_core, + and related modules. The hook execution order depends on the + Satisfy setting + and whether access control is required (Require directives).

+ +

The hooks execute in this order:

+ +
Hook: token_checker +

Parses any tokens in the request (e.g. bearer tokens, API keys) + that contain metadata such as user identities or IP addresses + relevant to the request. Runs before the access checker.

+ + +AP_DECLARE_HOOK(int, token_checker, (request_rec *r)) + + +

If this hook returns OK under Satisfy any, + the request is authorized immediately without running further + access/auth hooks.

+ + Note +

This hook is available in trunk only (not backported to 2.4 + at the time of writing).

 +
+ +
Hook: access_checker +

Applies additional access control to the resource. This hook runs + before a user is authenticated, so it is for restrictions + independent of user identity (e.g. IP-based access, time-of-day + restrictions). It runs independent of Require directive usage.

+ + +AP_DECLARE_HOOK(int, access_checker, (request_rec *r)) + + +

This is a RUN_ALL hook — all registered modules run. + Return OK to allow, or an HTTP error status to deny.

+
+ +
Hook: access_checker_ex +

Extended access control that runs after access_checker + but before user authentication. This hook can also bypass + authentication entirely by returning OK — used by + mod_authz_core to implement the new authorization + model where Require directives can grant access + without credentials (e.g. Require ip).

+ + +AP_DECLARE_HOOK(int, access_checker_ex, (request_rec *r)) + + +

Return OK to grant access (skipping authn unless + force_authn overrides), DECLINED to + require authentication, or an HTTP error status to deny.

+
+ +
Hook: force_authn +

Allows a module to force authentication to be required even when + access_checker_ex has already granted access. This is + useful when a module needs the authenticated user identity for + purposes beyond authorization (e.g. logging, personalization).

+ + +AP_DECLARE_HOOK(int, force_authn, (request_rec *r)) + + +

Return OK to force authentication, or + DECLINED to let later modules decide.

+
+ +
Hook: check_user_id (authn) +

Authenticates the user — analyzes the request headers, validates + credentials, and sets r->user and + r->ap_auth_type. This hook only runs when Apache + determines that authentication is required for this resource.

+ + +AP_DECLARE_HOOK(int, check_user_id, (request_rec *r)) + + +

Modules should register using ap_hook_check_authn() + rather than hooking check_user_id directly.

+
+ +
Hook: auth_checker (authz) +

Checks whether the authenticated user (r->user) + is authorized to access this resource. Runs after + check_user_id, and only when a Require directive is + in effect.

+ + +AP_DECLARE_HOOK(int, auth_checker, (request_rec *r)) + + +

Modules should register using ap_hook_check_authz() + rather than hooking auth_checker directly.

+
The Preparation Phase @@ -175,34 +380,52 @@ if ((access_status = ap_run_auth_checker(r)) != 0) { may set up their filters or other request handling parameters at this time.

+ +AP_DECLARE_HOOK(int, type_checker, (request_rec *r)) + +

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.

+

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 is the last + hook to run before content generation.

+ + +AP_DECLARE_HOOK(int, fixups, (request_rec *r)) + + +

This is a RUN_ALL hook — all registered modules + get a chance to run. Used by mod_env, + mod_headers, and others.

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

+ module can move its order as needed. There is no result code, + so actions in this hook must always succeed.

+ + +AP_DECLARE_HOOK(void, insert_filter, (request_rec *r)) + + +

This is a VOID hook — no return value. Used by + mod_deflate, mod_filter, + mod_ssl, and other filter modules to insert + themselves into the output filter chain.

Hook: handler @@ -210,10 +433,82 @@ if ((access_status = ap_run_auth_checker(r)) != 0) { 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 + subrequest, but simply list 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.

+ + +AP_DECLARE_HOOK(int, handler, (request_rec *r)) + +
+
+ +
The Logging Phase +
Hook: log_transaction +

After the response has been sent to the client, modules can + perform logging activities. This hook is declared in + http_protocol.h and runs outside of + ap_process_request_internal().

+ + +AP_DECLARE_HOOK(int, log_transaction, (request_rec *r)) + + +

Used by: mod_log_config, + mod_log_forensic, mod_logio

+ +

Return OK or DECLINED. Errors at + this stage do not affect the client response (it has already + been sent).

+ +
Hook: dirwalk_stat +

This hook is called during directory walks to allow modules to + handle or emulate the apr_stat() calls needed to + traverse the filesystem. This enables modules to serve content + from non-filesystem backends (databases, remote storage, etc.) + while still participating in the directory walk mechanism.

+ + +AP_DECLARE_HOOK(apr_status_t, dirwalk_stat, + (apr_finfo_t *finfo, request_rec *r, apr_int32_t wanted)) + + +

Return an apr_status_t value, or + AP_DECLINED to let later modules (or the default + apr_stat() call) decide.

+
+ +
Hook Types and Ordering +

Each hook uses one of the following execution strategies:

+ +
+
RUN_FIRST
+
Hooks stop at the first module that does not return + DECLINED. Used by: pre_translate_name, + translate_name, map_to_storage, + check_user_id, type_checker, + access_checker_ex, auth_checker, + force_authn, token_checker, + dirwalk_stat.
+ +
RUN_ALL
+
Every registered module runs unless one returns an error. + Used by: fixups, access_checker, + create_request, post_perdir_config.
+ +
VOID
+
Every registered module runs with no return value. + Used by: insert_filter.
+
+ +

Modules control their position in the hook chain using the + order, predecessors, and + successors arguments to the ap_hook_* + registration functions. See the + module guide for details.

+
+