<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_lua.xml.meta">

<name>mod_lua</name>

<description>Provides Lua hooks into various portions of the httpd

request processing</description>

<status>experimental</status>

<sourcefile>mod_lua.c</sourcefile>

<identifier>lua_module</identifier>

<compatibility>2.4 and later</compatibility>

<summary>

<p>Someone needs to write this.</p>

</summary>

<section id="basicconf"><title>Basic Configuration</title>

The basic module loading directive is

<example>

LoadModule apreq_module modules/mod_apreq2.so<br />

LoadModule wombat_module modules/mod_wombat.so

</example>

<p>

<code>mod_lua</code> provides a handler named <code>lua-script</code>,

which can be used with an <code>AddHandler</code> directive:</p>

<example>

AddHandler lua-script .lua

</example>

<p>

This will cause any <code>.lua</code> file to be evaluated by

<code>mod_lua</code>.

</p>

</section>

<section id="writinghandlers"><title>Writing Handlers</title>

<p><code>mod_lua</code> always looks to invoke a function for the handler, rather than

just evaluating a script body CGI style. A handler function looks

something like this:</p>

<example><title>example.lua</title><pre>

require "string"

function handle_something(r)

r.content_type = "text/plain"

r:puts("Hello Lua World!\n")

if r.method == 'GET' then

for k, v in pairs( r:parseargs() ) do

r:puts( string.format("%s: %s", k, v) )

end

elseif r.method == 'POST' then

for k, v in pairs( r:parsebody() ) do

r:puts( string.format("%s: %s", k, v) )

end

else

r:puts("unknown HTTP method " .. r.method)

end

end

</pre></example>

<p>

This handler function just prints out the uri or form encoded

arguments to a plaintext page.

</p>

<p>

This means (and in fact encourages) that you can have multiple

handlers (or hooks, or filters) in the same script.

</p>

</section>

<section id="datastructures"><title>Data Structures</title>

<dl>

<dt>request_rec</dt>

<dd>

<p>The request_rec is mapped in as a userdata. It has a metatable

which lets you do useful things with it. For the most part it

has the same fields as the request_rec struct (see httpd.h

until we get better docs here) many of which are writeable as

well as readable, and has (at least) the following methods:</p>

<example>

r:puts("hello", " world", "!") -- print to response body

</example>

</dd>

</dl>

</section>

<section id="logging"><title>Logging Functions</title>

<example>

r:debug("This is a debug log message")<br />

r:info("This is an info log message")<br />

r:notice("This is an notice log message")<br />

r:warn("This is an warn log message")<br />

r:err("This is an err log message")<br />

r:alert("This is an alert log message")<br />

r:crit("This is an crit log message")<br />

r:emerg("This is an emerg log message")<br />

</example>

</section>

<directivesynopsis>

<name>LuaRoot</name>

<description>Specify the base path for resolving relative paths for mod_lua directives</description>

<syntax>LuaRoot /path/to/a/directory</syntax>

<usage>

<p>Specify the base path which will be used to evaluate all

relative paths within mod_wombat. If not specified they

will be resolved relative to the current working directory,

which may not always work well for a server.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaScope</name>

<description>One of once, request, conn, server -- default is once</description>

<syntax>LuaScope once|request|conn|server [max|min max]</syntax>

<usage>

<p>Specify the lifecycle scope of the Lua interpreter which will

be used by handlers in this "Directory." The default is "once"</p>

<dl>

<dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>

<dt>request:</dt> <dd>use the interpreter to handle anything based on

the same file within this request, which is also

request scoped.</dd>

<dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>

<dt>server:</dt> <dd>This one is different than others because the

server scope is quite long lived, and multiple threads

will have the same server_rec. To accommodate this

server scoped interpreter are stored in an apr

resource list. The min and max arguments are intended

to specify the pool size, but are unused at this time.</dd>

</dl>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaMapHandler</name>

<description>Map a path to a lua handler</description>

