akdubya-rack-thumb 0.2.2

data/README.rdoc

@@ -0,0 +1,81 @@
+== Rack::Thumb: Drop-in image thumbnailing for your Rack stack
+
+<tt>Rack::Thumb</tt> is drop-in dynamic thumbnailing middleware for Rack-based
+applications, featuring simple configuration, optional security (via url-signing),
+and maximum flexibility.
+
+== Getting Started
+
+You will need ImageMagick and the Mapel gem (http://github.com/akdubya/mapel).
+
+  gem install akdubya-rack-thumb
+
+  # rackup.ru
+  require 'myapp'
+  require 'rack/thumb'
+
+  use Rack::Thumb
+  use Rack::Static, :urls => ["/media"]
+
+  run MyApp.new
+
+<tt>Rack::Thumb</tt> is file-server agnostic to provide maximum deployment
+flexibility. Simply set it up in front of any application that's capable of
+serving source images (I'm using it with an app that serves images from CouchDB).
+
+See the example directory for more <tt>Rack</tt> configurations. Because
+thumbnailing is an expensive operation, you should run <tt>Rack::Thumb</tt>
+behind a cache, such as the excellent <tt>Rack::Cache</tt>.
+
+== Rendering Options
+
+<tt>Rack::Thumb</tt> intercepts requests for images that have urls of
+the form <code>/path/to/image_{metadata}.ext</code> and returns rendered
+thumbnails. Rendering options include +width+, +height+ and +gravity+. If
+both +width+ and +height+ are supplied, images are cropped and resized
+to fit the aspect ratio.
+
+Link to thumbnails from your templates as follows:
+
+  /media/foobar_50x50.jpg     # => Crop and resize to 50x50
+  /media/foobar_50x50-nw.jpg  # => Crop and resize with northwest gravity
+  /media/foobar_50x.jpg       # => Resize to a width of 50, preserving AR
+  /media/foobar_x50.jpg       # => Resize to a height of 50, preserving AR
+
+== URL Signing
+
+To prevent pesky end-users and bots from flooding your application with
+render requests you can set up <tt>Rack::Thumb</tt> to check for a <tt>SHA-1</tt>
+signature that is unique to every url. Using this option, only thumbnails requested
+by your templates will be valid. Example:
+
+  use Rack::Thumb(
+    :secret => "My secret",   # => Don't tell anyone!
+    :key_length => "16"       # => Only use 16 digits of the SHA-1 key
+  )
+
+You can then use your +secret+ to generate secure links in your templates using
+Ruby's built-in <tt>Digest::SHA1</tt> library:
+
+  /media/foobar_50x100-sw-a267c193a7eff046.jpg  # => Successful
+  /media/foobar_120x250-a267c193a7eff046.jpg    # => Returns a bad request error
+
+There are no helper modules just yet but it's easy enough to roll your own.
+
+== Deep Thoughts
+
+<tt>Rack::Thumb</tt> respects any extra headers you set in your downstream app.
+You are free to set caching policies, etc. however you like. Incoming HEAD requests
+skip the rendering step.
+
+There are a decent number of specs but the middleware isn't very strict at
+checking options at the moment, and I'm sure there are a few edge cases that need
+to be looked into. Comments, suggestions and bug reports are welcome.
+
+== Meta
+
+Written by Aleks Williams (http://github.com/akdubya)
+
+Released under the MIT License: www.opensource.org/licenses/mit-license.php
+
+github.com/akdubya/rack-thumb

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'fileutils'
+
+task :default => [:test]
+task :spec => :test
+
+name = 'rack-thumb'
+version = '0.2.2'
+
+spec = Gem::Specification.new do |s|
+  s.name = name
+  s.version = version
+  s.summary = "Drop-in image thumbnailing for your Rack stack."
+  s.description = "Drop-in image thumbnailing middleware for your Rack stack (Merb, Sinatra, Rails, etc)."
+  s.author = "Aleksander Williams"
+  s.email = "alekswilliams@earthlink.net"
+  s.homepage = "http://github.com/akdubya/rack-thumb"
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.files = %w(Rakefile README.rdoc) + Dir.glob("{lib,spec,example}/**/*")
+  s.require_path = "lib"
+  s.add_dependency("akdubya-mapel", ">= 0.1.1")
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.need_tar = true if RUBY_PLATFORM !~ /mswin/
+end
+
+desc "Install as a system gem"
+task :install => [ :package ] do
+  sh %{sudo gem install pkg/#{name}-#{version}.gem}
+end
+
+desc "Uninstall as a system gem"
+task :uninstall => [ :clean ] do
+  sh %{sudo gem uninstall #{name}}
+end
+
+desc "Create a gemspec file"
+task :make_spec do
+  File.open("#{name}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "spec"
+  t.test_files = FileList['spec/*_spec.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |t|
+  t.rdoc_dir = 'rdoc'
+  t.title = "Rack Thumb: Drop-in image thumbnailing for your Rack stack"
+  t.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+  t.options << '--charset' << 'utf-8'
+  t.rdoc_files.include('README.rdoc')
+  t.rdoc_files.include('lib/rack/rack-thumb.rb')
+  t.rdoc_files.include('lib/rack/rack-thumb/*.rb')
+end

data/example/file.ru

@@ -0,0 +1,7 @@
+require 'rack/thumb'
+
+use Rack::ShowExceptions
+use Rack::CommonLogger
+use Rack::Thumb
+
+run Rack::File.new(::File.dirname(__FILE__) + '/public')

data/example/frank.rb

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'thin'
+require 'sinatra'
+require 'rack/cache'
+require 'rack/thumb'
+
+use Rack::Cache,
+  :metastore   => 'file:/var/cache/rack/meta',
+  :entitystore => 'file:/var/cache/rack/body'
+use Rack::Thumb
+
+get '/' do
+  "Hello World!"
+end

data/example/static.ru

@@ -0,0 +1,10 @@
+require 'rack/thumb'
+
+use Rack::ShowExceptions
+use Rack::CommonLogger
+use Rack::Thumb
+use Rack::Static, :urls => ["/images"], :root => "public"
+
+app = lambda { |env| [200, {"Content-Type" => "text/plain"}, ["Hello World!"]] }
+
+run app

data/lib/rack/thumb.rb

@@ -0,0 +1,270 @@
+require 'rack'
+require 'mapel'
+require 'digest/sha1'
+
+require 'tempfile'
+
+Tempfile.class_eval do
+  def make_tmpname(basename, n)
+    ext = nil
+    sprintf("%s%d-%d%s", basename.to_s.gsub(/\.\w+$/) { |s| ext = s; '' }, $$, n, ext)
+  end
+end
+
+module Rack
+
+#   The Rack::Thumb middleware intercepts requests for images that have urls of
+#   the form <code>/path/to/image_{metadata}.ext</code> and returns rendered
+#   thumbnails. Rendering options include +width+, +height+ and +gravity+. If
+#   both +width+ and +height+ are supplied, images are cropped and resized
+#   to fit the aspect ratio.
+#
+#   Rack::Thumb is file-server agnostic to provide maximum deployment
+#   flexibility. Simply set it up in front of any downstream application that
+#   can serve the source images. Example:
+#
+#     # rackup.ru
+#     require 'rack/thumb'
+#
+#     use Rack::Thumb
+#     use Rack::Static, :urls => ["/media"]
+#
+#     run MyApp.new
+#
+#   See the example directory for more <tt>Rack</tt> configurations. Because
+#   thumbnailing is an expensive operation, you should run Rack::Thumb
+#   behind a cache, such as <tt>Rack::Cache</tt>.
+#
+#   Link to thumbnails from your templates as follows:
+#
+#     /media/foobar_50x50.jpg     # => Crop and resize to 50x50
+#     /media/foobar_50x50-nw.jpg  # => Crop and resize with northwest gravity
+#     /media/foobar_50x.jpg       # => Resize to a width of 50, preserving AR
+#     /media/foobar_x50.jpg       # => Resize to a height of 50, preserving AR
+#
+#   To prevent pesky end-users and bots from flooding your application with
+#   render requests you can set up Rack::Thumb to check for a <tt>SHA-1</tt> signature
+#   that is unique to every url. Using this option, only thumbnails requested
+#   by your templates will be valid. Example:
+#
+#     use Rack::Thumb(
+#       :secret => "My secret",
+#       :key_length => "16"       # => Only use 16 digits of the SHA-1 key
+#     )
+#
+#   You can then use your +secret+ to generate secure links in your templates:
+#
+#     /media/foobar_50x100-sw-a267c193a7eff046.jpg  # => Successful
+#     /media/foobar_120x250-a267c193a7eff046.jpg    # => Returns a bad request error
+#
+
+  class Thumb
+    RE_TH_BASE = /_([0-9]+x|x[0-9]+|[0-9]+x[0-9]+)(-(?:nw|n|ne|w|c|e|sw|s|se))?/
+    RE_TH_EXT = /(\.(?:jpg|jpeg|png|gif))/i
+    TH_GRAV = {
+      '-nw' => :northwest,
+      '-n' => :north,
+      '-ne' => :northeast,
+      '-w' => :west,
+      '-c' => :center,
+      '-e' => :east,
+      '-sw' => :southwest,
+      '-s' => :south,
+      '-se' => :southeast
+    }
+
+    def initialize(app, options={})
+      @app = app
+      @keylen = options[:keylength]
+      @secret = options[:secret]
+      @routes = generate_routes(options[:urls] || ["/"], options[:prefix])
+    end
+
+    # Generates routes given a list of prefixes.
+    def generate_routes(urls, prefix = nil)
+      urls.map do |url|
+        prefix = prefix ? Regexp.escape(prefix) : ''
+        url = url == "/" ? '' : Regexp.escape(url)
+        if @keylen
+          /^#{prefix}(#{url}\/.+)#{RE_TH_BASE}-([0-9a-f]{#{@keylen}})#{RE_TH_EXT}$/
+        else
+          /^#{prefix}(#{url}\/.+)#{RE_TH_BASE}#{RE_TH_EXT}$/
+        end
+      end
+    end
+
+    def call(env)
+      dup._call(env)
+    end
+
+    def _call(env)
+      response = catch(:halt) do
+        throw :halt unless %w{GET HEAD}.include? env["REQUEST_METHOD"]
+        @env = env
+        @path = env["PATH_INFO"]
+        @routes.each do |regex|
+          if match = @path.match(regex)
+            @source, dim, grav = extract_meta(match)
+            @image = get_source_image
+            @thumb = render_thumbnail(dim, grav) unless head?
+            serve
+          end
+        end
+        nil
+      end
+
+      response || @app.call(env)
+    end
+    
+    # Extracts filename and options from the path.
+    def extract_meta(match)
+      result = if @keylen
+        extract_signed_meta(match)
+      else
+        extract_unsigned_meta(match)
+      end
+
+      throw :halt unless result
+      result
+    end
+
+    # Extracts filename and options from a signed path.
+    def extract_signed_meta(match)
+      base, dim, grav, sig, ext = match.captures
+      digest = Digest::SHA1.hexdigest("#{base}_#{dim}#{grav}#{ext}#{@secret}")[0..@keylen-1]
+      throw(:halt, forbidden) unless sig && (sig == digest)
+      [base + ext, dim, grav]
+    end
+
+    # Extracts filename and options from an unsigned path.
+    def extract_unsigned_meta(match)
+      base, dim, grav, ext = match.captures
+      [base + ext, dim, grav]
+    end
+
+    # Fetch the source image from the downstream app, returning the downstream
+    # app's response if it is not a success.
+    def get_source_image
+      status, headers, body = @app.call(@env.merge(
+        "PATH_INFO" => @source
+      ))
+
+      unless (status >= 200 && status < 300) &&
+          (headers["Content-Type"].split("/").first == "image")
+        throw :halt, [status, headers, body]
+      end
+
+      @source_headers = headers
+
+      if !head?
+        if body.respond_to?(:path)
+          ::File.open(body.path, 'rb')
+        elsif body.respond_to?(:each)
+          data = ''
+          body.each { |part| data << part.to_s }
+          Tempfile.new(::File.basename(@path)).tap do |f|
+            f.binmode
+            f.write(data)
+            f.close
+          end
+        end
+      else
+        nil
+      end
+    end
+
+    # Renders a thumbnail from the source image. Returns a Tempfile.
+    def render_thumbnail(dim, grav)
+      gravity = grav ? TH_GRAV[grav] : :center
+      dimensions = parse_dimensions(dim)
+      output = create_tempfile
+      cmd = Mapel(@image.path).gravity(gravity)
+      width, height = dimensions
+      if width && height
+        cmd.resize!(width, height)
+      else
+        cmd.resize(width, height, 0, 0, :>)
+      end
+      cmd.to(output.path).run
+      output
+    end
+
+    # Serves the thumbnail. If this is a HEAD request we strip the body as well
+    # as the content length because the render was never run.
+    def serve
+      lastmod = Time.now.httpdate
+      # Use origin content type?
+      ctype = Mime.mime_type(::File.extname(@path), 'text/plain')
+
+      response = if head?
+        @source_headers.delete("Content-Length")
+        [200, @source_headers.merge(
+            "Last-Modified"  => lastmod,
+            "Content-Type"   => ctype
+          ), []]
+      else
+        [200, @source_headers.merge(
+            "Last-Modified"  => lastmod,
+            "Content-Type"   => ctype,
+            "Content-Length" => ::File.size(@thumb.path).to_s
+          ), self]
+      end
+
+      throw :halt, response
+    end
+
+    # Parses the rendering options; returns false if rendering options are invalid
+    def parse_dimensions(meta)
+      dimensions = meta.split('x').map do |dim|
+        if dim.empty?
+          nil
+        elsif dim[0].to_i == 0
+          throw :halt, bad_request
+        else
+          dim.to_i
+        end
+      end
+      dimensions.any? ? dimensions : throw(:halt, bad_request)
+    end
+
+    def resolve(uri)
+      uri = URI.parse(uri) unless uri.respond_to?(:scheme)
+      if uri.scheme == "file"
+        ::File.expand_path(uri.opaque || uri.path)
+      else
+        uri.to_s
+      end
+    end
+
+    # Creates a new tempfile
+    def create_tempfile
+      Tempfile.new(::File.basename(@path)).tap { |f| f.close }
+    end
+
+    def bad_request
+      body = "Bad thumbnail parameters in #{@path}\n"
+      [400, {"Content-Type" => "text/plain",
+         "Content-Length" => body.size.to_s},
+       [body]]
+    end
+
+    def forbidden
+      body = "Bad thumbnail signature in #{@path}\n"
+      [403, {"Content-Type" => "text/plain",
+         "Content-Length" => body.size.to_s},
+       [body]]
+    end
+
+    def head?
+      @env["REQUEST_METHOD"] == "HEAD"
+    end
+
+    def each
+      ::File.open(@thumb.path, "rb") { |file|
+        while part = file.read(8192)
+          yield part
+        end
+      }
+    end
+  end
+end

data/spec/base_spec.rb

@@ -0,0 +1,167 @@
+require File.dirname(__FILE__) + '/helpers'
+
+describe "Rack::Thumb Base" do
+  before do
+    @app = Rack::File.new(::File.dirname(__FILE__))
+  end
+
+  it "should render a thumbnail with width only" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_50x.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 6221
+    res.body.bytesize.should == 6221
+  end
+
+  it "should render a thumbnail with height only" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_x50.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 5912
+    res.body.bytesize.should == 5912
+  end
+
+  it "should render a thumbnail with width and height (crop-resize)" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_50x50.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 6074
+    res.body.bytesize.should == 6074
+  end
+
+  it "should render a thumbnail with width, height and gravity (crop-resize)" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_50x100-sw.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 6696
+    res.body.bytesize.should == 6696
+  end
+
+  it "should render a thumbnail with a signature" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app, :keylength => 16,
+      :secret => "test"))
+
+    sig = Digest::SHA1.hexdigest("/media/imagick_50x100-sw.jpgtest")[0..15]
+    res = request.get("/media/imagick_50x100-sw-#{sig}.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 6696
+    res.body.bytesize.should == 6696
+  end
+
+  it "should not render a thumbnail that exceeds the original image's dimensions" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_1000x1000.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    # There is a miniscule difference between this and the original
+    # because this is run through the processor.
+    res.content_length.should == 97373
+    res.body.bytesize.should == 97373
+  end
+
+  it "should work with non-file source bodies" do
+    app = lambda { |env| [200, {"Content-Type" => "image/jpeg"},
+        [::File.read(::File.dirname(__FILE__) + "/media/imagick.jpg")]] }
+
+    request = Rack::MockRequest.new(Rack::Thumb.new(app))
+
+    res = request.get("/media/imagick_50x.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 6221
+    res.body.bytesize.should == 6221
+  end
+
+  it "should return forbidden if the signature is invalid" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app, :keylength => 16,
+      :secret => "test"))
+
+    res = request.get("/media/imagick_50x100-sw-9922d04b14049f85.jpg")
+    res.should.be.forbidden
+    res.body.should == "Bad thumbnail signature in /media/imagick_50x100-sw-9922d04b14049f85.jpg\n"
+  end
+
+  it "should return bad request if the dimensions are bad" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_0x50.jpg")
+    res.should.be.client_error
+    res.body.should == "Bad thumbnail parameters in /media/imagick_0x50.jpg\n"
+  end
+
+  it "should return bad request if dimensions contain leading zeroes" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/imagick_50x050.jpg")
+    res.should.be.client_error
+    res.body.should == "Bad thumbnail parameters in /media/imagick_50x050.jpg\n"
+  end
+
+  it "should return the application's response if the source file is not found" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.get("/media/dummy_50x50.jpg")
+    res.should.be.not_found
+    res.body.should == "File not found: /media/dummy.jpg\n"
+  end
+
+  it "should return the application's response if it does not recognize render options" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app, :keylength => 16,
+      :secret => "test"))
+
+    res = request.get("/media/imagick_50x50!.jpg")
+    res.should.be.not_found
+    res.body.should == "File not found: /media/imagick_50x50!.jpg\n"
+  end
+
+  it "should pass non-thumbnail image requests to the application" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app, :keylength => 16,
+      :secret => "test"))
+
+    res = request.get("/media/imagick.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should == 97374
+    res.body.bytesize.should == 97374
+  end
+
+  it "should not render on a HEAD request" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.request("HEAD", "/media/imagick_50x50.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should.be.nil
+    res.body.bytesize.should == 0
+  end
+
+  it "should preserve any extra headers provided by the downstream app" do
+    app = lambda { |env| [200, {"X-Foo" => "bar", "Content-Type" => "image/jpeg"},
+        ::File.open(::File.dirname(__FILE__) + "/media/imagick.jpg")] }
+
+    request = Rack::MockRequest.new(Rack::Thumb.new(app))
+
+    res = request.request("HEAD", "/media/imagick_50x50.jpg")
+    res.should.be.ok
+    res.content_type.should == "image/jpeg"
+    res.content_length.should.be.nil
+    res.headers["X-Foo"].should == "bar"
+  end
+
+  it "should forward POST/PUT/DELETE requests to the downstream app" do
+    request = Rack::MockRequest.new(Rack::Thumb.new(@app))
+
+    res = request.post("/media/imagick_50x50.jpg")
+    res.should.not.be.successful
+  end
+end

data/spec/helpers.rb

@@ -0,0 +1,9 @@
+require 'bacon'
+require File.dirname(File.dirname(__FILE__)) + '/lib/rack/thumb'
+require 'rack/mock'
+
+class String
+  def each(*args, &block)
+    each_line(*args, &block)
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: akdubya-rack-thumb
+version: !ruby/object:Gem::Version 
+  version: 0.2.2
+platform: ruby
+authors: 
+- Aleksander Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-11 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: akdubya-mapel
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.1
+    version: 
+description: Drop-in image thumbnailing middleware for your Rack stack (Merb, Sinatra, Rails, etc).
+email: alekswilliams@earthlink.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- README.rdoc
+- lib/rack
+- lib/rack/thumb.rb
+- spec/media
+- spec/media/imagick.jpg
+- spec/base_spec.rb
+- spec/helpers.rb
+- example/frank.rb
+- example/static.ru
+- example/public
+- example/public/images
+- example/public/images/imagick.jpg
+- example/file.ru
+has_rdoc: true
+homepage: http://github.com/akdubya/rack-thumb
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Drop-in image thumbnailing for your Rack stack.
+test_files: []
+