lighttpd2/doc/mod_lua.xml

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:lighttpd.net:lighttpd2/doc1">
	<short>load lua plugins and actions</short>

	<description>
		<textile><![CDATA[
			Also see "Lua API":core_lua.html#core_lua.
		]]></textile>
	</description>

	<setup name="lua.plugin">
		<short>load file as lua plugin</short>
		<parameter name="filename">
			<short>the file containing the lua code</short>
		</parameter>
		<parameter name="options">
			<short>A key-value table with options; no options available yet</short>
		</parameter>
		<parameter name="lua-args">
			<short>arguments forwarded to the lua plugin</short>
		</parameter>
		<description>
			<textile>
				A lua plugin can register setup and action callbacks (like any C module) by creating a setups / actions table in the global lua namespace.

				The filename and the third argument @lua-args@ are available as parameters in @...@ in the lua script.
			</textile>
		</description>
		<example>
			<config>
				setup {
					module_load "mod_lua";
					lua.plugin "secdownload.lua";
				}
			</config>
		</example>
	</setup>

	<example title="Example plugin" anchor="#">
		<description><textile>
			(see "contrib/core.lua":http://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib/core.lua for a real example)
		</textile></description>

		<config>
			local filename, args = ...

			-- args are from the lua.plugin line

			local function simple(actionarg)
				-- actionarg is the parameter from the 'single "/xxx";' action line

				-- create an action:
				return action.respond()
			end

			actions = {
				["simple"] = simple,
			}
		</config>
	</example>

	<action name="lua.handler">
		<short>load file as lua config</short>
		<parameter name="filename">
			<short>the file containing the lua code</short>
		</parameter>
		<parameter name="options">
			<table>
				<entry name="ttl">
					<short>time in seconds after which the file is checked for modifications and reloaded. 0 disables reloading (default 0)</short>
				</entry>
			</table>
		</parameter>
		<parameter name="lua-args">
			<short>arguments forwarded to the lua plugin</short>
		</parameter>
		<description>
			<textile>
				lua.handler is basically the same as "include_lua":core_config.html#core_config__includes with the following differences:
				* each worker loads the lua file itself
				* it isn't loaded before it is used, so you won't see errors in the script at load time
				* it cannot call setup functions
				* it supports arguments to the script (@local filename, args = ...@)
				* doesn't lock the global lua lock, so it performs better when you use multiple workers

				See "contrib/core.lua":http://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib/core.lua for how we load some external actions like "contrib/core__xsendfile.lua":http://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib/core__xsendfile.lua
			</textile>
		</description>
		<example>
			<config>
				setup {
					module_load "mod_lua";
					lua.plugin "secdownload.lua";
				}

				if req.path =^ "/app" {
					lua.handler "/etc/lighttpd/pathrewrite.lua", [ "ttl" => 300 ], "/app";
				}
			</config>
		</example>
	</action>
</module>