diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 96 |
1 files changed, 96 insertions, 0 deletions
@@ -0,0 +1,96 @@ += upr - Upload Progress for Rack + +upr is Rack middleware that allows browser-side upload progress +monitoring. It is based on the "mongrel_upload_progress" module, but +allows any Moneta-backing store in additon 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!}[http://rainbows.rubyforge.org/] with a +handful of concurrency models: + +* ThreadSpawn +* ThreadPool +* Revactor* + +For use with Revactor, the use of network-based Moneta stores or DRb is +only advised if those stores are using Revactor-aware sockets. + +== JavaScript/HTML Compatibility + +The current developer does not react well with GUIs. Thus all (R)HTML +and Prototype JavaScript code was stolen from mongrel_upload_progress. +Contributions to add compatibility to newer JavaScript frameworks such +as JQuery and browsers are very welcome. + +== Backend Compatibility + +We depend on {Moneta}[http://github.com/wycats/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}[http://wiki.nginx.org/NginxHttpUploadProgressModule] +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}[http://unicorn.bogomips.org/] 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}[http://git.bogomips.org/cgit/upr.git/tree/examples/rails_app-2.3.4] +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). See the included LICENSE file for details. + +upr is 100% Free Software. + +== 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. + +* email: mailto:upr@librelist.com (follow instructions) +* git: git://git.bogomips.org/upr.git +* cgit: http://git.bogomips.org/cgit/upr.git + +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 :) |