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 DocumentationRequest 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, 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: 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.

      Modules should register using ap_hook_check_access()
      rather than hooking access_checker directly.
    

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

      Modules should register using ap_hook_check_access_ex()
      rather than hooking access_checker_ex directly.
    

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

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


Available Languages:  en 

Copyright 2026 The Apache Software Foundation.Licensed under the Apache License, Version 2.0.
Modules | Directives | FAQ | Glossary | Sitemap | Report a bug