Request Processing in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.4








Modules | Directives | FAQ | Glossary | Sitemap
Apache HTTP Server Version 2.4



Apache > HTTP Server > Documentation > Version 2.4 > Developer DocumentationRequest Processing in the Apache HTTP Server 2.x

Available Languages:  en 


    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.

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


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


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

    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:

    if ((access_status = ap_run_access_checker(r)) != 0) {
    return decl_die(access_status, "check access", r);
}

if ((access_status = ap_run_check_user_id(r)) != 0) {
    return decl_die(access_status, "check user", r);
}

if ((access_status = ap_run_auth_checker(r)) != 0) {
    return decl_die(access_status, "check authorization", r);
}



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.
    


Available Languages:  en 

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