The ModSnakePyMod API is a specialized API available to callbacks within PyMods, called from mod_snake. Occasionally a ModSnakePyMod object will be passed into a PyMod's callback function. This object has special attributes and methods for dictating how a PyMod will interact with the Apache server.
ModSnakePyMod.add_hook( hookname, hookfunc)
Valid within the __init__ method of the PyMod's object class.
hookname - (type String) a hook name from the hook table in Table 1
hookfunc - (type Callable) a function to call when the given hookname phase is reached by the server.
This routine registers hooks that Apache can call at designated time. A ModSnakePyMod is passed into the __init__ method via mod_snake. The hookname can be a variety of strings, each cooresponding to a different hook phase within Apache. The hookfunc is the callback function to call whenever the phase cooresponding to hookname is reached. In the subsequent sections, when referring to any specific hook (i.e. 'create_dir_config') the reference is to the actual function (hookfunc) associated with it by the PyMod.
Table 1. Mod Snake/Apache Hooks
Hook Name | Apache Equivalent |
---|---|
create_dir_config | The per-dir creation function within the module record |
merge_dir_config | The per-dir merge function within the module record |
create_svr_config | The per-server creation function within the module record |
merge_svr_config | The per-server merge function within the module record |
post_config | ap_hook_post_config |
open_logs | ap_hook_open_logs |
pre_connection | ap_hook_pre_connection |
process_connection | ap_hook_process_connection |
post_read_request | ap_hook_post_read_request |
translate_name | ap_hook_translate_name |
header_parser | ap_hook_header_parser |
access_checker | ap_hook_access_checker |
check_user_id | ap_hook_check_user_id |
auth_checker | ap_hook_auth_checker |
fixups | ap_hook_fixups |
content-handler | The handler_rec structure within the module |
log_transaction | ap_hook_log_transaction |
insert_filter | ap_hook_insert_filter |
create_dir_config( path)
path - (type String or None) A path given to the PyMod, designating the association between the callback's return data and the path. This pertains to the directory that the directory config is being created for. For instance, when a .htaccess in a particular directory is read.
The PyMod may return any data it wishes from this callback. mod_snake will pass the return value from this method to a variety of other callbacks, registered by the PyMod.
Apache will call the create_dir_config callback in the PyMod whenever it is required to generate per-directory configuration data. path may be None, indicating that the path associated with this call is in a server context, and not necessarily associated with any given directory.
merge_dir_config( per_dir1, per_dir2)
per_dir1 - The base per-directory PyMod data
per_dir2 - The sub-directory per-directory PyMod data
The PyMod may return any data it wishes from this callback. If this callback is not performed, it is the same as though this callback returned per_dir2. mod_snake will pass the return value from this function to a variety of other callbacks, registered by the PyMod.
Apache occasionally gives modules the chance to combine per-directory configuration information into 1 per-dir configuration. Apache gives the base and new directory configuration information back to the module, and the module must combine them in whatever fashion it sees fit. This can be especially useful for doing fine grained configuration throughout sub-directories.
create_svr_config( svr)
svr - The server for which the configuration is being created for
The PyMod may return any data it wishes from this callback. mod_snake will pass the return value from this function to a variety of other callbacks, registered by the Python module.
Apache will call the create_svr_config callback in the module whenever the module is required to generate per-server configuration data.
merge_svr_config( per_svr1, per_svr2)
per_svr1 - The base per-server module data
per_svr2 - The new per-server module data
The PyMod may return any data it wishes from this callback. If this callback is not performed, it is the same as though this callback returned per_svr2. mod_snake will pass the return value from this function to a variety of other callbacks, registered by the Python module.
Apache occasionally gives modules the chance to combine per-server configuration information into 1 per-server configuration. Apache gives the base and new server configuration information back to the module, and the module must combine them in whatever fashion it sees fit.
post_config( svr_cfg)
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks
The result of post_config is not checked, nor used.
This callback is called after Apache has read the configuration file. Keep in mind that Apache does read the configuration file more than one time.
open_logs( svr_cfg, module)
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
module - (type ModSnakePyMod) a reference to the module's external representation. This can be used to obtain the current server record, etc.
The result of open_logs is not checked, nor used.
The open_logs callback will be called when Apache has finished reading the configuration and allows modules to open up logs. Module writers may want to register this hook if they intend to write their own logging routines (instead of using built in mod_snake API calls), as it gives them 'special' permission to open logfiles prior to becoming an ordinary (no-permissions) process. mod_snake passes in a ModSnakePyMod module descriptor, which the module can use at its discretion.
pre_connection( svr_cfg, conn_rec)
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
conn_rec - (type conn_rec) Information about the current connection.
The result of pre_connection is not checked, nor used.
This hook is only available when mod_snake is running on an Apache 2.0 server.
The pre_connection callback is called when Apache receives an incoming connection on a socket. All pre_connection callbacks are run until one returns a value other than OK or DECLINED.
process_connection( svr_cfg, conn_rec)
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
conn_rec - (type conn_rec) Information about the current connection.
The result of process_connection is used to determine whether further action must be performed. If the return value is OK, the connection is dropped.
This hook is only available when mod_snake is running on an Apache 2.0 server.
The process_connection callback is made directly after the pre_connection callback. All process_connection callbacks are run until one returns a value other than DECLINED.
post_read_request( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of post_read_request is one of the standard Apache hook result codes.
The post_read_request callback is executed directly after the request has been made and before any URI translation is performed. All post_read_request callbacks are executed in all modules until one returns a value other than OK or DECLINED.
translate_name( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of translate_name is one of the standard Apache hook result codes.
The translate_name callback is executed after the post_read_request callback is performed, and before the header_parsing callback is executed. During this phase a module may perform translations on the requested URI. All translate_name callbacks are executed in all modules until one returns a value other than DECLINED.
header_parser( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of header_parser is one of the standard Apache hook result codes.
The header_parser callback is made when Apache wants to give a chance to the module to validate or deny a given request. The module can inspect the values of request_rec.method to determine an appropriate course of action. All header_parser callbacks are executed in all modules until one returns a value other than OK or DECLINED.
access_checker( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of access_checker is one of the standard Apache hook result codes.
The access_checker callback is called after the header_parser stage, and gives the module an opportunity to allow or deny a request based upon whichever criteria it wishes. mod_access uses the access_checker hook in order to allow or deny requests based upon various criteria such as IP address.
check_user_id( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of check_user_id is one of the standard Apache hook result codes.
The check_user_id callback allows modules to perform user authentication before allowing them to proceed. This can be done in a variety of ways, such as a database, configuration directive, or anything the module wishes. This routine should typically return one of 3 values, HTTP_UNAUTHORIZED, OK, and DECLINED, but need not be limited by these. All check_user_id handlers are run until one returns a value other than DECLINED.
auth_checker( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of auth_checker is one of the standard Apache hook result codes.
The auth_checker callback allows modules to grant or deny access to data based upon their user data. All auth_checker handlers are run until one returns a value other than DECLINED.
type_checker( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of type_checker is one of the standard Apache hook result codes.
The type_checker callback is used to determine a MIME type for the requested document. The module can use this callback and use whatever server configuration it desires to associate a type with the requested document. This type is later used to determine which handler will be called for the type. All type_checker handlers are run until one returns a value other than DECLINED.
fixups( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of fixups is one of the standard Apache hook result codes.
The fixups callback is used as a last ditch effort by modules to tweak any headers, etc. before the request is handed off to the content-handler. mod_env uses this stage to add various environment variables before passing along the request. All fixups handlers are run until one returns something ore than OK or DECLINED.
content_handler( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of content_handler is one of the standard Apache hook result codes.
The content_handler is used to actually generate content to be returned to the client. This can range in anything from reading files on the system, to querying database entries, to formulating data from the system environment. The content_handler phase in mod_snake is slightly different than that in regular Apache, in that if a module registers with the content_handler phase, all requsets for any content will be passed into this routine. If the module does not wish to handle the request for a specific content type, it can return DECLINED. All content_handler handlers are run until one returns something other than DECLINED.
log_transaction( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of log_transaction is one of the standard Apache hook result codes.
The log_transaction handler enables modules to do any specialized logging after the request has been processed, and the content been sent to the client. All log_transaction handlers are run until one returns a value other than OK or DECLINED.
insert_filter( dir_cfg, svr_cfg, request_rec)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
request_rec - (type request_rec) Information about the incoming request.
The result of insert_filter is one of the standard Apache hook result codes.
This hook is only available when mod_snake is running on an Apache 2.0 server.
The insert_filter hook is called directly after the fixups callback. Within this hook, the PyMod can add a filter to the filter chain (See the section called add_output_filter). All insert_filter hooks are run, regardless of return value.
Hooks may return any integer value that they wish, but there are already a myriad of established return values and associated meanings. The values used internally within Apache (and thus available to modules through the mod_snake API, such as mod_snake.HTTP_UNAUTHORIZED) include:
Table 2. Standard Hook Return Values
DONE |
DECLINED |
OK |
HTTP_CONTINUE |
HTTP_SWITCHING_PROTOCOLS |
HTTP_OK |
HTTP_CREATED |
HTTP_ACCEPTED |
HTTP_NON_AUTHORITATIVE |
HTTP_NO_CONTENT |
HTTP_RESET_CONTENT |
HTTP_PARTIAL_CONTENT |
HTTP_MULTI_STATUS |
HTTP_MULTIPLE_CHOICES |
HTTP_MOVED_PERMANENTLY |
HTTP_MOVED_TEMPORARILY |
HTTP_SEE_OTHER |
HTTP_NOT_MODIFIED |
HTTP_USE_PROXY |
HTTP_TEMPORARY_REDIRECT |
HTTP_BAD_REQUEST |
HTTP_UNAUTHORIZED |
HTTP_PAYMENT_REQUIRED |
HTTP_FORBIDDEN |
HTTP_NOT_FOUND |
HTTP_METHOD_NOT_ALLOWED |
HTTP_NOT_ACCEPTABLE |
HTTP_PROXY_AUTHENTICATION_REQUIRED |
HTTP_REQUEST_TIME_OUT |
HTTP_CONFLICT |
HTTP_DONE |
HTTP_LENGTH_REQUIRED |
HTTP_PRECONDITION_FAILED |
HTTP_REQUEST_ENTITY_TOO_LARGE |
HTTP_REQUEST_URI_TOO_LARGE |
HTTP_UNSUPPORTED_MEDIA_TYPE |
HTTP_RANGE_NOT_SATISFIABLE |
HTTP_EXPECTATION_FAILED |
HTTP_UNPROCESSABLE_ENTITY |
HTTP_LOCKED |
HTTP_FAILED_DEPENDENCY |
HTTP_INTERNAL_SERVER_ERROR |
HTTP_NOT_IMPLEMENTED |
HTTP_BAD_GATEWAY |
HTTP_SERVICE_UNAVAILABLE |
HTTP_GATEWAY_TIME_OUT |
HTTP_VERSION_NOT_SUPPORTED |
HTTP_VARIANT_ALSO_VARIES |
HTTP_INSUFFICIENT_STORAGE |
HTTP_NOT_EXTENDED |
Note that DONE has the special meaning that the module has served the response completely, and no other hooks should be called, OK has the special meaning that the handler has handled a given phase, and DECLINED means that the handler did not process the stage, and that Apache should continue to look for a handler to process it.
ModSnakePyMod.add_directives( directive_dict)
Valid within the __init__ method of the module's object class.
directive_dict - A dictionary specifying the name, location, type, and callbacks for Python created configuration directives. The dictionary has the form:
{ ``DirectiveName'' : (directive_location, functype, func_ptr), ... } |
Python written modules running under mod_snake have the same ability as C written modules when it comes to creating custom configuration directives. The directive_dict contains a dictionary of directive names, and associated attributes.
DirectiveName - specifies the textual name within the Apache configuration file to trigger the modules directive handler (func_ptr). This value is case insensitive.
directive_location - Puts a limit on the locations where this directive is valid. The supported values may also be binary ORed togther to combine multiple types of locations. The current possible values are:
mod_snake.OR_LIMIT - The directive is valid in the main configuration file inside <directory> and <Location> blocks, and also within .htaccess files when AllowOverride Limit is set.
mod_snake.OR_OPTIONS - The directive is valid anywhere in the main configuration file, and also within .htaccess files when AllowOverride Options is set.
mod_snake.OR_FILEINFO - The directive is valid anywhere in the main configuration file, and also within .htaccess files when AllowOverride FileInfo is set.
mod_snake.OR_AUTHCFG - The directive is valid in the main configuration file inside <directory> and <Location> blocks, and also within .htaccess files when AllowOverride AuthConfig is set.
mod_snake.OR_INDEXES - The directive is valid anywhere in the main configuration file, and also within .htaccess files when AllowOverride Indexes is set.
mod_snake.ACCESS_CONF - The directive is valid in the main configuration file within <directory> and <Location> blocks.
mod_snake.RSRC_CONF - The directive is valid in the main configuration file, outside of <directory> and <Location> blocks.
mod_snake.OR_ALL - The directive is valid anywhere.
functype - Designates the format that the arguments to the directive callback function take. This alleviates some of the hassle of having each module parse all of their directives manually. Note that the callback functions associated with the functype can potentially have many different declarations (especially when doing 1 or etc.).
mod_snake.RAW_ARGS - The arguments to the directive are passed in, unparsed.
func( self, dir_data, argline)
mod_snake.TAKE1 - The directive takes only one argument
func( self, dir_data, arg1)
mod_snake.TAKE2 - The directive takes exactly two arguments
func( self, dir_data, arg1, arg2)
mod_snake.ITERATE - The directive can take multiple arguments, but the associated callback function will be executed once for each argument.
func( self, dir_data, arg1)
mod_snake.ITERATE2 - The directive can take at least 2 arguments, but the second argument is iterated over, for > 2 arguments.
func( self, dir_data, arg1, arg2)
mod_snake.FLAG - The directive takes 1 argument, 'on' or 'off'. Within the module this argument is represented as true or false.
func( self, dir_data, on_or_off)
mod_snake.NO_ARGS - The directive takes no arguments
func( self, dir_data)
mod_snake.TAKE12 - The directive can take either 1 or 2 arguments
func( self, dir_data, arg1, *arg2)
mod_snake.TAKE3 - The directive takes exactly 3 arguments
func( self, dir_data, arg1, arg2, arg3)
mod_snake.TAKE23 - The directive takes either 2 or 3 arguments
func( self, dir_data, arg1, *arg23)
mod_snake.TAKE123 - The directive takes either 1, 2 or 3 arguments
func( self, dir_data, *arg123)
mod_snake.TAKE13 - The directive takes either 1 or 3 arguments
func( self, dir_data, *arg1or3)
func_ptr - A pointer to a function to call when the directive is processed within the configuration file. The function prototype must match that expected by the caller (as given by the functype). In addition, the first argument passed to func_ptr is that of a per-directory data structure, as returned by the modules create_dir_config callback, if it exists.
This attribute of the ModSnakePyMod object holds the value of the profiling object. If profiling is not enabled, this value will be None. The profiling object is an instantiation of profile.Profile class.
This attribute of the ModSnakePyMod object holds the value of the Python module containing the loaded pymod. For instance, if the pymod loaded into the server via the SnakeModule line was: SnakeModule spam.eggs, the module attribute will contain a reference to the spam module.
ModSnakePyMod.add_version_component(vers)
The HTTP header, "Server: ", returned by Apache on requests can be set to include additional information for modules loaded. This method can be used to add module data into the server string which all clients see. The string should be of the form, "module/version", such as "mod_snake/1.2.3". This routine should be called in the module's initialization phase.
ModSnakePyMod.get_hooks()
This method returns a dictionary of { hookname : funcref } pairs.
The get_hooks method looks directly within the loaded PyMod to determine which hooks it has hooked into (via add_hook). The returned value is a dictionary containing the hook name and a reference to the function which gets called for that hook.
ModSnakePyMod.register_output_filter( name, callback, type )
name - The name of the filter. This string is left to the PyMod's discretion. It distinguishes it from other filters, and allows it to be added from external means, such as httpd.conf
callback - The function which should be called when it is given its turn to process outgoing data.
type - One of mod_snake.FTYPE_CONTENT, mod_snake.FTYPE_HTTP_HEADER, mod_snake.FTYPE_TRANSCODE, mod_snake.FTYPE_CONNECTION, or mod_snake.FTYPE_NETWORK indicating when the filter should be run. Content filters are for altering content. Transcode is a special type of filter type for doing transport based encoding (chunking). Connection based filters are filters which modify content, but are done on a more connection oriented basis. Network are the lowest level filter possible -- they read/write data directly to the remote client. The aforementioned filter types are sorted in execution order, with NETWORK being the first run on input filters, and last run on output filters.
This function is only available when mod_snake is running on an Apache 2.0 server.
By using output filters, PyMods have the ability to process data written by content generators before it is sent to the remote client. This routine only needs to be called once in each module for each filter. It provides Apache with information needed to associate the textual name of the filter with the callback function.
output_filter( dir_cfg, svr_cfg, filter, brigade)
dir_cfg - Directory configuration, as returned by calls to the create_dir_config and merge_dir_config hooks.
svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks.
filter - Information about the current running filter. This object contains many attributes. See the section called filter API.
brigade - A bucket brigade of data to be filtered. See the section called brigade API
The return value should be 0 on success, -1 to indicate failure.
output_filter is only a prototype for the callback to register_output_filter. In order for this callback to ever be invoked, it must be added to the filter chain via add_output_filter.