Apache Handlers

A
pache handles HTTP requests in stages. The functions responsible for each stage are called handlers. Apache modules can register handlers for various processing stages.

When a handler is invoked, it has a single argument: the request object. This object contains all information about the current request, such as the method, URI, headers, hostname, etc. In some stages, the handler is expected to fill in fields in the request object. For example, one processing stage involves the translation of the URI from the request (e.g., /docs/misc/API.html) into a filename (e.g., /usr/www/docs/docs/misc/API.html). The handler at this stage is responsible for calculating the filename and inserting it into the correct field in the request object.

A handler can have one of three outcomes. It can:

  • handle the stage,
  • decline to handle the stage, or
  • signal an error condition.
When a handler handles its stage, processing proceeds immediately to the next stage. If a handler declines to handle a stage, Apache finds another handler for the same stage. Apache's built-in handlers are the handlers of last resort, and will not decline. A handler may also signal an error condition (such as 404 Not Found or 500 Internal Server Error), in which case Apache begins construction of an error page (and may invoke more handlers in the process).

When thinking about handlers, keep in mind that Apache is a preforked server, meaning that there are many independent Apache processes running at any time, and an incoming request could go to any one of those processes. So two requests, even if they are from the same user, may go to two entirely different processes. This makes it impossible to store any information about a user within a handler. In this site, all such information is stored in the database, which is shared among all Apache processes.

More information on Apache handlers is available in the Apache API notes. The mod_python documentation also has a nice overview of Apache handlers.