msys.registerModule
Name
msys.registerModule — Register a Lua module with the system.
Synopsis
msys.registerModule(modname, table);
modname: string table: table
Description
Register a Lua module with the system. The first parameter is the name of the module. This is currently only used in error messages, but should be unique by module for future expansion. The module name should match the name you set in the script stanza within the script module. The second parameter is a function table; the keys of the table correspond to defined callouts. The idiom for registering a module is:
require("msys.core")
local mod = {};
function mod:validate_ehlo(str, accept, vctx)
print("ehlo string is:", msys.expandMacro("%{vctx_conn:ehlo_string}"));
return msys.core.VALIDATE_CONT;
end
msys.registerModule("ehlo_phase", mod);
The predefined functions are:
-
init()
-
deinit()
-
validate_connect(accept, vctx)
-
validate_ehlo(str, accept, vctx)
-
validate_mailfrom(str, accept, vctx)
-
validate_rcptto(msg, str, accept, vctx)
-
validate_data(msg, accept, vctx)
-
validate_data_spool(msg, accept, vctx)
-
validate_data_spool_each_rcpt(msg, accept, vctx)
-
validate_set_binding(msg)
-
validate_rcptto_list(list_node, vctx)
-
validate_rcptto_list_final(node, vctx)
-
validate_dealloc()
init Registration point for long-lived state, such as timed events or control functions. You should avoid using the init routine unless necessary, as it ties up an additional interpreter on the main scheduler thread. In the current architecture, things set up via the init routine have strong thread affinity with the scheduler thread and are not suitable for scheduling jobs to thread pools. The init event occurs when the script module's init routine is called. A configuration reload should suffice to trigger this event.
The init routine must return true if it successfully initializes. Any other return value results in a failure to apply the configuration.
deinit is the resource destruction point for things that were set up via the init routine. It must return true if it was successful, otherwise it can result in resources not being cleaned up.
validate_dealloc() maps to the validate_local_dealloc function from the validation subsystem. validate_dealloc() is only invoked if defined and if an earlier phase of processing invoked Lua code from this module. Its purpose is to allow your code a chance to act when the validate_context is torn down. If you used "self" in an earlier validation phase, it will be available in this function. You do not (and should not) need to define this callback unless you are doing something esoteric and accessing resources outside of the usual garbage collection mechanism. In most cases, your per-session state will be collected automatically.
Hook points may also be registered, for example:
-- reroute all mail via example.com
function mod:core_config_get_message_routing_domain(scope, msg, buff)
buff:set("example.com");
return #buff;
end
When invoking hooks, if the hook is defined as having a char * parameter followed by an int parameter, then the pair will be used to construct an ec_string object that uses the string as the storage with a maximum length as given by the integer parameter. This allows modification of the string without ambiguity of the ownership of the associated memory.
Because this function is in the msys namespace, an explicit require is not necessary.