ModSnakePyMod API

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.

add_hook

Synopsis

ModSnakePyMod.add_hook( hookname, hookfunc)

Validity

Valid within the __init__ method of the PyMod's object class.

Arguments

Description

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

Synopsis

create_dir_config( path)

Arguments

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

Return Value

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.

Description

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

Synopsis

merge_dir_config( per_dir1, per_dir2)

Arguments

  • per_dir1 - The base per-directory PyMod data

  • per_dir2 - The sub-directory per-directory PyMod data

Return Value

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.

Description

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

Synopsis

create_svr_config( svr)

Arguments

  • svr - The server for which the configuration is being created for

Return Value

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.

Description

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

Synopsis

merge_svr_config( per_svr1, per_svr2)

Arguments

  • per_svr1 - The base per-server module data

  • per_svr2 - The new per-server module data

Return Value

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.

Description

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

Synopsis

post_config( svr_cfg)

Arguments

  • svr_cfg - Server configuration, as returned by calls to the create_svr_config and merge_svr_config hooks

Return Value

The result of post_config is not checked, nor used.

Description

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

Synopsis

open_logs( svr_cfg, module)

Arguments

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

Return Value

The result of open_logs is not checked, nor used.

Description

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

Synopsis

pre_connection( svr_cfg, conn_rec)

Arguments

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

Return Value

The result of pre_connection is not checked, nor used.

Compatability

This hook is only available when mod_snake is running on an Apache 2.0 server.

Description

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

Synopsis

process_connection( svr_cfg, conn_rec)

Arguments

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

Return Value

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.

Compatability

This hook is only available when mod_snake is running on an Apache 2.0 server.

Description

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

Synopsis

post_read_request( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of post_read_request is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

translate_name( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of translate_name is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

header_parser( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of header_parser is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

access_checker( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of access_checker is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

check_user_id( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of check_user_id is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

auth_checker( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of auth_checker is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

type_checker( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of type_checker is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

fixups( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of fixups is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

content_handler( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of content_handler is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

log_transaction( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of log_transaction is one of the standard Apache hook result codes.

Descriptions

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

Synopsis

insert_filter( dir_cfg, svr_cfg, request_rec)

Arguments

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

Return Value

The result of insert_filter is one of the standard Apache hook result codes.

Compatability

This hook is only available when mod_snake is running on an Apache 2.0 server.

Descriptions

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.

Standard Hook Return Values

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.

add_directives

Synopsis

ModSnakePyMod.add_directives( directive_dict)

Validity

Valid within the __init__ method of the module's object class.

Arguments

Description

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.

profile_obj

Synopsis

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.

module

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.

add_version_component

Synopsis

ModSnakePyMod.add_version_component(vers)

Description

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.

get_hooks

Synopsis

ModSnakePyMod.get_hooks()

Return Value

This method returns a dictionary of { hookname : funcref } pairs.

Description

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.

register_output_filter

Synopsis

ModSnakePyMod.register_output_filter( name, callback, type )

Arguments

Compatability

This function is only available when mod_snake is running on an Apache 2.0 server.

Description

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

Synopsis

output_filter( dir_cfg, svr_cfg, filter, brigade)

Arguments

  • 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

Return Value

The return value should be 0 on success, -1 to indicate failure.

Description

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.