t_bird 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8bed597706b18d287438b31c1a9be55fa0528453
-  data.tar.gz: 09c9333f2f2946f1a1166e221f0f268310eb7a02
+  metadata.gz: 165550328a315a0ceb17e4176ec881efbc24c091
+  data.tar.gz: 0f66fcca8da662fb05d55a3575ac8608e49f82b4
 SHA512:
-  metadata.gz: af944ed056e75ff4380f215290d5dd354daeacf9b4db1856495fa1b087d2780c119e1269bdb6353ef02259d1d9f33137daaaf9d42b7927e977379fdf4c7bb409
-  data.tar.gz: 43aa1b46dedb3d0c2d1ed0c3cdfb53ce74fe963ddceee50ade17c376a39bd7322b99a8622b0115e9b1c12f84f0bc3b73cc8966bd33bf379f1f01724fb499907d
+  metadata.gz: 38fa5f3ff9c0d32d372d837d8fe9619d9e59216caa75b8085e2d8f2e541963067ace76a422af46cdf18427fdf12b09ab6df727f0b94c7aab04131eb59b912ecb
+  data.tar.gz: 17fa255fbc9856f9d653e040ba860de76a3064e19d57b0cc0a3123407c14ce2014b3dd8cf6369a681252538df98d074664aeab527743d28a03f50a177bce88b5

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2
+  - jruby-19mode
+  - rbx-19mode

data/README.md

@@ -1,6 +1,13 @@
-# TBird
+# t_bird
 