<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>

<usage>

<p>This directive matches a uri pattern to invoke a specific

handler function in a specific file. It uses PCRE regular

expressions to match the uri, and supports interpolating

match groups into both the file path and the function name

be careful writing your regular expressions to avoid security

issues.</p>

<example><title>Examples:</title>

LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2

</example>

<p>This would match uri's such as /photos/show?id=9

to the file /scripts/photos.lua and invoke the

handler function handle_show on the lua vm after

loading that file.</p>

<example>

LuaMapHandler /bingo /scripts/wombat.lua

</example>

<p>This would invoke the "handle" function, which

is the default if no specific function name is

provided.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaPackagePath</name>

<description>Add a directory to lua's package.path</description>

<syntax>LuaPackagePath /path/to/include/?.lua</syntax>

<usage><p>Add a path to lua's module search path. Follows the same

conventions as lua. This just munges the package.path in the

lua vms.</p>

<example><title>Examples:</title>

LuaPackagePath /scripts/lib/?.lua<br />

LuaPackagePath /scripts/lib/?/init.lua

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaPackageCPath</name>

<description>Add a directory to lua's package.cpath</description>

<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>

<usage>

<p>Add a path to lua's shared library search path. Follows the same

conventions as lua. This just munges the package.cpath in the

lua vms.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaCodeCache</name>

<description>Configure the compiled code cache.</description>

<syntax>LuaCodeCache stat|forever|never</syntax>

<usage><p>

Specify the behavior of the in-memory code cache. The default

is stat, which stats the top level script (not any included

ones) each time that file is needed, and reloads it if the

modified time indicates it is newer than the one it has

already loaded. The other values cause it to keep the file

cached forever (don't stat and replace) or to never cache the

file.</p>

<p>In general stat or forever is good production and stat or never

for deveopment.</p>

<example><title>Examples:</title>

LuaCodeCache stat<br />

LuaCodeCache forever<br />

LuaCodeCache never<br />

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookTranslateName</name>

<description>Provide a hook for the translate name phase of request processing</description>

<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>

Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of

request processing. The hook function receives a single

argument, the request_rec, and should return a status code,

which is either an HTTP error code, or the constants defined

in the apache2 module: apache2.OK, apache2.DECLINED, or

apache2.DONE. </p>

<p>For those new to hooks, basically each hook will be invoked

until one of them returns apache2.OK. If your hook doesn't

want to do the translation it should just return

apache2.DECLINED. If the request should stop processing, then

return apache2.DONE.</p>

<p>Example:</p>

<example>

LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper<br />

<br />

-- /scripts/conf/hooks.lua --<br />

function silly_mapper(r)<br />

if r.uri == "/" then<br />

r.file = "/var/www/home.lua"<br />

return apache2.OK<br />

else<br />

return apache2.DECLINED<br />

end<br />

end<br />

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookFixups</name>

<description>Provide a hook for the fixups phase of request

processing</description>

<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>

Just like LuaHookTranslateName, but executed at the fixups phase

</directivesynopsis>

<directivesynopsis>

<name>LuaHookMapToStorage</name>

<description>Provide a hook for the map_to_storage phase of request processing</description>

<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>...</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookCheckUserID</name>

<description>Provide a hook for the check_user_id phase of request processing</description>

<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>...</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookTypeChecker</name>

<description>Provide a hook for the type_checker phase of request processing</description>

<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>...</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookAuthChecker</name>

<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>...</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookAccessChecker</name>

<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>...</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookAuthChecker</name>

<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>...</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaHookInsertFilter</name>

<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>

<usage><p>Not Yet Implemented</p></usage>

</directivesynopsis>

<directivesynopsis>

<name>LuaQuickHandler</name>

<description>Provide a hook for the quick handler of request processing</description>

<syntax></syntax>

<usage><p>...</p></usage>

</directivesynopsis>

</modulesynopsis>