README

   1 = upr - Upload Progress for Rack
   2
   3 upr is Rack middleware that allows browser-side upload progress
   4 monitoring.  It is based-on the "mongrel_upload_progress" module, but
   5 allows any Moneta backing store in addition to DRb.  There is also a
   6 packaged example for using an ActiveRecord model for Rails.
   7
   8 == Demo
   9
  10 You can see upr it in action at http://upr-demo.bogomips.org/
  11 It will report the size and SHA1 of the file you've uploaded.
  12 Much of the demo was stolen from mongrel_upload_progress.
  13
  14 == Web Server Compatibility
  15
  16 While upr is completely Rack::Lint-compatible, upr is only compatible
  17 with Rack web servers that support a streaming "rack.input".  Currently
  18 this is limited to {Rainbows!}[http://rainbows.rubyforge.org/] with a
  19 handful of concurrency models:
  20
  21 * ThreadSpawn
  22 * ThreadPool
  23 * Revactor*
  24
  25 For use with Revactor, the use of network-based Moneta stores or DRb is
  26 only advised if those stores are using Revactor-aware sockets.
  27
  28 == JavaScript/HTML Compatibility
  29
  30 The current developer does not react well with GUIs.  Thus all (R)HTML
  31 and Prototype JavaScript code was stolen from mongrel_upload_progress.
  32
  33 Contributions to add compatibility for more modern things like JQuery
  34 and HTML5 are very welcome.
  35
  36
  37 == Backend Compatibility
  38
  39 We depend on {Moneta}[http://github.com/wycats/moneta], which allows the
  40 use of a multitude of key-value stores.  We also provide a
  41 DRb+Moneta::Memory server to ease transitions from
  42 mongrel_upload_progress.
  43
  44 Additionally, there is an example for using Rails ActiveRecord as a
  45 backend storage mechanism.  Cookie-based upload tracking may eventually
  46 be used, too (contributions very welcome).
  47
  48 == Proxy Compatibility
  49
  50 No proxy is required when used with Rainbows!
  51
  52 The only incompatible HTTP proxy we know of is nginx.  nginx will buffer
  53 large requests to the filesystem before sending them to the backend.
  54 nginx has its own 3rd-party module for
  55 {upload progress}[http://wiki.nginx.org/NginxHttpUploadProgressModule]
  56 and may be used instead of upr.
  57
  58 Most other HTTP-aware and all TCP-only proxies should be compatible.
  59 Disabling Nagle's algorithm in both the Rack web server and proxy is
  60 advised for lower latency, especially with stunnel.
  61
  62 == Unicorn Compatibility
  63
  64 While {Unicorn}[http://unicorn.bogomips.org/] provides the streaming
  65 "rack.input" for Rainbows!, using Unicorn with upr is generally NOT
  66 recommended.  Unicorn only supports fast clients and progress reporting
  67 is unnecessary unless clients are uploading files that are hundreds of
  68 megabyte in size or larger.
  69
  70 == Getting Started
  71
  72   gem install upr
  73
  74 For Rails, look at the Rails application
  75 {example}[http://git.bogomips.org/cgit/upr.git/tree/examples/rails_app-2.3.4]
  76 and RDoc.  More documentation is on the way.
  77
  78 == Disclaimer
  79
  80 There is NO WARRANTY whatsoever if anything goes wrong, but let us know
  81 and we'll try our best to fix it.
  82
  83 == License
  84
  85 upr is copyright 2009 by all contributors (see logs in git).  It is
  86 based on mongrel_upload_progress and carries the same license (Ruby +
  87 GPL2).  Bundled examples may different Free Software licenses, see the
  88 included LICENSE file for details.
  89
  90 upr is 100% Free Software.  We will never support the proliferation of
  91 non-Free browsers or plugins.
  92
  93 == Contact
  94
  95 All feedback (bug reports, user/development dicussion, patches, pull
  96 requests) go to the mailing list/newsgroup.  Patches must be sent inline
  97 (git format-patch -M + git send-email).  No top posting.
  98
  99 To subscribe or post to the mailing list, just send an email to
 100 upr@librelist.com and follow the instructions in the automated reply.
 101
 102 * email: mailto:upr@librelist.com
 103 * git: git://git.bogomips.org/upr.git
 104 * cgit: http://git.bogomips.org/cgit/upr.git
 105
 106 We will adhere to mostly the same conventions for patch submissions as
 107 git itself.  See the Documentation/SubmittingPatches document
 108 distributed with git on on patch submission guidelines to follow.  Just
 109 don't email the git mailing list with upr patches :)