httpthumbnailer 0.3.1 → 1.0.0

data/Gemfile

@@ -1,21 +1,20 @@
 source "http://rubygems.org"
+ruby "1.9.3"
 
-gem "sinatra", ">= 1.2.6"
-gem "mongrel", ">= 1.2.0.pre2"
+gem "unicorn-cuba-base", "~> 1.0"
 gem "rmagick", "~> 2"
-gem "haml", "~> 3"
-gem "ruby-ip", "~> 0.9"
-gem "cli", "~> 1.1.0"
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rspec", "~> 2.3.0"
+  gem "rspec", "~> 2.13"
+  gem "rspec-mocks", "~> 2.13"
   gem "cucumber", ">= 0"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.6.4"
-  gem "rcov", ">= 0"
-  gem "daemon", "~> 1"
-  gem "httpclient", "~> 2.2"
+  gem "capybara", "~> 1.1"
+  gem "jeweler", "~> 1.8.4"
+  gem "httpclient", "~> 2.3"
   gem "rdoc", "~> 3.9"
+  gem "multipart-parser", "~> 0.1.1"
+  gem "daemon", "~> 1.1"
 end
+

data/Gemfile.lock

@@ -1,69 +1,93 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    builder (3.0.0)
-    cli (1.1.0)
-    cucumber (1.1.2)
+    builder (3.2.0)
+    capybara (1.1.4)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      selenium-webdriver (~> 2.0)
+      xpath (~> 0.1.4)
+    childprocess (0.3.9)
+      ffi (~> 1.0, >= 1.0.11)
+    cli (1.1.1)
+    cuba (3.1.0)
+      rack
+    cucumber (1.3.1)
       builder (>= 2.1.2)
-      diff-lcs (>= 1.1.2)
-      gherkin (~> 2.6.2)
-      json (>= 1.4.6)
-      term-ansicolor (>= 1.0.6)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.12.0)
+      multi_json (~> 1.3)
     daemon (1.1.0)
-    daemons (1.0.10)
-    diff-lcs (1.1.3)
-    gem_plugin (0.2.3)
-    gherkin (2.6.5)
-      json (>= 1.4.6)
+    diff-lcs (1.2.4)
+    facter (1.6.18)
+    ffi (1.8.1)
+    gherkin (2.12.0)
+      multi_json (~> 1.3)
     git (1.2.5)
