image_vise 0.0.16

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a1fd49220c9d775bba0d8f8a5646b2e78a4412c5
+  data.tar.gz: 8b0033eed381e0c135bf8b109cc9013f63e58bdd
+SHA512:
+  metadata.gz: a46027f576b9237097f7813d76399b9bfddd23e6c2d948416cee63e758236d56791ec1b33cef0a3ab9322e1817424c5ac4b167216cd210bfeba2cf54b6fde4da
+  data.tar.gz: 376b9f9efe967201740f83f4778df4eff720dc8525c7a62d2d36e326acc16d18e5c2e10cf85c974bcc5db956dcb063d4a33b8536a74d33c88f888da3be734f15

data/Gemfile

@@ -0,0 +1,21 @@
+source 'https://rubygems.org'
+
+gem 'bundler'
+gem 'patron', '~> 0.6'
+gem 'rmagick', '~> 2.15', :require => 'rmagick'
+gem 'exceptional_fork', '~> 1.2'
+gem 'ks'
+gem 'magic_bytes'
+
+group :development do
+  gem 'simplecov'
+  gem 'rack-cache'
+  gem 'strenv'
+  gem 'addressable', :require => %w( addressable/uri )
+  gem 'rack', '~> 1'
+  gem 'rack-test'
+  gem 'foreman'
+  gem 'rspec', '~> 3.2', '< 3.3'
+  gem 'rake', '~> 10'
+  gem "jeweler"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2016 WeTransfer
+
+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.md

