The Module Type Calling Sequence
This is an in-depth rehash of the module type calling
sequence description discussed briefly earlier. As already
noted, a request generally sifts down through the various type levels,
until some module handles it or it ends up a file not found error.
A failure usually means that the request is passed on to the next
level. What happens when a module succeeds in treating the request
depends on the level, and will be described in each case.
- Protocol Modules
First off, the request in intercepted on the socket by a protocol
module. The protocol module (not located in server/modules/
as the other modules shipped with roxen; the protocol modules are
found in server/protocols/ and are spawned off from the stub
classes in server/roxen.pike) handles the low-level talking
to the client in the protocol at hand, resolves what virtual server
should handle the request, and gets the wheel rolling. The protocol
module object instance is the RequestID object which will tag along
for the rest of the request, bearing all request-local state.
- The Memory Cache
Before leaving the protocol module, sending the request forth to the
various module types, the RAM cache is checked for an already rendered
version of the page. If the cache had an equivalent entry that didn't
need to be regenerated, it gets sent right away, giving us a nice
speed boost, in comparison with the time it would take to render it
all over again. What constitutes "an equivalent entry" is covered in
greater detail where The Memory Cache is
explained. A cached request then gets promoted to the final (logging)
stage in this list, the rest sift down through the rest of the module
- Authentication Modules, type MODULE_AUTH
Next stop in the chain is the authentication module, when present. The
authentication module has a look on the request object, sets some
flags and regardless of the success or failure, the request moves on.
It is noteworthy that this level is only entered when the client sent
an authorization header, so authentication modules based on other
criteria probably also double as some other module type(s).
- First Try Modules, type MODULE_FIRST
The next class of modules that see the request are the First modules.
If a first try module would decide to handle the request on its own,
the request is passed along to the filter level further down the
- Location Modules, type MODULE_LOCATION
Still unhandled requests now undergo a check for what path was
accessed, and is then routed to location modules accordingly, until a
response is generated or there are no location modules left. After
this, a non-handled request move on to the filter level. A handled
request returning a Stdio.File object is forwarded to the extension
module level and a returned directory indicator is passed on to the
directory listing module. All other results are forwarded to the
- The Directory Listing Module, type MODULE_DIRECTORIES
The request was considered a directory, and it is up to the directory
listing module to generate some form of directory listing or
representation of the directory at hand. Regardless of success or
failure to do so, the request moves on to the filter level.
- File Extension Modules, type MODULE_FILE_EXTENSION
Stdio.File objects generated by previous levels are sent to the file
extension modules according to the filename extension of the virtual
file. File Extension modules are typically used to implement
interfacing to external processes, such as a CGI engine. Regardless of
success, the request will be passed on to the filter level.
- The Content Type Module, type MODULE_TYPES
content-type module, although mostly orthogonal to the request path
calling chain, possibly being hailed from any module, also may be
invoked automatically by roxen. This happens in the event of a
Stdio.File object being returned from the extension module level. The
content-type module is then invoked to devise a content-type for the
result based on the name of the virtual
- Filter Modules, type MODULE_FILTER
All requests then pass through the filter module stage for possible
processing of the returned data before sending away the result to the
browser. It is worth noticing that the state of the request at this
stage could differ a lot; for instance a directory listing, an open
file descriptor or even the yet unhandled request (candidate to become
a file not found message). If the request is still not handled after
the filter module stage, it is forwarded to the MODULE_LAST type
stage, otherwise it is forwarded to the protocol module once more.
- Last Modules, type MODULE_LAST
If the entire module type calling sequence passed so far has failed to
return a response, the last modules will have a final shot at catching
the request before roxen returns a file not found error. Regardless of
result, the request is forwarded from the MODULE_LAST stage to the
- Protocol Modules
The protocol module which originally set this chain going is returned
the result from previous stages and starts sending the result to the
client in response to the request.
- Logger Modules, type MODULE_LOGGER
Once the protocol module has initiated the response transfer to the
client, the logger modules get a shot at logging some information in
some way, until one of them decides that the request shall not see any
other log modules or there are no more loggers left. Since the request
has already been sent (or is just being sent), the logger modules can
not alter the response seen by the client.