mod_progress¶

• mod_progress
• Description
• Setup Actions
• Options
• Actions
• Example Config

Description¶

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 the 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.

Setup Actions¶

• progress.ttl <duration>
  Sets the time to live in seconds for entries after a disconnect in the internal lookup table. Defaults to 30 seconds.
  Example: progress.ttl 60;

Options¶

• progress.methods = <methods>
  Defines which request methods should be tracked. Defaults to POST only.
  Example: progress.methods = ("GET", "POST");
• progress.debug = <true|false>
  If enabled, debug output is written to the log for progress.track and progress.show actions.
  Useful while implementing the website code. Defaults to false.
  Example: progress.debug = true;

Actions¶

• progress.track
  Tracks the current request if the X-Progress-ID querystring key is supplied. If the request finishes, the state information is kept for progress.ttl seconds.
  Example: progress.track;
• progress.show [format]
  Returns state information about the request tracked by the ID specified by X-Progress-ID.
  An optional format parameter can be one of "legacy", "json" or "jsonp". Defaults to "json".
  Example output depending on format:
  • 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 (here "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".

Example Config¶

setup {
    module_load "mod_progress";
}

if req.path == "/upload.php" { progress.track; }
if req.path == "/progress" { progress.show; }