<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:lighttpd.net:lighttpd2/doc1">
	<short>track connection progress (state) via a unique identifier</short>

	<description><markdown><![CDATA[
		mod_progress lets you track connection progress (or rather state) using a lookup table in which connections are registered via a random unique identifier specified with the request.  
		It is most commonly used to implement progress bars for file uploads.

		A request to the webserver is registered using the `progress.track` action and being tracked by a random unique identifier supplied with the `X-Progress-Id` querystring parameter.  
		From that moment on, other requests can fetch the state of the first request through the `progress.show` action specifying the `X-Progress-Id` used earlier.  
		Even after a tracked request finished and the connection to the client is gone, requests can for a limited amount of time get the status of it to see it as "done".

		Check the source code there for further insight.
	]]></markdown></description>


	<setup name="progress.ttl">
		<short>Time to live in seconds for entries after a disconnect in the internal lookup table</short>
		<parameter name="ttl">
			<short>time to live in seconds (default: 30)</short>
		</parameter>
	</setup>

	<option name="progress.methods">
		<short>Request methods to track</short>
		<parameter name="methods" />
		<default><value>("POST")</value></default>
		<example>
			<config><![CDATA[
				setup {
					module_load "mod_progress";
					progress.methods ("PUT", "POST");
				}
			]]></config>
		</example>
	</option>

	<action name="progress.track">
		<short>tracks the current request if the X-Progress-ID querystring key is supplied</short>
	</action>

	<action name="progress.show">
		<short>returns state information about the request tracked with the ID specified by the X-Progress-ID querystring parameter</short>
		<parameter name="format">
			<short>(optional) output format, one of "legacy", "json" or "jsonp". Defaults to "json".</short>
		</parameter>
		<description><markdown><![CDATA[
			Output formats:

			* legacy: `new Object({"state": "running"", "received": 123456, "sent": 0, "request_size": 200000, "response_size": 0})`
			* json: `{"state": "running", "received": 123456, "sent": 0, "request_size": 200000, "response_size": 0}`
			* jsonp: `progress({"state": "running", "received": 123456, "sent": 0, "request_size": 200000, "response_size": 0})`  
				The function name (default "progress") can be altered by supplying a X-Progress-Callback querystring parameter.

			The JSON object can contain the following members:

			* **state**: One of `"unknown"`, `"running"`, `"done"` or `"error"`.
			* **received**: Bytes received by lighty or uploaded by the client.
			* **request_size**: Total size of request or uploaded file as specified via the Content-Length request header.
			* **sent**: Bytes sent by lighty or downloaded by the client.
			* **response_size**: Total size of response. Attention: this might grow over time in case of streaming from a backend.
			* **status**: HTTP status code of response.

			`received`, `request_size`, `sent` and `response_size` are only available if `state` is `"running"` or `"done"`.
			`status` is only available if `state` is `"error"`.
		]]></markdown></description>

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

				if req.path == "/upload.php" { progress.track; }
				if req.path == "/progress" { progress.show; }
			]]></config>
		</example>
	</action>

	<option name="progress.debug">
		<short>enable debug output</short>
		<default><value>false</value></default>
	</option>

</module>
