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