uploadprogress

Track POST upload progress for progress bars

dynamic moduleBSD-2-Clausesource

Overview

nginx-upload-progress-module tracks multipart POST uploads as nginx proxies them to an upstream server. JavaScript on the upload page can poll a progress endpoint and render a progress bar while the file is still transferring.

The client tags each upload with an X-Progress-ID header or query parameter. nginx keeps received and expected byte counts in a shared memory zone and reports them on request as JSONP, plain JSON, or a custom template.

The module is written by Brice Figureau. It only observes the request as it passes through, so the upstream application needs no changes.

Key directives

upload_progressDeclares a shared memory zone in the http block that holds per-upload progress state.

track_uploadsEnables tracking for an upload location and keeps finished-upload state around for a configurable timeout; it must be the last directive in the location.

report_uploadsServes progress reports from a probe location, returning the received and total byte counts for the upload named by X-Progress-ID.

upload_progress_json_outputSwitches the report format from the default JSONP-style JavaScript to plain JSON.

upload_progress_templateCustomizes the response body per upload state (starting, uploading, done, error) using nginx variables.

Example

nginx.conf

load_module modules/ngx_http_uploadprogress_module.so; http { upload_progress uploads 1m; server { location /upload { proxy_pass http://127.0.0.1:8080; track_uploads uploads 30s; } location = /progress { report_uploads uploads; } } }

Availability

Ships as a dynamic module in libnginx-mod-http-uploadprogress, installed automatically with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.