mod_lua.xml revision 6b4cd1f143d5d7244d2476d1e28456212faddb72
fb51a6b789d85113d0976148685b0063c294220drbowen<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
77a0265761f1bec2aaa0b4116c644f8066e349e3rbowen<!-- $LastChangedRevision$ -->
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen Licensed to the Apache Software Foundation (ASF) under one or more
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen contributor license agreements. See the NOTICE file distributed with
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen this work for additional information regarding copyright ownership.
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen The ASF licenses this file to You under the Apache License, Version 2.0
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen (the "License"); you may not use this file except in compliance with
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen the License. You may obtain a copy of the License at
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen Unless required by applicable law or agreed to in writing, software
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen distributed under the License is distributed on an "AS IS" BASIS,
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen See the License for the specific language governing permissions and
b07b82e44c32825d6226ee801d2ed91555e593d1rbowen limitations under the License.
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<description>Provides Lua hooks into various portions of the httpd
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenrequest processing</description>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<section id="basicconf"><title>Basic Configuration</title>
889dc1728817c1c56d0c8d894c768614e346d86ecovenerThe basic module loading directive is
fb51a6b789d85113d0976148685b0063c294220drbowen<code>mod_lua</code> provides a handler named <code>lua-script</code>,
fb51a6b789d85113d0976148685b0063c294220drbowenwhich can be used with an <code>AddHandler</code> directive:</p>
3e30fa5f420fe7302a4cdcd79cb001958fd54a13rbowenAddHandler lua-script .lua
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenThis will cause any <code>.lua</code> file to be evaluated by
fb51a6b789d85113d0976148685b0063c294220drbowen<section id="writinghandlers"><title>Writing Handlers</title>
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen<p><code>mod_lua</code> always looks to invoke a function for the handler, rather than
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowenjust evaluating a script body CGI style. A handler function looks
fb51a6b789d85113d0976148685b0063c294220drbowensomething like this:</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier require "string"
4b2d52ed83bf31730c8b6bbe7c06d806dc3a0c4erbowen function handle_something(r)
92e5d4326ae44f79da5cb049470daba604506846poirier r:puts("Hello Lua World!\n")
92e5d4326ae44f79da5cb049470daba604506846poirier if r.method == 'GET' then
fb51a6b789d85113d0976148685b0063c294220drbowen for k, v in pairs( r:parseargs() ) do
fb51a6b789d85113d0976148685b0063c294220drbowen r:puts( string.format("%s: %s", k, v) )
889dc1728817c1c56d0c8d894c768614e346d86ecovener elseif r.method == 'POST' then
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim for k, v in pairs( r:parsebody() ) do
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim r:puts( string.format("%s: %s", k, v) )
889dc1728817c1c56d0c8d894c768614e346d86ecovener r:puts("unknown HTTP method " .. r.method)
92e5d4326ae44f79da5cb049470daba604506846poirierThis handler function just prints out the uri or form encoded
92e5d4326ae44f79da5cb049470daba604506846poirierarguments to a plaintext page.
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jimThis means (and in fact encourages) that you can have multiple
cf7d90693f7579700c4f7e663adb83196f903df1covenerhandlers (or hooks, or filters) in the same script.
92e5d4326ae44f79da5cb049470daba604506846poirier<section id="datastructures"><title>Data Structures</title>
92e5d4326ae44f79da5cb049470daba604506846poirier <p>The request_rec is mapped in as a userdata. It has a metatable
92e5d4326ae44f79da5cb049470daba604506846poirier which lets you do useful things with it. For the most part it
92e5d4326ae44f79da5cb049470daba604506846poirier has the same fields as the request_rec struct (see httpd.h
92e5d4326ae44f79da5cb049470daba604506846poirier until we get better docs here) many of which are writeable as
92e5d4326ae44f79da5cb049470daba604506846poirier well as readable, and has (at least) the following methods:</p>
92e5d4326ae44f79da5cb049470daba604506846poirier r:puts("hello", " world", "!") -- print to response body
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<section id="logging"><title>Logging Functions</title>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:debug("This is a debug log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:info("This is an info log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:notice("This is an notice log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:warn("This is an warn log message")<br />
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen r:err("This is an err log message")<br />
92e5d4326ae44f79da5cb049470daba604506846poirier r:alert("This is an alert log message")<br />
92e5d4326ae44f79da5cb049470daba604506846poirier r:crit("This is an crit log message")<br />
889dc1728817c1c56d0c8d894c768614e346d86ecovener r:emerg("This is an emerg log message")<br />
889dc1728817c1c56d0c8d894c768614e346d86ecovener<directivesynopsis>
92e5d4326ae44f79da5cb049470daba604506846poirier<description>Specify the base path for resolving relative paths for mod_lua directives</description>
92e5d4326ae44f79da5cb049470daba604506846poirier <p>Specify the base path which will be used to evaluate all
92e5d4326ae44f79da5cb049470daba604506846poirier relative paths within mod_wombat. If not specified they
bb57315f942d09c744543fe41e453bd0181fd93ecovener will be resolved relative to the current working directory,
bb57315f942d09c744543fe41e453bd0181fd93ecovener which may not always work well for a server.</p>
bb57315f942d09c744543fe41e453bd0181fd93ecovener</directivesynopsis>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<directivesynopsis>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<description>One of once, request, conn, server -- default is once</description>
bb57315f942d09c744543fe41e453bd0181fd93ecovener<syntax>LuaScope once|request|conn|server [max|min max]</syntax>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <p>Specify the lifecycle scope of the Lua interpreter which will
bb57315f942d09c744543fe41e453bd0181fd93ecovener be used by handlers in this "Directory." The default is "once"</p>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
bb57315f942d09c744543fe41e453bd0181fd93ecovener <dt>request:</dt> <dd>use the interpreter to handle anything based on
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim the same file within this request, which is also
bb57315f942d09c744543fe41e453bd0181fd93ecovener request scoped.</dd>
8e9a311b466b8a3d2782af71a432a6a7ee2cd2f0covener <dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
92e5d4326ae44f79da5cb049470daba604506846poirier <dt>server:</dt> <dd>This one is different than others because the
92e5d4326ae44f79da5cb049470daba604506846poirier server scope is quite long lived, and multiple threads
92e5d4326ae44f79da5cb049470daba604506846poirier will have the same server_rec. To accommodate this
92e5d4326ae44f79da5cb049470daba604506846poirier server scoped interpreter are stored in an apr
92e5d4326ae44f79da5cb049470daba604506846poirier resource list. The min and max arguments are intended
92e5d4326ae44f79da5cb049470daba604506846poirier to specify the pool size, but are unused at this time.</dd>
92e5d4326ae44f79da5cb049470daba604506846poirier</directivesynopsis>
92e5d4326ae44f79da5cb049470daba604506846poirier<directivesynopsis>
92e5d4326ae44f79da5cb049470daba604506846poirier<description>Map a path to a lua handler</description>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<syntax>LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]</syntax>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen <p>This directive matches a uri pattern to invoke a specific
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen handler function in a specific file. It uses PCRE regular
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen expressions to match the uri, and supports interpolating
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen match groups into both the file path and the function name
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen be careful writing your regular expressions to avoid security
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim issues.</p>
92e5d4326ae44f79da5cb049470daba604506846poirier LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier handler function handle_show on the lua vm after
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier loading that file.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>This would invoke the "handle" function, which
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier is the default if no specific function name is
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier provided.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
fc57cc74ee4e73618f74a7a62ea6ac77546666dacovener<description>Add a directory to lua's package.path</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaPackagePath /path/to/include/?.lua</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <usage><p>Add a path to lua's module search path. Follows the same
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier conventions as lua. This just munges the package.path in the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier lua vms.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Add a directory to lua's package.cpath</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaPackageCPath /path/to/include/?.soa</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>Add a path to lua's shared library search path. Follows the same
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier conventions as lua. This just munges the package.cpath in the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier lua vms.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Configure the compiled code cache.</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier Specify the behavior of the in-memory code cache. The default
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier is stat, which stats the top level script (not any included
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier ones) each time that file is needed, and reloads it if the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier modified time indicates it is newer than the one it has
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier already loaded. The other values cause it to keep the file
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier cached forever (don't stat and replace) or to never cache the
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>In general stat or forever is good production and stat or never
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier for deveopment.</p>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaCodeCache stat<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaCodeCache forever<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaCodeCache never<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the translate name phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookTranslateName /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier request processing. The hook function receives a single
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier argument, the request_rec, and should return a status code,
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier which is either an HTTP error code, or the constants defined
92e5d4326ae44f79da5cb049470daba604506846poirier in the apache2 module: apache2.OK, apache2.DECLINED, or
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier <p>For those new to hooks, basically each hook will be invoked
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier until one of them returns apache2.OK. If your hook doesn't
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier want to do the translation it should just return
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier apache2.DECLINED. If the request should stop processing, then
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier function silly_mapper(r)<br />
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the fixups phase of request
249cc9b3d83d3c60666269b90ecb9f1390d32165poirierprocessing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookFixups /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier Just like LuaHookTranslateName, but executed at the fixups phase
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the map_to_storage phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookMapToStorage /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the check_user_id phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookCheckUserID /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<description>Provide a hook for the type_checker phase of request processing</description>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookTypeChecker /path/to/lua/script.lua hook_function_name</syntax>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookAccessChecker /path/to/lua/script.lua hook_function_name</syntax>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<directivesynopsis>
249cc9b3d83d3c60666269b90ecb9f1390d32165poirier<syntax>LuaHookAuthChecker /path/to/lua/script.lua hook_function_name</syntax>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<syntax>LuaHookInsertFilter /path/to/lua/script.lua hook_function_name</syntax>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
92e5d4326ae44f79da5cb049470daba604506846poirier<directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen<description>Provide a hook for the quick handler of request processing</description>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</directivesynopsis>
e27eee5caa6c1bf3853c11253ae82303cff0e40brbowen</modulesynopsis>