<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:lighttpd.net:lighttpd2/doc1" title="mod_core (lua)" order="mod_lua:core">
	<short>provides some useful helpers written in lua</short>

	<section title="Install">
		<markdown>
			By default distributions (and `make install`) should provide the necessary files; but you can always find them in the [contrib](https://git.lighttpd.net/lighttpd/lighttpd2.git/tree/contrib) folder:

			* `core.lua`
			* `core__cached_html.lua`
			* `core__xsendfile.lua`

			That way you can modify them for your own needs if you have to (although it is recommended to change the names of the files and the actions, so you don't get conflicts).

			lighttpd should search for `core.lua` in the correct (install) locations, so you don't need the absolute path here.
		</markdown>
	</section>

	<action name="core.wsgi">
		<short>Splits the url into SCRIPT_NAME (the subdirectory a web application is mounted at) and PATH_INFO (the path the web application should route)</short>
		<parameter name="prefix">
			<short>URL prefix ("subdirectory") the web application is mounted at</short>
		</parameter>
		<parameter name="action">
			<short>action block connecting to the wsgi backend</short>
		</parameter>
		<description><markdown>
			See [Howto WSGI](https://redmine.lighttpd.net/projects/lighttpd2/wiki/Howto_WSGI) for an example.

			WSGI applications expect the url to be split into `SCRIPT_NAME` and `PATH_INFO` (CGI environment variables); `SCRIPT_NAME` is their "application root", and `PATH_INFO` the requested resource in the application.  
			By default, lighttpd uses an empty `PATH_INFO` (unless you used the "pathinfo;" action, but this doesn't help as we're not dealing with static files here).

			**Important**: WSGI is an "extension" of CGI; it doesn't specify a transport protocol, you can use it with plain CGI, FastCGI or SCGI (or anything else that supports the basic CGI protocol)
		</markdown></description>

		<example>
			<description><markdown>
				Example: Trac in `/trac`, listening via FastCGI on `unix:/var/run/lighttpd/trac.socket`.
			</markdown></description>
			<config>
				setup {
					module_load ("mod_lua", "mod_fastcgi");
					lua.plugin "core.lua";
				}
				core.wsgi ( "/trac", { fastcgi "unix:/var/run/lighttpd/trac.socket"; } );
			</config>
		</example>
	</action>

	<action name="core.cached_html">
		<short>try to find a file for the current url with ".html" suffix, if we couldn't find a static file for the url yet and the url doesn't already have the ".html" suffix.</short>
		<example>
			<config>
				setup {
					module_load "mod_lua";
					lua.plugin "core.lua";
				}
				docroot "/some/dynamic/app/public";
				core.cached_html;
				if physical.is_file {
					header.add ("X-cleanurl", "hit");
				} else {
					header.add ("X-cleanurl", "miss");
					fastcgi "/var/run/lighttpd/dynamic-app.sock";
				}
			</config>
		</example>
	</action>

	<action name="core.xsendfile">
		<short>provides a simple X-Sendfile feature; send a "X-Sendfile: /path/to/file" response header from your backend</short>
		<parameter name="docroot">
			<short>(optional) doc-root the files has be in</short>
		</parameter>
		<example>
			<config>
				setup {
					module_load ("mod_lua", "mod_fastcgi");
					lua.plugin "core.lua";
				}
				fastcgi "/var/run/lighttpd/dynamic-app.sock";
				core.xsendfile "/some/dynamic/app/";
			</config>
		</example>
	</action>

	<action name="auth.require_user">
		<short>require a specific authenticated user</short>
		<parameter name="userlist">
			<short>list of usernames to allow</short>
		</parameter>
		<description><markdown>
			This helper constructs a regular expression to match against request.environment["REMOTE_USER"], so the example below is the same as:

			```
			auth.plain [ "method" => "basic", "realm" => "test", "file" => "/etc/lighttpd2/test.plain" ];
			if req.env["REMOTE_USER"] !~ "^(foo1|foo2)$" { auth.deny; }
			```

			This action uses lua only to create the action, no lua is executed to handle requests in this case.

			Be careful: the empty username matches unauthenticated users.
		</markdown></description>
		<example>
			<config>
				setup {
					module_load "mod_lua";
					lua.plugin "core.lua";
				}
				auth.plain [ "method" => "basic", "realm" => "test", "file" => "/etc/lighttpd2/test.plain" ];
				auth.require_user ("foo1", "foo2");
			</config>
		</example>


	</action>
</module>
