You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

88 lines
3.7 KiB

<?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>
<textile><![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".
A live demonstration of a progress bar implementation can be seen at http://demo.lighttpd.net/progress/
Check the sourcecode there for further insight.
]]></textile>
</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>
<textile><![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"@.
]]></textile>
</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>