upr - Upload Progress for Rack

upr is Rack middleware that allows browser-side upload progress monitoring. It is based on (and should be client-side compatible with) several upload progress modules including ones used by leading web servers. It allows any Moneta backing store in addition to DRb. There is also a packaged example for using an ActiveRecord model for Rails.

Web Server Compatibility

While upr is completely Rack::Lint-compatible, upr is only compatible with Rack web servers that support a streaming “rack.input“. Currently this is limited to Rainbows! with a handful of concurrency models:

For use with Revactor, the use of network-based Moneta stores or DRb is only advised if those stores are using Revactor-aware sockets.

Likewise, with the *FiberSpawn and FiberPool models, any network based stores should be using the wrapper class Rainbows::Fiber::IO

JavaScript/CSS/HTML Compatibility

The current developer does not react well with GUIs. Thus all (R)HTML, JavaScript and CSS example code was stolen from one of the following:

  1. mongrel_upload_progress mongrel.rubyforge.org/wiki/UploadProgress

  2. jquery-upload-progress github.com/drogus/jquery-upload-progress

  3. mongrel_streaming_upload_progress rubyforge.org/pipermail/mongrel-users/2007-July/003747.html

This means our module should also be compatible with any of these interfaces.

Contributions to enhance compatibility for more modern things like jQuery and HTML5 are very welcome. We would prefer as much as possible to NOT proliferate new AJAX sub-protocols and use existing ones whenever possible. Our current favorite is the Ajax.Pull JavaScript used in ry dahl’s mongrel_streaming_upload_progress because it only requires a one extra HTTP request to pull all the status notifications.

Backend Compatibility

We depend on Moneta, which allows the use of a multitude of key-value stores. We also provide a DRb+Moneta::Memory server to ease transitions from mongrel_upload_progress.

Additionally, there is an example for using Rails ActiveRecord as a backend storage mechanism. Cookie-based upload tracking may eventually be used, too (contributions very welcome).

Proxy Compatibility

No proxy is required when used with Rainbows!

The only incompatible HTTP proxy we know of is nginx. nginx will buffer large requests to the filesystem before sending them to the backend. nginx has its own 3rd-party module for upload progress and may be used instead of upr.

Most other HTTP-aware and all TCP-only proxies should be compatible. Disabling Nagle’s algorithm in both the Rack web server and proxy is advised for lower latency, especially with stunnel.

Unicorn Compatibility

While Unicorn provides the streaming “rack.input“ for Rainbows!, using Unicorn with upr is generally NOT recommended. Unicorn only supports fast clients and progress reporting is unnecessary unless clients are uploading files that are hundreds of megabyte in size or larger.

Getting Started

  gem install upr

For Rails, look at the Rails application example and RDoc. More documentation is on the way.

Disclaimer

There is NO WARRANTY whatsoever if anything goes wrong, but let us know and we’ll try our best to fix it.

License

upr is copyright 2009 by all contributors (see logs in git). It is based on mongrel_upload_progress and carries the same license (Ruby + GPL2). Bundled examples may different Free Software licenses, see the included LICENSE file for details.

upr is 100% Free Software. We will never support the proliferation of non-Free browsers or plugins.

Contact

All feedback (bug reports, user/development dicussion, patches, pull requests) go to the mailing list/newsgroup. Patches must be sent inline (git format-patch -M + git send-email). No top posting.

To subscribe or post to the mailing list, just send an email to upr@librelist.com and follow the instructions in the automated reply.

We will adhere to mostly the same conventions for patch submissions as git itself. See the Documentation/SubmittingPatches document distributed with git on on patch submission guidelines to follow. Just don’t email the git mailing list with upr patches :)

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.