imageproxy 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,14 @@
+source :rubygems
+
+gem "rack"
+gem "rake"
+gem "mime-types"
+
+group :development, :test do
+  gem "heroku"
+  gem "shotgun"
+  gem "rspec"
+  gem "rack-test", :require => "rack/test"
+  gem "awesome_print"
+  gem "jeweler"
+end

data/Gemfile.lock

@@ -0,0 +1,48 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    awesome_print (0.3.2)
+    configuration (1.2.0)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    heroku (1.18.3)
+      launchy (~> 0.3.2)
+      rest-client (>= 1.4.0, < 1.7.0)
+    jeweler (1.6.2)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    launchy (0.3.7)
+      configuration (>= 0.0.5)
+      rake (>= 0.8.1)
+    mime-types (1.16)
+    rack (1.2.2)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rake (0.8.7)
+    rest-client (1.6.1)
+      mime-types (>= 1.16)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+    shotgun (0.9)
+      rack (>= 1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print
+  heroku
+  jeweler
+  mime-types
+  rack
+  rack-test
+  rake
+  rspec
+  shotgun

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Erik Hanson
+
+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.mdown

@@ -0,0 +1,296 @@
+imageproxy
+==========
+
+A image processing proxy server, written in Ruby as a Rack application.
+
+There are many possible uses for this, but one major use is to resize images on-the-fly directly from HTML code, rather than processing the image when it is first uploaded or created. For example, if a user uploads a file to your site and it gets stored in http://example.com/uploads/39c0c11af.png, you could show a 50x50 px version like this:
+
+    <img src="http://example.com/convert?resize=50x50&source=http%3A%2F%2Fexample.com%2Fuploads%2F39c0c11af.png">
+
+If you ever decided to change the size, you wouldn't have to re-encode anything, just change the HTML:
+
+    <img src="http://example.com/convert?resize=75x75&source=http%3A%2F%2Fexample.com%2Fuploads%2F39c0c11af.png">
+
+See http://imageproxy.heroku.com/selftest for some examples (it's running on Heroku's free plan, so it will be a bit slow).
+
+Status
+------
+
+This project is pretty new. There are definitely some improvements that can be/need to be made. Suggestions and pull requests are welcome.
+
+### Current Features
+
+  * display information about an image
+  * resize, flip, rotate, change format and change quality of images
+  * standard query-parameter based URLs as well as Amazon CloudFront-compatibile URLs
+  * tested on Heroku and Amazon EC2
+  * use the requester's user agent string
+  * signed requests (to stop unauthorized use)
+  * obfuscated params
+
+### Future Features
+
+Feel free to help out with some of these :)
+
+  * better documentation
+  * X-Sendfile / X-Accel-Redirect header
+  * signature generation testing tool
+  * try mounting inside a Rails app
+  * Rails helper for generating image tags that use imageproxy
+  * package as a gem?
+  * nice error messages for improper API use
+  * performance
+
+
+PERFORMANCE
+-----------
+
+imageproxy doesn't do any sort of caching. That kind of thing is better left up to CDNs (like Amazon CloudFront or VoxCast CDN) or to caching proxies such as Varnish.
+
+Also, imageproxy itself isn't nearly as fast as it could be. It's written in an interpreted language, and it shells out to curl and ImageMagick to do its work. Presumably, it would be way faster written in C as an Apache module, but this implementation was quite a bit easier :)
+
+
+API
+---
+
+There are two major functions: `identify` and `convert`, plus a helpful `selftest` function.
+
+### Identify
+
+`identify` spits out a lot of information about the provided image.
+
+#### Parameters
+
+`source` *(Required)* The URL of the image to identify.
+
+`signature` To stop unauthorized use. See the "Signing Requests" section of this document.
+
+### Convert
+
+`convert` converts an image.
+
+#### Parameters
+
+`source` *(Required)* The URL of the image to convert. (Also aliased to `src`.)
+
+`resize` The new size of the image, in "WxH" format (e.g., `20x30`).
+
+`thumbnail` The new size of the image, in "WxH" format (e.g., `20x30`). Thumbnailing assumes the resulting image will be pretty small and makes some optimizations.
+
+`shape` The shape of the image, when `resize`ing or `thumbnail`ing to a different aspect ratio. The value can be `preserve` which will preserve the original aspect ratio, `pad` which will add padding to keep the proper aspect ratio (you can supply a `background` parameter to choose the background color to pad with, or leave blank to pad with transparent color if the image format allows it), and `cut` which will cut the image to fit the new size.
+
+`flip` Flip the image. The value can be `horizontal` or `vertical`.
+
+`rotate` Rotate the image. The value can be any number. When rotating to a non-right-angle, you can specify the `background` parameter to choose the color for the background.
+
+`format` Change the format. Possible formats include `gif`, `jpg`, `png`, `png8`, etc.
+
+`quality` Choose the compression quality for formats that support lossy compression. The value can be any number from 0 to 100.
+
+`progressive` Choose whether a JPEG image should be a progressive JPEG or not. Possible values are `true` and `false`.
+
+`background` Some operations allow for a background color to be provided. The format is hex (e.g., `#ff00ff`) or rgba (e.g., `rgba(20,30,19,0.4)`)
+
+`signature` To stop unauthorized use. See the "Signing Requests" section of this document.
+
+`allowed_domains` A comma-separated list of second-level domains (e.g., "example.com, example.org") that are valid domains for the `source` parameter. If not specified, then the `source` parameter can reference any domain.
+
+`max_size` The maximum dimension allowed for a `resize` or `thumbnail` operation. Specifying `20` would cause a resize of `10x30` to fail because the maximum dimension of `20` is less than the largest requested dimension of `30`.
+
+### Request Format
+
+The request must start with `identify` or `convert` (for backwards-compatibility, `process` is a synonym for `convert`).
+
+The parameters can be query string parameters, like this:
+
+    http://example.com/convert?resize=100x100&shape=cut
+
+Or, the parameters can be Amazon CloudFront-compatible URLs, like this:
+
+    http://example.com/convert/resize/100x100/shape/cut
+
+You can also mix the parameters if you like. This doesn't make much sense except for the case of the `signature` parameter which must be a query param:
+
+    http://example.com/convert/resize/100x100?signature=szFGj470w%2ByhJYJfTRryFLF9msA%3D
+
+**Important:** Make sure to URL escape all query parameters. When using the CloudFront-compatible URL format, make sure to **double-escape** the source URL:
+
+    http://example.com/convert?resize=100x100&source=http://www.google.com/images/logos/ps_logo2.png # WRONG - not escaped
+    http://example.com/convert?resize=100x100&source=http%3A%2F%2Fwww.google.com%2Fimages%2Flogos%2Fps_logo2.png # RIGHT - escaped
+
+    http://exampe.com/convert/resize/100x100/source/http://www.google.com/images/logos/ps_logo2.png # WRONG - not escaped
+    http://exampe.com/convert/resize/100x100/source/http%3A%2F%2Fwww.google.com%2Fimages%2Flogos%2Fps_logo2.png # WRONG - only escaped once
+    http://exampe.com/convert/resize/100x100/source/http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png # RIGHT - escaped and then escaped again
+
+### Signing Requests
+
+To require that requests are signed, set the following two environment variables:
+
+    IMAGEPROXY_SIGNATURE_REQUIRED=true
+    IMAGEPROXY_SIGNATURE_SECRET=some secret key
+
+Then add a `signature` parameter to your query string or path.
+
+The signature is calculated with the following formula, which is the same formula that Amazon Web Services uses:
+
+    URLSafeBase64( HMAC-SHA1( UTF-8-Encoding-Of( YourSecretKey, StringToSign ) ) );
+
+Where YourSecretKey is a secret key that you make up, and StringToSign is the full path of the request, excluding host name and the "signature" parameter, in the same order as in the query. For `http://example.com/convert/resize/100x100?shape=cut&signature=szFGj470w%2ByhJYJfTRryFLF9msA%3D` the StringToSign would be `/convert/resize/100x100?shape=cut`.
+
+URL safe base64 is the normal encoding but with replacing the + with - and / with _.
+
+Example Ruby code to generate the signature:
+
+    digest = OpenSSL::Digest::Digest.new("sha1")
+    Base64.encode64(OpenSSL::HMAC.digest(digest, your_secret_key, your_query_string)).strip.tr('+/', '-_')
+
+### Obfuscating Requests
+
+You may obfuscate your requests by Base64 encoding and then URL encoding your query string or path. The parameter name for this encoded value is `_` if you're using a query string or `-` if you're using a path. Example:
+
+    http://example.com/convert?src=http://example.com/dog.jpg&resize=10x10
+    http://example.com/convert?_=c3JjPWh0dHA6Ly9leGFtcGxlLmNvbS9kb2cuanBnJnJlc2l6ZT0xMHgxMA%3D%3D
+    http://example.com/convert/-/c3JjPWh0dHA6Ly9leGFtcGxlLmNvbS9kb2cuanBnJnJlc2l6ZT0xMHgxMA%3D%3D
+
+### Example requests
+
+CloudFront-compatible URLs:
+
+    http://example.com/convert/resize/100x100/source/http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+    http://example.com/identify/source/http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Regular query string URLs:
+
+    http://example.com/convert?resize=100x100&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+    http://example.com/identify?source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Resize:
+
+    http://example.com/convert?resize=100x100&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Resize with padding:
+
+    http://example.com/convert?resize=100x100&shape=pad&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+    http://example.com/convert?resize=100x100&shape=pad&background=%23ff00ff&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Resize with cutting:
+
+    http://example.com/convert?resize=100x100&shape=cut&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Flipping:
+
+    http://example.com/convert?flip=horizontal&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+    http://example.com/convert?flip=vertical&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Rotating:
+
+    http://example.com/convert?rotate=90&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+    http://example.com/convert?rotate=120&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+    http://example.com/convert?rotate=120&background=%23ff00ff&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+Combo:
+
+    http://example.com/convert?resize=100x100&shape=cut&rotate=45&background=%23ff00ff&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png
+
+With signature (signed with secret key "SEEKRET"):
+
+    http://example.com/convert/resize/100x100/source/http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png?signature=iNoljMh0kALsoxRLzJfr7Wcq%2BnY%3D
+    http://example.com/convert?resize=100x100&source=http%253A%252F%252Fwww.google.com%252Fimages%252Flogos%252Fps_logo2.png&signature=KLga1QNdCY8Xu4thsKdbTUjnYAk%3D
+
+
+### Selftest
+
+You can go to the `/selftest` URL to see everything in action. For example: [http://imageproxy.heroku.com/selftest](http://imageproxy.heroku.com/selftest).
+
+
+Sample EC2 Installation Recipe
+------------------------------
+
+Create and boot an instance of an AWS Linux AMI using [Amazon's EC2 console](https://console.aws.amazon.com/ec2/). In this example, I used a "micro" instance.
+
+ssh into the instance as user `ec2-user`
+
+Make a directory for the proxy:
+
+    sudo mkdir /opt/imageproxy
+    sudo chown ec2-user:ec2-user /opt/imageproxy
+
+Install the Ruby HTTP stack + ImageMagick:
+
+    sudo yum -y install make gcc gcc-c++ http rubygems ruby-devel openssl-devel zlib-devel httpd-devel git curl-devel openssl ImageMagick ImageMagick-devel
+
+Install passenger:
+
+    sudo gem install passenger
+    sudo passenger-install-apache2-module
+
+Update the Apache config as suggested by the passenger installer
+
+    LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.5/ext/apache2/mod_passenger.so
+    PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.5
+    PassengerRuby /usr/bin/ruby
+
+Set up a VirtualHost as suggested by the passenger installer
+
+    <VirtualHost *:80>
+        ServerName ec2-184-72-213-98.compute-1.amazonaws.com
+        DocumentRoot /opt/imageproxy/public
+        <Directory /opt/imageproxy/public>
+            Allow from all
+            Options -MultiViews
+        </Directory>
+    </VirtualHost>
+
+Clone the imageproxy code:
+
+    git clone git://github.com/eahanson/imageproxy.git
+
+Install the gems:
+
+    bundle install
+
+Start Apache:
+
+    sudo /etc/init.d/httpd start
+
+
+Sample Heroku Installation Recipe
+------------------------------
+
+Clone the imageproxy code:
+
+    git clone git://github.com/eahanson/imageproxy.git
+
+Set up Heroku:
+
+    http://devcenter.heroku.com/articles/quickstart
+
+Deploy:
+
+    git push heroku master
+
+
+If You Want To Modify The Code
+------------------------------
+
+Tun run the server locally:
+
+    rackup
+
+Make sure everthing is working:
+
+    http://localhost:9292/selftest
+
+To run the specs
+
+    rake spec
+
+Thanks
+------
+
+Thanks to [David Hall](https://github.com/moonhouse) for code contributions.
+
+License
+-------
+
+Licensed under the MIT license. See LICENSE.txt.

data/Rakefile

@@ -0,0 +1,42 @@
+require 'bundler'
+Bundler.require :test
+
+desc "Run all specs"
+task :spec do
+  system 'rspec --format nested --color spec'
+end
+
+task :default => :spec
+
+desc "Run the server locally (for development)"
+task :run do
+  require 'uri'
+  puts <<EOF
+
+See examples at:
+
+  http://localhost:9393/selftest
+
+If you set IMAGEPROXY_SIGNATURE_REQUIRED and IMAGEPROXY_SIGNATURE_SECRET
+environment variables, then the requests in the selftest will be
+signed.
+
+EOF
+  system 'shotgun'
+end
+
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "imageproxy"
+  gem.homepage = "http://github.com/eahanson/imageproxy"
+  gem.license = "MIT"
+  gem.summary = %Q{A image processing proxy server, written in Ruby as a Rack application.}
+  gem.description = %Q{A image processing proxy server, written in Ruby as a Rack application. Requires ImageMagick.}
+  gem.email = "erik@eahanson.com"
+  gem.authors = ["Erik Hanson"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/config.ru

@@ -0,0 +1,7 @@
+require 'bundler'
+require 'rack/sendfile'
+
+require File.join(File.expand_path(File.dirname(__FILE__)), "imageproxy")
+require File.join(File.expand_path(File.dirname(__FILE__)), "lib", "server")
+
+run Rack::Sendfile.new(Server.new)

data/imageproxy.gemspec

@@ -0,0 +1,90 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{imageproxy}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Erik Hanson"]
+  s.date = %q{2011-06-08}
+  s.description = %q{A image processing proxy server, written in Ruby as a Rack application. Requires ImageMagick.}
+  s.email = %q{erik@eahanson.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.mdown"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.mdown",
+    "Rakefile",
+    "VERSION",
+    "config.ru",
+    "imageproxy.gemspec",
+    "imageproxy.rb",
+    "lib/command.rb",
+    "lib/compare.rb",
+    "lib/convert.rb",
+    "lib/identify.rb",
+    "lib/options.rb",
+    "lib/selftest.rb",
+    "lib/server.rb",
+    "lib/signature.rb",
+    "public/background.png",
+    "public/sample.png",
+    "public/sample_10x20.png",
+    "spec/command_spec.rb",
+    "spec/convert_spec.rb",
+    "spec/options_spec.rb",
+    "spec/server_spec.rb",
+    "spec/signature_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/eahanson/imageproxy}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{A image processing proxy server, written in Ruby as a Rack application.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rack>, [">= 0"])
+      s.add_runtime_dependency(%q<rake>, [">= 0"])
+      s.add_runtime_dependency(%q<mime-types>, [">= 0"])
+      s.add_development_dependency(%q<heroku>, [">= 0"])
+      s.add_development_dependency(%q<shotgun>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<rack-test>, [">= 0"])
+      s.add_development_dependency(%q<awesome_print>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<rack>, [">= 0"])
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<mime-types>, [">= 0"])
+      s.add_dependency(%q<heroku>, [">= 0"])
+      s.add_dependency(%q<shotgun>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<rack-test>, [">= 0"])
+      s.add_dependency(%q<awesome_print>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rack>, [">= 0"])
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<mime-types>, [">= 0"])
+    s.add_dependency(%q<heroku>, [">= 0"])
+    s.add_dependency(%q<shotgun>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<rack-test>, [">= 0"])
+    s.add_dependency(%q<awesome_print>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+