-Straight forward file uploads for Ruby Apps.
+Uploading is... fun, fun, fun, until daddy takes the `t_bird` away.
+
+
+## Project Status
+
+- Build: [![Build Status](https://secure.travis-ci.org/xentek/t_bird.png)](http://travis-ci.org/xentek/t_bird)
+- Dependencies: [![Dependency Status](https://gemnasium.com/xentek/t_bird.png)](https://gemnasium.com/xentek/t_bird)
+- Code Quality: [![Code Climate](https://d3s6mut3hikguw.cloudfront.net/github/xentek/t_bird.png)](https://codeclimate.com/github/xentek/t_bird)
 
 ## Installation
 
@@ -15,8 +22,8 @@ And then execute:
 ## Why?
 
 I became frustrated by the very coupled design of the leading ruby
-upload libraries and wanted something that was a little more modular (to
-allow for flexibility), wasn't glued to a `model` class, and fulfilled my
+upload libraries and wanted something that was a more modular (to
+allow for flexibility), wasn't glued to a `model`, and fulfilled my
 most common use case out of the box: 
 
  - Upload an image, posted from a multi-part form,
@@ -26,7 +33,146 @@ most common use case out of the box:
 
 ## Usage
 
-_Coming Soon_
+First, configure `t_bird` with a few settings:
+
+````ruby
+TBird::Configuration.configure |config|
+  config.aws_key 'amazon access key id'
+  config.aws_secret 'amazon secret access key'
+  config.aws_bucket 'name of s3 bucket that already exists'
+  config.thumbnail_size 100
+end
+````
+Place this code so that it runs when your app boots.
+
+- If you're using Sinatra or Rack, `config.ru` is probably a good spot.
+- If you're using Rails, put the configuration in an initializer, e.g. `config/initializers/t_bird.rb`.
+
+Then, assuming you have a multipart form like this:
+
+````ruby
+form enctype="multipart/form-data" method="POST"
+  input type="file" name="brand[image]"
+  input type="submit"
+````
+_Example is using [slim](http://slim-lang.com) for clarity and terseness, but that doesn't mean you have to._
+
+In the action the form posts to, grab the uploaded file and upload it with `t_bird`:
+
+````ruby
+uploader = TBird::Uploader.new(params[:brand][:image])
+
+uploader.upload! # return value is same as uploader.uploads
+
+uploader.uploads # returns a hash of urls pointing to your image versions
+                 # store this in the way that makes the most sense for your app
+````
+
+- By default, there are two `versions` defined: `:thumbnail` and `:original`.
+- `:thumbnail` will create crop a square image from the upload.
+  - You can control the size of the square by setting `thumbnail_size` in your configuration (see above).
+- `:original` will be the raw, unadulterated file that the user submitted.
+
+## Options
+
+There are three options you can pass into your `TBird::Uploader` instance:
+
+  - `:identifer`
+    - app specific identifer for his upload, e.g. your model's databae ID, timestamp, whatever
+    - used as the folder this file's uploads are stored in on s3
+      - you can pass a path fragment here to create a folder heirarchy, e.g. 'uploads/images'
+      - don't want any folders?, just pass an empty string, e.g. `''`
+    - defaults to a `SHA1` digest of the `original_filename`
+    - value should be URL safe, no encoding is done for you by `t_bird`
+  - `:token`
+    - needs to be a unique value per upload, to help avoid name collisions and writing over existing files
+    - used as part of the filename, version and extension are
+      automatically appended on to the end.
+    - defaults to a [UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier), think hard before straying from this strategy
+    - value should be URL safe, no encoding is done for you by `t_bird`
+  - `:metadata`
+    - value must be a hash, as it will be merged in when your uploader is instantiated
+    - the file's `content_type` is automatically added to this hash
+    - values in this hash will be stored, with your file, on S3 as metadata.
+      - this could be used for versioning your files, e.g. `version: 2` , marking them with
+        the name/title of the model it's associated with, etc.
+      - `t_bird` doesn't provide any read access to this metadata, once it's stored on S3, so it's up to you to use S3's API to do anything with it.
+
+## Custom Uploaders
+
+In order to define custom versions, and other advanced customization, create a subclass of `TBird::Uploader`:
+
+````ruby
+class FileUploader < TBird::Uploader
+  version :original do
+    ->(file) { file.original }
+  end
+end
+````
+
+- In this simple example we have created a subclass and defined a single
+version, `:original`, that skips processing the file, making `FileUploader` suitable
+for handling non-image uploads.
+- No other versions were defined, so only `:original` will be created.
+  - In other words, if you create a subclass without any `versions`
+    defined, your uploader won't upload anything.
+
+Here's a more complex example that defines several custom `versions`:
+
+````ruby
+class ComplexUploader < TBird::Uploader
+
+  # resizes image to a *width* of 200px, maintains aspect ratio
+  version :small do
+    ->(img) { img.resize '200' } 
+  end
+
+  # resizes image to a *height* of 300px, maintains aspect ratio
+  version :large do
+    ->(img) { img.resize 'x300' }
+  end
+
+  # resizes image to a *height* of 300px, maintains aspect ratio
+  version :resized do
+    ->(img) { img.resize '500x300' }
+  end
+
+  # custom thumbnail size, allowing your to ignore TBird::Configuration.thumbnail_size
+  # on an uploader by uploader basis
+  version :thumbnail do
+    ->(img) { img.thumbnail 200 }
+  end
+
+  # want MOAR power?
+  # use process, which gets you inside a MiniMagick::Image#combine_options block
+  version :complex do
+    lambda do |img|
+      img.process do |magick|
+        magick.sample "50%"
+        magick.rotate "-90>"
+        magick.quality '88'
+      end
+    end
+  end
+end
+````
+For more information on `MiniMagick::Image#combine_options`, refer to the [mini_magick docs](https://github.com/minimagick/minimagick/blob/master/README.md).
+
+:skull: `TBird::Processor#process` can be a _very sharp stick_, so carefully test your processing code with a variety of files in a non-production environment, and as usual be wary of using values from outside of your class as input for your processing routines.
+
+## More customization options
+
+- Redefine the `namer` method in your subclass to switch out the object that's responsible for generating the name used on S3.
+  - Your object must respond to `new_name`, and take the `version`, which will be a symbol, as input.
+- Redefine the `processor` method in your subclass to switch out the processing library.
+  - Blocks defined by the `version` macro will be passed an instance of your `processor`,
+    so be sure that your `processor` will respond to any methods the code inside your blocks call on it. 
+- Redefine the `upload!` to remix the whole show!
+  - really the sky's the limit here, but at some point you might be
+    better of just writing your own uploader class.
+  - Currently this is the only way to swith out S3 for another storage provider.
+    - Better support changing the storage mechanism will likely come out in a future version.
+    - Talk to me before working on a patch for this, so we can agree on implementation.
 
 ## Contributing
 
@@ -35,7 +181,10 @@ _Coming Soon_
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+6. ???
+7. Profit!
 
-## Shout Outs
+#### Colophon
 
-Sample image, used in tests, was provided by [cherrylet](http://www.flickr.com/photos/cherrylet/10258332985/sizes/o/in/photostream/), under the Creative Commons 2.0. No endorsement of this library by the photographer is intended or implied.
+  - This project was not named after the Thunderbird model of car. Ford Motor Company does not have any connection to, or responsibility for this project, and does not endorse it in any way (or even know it exists).
+  - Sample image, used in tests, was provided by [cherrylet](http://www.flickr.com/photos/cherrylet/10258332985/sizes/o/in/photostream/), under the Creative Commons 2.0. No endorsement of this library by the photographer is intended or implied.

data/lib/t_bird/namer.rb

@@ -2,14 +2,15 @@
 
 require 'digest/sha1'
 require 'pathname'
+require 'securerandom'
 
 module TBird
   class Namer
     attr_reader :ext, :identifier, :token
-    def initialize(original_filename, identifier = nil, token = SecureRandom.uuid)
+    def initialize(original_filename, identifier = nil, token = nil)
       @ext = Pathname.new(original_filename).extname
       @identifier = identifier || Digest::SHA1.hexdigest(original_filename)
-      @token = token
+      @token = token || SecureRandom.uuid
     end
 
     def new_name(version = 'original')

data/lib/t_bird/processor.rb

@@ -4,34 +4,41 @@ require 'mini_magick'
 
 module TBird
   class Processor
-    attr_reader :image, :thumbnail_size
+    attr_reader :image
     def initialize(file_blob)
       @image = MiniMagick::Image.read(file_blob)
-      @thumbnail_size = Configuration.thumbnail_size
     end
 
     def process(&block)
-      image.combine_options do |magick|
-        block.call(magick) if block_given?
+      image.combine_options do |img|
+        block.call(img) if block_given?
       end
       image
     end
 
+    def stream
+      image.write StringIO.new
+    end
+    
+    def original
+      image # noop
+    end
+
     def resize(size)
-      process do |magick|
-        magick.resize size
+      process do |img|
+        img.resize size
       end
     end
 
-    def thumbnail
-      process do |magick|
-        magick.auto_orient
-        magick.thumbnail "x#{thumbnail_size*2}"
-        magick.resize "#{thumbnail_size*2}x<"
-        magick.resize "50%"
-        magick.gravity "center"
-        magick.crop "#{thumbnail_size}x#{thumbnail_size}+0+0"
-        magick.quality 92
+    def thumbnail(thumbnail_size = Configuration.thumbnail_size)
+      process do |img|
+        img.auto_orient
+        img.thumbnail "x#{thumbnail_size*2}"
+        img.resize "#{thumbnail_size*2}x<"
+        img.resize "50%"
+        img.gravity "center"
+        img.crop "#{thumbnail_size}x#{thumbnail_size}+0+0"
+        img.quality 92
       end
     end
   end

data/lib/t_bird/transmitter.rb

@@ -10,15 +10,19 @@ module TBird
       @name = name
       @file = file
       @metadata = default_metadata.merge(metadata)
+      connect!
     end
 
     def transmit!
-      connect!
-      @tranmission = S3Object.store(name, file, Configuration.aws_bucket, metadata)
+      if @transmission.nil?
+        @transmission = S3Object.store(name, file, Configuration.aws_bucket, metadata)
+      end
+      @success ||= Service.response.success?
+      @success
     end
 
     def url
-      @transmission.url
+      @url ||= S3Object.url_for(name, Configuration.aws_bucket, authenticated: false, use_ssl: true)
     end
 
     private

data/lib/t_bird/uploader.rb

@@ -1,29 +1,59 @@
 # encoding: utf-8
 
 module TBird
-  class Upload
-    attr_reader :options
+  class Uploader
+    attr_reader :file, :options, :uploads, :content_type, :original_filename
     def initialize(file, options = {})
-      @options = default_options.merge(options)
       @file = file
+      @options = default_options.merge(options)
+      @uploads = {}
+      @content_type = @file.content_type
+      @original_filename = @file.original_filename
+      @options[:metadata].merge!(content_type: content_type)
+    end
+
+    def namer
+      @namer ||= Namer.new(original_filename, options[:identifier], options[:token])
     end
 
-    def content_type
-      @file_data ||= @file.content_type
+    def processor
+      @processor ||= Processor.new(@file)
     end
 
-    def original_filename
-      @file_data ||= @file.original_filename
+    def upload!
+      versions.each do |version,block|
+        block.call(processor)
+        transmission = Transmitter.new(namer.new_name(version), processor.stream, options[:metadata])
+        transmission.transmit!
+        @uploads[version] = transmission.url
+      end
+      uploads
     end
 
-    def original_file
-      @file_data ||= @file.read
+    def versions
+      self.class.versions
+    end
+
+    def self.versions
+      @versions ||= { 
+        thumbnail: ->(img) { img.thumbnail },
+        original: ->(img) { img.original }
+      }
+    end 
+
+    def self.version(name, &block)
+      @versions ||= {}
+      @versions[name.to_sym] = block
     end
 
     private
 
     def default_options
-      {}
+      {
+        identifier: nil,
+        token: nil,
+        metadata: {}
+      }
     end
   end
 end

data/lib/t_bird/version.rb

@@ -1,3 +1,3 @@
 module TBird
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/spec_helper.rb

@@ -16,8 +16,6 @@ MiniTest::Reporters.use! MiniTest::Reporters::SpecReporter.new
 
 require 'mocha/setup'
 require 'rack/test'
-#include Rack::Test::Methods
-
 require 'uuid'
 
 module TBirdSpecData

data/spec/t_bird/processor_spec.rb

@@ -6,38 +6,37 @@ describe TBird::Processor do
   include TBirdSpecData
 
   before do
-    @custom_process = Proc.new do |magick|
-                        magick.resize '50%'
-                        magick.quality 88
-                      end
-
+    @custom_process = ->(img) { img.quality 88 }
     @processor = TBird::Processor.new(upload_file)
-    @versions = {
-                  thumb: '90x90',
-                  medium: '300',
-                  large: 'x300',
-                  custom: @custom_process
-                }
   end
 
   it "can process an image" do
     image = @processor.process(&@custom_process)
-    image.write StringIO.new
     image.valid?.must_equal true
     image.destroy!
   end
 
-  it "can process image into a thubnail" do
+  it "can thumbnail an image" do
     image = @processor.thumbnail
-    image.write StringIO.new
     image.valid?.must_equal true
     image.destroy!
   end
 
   it "can resize an image" do
     image = @processor.resize('300')
-    image.write StringIO.new
     image.valid?.must_equal true
     image.destroy!
   end
+
+  it "can return the original image" do
+    image = @processor.original
+    image.valid?.must_equal true
+    image.destroy!
+  end
+
+  it "can write image to a stream" do
+    image = @processor.resize('x200')
+    @processor.stream.must_be_instance_of StringIO
+    image.destroy!
+  end
 end

data/spec/t_bird/transmitter_spec.rb

@@ -17,13 +17,20 @@ describe TBird::Transmitter do
 
     AWS::S3::S3Object.stubs(:connected?).returns(true)
     AWS::S3::Base.stubs(:establish_connection!).with(keys)
+    AWS::S3::Service.stubs(response: stub(:success? => true))
 
     @stored_filename = '1/sample_original.jpg'
-    @transmitter = TBird::Transmitter.new(@stored_filename, upload_filedata, { content_type: 'image/jpeg' })
+    @upload = upload_file
+    @transmitter = TBird::Transmitter.new(@stored_filename, @upload, { content_type: 'image/jpeg' })
   end
 
   it "transmit file to store" do
-    AWS::S3::S3Object.expects(:store).with(@stored_filename, upload_filedata, 'bucket', {:access => :public_read, :content_type => 'image/jpeg'})
+    AWS::S3::S3Object.expects(:store).with(@stored_filename, @upload, 'bucket', {:access => :public_read, :content_type => 'image/jpeg'})
     @transmitter.transmit!
   end
+
+  it "can return the S3 url for the file uploaded" do
+    AWS::S3::S3Object.expects(:url_for).with(@stored_filename, 'bucket', authenticated: false, use_ssl: true)
+    @transmitter.url
+  end
 end

data/spec/t_bird/uploader_spec.rb

@@ -2,22 +2,55 @@
 
 require 'spec_helper'
 
-describe TBird::Upload do
+describe TBird::Uploader do
   include TBirdSpecData
 
   before do
-    @tbird_upload = TBird::Upload.new(upload_file)
+    @uploader = TBird::Uploader.new(upload_file)
+    @urls = ['https://s3.example.com/5a3f124f68b57512d3865da4c527f6b7bbd4173a/b54c0891-92a1-4641-8334-d396d5cc21c4_thumbnail.jpg',
+             'https://s3.example.com/5a3f124f68b57512d3865da4c527f6b7bbd4173a/b54c0891-92a1-4641-8334-d396d5cc21c4_original.jpg']
   end
 
-  it "can return original filename" do
-    @tbird_upload.original_filename.must_equal 'sample.jpg'
+  it "can return the file" do
+    @uploader.file.wont_be_nil
   end
 
-  it "can return content type" do
-    @tbird_upload.content_type.must_equal 'image/jpeg'
+  it "can return the options" do
+    @uploader.options.must_equal({ identifier: nil, token: nil, metadata: { content_type: "image/jpeg" } })
   end
 
-  it "can return the original file binary data" do
-    @tbird_upload.original_file.wont_be_nil
+  it "can return the content type" do
+    @uploader.content_type.must_equal 'image/jpeg'
+  end
+
+  it "can return the original filename" do
+    @uploader.original_filename.must_equal 'sample.jpg'
+  end
+
+  it "can return an instance of Processor" do
+    @uploader.processor.must_be_instance_of TBird::Processor
+  end
+  
+  it "can return an instance of Namer" do
+    @uploader.namer.must_be_instance_of TBird::Namer
+  end
+
+  it "can return the registered versions" do
+    @uploader.versions.must_equal TBird::Uploader.versions
+  end
+
+  it "can upload all versions" do
+    TBird::Transmitter.any_instance.stubs(:transmit!)
+    TBird::Transmitter.any_instance.stubs(:url).returns(*@urls)
+
+    @uploader.upload!.must_equal({ thumbnail: @urls.first, original: @urls.last })
+  end
+
+  it "can return the upload urls" do
+    TBird::Transmitter.any_instance.stubs(:transmit!)
+    TBird::Transmitter.any_instance.stubs(:url).returns(*@urls)
+
+    @uploader.upload!
+    @uploader.uploads.must_equal({ thumbnail: @urls.first, original: @urls.last })
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: t_bird
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Eric Marden
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-22 00:00:00.000000000 Z
+date: 2013-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_magick
@@ -88,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md