If you want to use this because you are performing HTML5 file uploads, you may be doing it the "old way".
There is a "new", better way of doing this. It may be a better solution for your problems.
However, if this is not the case, please read on. I hope you find this middleware useful.
I have received reports of this middleware not working properly on Windows environments. Unfortunately, I am not able to fix this. If you encounter such problems and are able to provide a fix with a test case, I'll be delighted to include it in a future version of this software.
Rack::RawUpload converts raw uploads into normal multipart requests, like those in a form. Rack applications can then read these as normal (using params
for example), rather than from env['rack.input']
or similar.
Rack::RawUpload performs this conversion when all these conditions are met:
- The request method is POST or PUT
- The mimetype is NOT one of
application/x-www-form-urlencoded
multipart/form-data
- The Content-Length is greater than 0
The simpler case. Add these lines in your config.ru
, where appropriate:
require 'rack/raw_upload'
use Rack::RawUpload
If you want to limit the conversion to a few known paths, do:
require 'rack/raw_upload'
use Rack::RawUpload, :paths => ['/upload/path', '/alternative/path.*']
You can also make it so that the conversion only happens when explicitly required by the client using a header. This would be X-File-Upload: true
to make the conversion regardless of the content type. A value of X-File-Upload: smart
would ask for the normal detection to be performed. For this, use the following setting:
use Rack::RawUpload, :explicit => true
Add this to your Gemfile
gem 'rack-raw-upload'
and then add the middleware in application.rb
config.middleware.use 'Rack::RawUpload'
The upload is made into a request argument called file
. In several popular frameworks, this can be accessed as params[:file]
. This includes Rails and Sinatra, but may be different in other frameworks.
Raw uploads, due to their own nature, can't provide additional arguments in the request. This limitation can be worked around using headers.
X-File-Name
: specify the name of the uploaded file.X-File-Upload
: explicitly tells whether to perform the conversion or not. Possible values are 'true' (string), 'false' (string) or 'smart'. Default is 'smart', unless the middleware is initialized with:explicit => true
, in which case default is 'false'.X-Params
: query string with additional arguments. On Rails or Sinatra, you can read these asparams[:name_of_argument]
.X-JSON-Params
: same thing, but in the form of a JSON string.X-Query-Params
: deprecated. Equivalent toX-JSON-Params
. Will be removed in future versions.
A blog post on Ajax uploads. These are raw uploads and can be greatly simplified with this middleware:
This middleware should work with Ruby 1.8.7, 1.9.2, 1.9.3, REE, Rubinius and JRuby. Tests for all these platforms are run on the wonderful Travis-CI regularly, and the current status of these is: