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.

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

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

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

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

5. 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 filter level.

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

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

8. The Content Type Module, type MODULE_TYPES
   
   

   The 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 file accessed.

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

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

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

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