pail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 54c0ae0fb36a073adbf4ac0f4231991841572362
+  data.tar.gz: 0d75a69b5b42b896fc6d746c3f537389edc76b08
+SHA512:
+  metadata.gz: 5ac65e006f9ffc929175457c409b62c78156d5aa0d09faf07a52f31e810ccd9a65f428519769a41652d80316935cb3ada13e2c2c3fd0b9606790177fcaf39299
+  data.tar.gz: 24fb2095bb633a60dd922e217b4223e8515acdd915bdce0cc837471ab0f3154e02b12ac6fc1646f41e33e09352d9fcf9e6698f40c55c5042d2ec265654d4aea6

data/.coveralls.yml

@@ -0,0 +1,2 @@
+service_name: travis-ci
+repo_token: jy5plUVhx9Z8gE8dhQHSB0epLB00iDcBj

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 2.2.0
+
+before_install:
+  - gem install bundler -v 1.8
+
+script: 'bundle exec rspec'
+
+notifications:
+  email:
+    recipients:
+      - eddiej@gmail.com
+    on_failure: change
+    on_success: never

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pail.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,36 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features)
+
+## Uncomment to clear the screen before every task
+# clearing :on
+
+## Guard internally checks for changes in the Guardfile and exits.
+## If you want Guard to automatically start up again, run guard in a
+## shell loop, e.g.:
+##
+##  $ while bundle exec guard; do echo "Restarting Guard..."; done
+##
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard 'rspec', cmd: "bundle exec rspec" do
+  # watch /lib/ files
+  watch(%r{^lib/(.+).rb$}) do |m|
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  # watch /spec/ files
+  watch(%r{^spec/(.+).rb$}) do |m|
+    "spec/#{m[1]}.rb"
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Eddie Johnston
+
+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,218 @@
+# Pail
+
+[![Build Status](https://travis-ci.org/eddiej/pail.png?branch=master)](https://travis-ci.org/eddiej/pail) 
+[![Coverage Status](https://coveralls.io/repos/eddiej/pail/badge.png)](https://coveralls.io/r/eddiej/pail)
+
+
+Pail is a Ruby gem that makes it easy to upload files directly from your views to an Amazon S3 Bucket, bypassing your application server. 
+
+![Alt Image Text](https://raw.githubusercontent.com/eddiej/pail/gh-pages/in_progress.png "Optional Title")
+
+It uses the Plupload JavaScript uploader originally written for PHP, bundling the required Javascript libraries with convenience methods for generating the policy document and SHA1 signature needed to upload to S3. 
+Pail has the option of applying Twitter Boostrap progress-bar styling to the uploader, but it is unstyled by default.
+
+
+## Why Do I Need It?
+
+To avoid blocking your server during file uploads. There are two approaches to processing and storing file uploads from your Rails app to S3: pass-through uploading and direct uploading. 
+
+**Pass-through uploading**, which sends files to your Rails application before uploading them from there to S3 storage, is easy to implement, but your application's server threads will be tied up during the upload process which can have a blocking effect on your application. 
+
+If all of the available threads of your server are occupied by slow uploads, your application will become unavailable until one of the uploads finishes and frees up a thread. Some hosting providers like Heroku terminate requests that last longer than 30 seconds, so uploads that take any longer won't complete.
+
+**Direct uploading** makes a direct connection between the end-user's browser and S3, bypassing your application entirely. This will greatly reduce the processing required by your application and keep your threads free for other requests, but it can be complicated to implement. See [Heroku's Guide for direct uploading to S3 with Rails](https://devcenter.heroku.com/articles/direct-to-s3-image-uploads-in-rails) for an example implementation.
+
+Pail takes the complication out of direct uploading, allowing users to create a direct uploader with just one line of code.
+
+
+## Requirements
+
+Before you can upload to S3, you'll need to:
+
+- create a bucket
+- configure the bucket to allow uploads
+- generate a Base64 encoded Policy document
+- generate a Base64 encoded SHA1 encrypted signature
+
+Your S3 bucket needs to be created and configured manually, but Pail looks after the the policy document and signature generation. Pail needs access to three variables; the name of the bucket you'll be uploading to, an AWS access key id and secret access key. These should be made available as environrment variables in your Rails app. There are various wasy of doing this, you could use an initializer or a gem like [dotenv](https://github.com/bkeepers/dotenv).
+
+```ruby
+ENV['S3_BUCKET']=assets.mydomain.com
+ENV['AWS_ACCESS_KEY_ID']=AKIAJLAP2FSKJEBDFLWWA
+ENV['AWS_SECRET_ACCESS_KEY']=KKdkahb4kdfheb4KGcII8iRzpFymlUanYGszLf1U
+```
+
+### Configuring Your S3 Bucket
+
+Plupload provides a number of different runtimes including HTML5, Flash and Sliverlight. Depending on the runtime you wish to use, the configuration settings are slightly different. Configuring your S3 Bucket for the three main runtimes is documented below, see the [Plupload documentation](http://www.plupload.com/docs/Upload-to-Amazon-S3) for a more detailed explanation.
+
+#### HTML5 Runtime
+
+To use the HTML5 Runtime, you must add a CORS configuration similar to the one below in the `Permissions` section of the S3 bucket options. This is accessed from your S3 dashboard.
+
+```xml
+<CORSConfiguration>
+    <CORSRule>
+        <AllowedOrigin>*</AllowedOrigin>
+        <AllowedHeader>*</AllowedHeader>
+        <AllowedMethod>GET</AllowedMethod>
+        <AllowedMethod>POST</AllowedMethod>
+        <MaxAgeSeconds>3000</MaxAgeSeconds>
+    </CORSRule>
+</CORSConfiguration>
+```
+
+
+#### Flash Runtime
+
+Flash requires a `crossdomain.xml` policy file to be present at the root of your bucket to support cross-origin requests:
+
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE cross-domain-policy SYSTEM
+"http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
+<cross-domain-policy>
+ <allow-access-from domain="*" secure="false" />
+</cross-domain-policy>
+```
+
+#### Silverlight Runtime
+
+Silverlight uses its own Security Policy File - `clientaccesspolicy.xml`, but when all domains are allowed, it can fallback to `crossdomain.xml`.
+
+See the [Plupload documentation](http://www.plupload.com/docs/Upload-to-Amazon-S3#for-silverlight-runtime) for more information on generating `clientaccesspolicy.xml` for allowing only specific domains.
+
+
+### Policy Generation
+
+In order to upload to S3, each request musy be accompanied with a Base64 encoded policy, a set of rules your request should conform to. Amazon will reject requests with missing or invalid policy documents and respond with a 403 Forbidden error.
+
+When you call the `pail()` function, the gem will generate the policy using your private key and secret and inject the encrypted values into the configuration hash on your page. This means that your sensitive information doesn't get exposed on the front-end.
+
+### Signature Generation
+In addition to sending a Policy document, each request must also be signed with a HMAC-SHA1 encrypted and Base64 encoded signature which is created from you AWS Secret Access Key. Pail will generate the signature for you and insert the encryoted values into the configuration hash on the front-end.
+
+## Creating an Uploader
+
+To use the Pail, add the Gem to your Gemfile and include the Pail Javascript in your `application.js` file. Note that jQuery is a pre-requisite for Pail.
+
+<pre>
+//= require jquery
+//= require jquery_ujs
+//= require turbolinks
+//= require_tree .
+<b>//= require pail</b>
+</pre>
+
+
+
+Inserting an uploader onto a page is as simple as including a small amount of HTML markup and calling the `pail()` function in a view template. In an ERB file, this would look like:
+
+```ruby
+<%= pail() %>
+```
+
+Your HTML markup must provide:
+
+- a file select button
+- a cancel button
+- a placeholder element that will display information about the file being uploaded 
+
+The default IDs for each of these elements is `#selectfile`, `#resetupload`, and `#uploadfile` but these can be overridden via the options hash. The markup below contains the required elements:
+
+```html
+<div id='uploadcontainer'>
+ <h3>Upload A File</h3>
+ <div id='uploadfile'> 
+   <div class="progress"></div>
+ </div>
+ <button type="button" class="btn btn-default btn btn-sm" id="selectfile">Select File</button>
+ <button type="button" class="btn btn-danger btn btn-sm disabled" id="resetupload">Reset</button>
+</div>
+```
+
+
+    
+Any placeholder content can be placed within the `#uploadfile` element as long as it is wrapped in a containing element. By default, an empty div with the class 'progress' is inserted which displays an empty progress bar well. This will be replaced with a progress bar once a file is selected and put back again if the upload is reset. 
+
+### Parameters
+
+Custom options can be sent in a hash parameter of the `pail()` function. The options currently configurable in Pail and their default values are:
+
+```ruby
+options[:key] ||= 'test' 
+options[:acl] ||= 'public-read'
+options[:expiration_date] ||= 10.hours.from_now.utc.iso8601
+options[:max_filesize] ||= 500.kilabytes
+options[:content_type] ||= 'image/'
+options[:filter_title] ||= 'Images'
+options[:filter_extentions] ||= 'jpg,jpeg,gif,png,bmp'
+options[:runtimes] ||= 'html5'
+options[:selectid] ||= 'selectfile'
+options[:cancelid] ||= 'resetupload'
+options[:progress_bar_class] ||= 'progress-bar progress-bar-striped active'       
+```
+
+The [Plupload Options documentation](http://www.plupload.com/docs/Options) should be referred to for explanations of each value. The `selectid`, `cancelid` and `progress_bar_class` values are relevant only to Pail and not Plupload.
+
+### Upload Progress
+
+The upload progress bar uses the same markup as the [Twitter Bootstap progress bar](http://getbootstrap.com/components/#progress).
+
+```html
+<div class="progress">
+ <div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
+   <span class="file-info">Moonshine.jpg (453 kb) 60% </span>
+ </div>
+</div>
+```
+
+The control buttons and progress bar will be unstyled by default, but you can apply the Boostrap styles by including the Pail stylesheet from `application.css`:
+
+<pre>
+*
+*= require_tree .
+*= require_self
+<b>*= require pail</b>
+*/ 
+</pre>
+
+If you already use Twitter Bootstrap in your application, the styles from your theme will automatically be applied.
+
+## Upload Events
+
+Plupload defines a number of events that can be bound to, a full list of which can be found in the [Plupload documentation](http://www.plupload.com/docs/Uploader#events). By default, Pail uses event binding to change the style of the progress bar according to the state of the uploader.
+
+Additional functionality would generally be bound to the FileUploadaed event to perform additional actions once a file has been uploaded. Examples might include:
+
+- Insert the S3 url of the uploaded file into a hidden field and submit a form.
+- Send the S3 url to a controller via a remote AJAX call
+- Redirect to another page that displays the uploaded asset 
+
+To bind additional events, use the jQuery `bind` function after `<%= pail %>` has been called. 
+
+```javascript
+<script>
+  window.uploader.bind('FileUploaded', function(up, file, info) { alert (info); })
+</script>
+```
+
+Note that the uploader object created by the Plupload Javascript is added as a property of the window object and can be accessed by `window.uploader`.
+
+The default Pail events can be removed using the `unbind` function, e.g:
+
+```javascript
+<script>
+  window.uploader.unbind('UploadProgress')
+  window.uploader.unbind('FileUploaded')
+  ...
+</script>
+```
+
+## Testing
+Tests are written using RSpec. To start the test suite, run:
+
+```rails
+bundle exec rspec
+```
+or view the tests and results output on [Travis CI](https://travis-ci.org/eddiej/pail). 

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pail"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/pail.rb

@@ -0,0 +1,194 @@
+require "pail/version"
+require "pail/engine"
+
+module Pail
+  class Generate
+    def self.signature(secret_access_key, policy)
+      Base64.encode64(
+        OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha1'), secret_access_key, policy)
+      ).gsub("\n","")
+    end
+
+    def self.policy(bucket, expiration_date, acl, max_filesize)
+      Base64.encode64(
+        "{'expiration': '#{expiration_date}',
+          'conditions': [
+            {'bucket': '#{bucket}'},
+            {'acl': '#{acl}'},
+            {'success_action_status': '201'},
+            ['content-length-range', 0, #{max_filesize}],
+            ['starts-with', '$key', ''],
+            ['starts-with', '$Content-Type', ''],
+            ['starts-with', '$name', ''],
+            ['starts-with', '$Filename', '']
+          ]
+        }"
+      ).gsub(/\n|\r/, '')
+    end
+  end
+
+  module PailHelper
+    
+    def pail(options = {})   
+      # Read in the default bucket, AWS key and secret from environment variables.
+ 
+      @bucket = ENV['S3_BUCKET']
+      @access_key_id = ENV['AWS_ACCESS_KEY_ID']
+      @secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+      @options = options.dup
+
+      raise ArgumentError.new('a bucket, access key id and secret access key must be set') unless @bucket && @access_key_id && @secret_access_key
+
+      @options[:key] ||= 'uploads' # folder on AWS to store file in
+      @options[:acl] ||= 'public-read'
+      @options[:expiration_date] ||= 10.hours.from_now.utc.iso8601
+      @options[:max_filesize] ||= 104857600 # 100.megabytes
+      @options[:content_type] ||= 'image/' # Videos would be binary/octet-stream
+      @options[:filter_title] ||= 'Images'
+      @options[:filter_extensions] ||= 'jpg,jpeg,gif,png,bmp'
+      @options[:runtimes] ||= 'html5'
+
+      @options[:selectid] ||= 'selectfile'
+      @options[:cancelid] ||= 'resetupload'
+      @options[:progress_bar_class] ||= 'progress-bar progress-bar-striped active'
+
+      id = @options[:id] ? "_#{@options[:id]}" : ''
+
+      policy = Pail::Generate::policy(
+        @bucket,
+        @options[:expiration_date], 
+        @options[:acl], 
+        @options[:max_filesize]
+      )
+
+      signature = Pail::Generate::signature(@secret_access_key, policy)
+
+      out = ""
+      filters = "filters : [
+       {title : '#{@options[:filter_title]}', extensions : '#{@options[:filter_extensions]}'}
+      ],"
+      if @options[:filters]
+        filters = 'filters : ['
+        filters = filters + @options[:filters].join(',')
+        filters = filters + "],"
+      end
+
+
+      out << javascript_tag(<<JAVASCRIPT
+       
+        uploader = new plupload.Uploader({
+          browse_button : '#{@options[:selectid]}',
+          container : 'uploadcontainer',
+          runtimes : '#{@options[:runtimes]}',
+          url : 'https://s3.amazonaws.com/#{@bucket}/',
+          max_file_size : '#{number_to_human_size(@options[:max_filesize]).gsub(/ /,'').downcase}',
+          multipart: true,
+          multipart_params: {
+            'key': '#{@options[:key]}/${filename}',
+            'Filename': '${filename}', // adding this to keep consistency across the runtimes
+            'acl': '#{@options[:acl]}',
+            'Content-Type': '#{@options[:content_type]}',
+            'success_action_status': '201',
+            'AWSAccessKeyId' : '#{@access_key_id}',
+            'policy': '#{policy}',
+            'signature': '#{signature}'
+          },
+          // optional, but better be specified directly
+          file_data_name: 'file',
+          // re-use widget (not related to S3, but to Plupload UI Widget)
+          multiple_queues: true,
+          // Specify what files to browse for
+          #{filters}
+          // Flash settings
+          flash_swf_url : '/assets/plupload/Moxie.swf',
+          // Silverlight settings
+          silverlight_xap_url : '/assets/plupload/Moxie.xap',
+        });
+
+        placeholder = $('#uploadfile').children().first();
+        uploader.init() 
+        var queueMaxima = 1;
+
+        // 1. Files Added          
+        uploader.bind('FilesAdded', function(up, files) {           
+          $.each(files, function(i, file) {
+            $('#uploadfile').empty().append(' \
+              <div id="' + file.id + '" class="progress"> \
+                <div class="#{@options[:progress_bar_class]}" role="progressbar" aria-valuenow="'+file.percent+'" aria-valuemin="0" aria-valuemax="100"> \
+                  <span class="file-info">' + file.name + ' (' + plupload.formatSize(file.size) + ')</span>' +
+                '</div> \
+              </div>');
+          });
+          $('##{@options[:cancelid]}').removeClass('disabled')
+
+
+            
+          if(uploader.files.length > queueMaxima){
+            while(uploader.files.length > queueMaxima){
+              if(uploader.files.length > queueMaxima){
+                x = uploader.files[queueMaxima-1]
+                
+                $('#'+x.id).remove();
+                uploader.removeFile(uploader.files[queueMaxima-1]);
+                uploader.stop()
+              }
+            }
+            if(typeof(plupload_hook_removedExcessFromQueue) == "function"){plupload_hook_removedExcessFromQueue()}
+          }
+          up.start();
+          up.refresh(); // Reposition Flash/Silverlight
+        });
+
+        // 2. Right before Upload Starts
+        uploader.bind('BeforeUpload', function(up, file) {
+          $('#' + file.id + " .progress-bar")
+            .addClass('active')
+        });
+
+        // 2. Upload Progresses
+        uploader.bind('UploadProgress', function(up, file) {
+          $('#' + file.id + " .progress-bar")
+            .width(file.percent + "%")
+            .html('<span class="file-info">' + file.name + ' (' + plupload.formatSize(file.size) + ') ' + file.percent + "%</span>");
+        });
+
+        // 3. Error Occurs
+        uploader.bind('Error', function(up, err) {  
+          if($('.file-info').length > 0){
+            error_element = $('.file-info')
+          }
+          else{
+            error_element = $('.progress')
+          }
+          error_element.html("Error: " + err.code + ", " + err.message + (err.file ? " File: " + err.file.name : ""));
+          $('#' + err.file.id + " .progress-bar")
+            .addClass('progress-bar-danger')
+            .removeClass('active')
+        });
+
+        // 4. File is Uploaded
+        uploader.bind('FileUploaded', function(up, file) {
+          $('#' + file.id + " .progress-bar")
+            .addClass('progress-bar-success')
+            .removeClass('active')
+        });
+
+        // 5. Stop button is clicked.
+        $('#uploadcontainer').on('click', '##{@options[:cancelid]}', function(){
+          uploader.stop();
+          $('#uploadfile').html(placeholder);
+          $('##{@options[:cancelid]}').addClass('disabled')
+          $('#' + file.id + " .progress-bar")
+            .removeClass('active')
+          uploader.refresh(); // Reposition Flash/Silverlight
+        });
+
+        window.uploader = uploader;
+JAVASCRIPT
+)
+
+     raw(out);
+    end
+  end
+  ActionView::Base.send :include, PailHelper
+end