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

	<description><markdown><![CDATA[
		Also see [Lua API](core_lua.html#core_lua).
	]]></markdown></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><markdown>
			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.
		</markdown></description>
		<example>
			<config>
				setup {
					module_load "mod_lua";
					lua.plugin "secdownload.lua";
				}
			</config>
		</example>
	</setup>

	<example title="Example plugin" anchor="#">
		<description><markdown>
			(see [contrib/core.lua](https://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib/core.lua) for a real example)
		</markdown></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><markdown>
			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](https://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib/core.lua) for how we load some external actions like [contrib/core__xsendfile.lua](https://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib/core__xsendfile.lua).
		</markdown></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>