-    haml (3.1.3)
-    httpclient (2.2.3)
-    jeweler (1.6.4)
+    httpclient (2.3.3)
+    jeweler (1.8.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
-    json (1.6.1)
-    mongrel (1.2.0.pre2)
-      daemons (~> 1.0.10)
-      gem_plugin (~> 0.2.3)
-    rack (1.3.5)
-    rack-protection (1.1.4)
+      rdoc
+    json (1.7.7)
+    kgio (2.8.0)
+    mime-types (1.23)
+    multi_json (1.7.3)
+    multipart-parser (0.1.1)
+    nokogiri (1.5.9)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    raindrops (0.11.0)
+    rake (10.0.4)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    rmagick (2.13.2)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    ruby-ip (0.9.1)
+    rubyzip (0.9.9)
+    selenium-webdriver (2.32.1)
+      childprocess (>= 0.2.5)
+      multi_json (~> 1.0)
+      rubyzip
+      websocket (~> 1.0.4)
+    unicorn (4.6.3)
+      kgio (~> 2.6)
       rack
-    rake (0.9.2.2)
-    rcov (0.9.11)
-    rdoc (3.9.4)
-    rmagick (2.13.1)
-    rspec (2.3.0)
-      rspec-core (~> 2.3.0)
-      rspec-expectations (~> 2.3.0)
-      rspec-mocks (~> 2.3.0)
-    rspec-core (2.3.1)
-    rspec-expectations (2.3.0)
-      diff-lcs (~> 1.1.2)
-    rspec-mocks (2.3.0)
-    ruby-ip (0.9.0)
-    sinatra (1.3.1)
-      rack (~> 1.3, >= 1.3.4)
-      rack-protection (~> 1.1, >= 1.1.2)
-      tilt (~> 1.3, >= 1.3.3)
-    term-ansicolor (1.0.7)
-    tilt (1.3.3)
+      raindrops (~> 0.7)
+    unicorn-cuba-base (1.0.0)
+      cli (~> 1.1.0)
+      cuba (~> 3.0)
+      facter (~> 1.6.11)
+      raindrops (~> 0.11)
+      ruby-ip (~> 0.9)
+      unicorn (>= 4.6.2)
+    websocket (1.0.7)
+    xpath (0.1.4)
+      nokogiri (~> 1.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.0.0)
-  cli (~> 1.1.0)
+  capybara (~> 1.1)
   cucumber
-  daemon (~> 1)
-  haml (~> 3)
-  httpclient (~> 2.2)
-  jeweler (~> 1.6.4)
-  mongrel (>= 1.2.0.pre2)
-  rcov
+  daemon (~> 1.1)
+  httpclient (~> 2.3)
+  jeweler (~> 1.8.4)
+  multipart-parser (~> 0.1.1)
   rdoc (~> 3.9)
   rmagick (~> 2)
-  rspec (~> 2.3.0)
-  ruby-ip (~> 0.9)
-  sinatra (>= 1.2.6)
+  rspec (~> 2.13)
+  rspec-mocks (~> 2.13)
+  unicorn-cuba-base (~> 1.0)

data/README.md

@@ -1,99 +1,229 @@
-# httpthumbnailer
+# HTTP Thumbnailer
 
 HTTP API server for image thumbnailing and format conversion.
 
-It is using **ImageMagick** as the image processing library.
+It is using [ImageMagick](http://www.imagemagick.org) or [GraphicsMagick](http://www.graphicsmagick.org) via [RMagick](http://rmagick.rubyforge.org) gem as the image processing library.
+
+## Features
+
+* thumbnailing images with different aspect ratio keeping methods
+* support of many input and output formats
+* efficient API for generating multiple thumbnails from single input image with just one request
+* many image scaling and loading performance optimizations
+* efficient memory usage
+* memory limits and disk memory offloading support
+* based on [Unicorn HTTP server](http://unicorn.bogomips.org) with UNIX socket communication support
 
 ## Installing
 
-You will need the following system packages installed: `imagemagick`, `libpng`, `pkg-config`, `make`.
-Optionally you may want to install `fcgi` package and gem to be able to use it as **FastCGI** backend.
+You will need the following system packages installed: `imagemagick`, `pkg-config` and `make`.
+For PNG support install `libpng`. You may want to consult [ImageMagick](http://www.imagemagick.org) installation guide for more information on supported formats and required libraries.
 
 For Arch Linux you can use this commands:
 
-    pacman -S imagemagick
-    pacman -S libpng
-    pacman -S pkg-config
-    pacman -S make
+```bash
+pacman -S imagemagick
+pacman -S libpng
+pacman -S pkg-config
+pacman -S make
+```
 
 Then you can install the gem as usual:
 
-    gem install httpthumbnailer
+```bash
+gem install httpthumbnailer
+```
+
+Optionally install Ruby client library and tool:
+
+```bash
+gem install httpthumbnailer-client
+```
 
 ## Usage
 
-It can be started as a stand alone server or as FastCGI backend.
+### Getting started
+
+```bash
+# install httpthumbnailer (see above)
+# install httpthumbnailer-client
+gem install httpthumbnailer-client
+
+# start thumbnailing server in foreground (to stop hit Ctlr-C)
+httpthumbnailer --foreground --verbose
+
+# in another console thumbnail to standard output
+cat ~/Pictures/compute.jpg | httpthumbnailer-client -t crop,100,200,png > thumbnail.png
+
+# generate multiple thumbnails
+cat ~/Pictures/compute.jpg | httpthumbnailer-client -t crop,100,200,jpeg,quality:100 -t pad,200,200,png thumbnail1.jpg thumbnail2.png
+```
+
+In this example we use [httpthumbnailer-client](http://github.com/jpastuszek/httpthumbnailer-client) gem CLI tool that will use HTTP API of the server to generate thumbnails.
+
+### Running the server
 
-### Stand alone server
+HTTP Thumbnailer uses worker based server model thanks to [Unicorn HTTP server](http://unicorn.bogomips.org) gem.
 
-This mode is useful for testing.
-By default **Mongrel** will be used as HTTP handling library (you can use --server option to specify different server that is supported by Sinatra).
+To start the thumbnailer use `httpthumbnailer` command.
+By default it will start in background and will spawn CPU core number + 1 number of worker processes.
+It will be listening on **localhost** port **3100**.
 
-To start it in that mode run:
+To start in foreground with verbose output use `httpthumbnailer --verbose --foreground`.
+To see available switches and options use `httpthumbnailer --help`.
 
-    httpthumbnailer
+When running in background the master server process will store it's PID in `httpthumbnailer.pid` file. You can change pid file location with `--pid-file` option.
+If running as root you can use `--user` option to specify user with whose privileges the worker processes will be running.
 
-By default it will be listening on **localhost** port **3100**.
+### Logging
 
-### FastCGI
+`httpthumbnailer` logs to `httpthumbnailer.log` file in current directory by default. You can change log file location with `--log-file` option and verbosity with `--verbose` or `--debug` switch.
 
-In this mode you can run many **httpthumbnailer** instances so that requests will be load balanced between them equally.
-Since it is single threaded (some ImageMagick operations may be multithreaded) it will be able to max out only single CPU core.
-Therefore it is recommended to run as many instances as there are CPU cores available.
+Additionally `httpthumbnailer` will log requests in [common NCSA format](http://en.wikipedia.org/wiki/Common_Log_Format) to `httpthumbnailer_access.log` file. Use `--access-log-file` option to change location of access log.
 
-Make sure you have FastCGI system library installed.
+### Supported operations
 
-For Arch Linux you can use this command:
+As operation type you can select one of the following options:
+* fit - fit image within given dimensions keeping aspect ratio
+* crop - cut image to fit within given dimensions keeping aspect ratio
+* pad - fit scale image and pad image with background colour to given dimensions keeping aspect ratio
+* limit - fit scale image to given dimensions if it is larger than that dimensions
 
-    pacman -S fcgi
+### Supported formats
 
-And you have `fcgi` gem installed with:
+List of supported formats can be displayed with `httpthumbnailer --formats`.
+Optionally format `input` can be used to use the same thumbnail format as input image.
 
-    gem install fcgi
+### Thumbnail width and height
 
-Here is an example **Lighttpd** configuration:
+Width and height values are interpreted depending on operation.
+`input` string can be used for width and/or height to use input image width or height.
 
-    $SERVER["socket"] == ":3100" {
-        server.reject-expect-100-with-417 = "disable" 
-    	fastcgi.debug = 1
-    	fastcgi.server    = ( "/" =>
-    		((
-    			"socket" => "/var/run/lighttpd/httpthumbniler.sock",
-    			"bin-path" => "/usr/bin/httpthumbnailer -s fastcgi --no-bind --no-logging",
-    			"max-procs" => 2,
-    			"check-local" => "disable",
-    			"fix-root-scriptname" => "enable",
-    		))
-    	)
-    }
+### Thumbnail options
 
-The `"max-procs" => 2` controls the number of instances started.
-In case that the `httpthumbnailer` process crashes (may happen since it is using native libraries) it will be restarted by Lighttpd.
+Following options can be used with thumbnail specification:
+* quality - set output image quality; this is format specific: for JPEG 0 is maximum compression and 100 is maximum quality, for PNG first digit is zlib compression level and second one is filter level
+* background-color - color in HTML notation or textual description ('red', 'green' etc.) used for background when processing transparent images or padding; by default white background is used
 
 ### API
 
-Basically it works like that:
+#### Single thumbnail API
+
+To generate single thumbnail send input image with **PUT** request to URI in format:
+
+    /thumbnail/<operation type>,<width>,<height>,<format>[,<option key>:<option value>]*
+
+Server will respond with thumbnail data with correct **Content-Type** header value.
+
+For example the URI may look like this: 
+
+    /thumbnail/pad,100,100,png,background-color:green
+
+For detailed information about the API see [cucumber features](http://github.com/jpastuszek/httpthumbnailer/blob/master/features/thumbnail.feature).
+
+#### Multipart API
+
+To generate multiple thumbnails of single image send that image with **PUT** request to URI in format:
+
+    /thumbnails/<operation type>,<width>,<height>,<format>[,<option key>:<option value>]*[/<operation type>,<width>,<height>,<format>[,<option key>:<option value>]*]*
 
-1. PUT your image data to the server with URI describing thumbnail format (one or more)
-2. the server will respond with **multi-part content** with parts containing data of your thumbnails in order with proper **Content-type** headers set
+Server will respond with **multi-part content** with each part containing **Content-Type** header and thumbnail data corresponding to format defined in the URI.
 
 For example the URI may look like this: 
 
-    /thumbnail/crop,16,16,PNG/crop,4,8,JPG/pad,16,32,JPEG
+    /thumbnails/crop,16,16,png/crop,4,8,jpg/pad,16,32,jpeg
+
+HTTP Thumbnailer will generate 3 thumbnails: 
+ 1. 16x16 cropped PNG
+ 2. 4x8 cropped JPEG
+ 3. 16x32 colour padded JPEG
+
+For detailed information about the API see [cucumber features](http://github.com/jpastuszek/httpthumbnailer/blob/master/features/thumbnails.feature).
+
+### Ruby API client
+
+To make it easier to use this server [httpthumbnailer-client](http://github.com/jpastuszek/httpthumbnailer-client) gem provides useful class.
+
+### Memory limits
+
+Each worker uses [ImageMagick](http://www.imagemagick.org) memory usage limit feature.
+By default it will use up to 128MiB of RAM and up to 1GiB of disk backed virtual memory.
+To change this defaults use `--limit-memory` option for RAM limit and `--limit-disk` to control file backed memory mapping limit in MiB.
+
+## Status codes
+
+HTTP Thumbnailer will respond with different status codes on different situations.
+If all goes well 200 OK will be returned otherwise:
+
+### 400
+
+* requested thumbnail method is not supported
+* at least one image dimension is zero in thumbnail spec
+* missing option key or value in thumbnail spec
+* missing argument in in thumbnail spec
+* bad argument value
+
+### 413
+
+* request body is too long
+* input image is too big to fit in memory
+* memory or pixel cache limit has been exceeded
+
+### 415
+
+* unsupported media type - see **Supported formats** section
+
+### 500
+
+* unexpected error has occurred - see the log file
+
+### Multipart API
+
+In multipart API when error relates to single thumbnail `Content-Type: plain/text` header will be used for that part.
+In addition `Status` header will be set for failing part with number corresponding to above status codes.
+The body will contain description of the error.
+
+## Statistics API
+
+HTTP Thumbnailer comes with statistics API that shows various runtime collected statistics.
+It is set up under `/stats` URI. You can also request single stat with `/stats/<stat name>` request.
 
-It will generate 3 thumbnails: 
+Example:
 
-1. 16x16 cropped PNG
-2. 4x8 cropped JPEG
-3. 16x32 colour padded JPEG
+```bash
+$ curl 127.0.0.1:3100/stats
+total_requests: 119
+total_errors: 1
+calling: 1
+writing: 0
+total_images_loaded: 115
+total_images_prescaled: 30
+total_thumbnails_created: 147
+images_loaded: 0
+max_images_loaded: 3
+max_images_loaded_worker: 3
+total_images_created: 312
+total_images_destroyed: 312
+total_images_created_from_blob: 115
+total_images_created_initialize: 53
+total_images_created_resize: 101
+total_images_created_crop: 13
+total_images_created_sample: 30
+total_write_multipart: 16
+total_write: 101
+total_write_part: 48
+total_write_error: 1
+total_write_error_part: 0
 
-For detailed information about the API see [cucumber features](http://github.com/jpastuszek/httpthumbnailer/blob/master/features/httpthumbnailer.feature).
+$ curl 127.0.0.1:3100/stats/total_write_multipart
+16
+```
 
-### API client
+## See also
 
-To make it easy to use this server there is [httpthumbnailer-client](http://github.com/jpastuszek/httpthumbnailer-client) gem provided.
+[HTTP Image Store](https://github.com/jpastuszek/httpimagestore) service is configurable image storage and processing HTTP API server that uses this service as thumbnailing backend. 
 
-## Contributing to httpthumbnailer
+## Contributing to HTTP Thumbnailer
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
@@ -105,6 +235,6 @@ To make it easy to use this server there is [httpthumbnailer-client](http://gith
 
 ## Copyright
 
-Copyright (c) 2012 Jakub Pastuszek. See LICENSE.txt for
+Copyright (c) 2013 Jakub Pastuszek. See LICENSE.txt for
 further details.
 

data/VERSION

@@ -1 +1 @@
-0.3.1
+1.0.0