@@ -0,0 +1,203 @@
+# A thumbnailing server
+
+`ImageVise` is an image-from-url-as-a-service server for use either standalone or within a larger Rails/Rack
+framework. The main uses are:
+
+* Image resizing on request
+* Applying image filters
+
+It is implemented as a Rack application that responds to any URL and accepts the following query string parameters:
+
+* `q` - Bese-64 encoded JSON object with `src_url` and `pipeline` properties
+* `sig` - the HMAC signature of the hash with `url`, `w` and `h` computed on a query-string encode of them
+
+A request to `ImageVise` might look like this:
+
+    /?q=acbhGyfhyYErghff&sig=acfgheg123
+
+The URL that gets generated is best composed with the included `ImageVise.image_params` method. This method will
+take care of encoding the source URL and the commands in the right way, as well as signing.
+
+## Using ImageVise within a Rails application
+
+Mount ImageVise in your `routes.rb`:
+
+    mount '/images' => ImageVise
+
+and add an initializer (like `config/initializers/image_vise_config.rb`) to set up the permitted hosts
+
+    ImageVise.add_allowed_host! your_application_hostname
+    ImageVise.add_secret_key! ENV.fetch('IMAGE_VISE_SECRET')
+
+You might want to define a helper method for generating signed URLs as well, which will look something like this:
+
+    def thumb_url(source_image_url)
+      qs_params = ImageVise.image_params(src_url: source_image_url, secret: ENV.fetch('IMAGE_VISE_SECRET')) do |pipeline|
+         # For example, you can also yield `pipeline` to the caller
+        pipeline.fit_crop width: 128, height: 128, gravity: 'c'
+      end
+      '/images?' + Rack::Utils.build_query(qs_params) # or use url_for...
+    end
+
+## Using ImageVise within a Rack application
+
+Mount ImageVise under a script name in your `config.ru`:
+
+    map '/images' do
+      run ImageVise
+    end
+
+and add the initialization code either to `config.ru` proper or to some file in your application:
+
+    ImageVise.add_allowed_host! your_application_hostname
+    ImageVise.add_secret_key! ENV.fetch('IMAGE_VISE_SECRET')
+
+You might want to define a helper method for generating signed URLs as well, which will look something like this:
+
+    def thumb_url(source_image_url)
+      qs_params = ImageVise.image_params(src_url: source_image_url, secret: ENV.fetch('IMAGE_VISE_SECRET')) do |pipe|
+        # For example, you can also yield `pipeline` to the caller
+        pipe.fit_crop width: 256, height: 256, gravity: 'c'
+        pipe.sharpen sigma: 0.5, radius: 2
+        pipe.ellipse_stencil
+      end
+      # Output a URL to the app
+      '/images?' + Rack::Utils.build_query(image_request)
+    end
+
+## Operators and pipelining
+
+ImageVise processes an image using _operators_. Each operator is just like an adjustment layer in Photoshop, except
+that it can also resize the canvas. If you are familiar with node-based compositing systems like Shake, Nuke or Fusion
+the pipeline is a node DAG with only one connection arrow going all the way. The operations are always applied in a
+destructive way, so that the additional intermediate versions don't have to be deallocated manually after processing.
+
+Each Operator is described in the pipeline using a tuple (Array) of roughly this structure:
+
+    [<operator_name>, {"<operator_param1>": <operator_param1_value>}]
+
+You can have an unlimited number of such Operators per thumbnail, and they all get encoded in the URL (well,
+technically, you _are_ limited - by the URL length supported by your web server).
+
+For example, you can use the pipeline to apply a sharpening operator _after_ resising an image (for the lack
+of decent image filtering choices in ImageMagick proper).
+
+Here is an example pipeline, JSON-encoded (this is what is passed in the URL):
+
+    [
+      ["auto_orient", {}],
+      ["geom", {"geometry_string": "512x512"}],
+      ["fit_crop", {"width": 32, "height": 32, "gravity": "se"}],
+      ["sharpen", {"radius": 0.75, "sigma": 0.5}],
+      ["ellipse_stencil", {}]
+    ]
+
+The same pipeline can be created using the `Pipeline` DSL:
+
+    pipe = Pipeline.new.
+      auto_orient.
+      geom(geometry_string: '512x512').
+      fit_crop(width: 32, height: 32, gravity: 'se').
+      sharpen(radius: 0.75, sigma: 0.5).
+      ellipse_stencil
+
+and can then be applied to a `Magick::Image` object:
+
+     image = Magick::Image.read(my_image_path)[0]
+     pipe.apply!(image)
+
+## Performance and memory
+
+ImageVise uses ImageMagick and RMagick. It _does not_ shell out to `convert` or `mogrify`, because shelling out
+is _expensive_ in terms of wall clock. It _does_ do it's best to deallocate (`#destroy!`) the image it works on,
+but it is not 100% bullet proof.
+
+Additionally, in contrast to `convert` and `mogrify` ImageVise supports _stackable_ operations, and these operations
+might be repeated with different parameters. Unfortunately, `convert` is _not_ Shake, so we cannot pass a DAG of
+image operators to it and just expect it to work. If we want to do processing of multiple steps that `convert` is
+unable to execute in one call, we have to do
+
+     [fork+exec read + convert + write] -> [fork+exec read + convert + write] + ...
+
+for each operator we want to apply in a consistent fashion. We cannot stuff all the operators into one `convert`
+command because the order the operators get applied within `convert` is not clear, whereas we need a reproducible
+deterministic order of operations (as set in the pipeline). A much better solution is - load the image into memory
+**once**, do all the transformations, save. Additionally, if you use things like OpenCL with ImageMagick, the overhead
+of loading the library and compiling the compute kernels will outweigh _any_ performance gains you might get when
+actually using them. If you are using a library it is a one-time cost, with very fast processing afterwards.
+
+Also note that image operators are not per definition Imagemagick-specific - it's completely possible to not only use
+a different library for processing them, but even to use a different image processing server complying to the
+same protocol (a signed JSON-encodded waybill of HTTP(S) source-URL + pipeline instructions).
+
+## Using forked child processes for RMagick tasks
+
+You can optionally set the `IMAGE_VISE_ENABLE_FORK` environment variable to any value to enable forking. When this
+variable is set, ImageVise will fork a child process and perform the image processing task within that process,
+killing it afterwards and deallocating all the memory. This can be extremely efficient for dealing with potential
+memory bloat issues in ImageMagick/RMagick. However, loading images into RMagick may hang in a forked child. This
+will lead to the child being timeout-terminated, and no image is going to be rendered. This issue is known and
+also platform-dependent (it does not happen on OSX but does happen on Docker within Ubuntu Trusty for instance).
+
+So, this feature _does_ exist but your mileage may vary with regards to it's use.
+
+## Caching
+
+The app is _designed_ to be run behind a frontline HTTP cache. The easiest is to use `Rack::Cache`, but this might
+be instance-local depending on the storage backend used. A much better idea is to run ImageVise behind a long-caching
+CDN.
+
+## Shared HMAC keys for signed URLs
+
+To allow `ImageVise` to recognize the signature when the signature is going to be received, add it to the list
+of the shared keys on the `ImageVise` server:
+
+    ImageVise.add_secret_key!('ahoy! this is a secret!')
+
+A single `ImageVise` server can maintain multiple signature keys, so that you will be able to generate thumbnails from
+multiple applications all using different keys for their signatures. Every request will be validated against
+each key and if at least one key generates the same signature for the same given parameters, it is going to be
+accepted and the request will be allowed to go through.
+
+When running `ImageVise` as a standalone application you can add set the `VISE_SECRET_KEYS` environment 
+variable to a comma-separated list of keys you are willing to accept (no spaces after the commas).
+
+## Hostname validation
+
+By default, `ImageVise` will refuse to process images from URLs on "unknown" hosts. To mark a host as "known"
+tell `ImageVise` to
+
+    ImageVise.add_allowed_host!('my-image-store.ourcompany.co.uk')
+
+## State
+
+Except for the HTTP cache for redirects et.al no state is stored (`ImageVise` does not care whether you store
+your images using Dragonfly, CarrierWave or some custom handling code). All the app needs is the full URL.
+
+## FAQ
+
+* _Yo dawg, I thought you like URLs so I have put encoded URL in your URL so you can..._ - well, the only alternative
+  is also managing image storage, and this something we want to avoid to keep `ImageVise` stateless
+* _But the URLs can be exploited_ - this is highly unlikely if you pick strong keys for the HMAC signatures
+* _I can load any image into the thumbnailer_ - in fact, no. First you have the URL checks, and then - all the URLs
+  are supposed to be coming from the sources you trust since they are signed.
+
+## Running the tests, versioning, contributing
+
+By default, `bundle exec rake` will run RSpec and will also open the generated images using the `$ open` command available
+on your CLI. If you want to skip viewing those images, set the `SKIP_INTERACTIVE` environment variable to any value.
+
+The gem version is specified in `image_vise.rb`. When contributing, please follow:
+
+* 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.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+### Copyright
+
+Copyright (c) 2016 WeTransfer. See LICENSE.txt for further details.
+The licensing terms also apply to the `waterside_magic_hour.jpg` test image.

