rack-raw-upload 0.1.0

data/Gemfile

@@ -0,0 +1,9 @@
+source :rubygems
+
+gem 'json'
+
+group :development, :test do
+  gem 'rake'
+  gem 'rack-test'
+  gem 'shoulda'
+end

data/Gemfile.lock

@@ -0,0 +1,18 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    json (1.4.6)
+    rack (1.2.1)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rake (0.8.7)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  json
+  rack-test
+  rake
+  shoulda

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 New Bamboo Web Development Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# Rack Raw Upload middleware
+
+Rack::RawUpload converts raw file uploads into normal form input, so Rack applications can read these as normal (using `params` for example), rather than from `env['rack.input']` or similar.
+
+Rack::RawUpload know that a request is such an upload when the mimetype **is not** one of the following:
+
+* application/x-www-form-urlencoded
+* multipart/form-data
+
+Additionally, it can be told explicitly to perform the conversion, using the header `X-File-Upload`. See below for details.
+
+## Assumptions
+
+Rack::RawUpload expects that requests will:
+
+1. be POST requests
+2. set the mimetype `application/octet-stream`
+
+
+## Configuration
+
+The simpler case:
+
+    use Rack::RawUpload
+
+If you want to limit the conversion to a few known paths, do:
+
+    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
+
+
+## More options
+
+### Specifying the file name of the upload
+
+Raw uploads, due to their own nature, don't include the name of the file being uploaded. You can work around this limitation by specifying the filename as an HTTP header.
+
+When present, Rack::RawUpload will assume that the header ***`X-File-Name`*** will contain the filename.
+
+### Additional query parameters
+
+Again, the nature of raw uploads prevents us from sending additional parameters along with the file. As a workaround, you can specify there as a header too. They will be made available as normal parameters.
+
+When present, Rack::RawUpload will assume that the header ***`X-Query-Params`*** contains these additional parameters. The values are expected to be in the form of a **JSON** hash.
+
+## Additional info
+
+A blog post on HTML5 uploads, which are raw uploads, and can be greatly simplified with this middleware:
+
+* [http://blog.new-bamboo.co.uk/2010/7/30/html5-powered-ajax-file-uploads](http://blog.new-bamboo.co.uk/2010/7/30/html5-powered-ajax-file-uploads)

data/lib/rack/raw_upload.rb

@@ -0,0 +1,80 @@
+module Rack
+  class RawUpload
+
+    VERSION = '0.1.0'
+
+    def initialize(app, opts = {})
+      @app = app
+      @paths = opts[:paths]
+      @explicit = opts[:explicit]
+      @tmpdir = opts[:tmpdir] || Dir::tmpdir
+      @paths = [@paths] if @paths.kind_of?(String)
+    end
+
+    def call(env)
+      kick_in?(env) ? convert_and_pass_on(env) : @app.call(env)
+    end
+
+    def upload_path?(request_path)
+      return true if @paths.nil?
+
+      @paths.any? do |candidate|
+        literal_path_match?(request_path, candidate) || wildcard_path_match?(request_path, candidate)
+      end
+    end
+
+
+    private
+
+    def convert_and_pass_on(env)
+      tempfile = Tempfile.new('raw-upload.', @tmpdir)
+      tempfile = open(tempfile.path, "r+:BINARY")
+      tempfile << env['rack.input'].read
+      tempfile.flush
+      tempfile.rewind
+      fake_file = {
+        :filename => env['HTTP_X_FILE_NAME'],
+        :type => env['CONTENT_TYPE'],
+        :tempfile => tempfile,
+      }
+      env['rack.request.form_input'] = env['rack.input']
+      env['rack.request.form_hash'] ||= {}
+      env['rack.request.query_hash'] ||= {}
+      env['rack.request.form_hash']['file'] = fake_file
+      env['rack.request.query_hash']['file'] = fake_file
+      if query_params = env['HTTP_X_QUERY_PARAMS']
+        require 'json'
+        params = JSON.parse(query_params)
+        env['rack.request.form_hash'].merge!(params)
+        env['rack.request.query_hash'].merge!(params)
+      end
+      @app.call(env)
+    end
+
+    def kick_in?(env)
+      env['HTTP_X_FILE_UPLOAD'] == 'true' ||
+        ! @explicit && env['HTTP_X_FILE_UPLOAD'] != 'false' && raw_file_post?(env) ||
+        env.has_key?('HTTP_X_FILE_UPLOAD') && env['HTTP_X_FILE_UPLOAD'] != 'false' && raw_file_post?(env)
+    end
+
+    def raw_file_post?(env)
+      upload_path?(env['PATH_INFO']) &&
+        env['REQUEST_METHOD'] == 'POST' &&
+        content_type_of_raw_file?(env['CONTENT_TYPE'])
+    end
+
+    def literal_path_match?(request_path, candidate)
+      candidate == request_path
+    end
+
+    def wildcard_path_match?(request_path, candidate)
+      return false unless candidate.include?('*')
+      regexp = '^' + candidate.gsub('.', '\.').gsub('*', '[^/]*') + '$'
+      !! (Regexp.new(regexp) =~ request_path)
+    end
+    
+    def content_type_of_raw_file?(content_type)
+      ! %w{application/x-www-form-urlencoded multipart/form-data}.include?(content_type)
+    end
+  end
+end

data/test/raw_upload_test.rb

@@ -0,0 +1,185 @@
+require 'rubygems'
+require 'rack/test'
+require 'shoulda'
+require 'rack/raw_upload'
+require 'json'
+
+class RawUploadTest < Test::Unit::TestCase
+  include Rack::Test::Methods
+
+  def app
+    opts = @middleware_opts
+    Rack::Builder.new do
+      use Rack::RawUpload, opts
+      run Proc.new { |env| [200, {'Content-Type' => 'text/html'}, ['success']] }
+    end
+  end
+
+  def setup
+    @middleware_opts = {}
+    @path = __FILE__
+    @filename = File.basename(@path)
+    @file = File.open(@path)
+  end
+
+  def upload(env = {})
+    env = {
+      'REQUEST_METHOD' => 'POST',
+      'CONTENT_TYPE' => 'application/octet-stream',
+      'PATH_INFO' => '/some/path',
+      'rack.input' => @file,
+    }.merge(env)
+    request(env['PATH_INFO'], env)
+  end
+
+  context "raw file upload" do
+    should "work with Content-Type 'application/octet-stream'" do
+      upload('CONTENT_TYPE' => 'application/octet-stream')
+      assert_file_uploaded_as 'application/octet-stream'
+    end
+
+    should "work with Content-Type 'image/jpeg'" do
+      upload('CONTENT_TYPE' => 'image/jpeg')
+      assert_file_uploaded_as 'image/jpeg'
+    end
+
+    should "not work with Content-Type 'application/x-www-form-urlencoded'" do
+      upload('CONTENT_TYPE' => 'application/x-www-form-urlencoded')
+      assert_successful_non_upload
+    end
+
+    should "not work with Content-Type 'multipart/form-data'" do
+      upload('CONTENT_TYPE' => 'multipart/form-data')
+      assert_successful_non_upload
+    end
+    
+    should "be forced to perform a file upload if `X-File-Upload: true`" do
+      upload('CONTENT_TYPE' => 'multipart/form-data', 'HTTP_X_FILE_UPLOAD' => 'true')
+      assert_file_uploaded_as 'multipart/form-data'
+    end
+
+    should "not perform a file upload if `X-File-Upload: false`" do
+      upload('CONTENT_TYPE' => 'image/jpeg', 'HTTP_X_FILE_UPLOAD' => 'false')
+      assert_successful_non_upload
+    end
+
+    context "with X-File-Upload: smart" do
+      should "perform a file upload if appropriate" do
+        upload('CONTENT_TYPE' => 'multipart/form-data', 'HTTP_X_FILE_UPLOAD' => 'smart')
+        assert_successful_non_upload
+      end
+
+      should "not perform a file upload if not appropriate" do
+        upload('CONTENT_TYPE' => 'image/jpeg', 'HTTP_X_FILE_UPLOAD' => 'smart')
+        assert_file_uploaded_as 'image/jpeg'
+      end
+    end
+
+    context "with :explicit => true" do
+      setup do
+        @middleware_opts = { :explicit => true }
+      end
+
+      should "not be triggered by an appropriate Content-Type" do
+        upload('CONTENT_TYPE' => 'image/jpeg')
+        assert_successful_non_upload
+      end
+
+      should "be triggered by `X-File-Upload: true`" do
+        upload('CONTENT_TYPE' => 'image/jpeg', 'HTTP_X_FILE_UPLOAD' => 'true')
+        assert_file_uploaded_as 'image/jpeg'
+      end
+
+      should "kick in when `X-File-Upload: smart` and the request is an upload" do
+        upload('CONTENT_TYPE' => 'image/jpeg', 'HTTP_X_FILE_UPLOAD' => 'smart')
+        assert_file_uploaded_as 'image/jpeg'
+      end
+
+      should "stay put when `X-File-Upload: smart` and the request is not an upload" do
+        upload('CONTENT_TYPE' => 'multipart/form-data', 'HTTP_X_FILE_UPLOAD' => 'smart')
+        assert_successful_non_upload
+      end
+    end
+
+    context "with a given :tmpdir" do
+      setup do
+        @tmp_path = File.join(Dir::tmpdir, 'rack-raw-upload/some-dir')
+        FileUtils.mkdir_p(@tmp_path)
+        @middleware_opts = { :tmpdir => @tmp_path }
+      end
+
+      should "use it as temporary file store" do
+        upload
+        assert Dir.entries(@tmp_path).any?{|node| node =~ /raw-upload/ }
+      end
+    end
+
+    context "with query parameters" do
+      setup do
+        upload('HTTP_X_QUERY_PARAMS' => JSON.generate({
+          :argument => 'value1',
+          'argument with spaces' => 'value 2'
+        }))
+      end
+
+      should "convert these into arguments" do
+        assert_equal last_request.POST['argument'], 'value1'
+        assert_equal last_request.POST['argument with spaces'], 'value 2'
+      end
+    end
+
+    context "with filename" do
+      setup do
+        upload('HTTP_X_FILE_NAME' => @filename)
+      end
+
+      should "be transformed into a normal form upload" do
+        assert_equal @filename, last_request.POST["file"][:filename]
+      end
+    end
+  end
+  
+  context "path matcher" do
+    should "accept any path by default" do
+      rru = Rack::RawUpload.new(nil)
+      assert rru.upload_path?('/')
+      assert rru.upload_path?('/resources.json')
+      assert rru.upload_path?('/resources/stuff.json')
+    end
+
+    should "accept literal paths" do
+      rru = Rack::RawUpload.new nil, :paths => '/resources.json'
+      assert rru.upload_path?('/resources.json')
+      assert ! rru.upload_path?('/resources.html')
+    end
+
+    should "accept paths with wildcards" do
+      rru = Rack::RawUpload.new nil, :paths => '/resources.*'
+      assert rru.upload_path?('/resources.json')
+      assert rru.upload_path?('/resources.*')
+      assert ! rru.upload_path?('/resource.json')
+      assert ! rru.upload_path?('/resourcess.json')
+      assert ! rru.upload_path?('/resources.json/blah')
+    end
+    
+    should "accept several entries" do
+      rru = Rack::RawUpload.new nil, :paths => ['/resources.*', '/uploads']
+      assert rru.upload_path?('/uploads')
+      assert rru.upload_path?('/resources.*')
+      assert ! rru.upload_path?('/upload')
+    end
+  end
+  
+  def assert_file_uploaded_as(file_type)
+    file = File.open(@path)
+    received = last_request.POST["file"]
+    assert_equal file.gets, received[:tempfile].gets
+    assert_equal file_type, received[:type]
+    assert last_response.ok?
+  end
+
+  def assert_successful_non_upload
+    assert ! last_request.POST.has_key?('file')
+    assert last_response.ok?
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification 
+name: rack-raw-upload
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Pablo Brasero
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-09 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rack-test
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: Middleware that converts files uploaded with mimetype application/octet-stream into normal form input, so Rack applications can read these as normal, rather than as raw input.
+email: pablobm@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- lib/rack/raw_upload.rb
+- test/raw_upload_test.rb
+- LICENSE
+- README.md
+- Gemfile
+- Gemfile.lock
+has_rdoc: true
+homepage: https://github.com/newbamboo/rack-raw-upload
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Rack Raw Upload middleware
+test_files: []
+