mod_progress track connection progress (state) via a unique identifier

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 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
Check the source code there for further insight.

progress.ttl (setup)

Time to live in seconds for entries after a disconnect in the internal lookup table

progress.ttl ttl;
time to live in seconds (default: 30)

progress.methods (option)

Request methods to track

progress.methods methods;
Default value: ("POST")


setup {
	module_load "mod_progress";
	progress.methods ("PUT", "POST");

progress.track (action)

tracks the current request if the X-Progress-ID querystring key is supplied

progress.track; (action)

returns state information about the request tracked with the ID specified by the X-Progress-ID querystring parameter format;
(optional) output format, one of "legacy", "json" or "jsonp". Defaults to "json".

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


setup {
	module_load "mod_progress";

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

progress.debug (option)

enable debug output

progress.debug value;
Default value: false