data/Rakefile

@@ -0,0 +1,29 @@
+require 'rspec/core/rake_task'
+require 'jeweler'
+require_relative 'lib/image_vise'
+
+Jeweler::Tasks.new do |gem|
+  gem.version = ImageVise::VERSION
+  gem.name = "image_vise"
+  gem.summary = "Runtime thumbnailing proxy"
+  gem.description = "Image processing via URLs"
+  gem.email = "me@julik.nl"
+  gem.homepage = "https://github.com/WeTransfer/image_vise"
+  gem.authors = ["Julik Tarkhanov"]
+  gem.license = 'MIT'
+
+  # Do not package invisibles
+  gem.files.exclude ".*"
+  
+  # When running as a gem, do not lock all of our versions
+  # even though the lockfile is in the repo for running standalone
+  gem.files.exclude "Gemfile.lock"
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
+  t.pattern = 'spec/**/*_spec.rb'
+end
+task :default => :spec

data/examples/config.ru

@@ -0,0 +1,17 @@
+require File.dirname(__FILE__) + '/lib/image_vise'
+
+# Add all the secret keys specified in the environment separated by a comma
+if ENV['VISE_SECRET_KEYS']
+  ENV['VISE_SECRET_KEYS'].split(',').map do | key |
+    ImageVise.add_secret_key!(key.strip)
+  end
+end
+
+# Cover things with caching, even redirects (since we do not want to ask S3 too often)
+use Rack::Cache, :metastore => 'file:tmp/cache/rack/meta', :entitystore  => 'file:tmp/cache/rack/entity', 
+  :verbose => true, :allow_reload => false, :allow_revalidate => false
+
+# Serve runtime thumbnails, under a specific URL
+map '/images'do
+  run ImageVise
+end

data/image_vise.gemspec

