<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:lighttpd.net:lighttpd2/doc1">
	<short>caches content on memcached servers</short>

	<description>
		<textile><![CDATA[
			@lookup@ tries to find data associated with the key, and returns it as http body with status 200 if it finds something.
			@store@ stores a http body (generated by another backend) in memcached.

			Caching always requires you to think about what you want; you cannot cache content that changes with every request!

			So most of the time you probably want to set a TTL for the stored content in memcached; your users probably don't need new content to be available the next second, perhaps 60 seconds is still good (obviously not true for a chat...).

			The other way is to purge the keys in your dynamic backend; you can set the memcached content from your backend too, which probably is faster than @memcached.store@.

			If the key is longer than 255 bytes or contains characters outside the range 0x21 - 0x7e we will use a hash of it instead (for now sha1, but that may change).
		]]></textile>
	</description>

	<action name="memcached.lookup">
		<short>searches the content in a memcached database</short>
		<parameter name="options">
			<table>
				<entry name="server">
					<short>socket address as string (default: 127.0.0.1:11211)</short>
				</entry>
				<entry name="headers">
					<short>(boolean, not supported yet) whether to lookup headers too. if false content-type determined by request.uri.path (default: false)</short>
				</entry>
				<entry name="key">
					<short>pattern for lookup key (default: "%{req.path}")</short>
				</entry>
			</table>
		</parameter>
		<parameter name="action-hit">
			<short>action to run on cache hit (lookup was successful)</short>
		</parameter>
		<parameter name="action-miss">
			<short>action to run on cache miss (lookup was not successful)</short>
		</parameter>
	</action>

	<action name="memcached.store">
		<short>stores the generated respone in a memcached database</short>
		<parameter name="options">
			<table>
				<entry name="server">
					<short>socket address as string (default: 127.0.0.1:11211)</short>
				</entry>
				<entry name="flags">
					<short>(integer) flags for storing data (default 0)</short>
				</entry>
				<entry name="ttl">
					<short>ttl for storing (default 30; use 0 if you want to cache "forever")</short>
				</entry>
				<entry name="maxsize">
					<short>maximum size in bytes we want to store (default: 64*1024)</short>
				</entry>
				<entry name="headers">
					<short>(boolean, not supported yet) whether to store headers too (default: false)</short>
				</entry>
				<entry name="key">
					<short>pattern for store key (default: "%{req.path}")</short>
				</entry>
			</table>
		</parameter>
	</action>

	<example>
		<config><![CDATA[
			setup {
				module_load "mod_memcached";
			}

			memcached.lookup (["key" => "%{req.scheme}://%{req.host}%{req.path}"], {
				header.add "X-Memcached" => "Hit";
			}, {
				header.add "X-Memcached" => "Miss";
				docroot "/var/www";
			#	important: You need a content handler before memcached.store
				static;
				memcached.store ["key" => "%{req.scheme}://%{req.host}%{req.path}"];
			});
		]]></config>
	</example>

	<section title="Lua API" anchor="#">
		<textile><![CDATA[
			mod_memcached exports a Lua API to per-worker @luaState@s too (for use in lua.handler):

			@memcached.new(address)@ creates a new connection; a connection provides:
			* @req = con:get(key, cb | vr)@
			* @req = con:set(key, value, cb | vr, [ttl])@
			* @con:setq(key, value, [ttl])@

			If a callback was given, the callback gets called with a response object; otherwise the response will be in req.response when ready.

			The response object has:
			* @code@: 1 - Ok, 2 - Not stored, 3 - Exists, 4 - Not found, 5 - Error
			* @error@: error message
			* @key@: the lookup key
			* @flags@
			* @ttl@
			* @cas@
			* @data@
		]]></textile>
	</section>
</module>
