scale_down 0.6.1 → 0.7.0

data/CHANGES

@@ -1,3 +1,7 @@
+== 2012-01-26==
+Version 0.7.0
+Prefefined labels for image sizes
+
 == 2012-01-24 ==
 Version 0.6.1
 Minor change in CMYK conversion

data/README.md

@@ -1,64 +1,98 @@
 [![Build Status](https://secure.travis-ci.org/jweir/ScaleDown.png)](http://travis-ci.org/jweir/ScaleDown)
 
+The image scaling server used by [Fame Driver](http://famedriver.com).
+It supports dynamic sizes, image cropping and color conversion (CMYK to RGB).
+It only supports images on the same machine (this is not a distributed scaler).
+
 ScaleDown
 ==========
+So you want to scale an image?
+------------------------------
 
-An on demand image scaling server.
+You have an image on `example.com`. It has a public path of `/images/john/picture.png`.
+You want it scaled to fit in a 400x400 pixel box.  ScaleDown is running on the subdomain `images`.
 
-Images are scaled based upon their URL. An HMAC signature is used to prevent unauthorized scaling of images.
+    http://server/images/john/scaled/400x400/picture.png?HMAC_SIGNATURE
 
-Supports cropping images and converts CMYK to RGB.
+The scaled file is saved in a public path identical to the request. It will be statically served on the next request.
 
-URL Schema
-==========
+Geometry, Labels and Cropping
+==============================
 
-Your file on `example.com` has a public path of `/images/john/picture.png`. You want it scaled to fit in a 400x400 pixel box.  **ScaleDown** is running on the subdomain `images`.
+There are two methods of requesting a scaled image: label or geometry.
 
-The URL to your image would be:
+Labels
+------
 
-    http://images.example.com/images/john/scaled/400x400/picture.png?HMAC_SIGNATURE
+A label is a predefined box the scaled image will fit within.
+Labels are defined in the `config.ru` file.
 
-The scaled file is saved in a public path identical to the request. Once an image is scaled your webserve can statically server the file.
+```sh
+# A label called thumbnail has been defined as "100x100"
+# The below url will scale picture.png to fit into a 100 x 100 box
+http://server/images/john/scaled/thumbnail/picture.png
+                          ^^^^^^
+```
 
-The schema is
+```ruby
+# in your config.ru file
+  config.labels = {
+    "thumbnail" => "100x100"
+  }
+```
 
-    http://:host/:path_to_file/scaled/:geometry/:filename?:hmac_signature
+Geometry
+--------
 
-    :host           the address running ScaleDown
-    :path_to_file   the public path of the original file
-    `scaled`        keyword
-    :geometry       width x height and an optional `-crop`
-    :filename       the filename of the original image to scale
-    :hmac_signature security measure to validate the request
+Geometries allow the client to request an image of any size.
 
+A geometry defines a box the image must fit within: `WIDTHxHEIGHT`.
+
+
+```sh
+# scale to a 300 pixel width box by 900 pixel high box
+http://server/images/john/scaled/300x900/picture.png?HMAC_SIGNATURE
+                                 ^^^^^^^
+```
 
-Geometry & Cropping
-====================
+Either, but not both, dimensions may use the keyword `auto`. This will scale the image to fit the defined dimension.
 
-To crop an image include the `-crop` option.  The image will be scaled and cropped to fit the geometry.
+```sh
+# scale to a 500 pixel wide box, of any height
+http://server/images/john/scaled/500xauto/picture.png?HMAC_SIGNATURE
+                                     ^^^^
+```
 
-    http://images.example.com/images/scaled/400x300-crop/logo.png?A3SDACEDF
+When using a geometry an HMAC is required (see below).
+    
+Crop
+----
 
-Using `auto` as a dimension will fit the image to the other dimension.
+To crop an image include the `-crop` option.  The image will be scaled and cropped to fit the geometry. This is a simple crop positioned on the center and top of the image.
 
-For example, to ensure an image is 300 pixels wide set the height to auto
+Both geometry and labels accept the `-crop` option.
 
-    http://images.example.com/images/scaled/300xauto/logo.png/?A3SDACEDF
+```sh
+http://server/images/john/scaled/thumbnail-crop/picture.png
+http://server/images/john/scaled/100x100-crop/picture.png
+```
 
-There is a very simple `/info` function for getting image dimensions. It just returns a string with the WIDTHxHEIGHT.
+Info
+----
+There is a very simple `/info` function for getting image dimensions. It just returns a string with the WIDTHxHEIGHT of the original image.
 
-    http://images.example.com/images/logo.png/info
+    http://server/images/logo.png/info
 
 
-HMAC
-====
+HMAC & Geometry
+==============
 
-You don't want someone taking down your server with malicious URLs, so an HMAC signature is used.  This ensures that your URL was generated by a trusted source.
+An HMAC signature is required to prevent a DOS attack. This ensures that your URL was generated by a trusted source.
 
 HMAC requires a shared key between the application generating the URL and the ScaleDown server.
 
-Sample Ruby URL Generator
--------------------------
+Ruby HMAC URL Generator
+------------------
 
 ```ruby
 require 'ruby-hmac'
@@ -66,12 +100,12 @@ require 'ruby-hmac'
 def signed_image_url(absolute_path, filename, geometry)
   shared_secret = "secret"
   hmac = HMAC::SHA1.new(shared_secret).update([absolute_path, 'scaled', geometry, filename].join("/")).to_s[0...8]
-  "http://images.example.com#{[absolute_path, 'scaled', geometry, CGI.escape(filename)].join("/")}?#{hmac}"
+  "http://server#{[absolute_path, 'scaled', geometry, CGI.escape(filename)].join("/")}?#{hmac}"
 end
 ```
 
-Sample Node.js URL Generator
-----------------------------
+Node.js HMAC URL Generator
+---------------------
 
 ```javascript
 // Uses the Node.js crypot library
@@ -88,8 +122,23 @@ function signed_image_url(absolute_path, filename, geometry){
 }
 ```
 
-PNG, JPG, TIFF and other images supported
-========================================
+URL Schema
+==========
+
+The schema is
+
+    http://:host/:path_to_file/scaled/:target/:filename?:hmac_signature
+
+    :host           the address running ScaleDown
+    :path_to_file   the public path of the original file
+    `scaled`        keyword
+    :target         a label or width x height. An optional `-crop` can be included with either
+    :filename       the filename of the original image to scale
+    :hmac_signature security measure to validate the request(not required for labels)
+
+
+Supported Image Formats
+=======================
 
 ScaleDown will handle any image that Image Magick can process.  But there are some rules:
 
@@ -101,7 +150,9 @@ Installation & Configuration
 
     gem install scale_down
 
-Create a Rackup file (config.ru). See https://github.com/jweir/ScaleDown/tree/master/config_sample.ru more options
+Create a Rackup file (config.ru). 
+
+See https://github.com/jweir/ScaleDown/tree/master/config.sample.ru for all options
 
 ```ruby
 require 'rubygems'

data/config.sample.ru

@@ -0,0 +1,38 @@
+require 'scale_down'
+
+ScaleDown.tap do |config|
+
+  # The location of the public directory where the original are located
+  # This directory will also be the target for writing scaled images
+  # Most likely this will be a symbolic link to a shared directory
+  config.public_path = "#{File.expand_path(File.dirname(__FILE__))}/public"
+
+  # Labels are predefined geometries.
+  # They have the advantage of not requiring an HMAC signature in the URL
+  # The keys should be strings, not symbols
+  config.labels = {
+    "thumbnail" => "100x100"
+  }
+
+  # an array of the max width and height an image can be scaled, in pixels.
+  config.max_dimensions = [1200,1200]
+
+  # the max file size allowed for the original file to be scaled, in bytes
+  scaledown.max_file_size  = 25 * 1_048_576 # 25 Megabytes
+
+  # This is the shared secret for generating and verifying the HMAC signature.
+  # This string would be shared with any application generating URLS for scaled images
+  # http://www.random.org/strings/
+  config.hmac_key    = "secret"
+
+  # Change the method for generating the HMAC
+  config.hmac_method = HMAC::SHA1
+
+  # How long of an HMAC signature is required
+  config.hmac_length = 8
+
+  # Optional logger
+  # config.logger = YOUR_LOGGER
+end
+
+run ScaleDown::Controller

data/lib/scale_down/configuration.rb

@@ -31,6 +31,10 @@ module ScaleDown
     # +Must be set+
     attr_accessor :public_folder
 
+    # Labels are predefined gemeotries
+    attr_accessor :labels
+    ScaleDown.labels = Hash.new
+
     def public_folder=(str)
       @public_folder = str
       ScaleDown::Controller.public_folder = str

data/lib/scale_down/controller.rb

@@ -25,7 +25,7 @@ class ScaleDown::Controller < Sinatra::Application
     params = {
       :hmac     => request.env["QUERY_STRING"],
       :filename => parts.pop,
-      :geometry => parts.pop,
+      :target   => parts.pop, # the label or geometry
       :splat    => parts
     }
 
@@ -54,7 +54,7 @@ class ScaleDown::Controller < Sinatra::Application
     ScaleDown::Dispatcher.process \
       :path     => params[:splat].join("/"),
       :filename => params[:filename],
-      :geometry => params[:geometry],
+      :target   => params[:target],
       :hmac     => params[:hmac]
   end
 end

data/lib/scale_down/dispatcher.rb

@@ -37,11 +37,13 @@ class ScaleDown::Dispatcher
   end
 
   def image_options
-    dimensions, *options = @params[:geometry].split("-")
-    width, height = dimensions.split("x")
-    {:height => height.to_i, :width => width.to_i}.tap do |o|
-      options.each {|k| o[k.to_sym] = true}
-    end
+    width, height =  (target_is_label? ? ScaleDown.labels[target] : target).split("x")
+
+    {
+      :height => height.to_i,
+      :width  => width.to_i,
+      :crop   => crop?
+    }
   end
 
   def scale
@@ -51,8 +53,24 @@ class ScaleDown::Dispatcher
       :options => image_options
   end
 
+  def target
+    @dimensions ||= @params[:target].split(/-crop\Z/).first
+  end
+
+  def target_is_label?
+    @target_is_label ||= ScaleDown.labels.keys.include?(target)
+  end
+
+  def crop?
+    @crop ||= ! @params[:target].match(/-crop\Z/).nil?
+  end
+
   def valid_hmac?
-    ScaleDown.valid_hmac?(@params)
+    if target_is_label?
+      true
+    else
+      ScaleDown.valid_hmac?(@params)
+    end
   end
 
   def redirect_code
@@ -60,7 +78,7 @@ class ScaleDown::Dispatcher
   end
 
   def redirect_path
-    ["/"+@params[:path], @params[:geometry], scaled_filename].join("/")
+    ["/"+@params[:path], @params[:target], scaled_filename].join("/")
   end
 
   def root_file_exists?

data/lib/scale_down/version.rb

@@ -1,3 +1,3 @@
 module ScaleDown
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/scale_down.rb

@@ -19,7 +19,7 @@ module ScaleDown
 
 
   def self.valid_hmac?(params)
-    str = ["/", params[:path], "/", params[:geometry], "/", params[:filename]].join
+    str = ["/", params[:path], "/", params[:target], "/", params[:filename]].join
     hmac(str) == params[:hmac]
   end
 

data/test/scale_down/configuration_test.rb

@@ -9,5 +9,25 @@ class ScaleDown::Test < Test::Unit::TestCase
         assert_equal "/tmp/directory", ScaleDown::Controller.public_folder
       end
     end
+
+    context "labels" do
+      context "by default" do
+        should "be an empty hash" do
+        end
+      end
+
+      context "when defined" do
+        setup do
+          ScaleDown.labels = {
+            "thumbnail" => "40x40",
+            "large"     => "600x600"
+          }
+        end
+
+        should "return the defined hash" do
+          assert_equal "40x40", ScaleDown.labels["thumbnail"]
+        end
+      end
+    end
   end
 end

data/test/scale_down/controller_test.rb

@@ -12,16 +12,16 @@ class ScaleDown::Controller::Test < Test::Unit::TestCase
       ScaleDown::Dispatcher.expects(:process).with(
         :path     => "user/path/scaled",
         :filename => "filename.png",
-        :geometry => "400x300-crop-grayscale",
+        :target   => "400x300-crop-grayscale",
         :hmac     => "HMAC").
-      returns ["path","status"]
+        returns ["path","status"]
 
-      get '/user/path/scaled/400x300-crop-grayscale/filename.png?HMAC'
+        get '/user/path/scaled/400x300-crop-grayscale/filename.png?HMAC'
     end
   end
 
   context "a valid request" do
-    should "send the file" do
+    should "respond with the file" do
       ScaleDown::Dispatcher.expects(:process).returns ["/image-path", 302]
       get "/path/geo/filename?hmac"
 

data/test/scale_down/dispatcher_test.rb

@@ -14,7 +14,7 @@ class ScaleDown::Dispatcher::Test < Test::Unit::TestCase
       @params = {
         :path     => "file/path/scaled",
         :filename => "filename.png",
-        :geometry => "400x300-crop",
+        :target   => "400x300-crop",
         :hmac     => hmac[0...8]
       }
     end
@@ -87,8 +87,35 @@ class ScaleDown::Dispatcher::Test < Test::Unit::TestCase
       end
     end
 
-    context "process response" do
+    context "target" do
+      context "from a label" do
+        setup do
+          ScaleDown.labels = { "thumbnail" => "40x50" }
+          @subject = ScaleDown::Dispatcher.new :target => "thumbnail"
+        end
+
+        should "use the label's width and height" do
+          dim = @subject.image_options
+          assert_equal 40, dim[:width]
+          assert_equal 50, dim[:height]
+          assert_equal false, dim[:crop]
+        end
+
+        should "always valid the hmac" do
+          assert @subject.valid_hmac?
+        end
+
+        should "work with the cropped flag" do
+          @subject = ScaleDown::Dispatcher.new :target => "thumbnail-crop"
+          dim = @subject.image_options
+          assert_equal 40, dim[:width]
+          assert_equal 50, dim[:height]
+          assert_equal true, dim[:crop]
+        end
+      end
+    end
 
+    context "process response" do
       context "for an existing, unscaled image" do
         setup do
           File.expects(:exists?).with("/tmp/file/path/filename.png").returns true

data/test/scale_down_test.rb

@@ -26,7 +26,7 @@ class ScaleDown::Test < Test::Unit::TestCase
         @params = {
           :path     => "file/path",
           :filename => "filename.png",
-          :geometry => "400x300-crop",
+          :target   => "400x300-crop",
           :hmac     => hmac[0...8]
         }
       end
@@ -42,6 +42,7 @@ class ScaleDown::Test < Test::Unit::TestCase
 
     context "integration test" do
       setup do
+
         FileUtils.mkdir_p("/tmp/scale_down/test_images/example_1")
         FileUtils.cp fixture_path("files/graphic.png"), "/tmp/scale_down/test_images/example_1/graphic.png"
         FileUtils.mkdir_p("/tmp/scale_down/test_images/example_2")
@@ -58,7 +59,7 @@ class ScaleDown::Test < Test::Unit::TestCase
         assert_equal "300x500", last_response.body
       end
 
-      should "get an image and scale it" do
+      should "get an image with a geometry and scale it" do
         valid_get '/test_images/example_1/scaled/400x300-cropped/graphic.png'
         assert_equal 200, last_response.status
         assert File.exists?("/tmp/scale_down/test_images/example_1/scaled/400x300-cropped/graphic.png")
@@ -75,6 +76,29 @@ class ScaleDown::Test < Test::Unit::TestCase
         assert_equal 500, last_response.status
         assert !File.exists?("/tmp/scale_down/test_images/example_2/scaled/400x300-cropped/invalid_jpeg.jpg")
       end
+
+      context "using a label" do
+        setup do
+          ScaleDown.labels = { "very-large" => "600x600" }
+        end
+
+        should "get an image with a label and scale it" do
+          get '/test_images/example_1/scaled/very-large/graphic.png'
+          assert_equal 200, last_response.status
+          assert File.exists?("/tmp/scale_down/test_images/example_1/scaled/very-large/graphic.png")
+
+          get '/test_images/example_1/scaled/very-large-crop/graphic.png'
+          assert_equal 200, last_response.status
+          assert File.exists?("/tmp/scale_down/test_images/example_1/scaled/very-large-crop/graphic.png")
+        end
+
+        context "that does not exist" do
+          should "return an error" do
+            get '/test_images/example_1/scaled/toosmall/graphic.png'
+            assert_equal 403, last_response.status
+          end
+        end
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scale_down
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-24 00:00:00.000000000Z
+date: 2012-01-26 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rmagick
-  requirement: &2153706660 !ruby/object:Gem::Requirement
+  requirement: &2152325300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '2.1'
   type: :runtime
   prerelease: false
-  version_requirements: *2153706660
+  version_requirements: *2152325300
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &2153706160 !ruby/object:Gem::Requirement
+  requirement: &2152324800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *2153706160
+  version_requirements: *2152324800
 - !ruby/object:Gem::Dependency
   name: ruby-hmac
-  requirement: &2153705700 !ruby/object:Gem::Requirement
+  requirement: &2152324340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: 0.4.0
   type: :runtime
   prerelease: false
-  version_requirements: *2153705700
+  version_requirements: *2152324340
 - !ruby/object:Gem::Dependency
   name: contest
-  requirement: &2153705240 !ruby/object:Gem::Requirement
+  requirement: &2152323880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: 0.1.2
   type: :development
   prerelease: false
-  version_requirements: *2153705240
+  version_requirements: *2152323880
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2153704780 !ruby/object:Gem::Requirement
+  requirement: &2152323420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: 0.9.2.2
   type: :development
   prerelease: false
-  version_requirements: *2153704780
+  version_requirements: *2152323420
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &2153734500 !ruby/object:Gem::Requirement
+  requirement: &2152353140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -76,10 +76,10 @@ dependencies:
         version: 0.9.8
   type: :development
   prerelease: false
-  version_requirements: *2153734500
+  version_requirements: *2152353140
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &2153734040 !ruby/object:Gem::Requirement
+  requirement: &2152352680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -87,7 +87,7 @@ dependencies:
         version: 0.5.6
   type: :development
   prerelease: false
-  version_requirements: *2153734040
+  version_requirements: *2152352680
 description: ''
 email:
 - john@famedriver.com
@@ -102,7 +102,7 @@ files:
 - README.md
 - Rakefile
 - color_profiles/sRGB.icm
-- config_sample.ru
+- config.sample.ru
 - lib/scale_down.rb
 - lib/scale_down/configuration.rb
 - lib/scale_down/controller.rb

data/config_sample.ru

@@ -1,21 +0,0 @@
-require 'scale_down'
-
-ScaleDown.tap do |config|
-
-  # This is the shared secret.  Use something strong
-  # Perhaps a visit to http://www.random.org/strings/?num=10&len=20&digits=on&upperalpha=on&format=html&rnd=new
-  config.hmac_key    = "secret"
-
-  # You can use a different HMAC, see the ruby-hmac gen
-  config.hmac_method = HMAC::SHA1
-
-  # The length of the HMAC signature to use
-  config.hmac_length = 8
-
-  # The location of the public directory for serving static files
-  # This might be redudant since it will always, maybe, maybe not, be the same as root_path
-  config.public_path = "#{File.expand_path(File.dirname(__FILE__))}/public"
-
-end
-
-run ScaleDown::Controller