@@ -0,0 +1,116 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: image_vise 0.0.16 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "image_vise"
+  s.version = "0.0.16"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["Julik Tarkhanov"]
+  s.date = "2016-10-15"
+  s.description = "Image processing via URLs"
+  s.email = "me@julik.nl"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "examples/config.ru",
+    "image_vise.gemspec",
+    "lib/image_vise.rb",
+    "lib/image_vise/auto_orient.rb",
+    "lib/image_vise/crop.rb",
+    "lib/image_vise/ellipse_stencil.rb",
+    "lib/image_vise/file_response.rb",
+    "lib/image_vise/fit_crop.rb",
+    "lib/image_vise/geom.rb",
+    "lib/image_vise/image_request.rb",
+    "lib/image_vise/pipeline.rb",
+    "lib/image_vise/render_engine.rb",
+    "lib/image_vise/sharpen.rb",
+    "spec/image_vise/auto_orient_spec.rb",
+    "spec/image_vise/crop_spec.rb",
+    "spec/image_vise/ellipse_stencil_spec.rb",
+    "spec/image_vise/file_response_spec.rb",
+    "spec/image_vise/fit_crop_spec.rb",
+    "spec/image_vise/geom_spec.rb",
+    "spec/image_vise/image_request_spec.rb",
+    "spec/image_vise/pipeline_spec.rb",
+    "spec/image_vise/render_engine_spec.rb",
+    "spec/image_vise/sharpen_spec.rb",
+    "spec/image_vise_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/test_server.rb",
+    "spec/waterside_magic_hour.jpg"
+  ]
+  s.homepage = "https://github.com/WeTransfer/image_vise"
+  s.licenses = ["MIT"]
+  s.rubygems_version = "2.4.5.1"
+  s.summary = "Runtime thumbnailing proxy"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<bundler>, [">= 0"])
+      s.add_runtime_dependency(%q<patron>, ["~> 0.6"])
+      s.add_runtime_dependency(%q<rmagick>, ["~> 2.15"])
+      s.add_runtime_dependency(%q<exceptional_fork>, ["~> 1.2"])
+      s.add_runtime_dependency(%q<ks>, [">= 0"])
+      s.add_runtime_dependency(%q<magic_bytes>, [">= 0"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<rack-cache>, [">= 0"])
+      s.add_development_dependency(%q<strenv>, [">= 0"])
+      s.add_development_dependency(%q<addressable>, [">= 0"])
+      s.add_development_dependency(%q<rack>, ["~> 1"])
+      s.add_development_dependency(%q<rack-test>, [">= 0"])
+      s.add_development_dependency(%q<foreman>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, ["< 3.3", "~> 3.2"])
+      s.add_development_dependency(%q<rake>, ["~> 10"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<bundler>, [">= 0"])
+      s.add_dependency(%q<patron>, ["~> 0.6"])
+      s.add_dependency(%q<rmagick>, ["~> 2.15"])
+      s.add_dependency(%q<exceptional_fork>, ["~> 1.2"])
+      s.add_dependency(%q<ks>, [">= 0"])
+      s.add_dependency(%q<magic_bytes>, [">= 0"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<rack-cache>, [">= 0"])
+      s.add_dependency(%q<strenv>, [">= 0"])
+      s.add_dependency(%q<addressable>, [">= 0"])
+      s.add_dependency(%q<rack>, ["~> 1"])
+      s.add_dependency(%q<rack-test>, [">= 0"])
+      s.add_dependency(%q<foreman>, [">= 0"])
+      s.add_dependency(%q<rspec>, ["< 3.3", "~> 3.2"])
+      s.add_dependency(%q<rake>, ["~> 10"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<bundler>, [">= 0"])
+    s.add_dependency(%q<patron>, ["~> 0.6"])
+    s.add_dependency(%q<rmagick>, ["~> 2.15"])
+    s.add_dependency(%q<exceptional_fork>, ["~> 1.2"])
+    s.add_dependency(%q<ks>, [">= 0"])
+    s.add_dependency(%q<magic_bytes>, [">= 0"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<rack-cache>, [">= 0"])
+    s.add_dependency(%q<strenv>, [">= 0"])
+    s.add_dependency(%q<addressable>, [">= 0"])
+    s.add_dependency(%q<rack>, ["~> 1"])
+    s.add_dependency(%q<rack-test>, [">= 0"])
+    s.add_dependency(%q<foreman>, [">= 0"])
+    s.add_dependency(%q<rspec>, ["< 3.3", "~> 3.2"])
+    s.add_dependency(%q<rake>, ["~> 10"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+

data/lib/image_vise/auto_orient.rb

@@ -0,0 +1,10 @@
+# Applies ImageMagick auto_orient to the image, so that i.e. mobile photos
+# can be oriented correctly. The operation is applied destructively (changes actual pixel data)
+#
+# The corresponding Pipeline method is `auto_orient`.
+class ImageVise::AutoOrient
+  def apply!(magick_image)
+    magick_image.auto_orient!
+  end
+  ImageVise.add_operator 'auto_orient', self
+end

data/lib/image_vise/crop.rb

@@ -0,0 +1,32 @@
+# Crops the image to the given dimensions with a given gravity. Gravities are shorthand versions
+# of ImageMagick gravity parameters (see GRAVITY_PARAMS)
+#
+# The corresponding Pipeline method is `crop`.
+class ImageVise::Crop < Ks.strict(:width, :height, :gravity)
+  GRAVITY_PARAMS = {
+    'nw' => Magick::NorthWestGravity,
+    'n' => Magick::NorthGravity,
+    'ne' => Magick::NorthEastGravity,
+    'w' => Magick::WestGravity,
+    'c' => Magick::CenterGravity,
+    'e' => Magick::EastGravity,
+    'sw' => Magick::SouthWestGravity,
+    's' => Magick::SouthGravity,
+    'se' => Magick::SouthEastGravity,
+  }
+  
+  def initialize(*)
+    super
+    self.width = width.to_i
+    self.height = height.to_i
+    raise ArgumentError, ":width must positive" unless width > 0
+    raise ArgumentError, ":height must positive" unless height > 0
+    raise ArgumentError, ":gravity must be within the permitted values" unless GRAVITY_PARAMS.key? gravity
+  end
+  
+  def apply!(image)
+    image.crop!(GRAVITY_PARAMS.fetch(gravity), width, height, remove_padding_data_outside_window = true)
+  end
+
+  ImageVise.add_operator 'crop', self
+end

data/lib/image_vise/ellipse_stencil.rb

@@ -0,0 +1,43 @@
+# Applies an elliptic stencil around the entire image. The stencil will fit inside the image boundaries,
+# with about 1 pixel cushion on each side to provide smooth anti-aliased edges. If the input image to be
+# provessed is square, the ellipse will turn into a neat circle.
+#
+# This adds an alpha channel to the image being processed (and premultiplies the RGB channels by it). This
+# will force the RenderEngine to return the processed image as a PNG in all cases, instead of keeping it
+# in the original format.
+#
+# The corresponding Pipeline method is `ellipse_stencil`.
+class ImageVise::EllipseStencil
+  C_black = 'black'.freeze
+  private_constant :C_black
+
+  def apply!(magick_image)
+    # http://stackoverflow.com/a/13329959/153886
+    width, height = magick_image.columns, magick_image.rows
+    
+    center_x = (width / 2.0)
+    center_y = (height / 2.0)
+    # Make sure all the edges are anti-aliased
+    radius_width = center_x - 1.5
+    radius_height = center_y - 1.5
+
+    gc = Magick::Draw.new
+    gc.fill C_black
+    gc.ellipse(center_x, center_y, radius_width, radius_height, deg_start=0, deg_end=360)
+    
+    circle_img = Magick::Image.new(width, height)
+    gc.draw(circle_img)
+    
+    mask = circle_img.negate
+    mask.matte = false
+    
+    magick_image.matte = true
+    magick_image.composite!(mask, Magick::CenterGravity, Magick::CopyOpacityCompositeOp)
+  ensure
+    [mask, gc, circle_img].each do |maybe_image|
+      ImageVise.destroy(maybe_image)
+    end
+  end
+  
+  ImageVise.add_operator 'ellipse_stencil', self
+end

data/lib/image_vise/file_response.rb

@@ -0,0 +1,23 @@
+# Wrappers a given Tempfile for a Rack response.
+# Will close _and_ unlink the Tempfile it contains.
+class ImageVise::FileResponse
+  ONE_CHUNK_BYTES = 1024 * 512
+  def initialize(file)
+    @file = file
+  end
+  
+  def each
+    @file.flush # Make sure all the writes have been synchronized
+    # We can easily open another file descriptor
+    File.open(@file.path, 'rb') do |my_file_descriptor|
+      while data = my_file_descriptor.read(ONE_CHUNK_BYTES)
+        yield(data)
+      end
+    end
+  end
+  
+  def close
+    @file.close
+    @file.unlink
+  end
+end

data/lib/image_vise/fit_crop.rb

@@ -0,0 +1,33 @@
+# Fits the image based on the smaller-side fit. This means that the image is going to be fit
+# into the requested rectangle so that all of the pixels of the rectangle are filled. The
+# gravity parameter defines the crop gravity (on corners, sides, or in the middle).
+#
+# The corresponding Pipeline method is `fit_crop`.
+class ImageVise::FitCrop < Ks.strict(:width, :height, :gravity)
+  GRAVITY_PARAMS = {
+    'nw' => Magick::NorthWestGravity,
+    'n' => Magick::NorthGravity,
+    'ne' => Magick::NorthEastGravity,
+    'w' => Magick::WestGravity,
+    'c' => Magick::CenterGravity,
+    'e' => Magick::EastGravity,
+    'sw' => Magick::SouthWestGravity,
+    's' => Magick::SouthGravity,
+    'se' => Magick::SouthEastGravity,
+  }
+
+  def initialize(*)
+    super
+    self.width = width.to_i
+    self.height = height.to_i
+    raise ArgumentError, ":width must positive" unless width > 0
+    raise ArgumentError, ":height must positive" unless height > 0
+    raise ArgumentError, ":gravity must be within the permitted values" unless GRAVITY_PARAMS.key? gravity
+  end
+
+  def apply!(magick_image)
+    magick_image.resize_to_fill! width, height, GRAVITY_PARAMS.fetch(gravity)
+  end
+  
+  ImageVise.add_operator 'fit_crop', self
+end

data/lib/image_vise/geom.rb

@@ -0,0 +1,16 @@
+# Applies a transformation using an ImageMagick geometry string
+#
+# The corresponding Pipeline method is `geom`.
+class ImageVise::Geom < Ks.strict(:geometry_string)
+  def initialize(*)
+    super
+    self.geometry_string = geometry_string.to_s
+    raise ArgumentError, "the :geom parameter must be present and not empty" if self.geometry_string.empty?
+  end
+
+  def apply!(image)
+    image.change_geometry(geometry_string) { |cols, rows, _| image.resize!(cols,rows) }
+  end
+
+  ImageVise.add_operator 'geom', self
+end

data/lib/image_vise/image_request.rb

@@ -0,0 +1,68 @@
+require 'base64'
+
+class ImageVise::ImageRequest < Ks.strict(:src_url, :pipeline)
+  class InvalidRequest < ArgumentError; end
+  class SignatureError < InvalidRequest; end
+  class URLError < InvalidRequest; end
+  class MissingParameter < InvalidRequest; end
+  
+  # Initializes a new ParamsChecker from given HTTP server framework
+  # params. The params can be symbol- or string-keyed, does not matter.
+  def self.to_request(qs_params:, secrets:, permitted_source_hosts:)
+    base64_encoded_params = qs_params.fetch(:q) rescue qs_params.fetch('q')
+    given_signature = qs_params.fetch(:sig) rescue qs_params.fetch('sig')
+    
+    # Decode Base64 first - this gives us a stable serialized form of the request parameters
+    decoded_json = Base64.decode64(base64_encoded_params)
+
+    # Check the signature before decoding JSON (since we will be creating symbols and stuff)
+    raise SignatureError, "Invalid or missing signature" unless valid_signature?(decoded_json, given_signature, secrets)
+
+    # Decode the JSON
+    params = JSON.parse(decoded_json, symbolize_names: true)
+
+    # Pick up the URL and validate it
+    src_url = params.fetch(:src_url).to_s
+    raise URLError, "the :src_url parameter must be non-empty" if src_url.empty?
+    raise URLError, "#{src_url} is not permitted as source" unless valid_host?(src_url, permitted_source_hosts)
+
+    # Build out the processing pipeline
+    pipeline_definition = params.fetch(:pipeline)
+
+    new(src_url: src_url, pipeline: ImageVise::Pipeline.from_param(pipeline_definition))
+  rescue KeyError => e
+    raise InvalidRequest.new(e.message)
+  end
+
+  def to_query_string_params(signed_with_secret)
+    payload = JSON.dump(to_h)
+    {q: Base64.strict_encode64(payload), sig: OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, signed_with_secret, payload)}
+  end
+
+  def to_h
+    {pipeline: pipeline.to_params, src_url: src_url}
+  end
+  
+  def cache_etag
+    Digest::SHA1.hexdigest(JSON.dump(to_h))
+  end
+
+  private
+
+  def self.valid_signature?(for_payload, given_signature, secrets)
+    # Check the signature against every key that we have,
+    # since different apps might be using different keys
+    seen_valid_signature = false
+    secrets.each do | stored_secret |
+      expected_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, stored_secret, for_payload)
+      result_for_this_key = Rack::Utils.secure_compare(expected_signature, given_signature)
+      seen_valid_signature ||= result_for_this_key
+    end
+    seen_valid_signature
+  end
+
+  def self.valid_host?(src_url, permitted_hosts)
+    parsed_url = URI.parse(src_url)
+    permitted_hosts.include?(parsed_url.host)
+  end
+end