image_vise 0.0.25 → 0.0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4505547a1ef87774694ee0a4e0adda3354e9f676
-  data.tar.gz: c403f4147f907b10b2f13ca6ea2564f73bc21303
+  metadata.gz: cb3f1e2fdb272ce247b39af0ac465622ae4aab47
+  data.tar.gz: af4c923a506fa1b8e960f06cf6ac6686a0cda9d0
 SHA512:
-  metadata.gz: 736ed9bedaf46db49558b3fcec83d992368ccd670df57083be3e8ec66dbfc7bc31420a0debbd085b9237fdb29891b8c495bfbc27d0b6fac7e902b2f3938ef3f5
-  data.tar.gz: fe83b1a5f073e2b01075f6ba8f7e4451985727650e69ff390a1abc3350113639c8459e3e1341fcb45738390cf1750671694593edbcfd71bfa0db9802b66c49c7
+  metadata.gz: 436cf6a7fcbafd57c1d531530cf42e08f8aa746fa85aa99dfd3d672e1c6ec9a49c6775387cc7f0fbd183e9abb01c75b698e7a0664b4cd65d7115294bdf334bb5
+  data.tar.gz: b72ead80e081805e1705ea8f22a69dccca06a70967a5ba731c27938aa3a20469f482c23f62789bce1f9a90d71666d570e304dd2f35e22aee85ba0fea42872a72

data/DEVELOPMENT.md

@@ -0,0 +1,98 @@
+# NOTE: Until 1.0.0 ImageVise API is somewhat in flux
+
+## Defining image operators
+
+To add an image operator, define a class roughly like so, and add it to the list of operators.
+
+    class MyBlur
+      # The constructor must accept keyword arguments if your operator accepts them
+      def initialize(radius:, sigma:)
+        @radius = radius.to_f
+        @sigma = sigma.to_f
+      end
+      
+      # Needed for the operator to be serialized to parameters
+      def to_h
+        {radius: @radius, sigma: @sigma}
+      end
+      
+      def apply!(magick_image) # The argument is a Magick::Image
+        # Apply the method to the function argument
+        blurred_image = magick_image.blur_image(@radius, @sigma)
+        
+        # Some methods (without !) return a new Magick::Image.
+        # That image has to be composited back into the original.
+        magick_image.composite!(blurred_image, Magick::CenterGravity, Magick::CopyCompositeOp)
+      ensure
+        # Make sure to explicitly destroy() all the intermediate images
+        ImageVise.destroy(blurred_image)
+      end
+    end
+    
+    # This will also make `ImageVise::Pipeline` respond to `blur(radius:.., sigma:..)`
+    ImageVise.add_operator 'my_blur', MyBlur
+
+## Defining fetchers
+
+Fetchers are based on the scheme of the image URL. Default fetchers are already defined for `http`, `https`
+and `file` schemes. If you need to grab data from a database, for instance, you can define a fetcher and register
+it:
+
+    module DatabaseFetcher
+      def self.fetch_uri_to_tempfile(uri_object)
+        tf = Tempfile.new 'data-fetch'
+        
+        object_id = uri_object.path[/\d+/]
+        data_model = ProfilePictures.find(object_id)
+        tf << data_model.body
+        
+        tf.rewind; tf
+      rescue Exception => e
+        ImageVise.close_and_unlink(tf) # do not litter Tempfiles
+        raise e
+      end
+    end
+    
+    ImageVise.register_fetcher 'profilepictures', self
+
+Once done, you can use URLs like `profilepictures:/5674`
+
+## Overriding the render engine
+
+By default, `ImageVise.call` delegates to `ImageVise::RenderEngine.new.call`. You can mount your own subclass
+instead, and it will handle everything the same way:
+
+    class MyThumbnailer < ImageVise::RenderEngine
+      ...
+    end
+    
+    map '/thumbs' do
+      run MyThumbnailer.new
+    end
+
+Note that since the API is in flux the methods you can override in `RenderEngine` can change.
+So far none of them are private.
+
+## 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).

data/Gemfile

@@ -1,6 +1,5 @@
 source 'https://rubygems.org'
 
-gem 'bundler'
 gem 'patron', '~> 0.6'
 gem 'rmagick', '~> 2.15', :require => 'rmagick'
 gem 'exceptional_fork', '~> 1.2'
@@ -8,6 +7,8 @@ gem 'ks'
 gem 'magic_bytes'
 
 group :development do
+  gem 'bundler'
+  gem 'yard'
   gem 'simplecov'
   gem 'rack-cache'
   gem 'strenv'

data/README.md

@@ -129,40 +129,6 @@ 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 `yes` 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
 
@@ -207,50 +173,18 @@ Note that these are _glob_ patterns. The image path will be checked against them
 By default, the Rack app within ImageVise swallows all exceptions and returns the error message
 within a machine-readable JSON payload. If that doesn't work for you, or you want to add error
 handling using some error tracking provider, either subclass `ImageVise::RenderEngine` or prepend
-a module into it that will intercept the errors. For example, [Sentry](https://sentry.io) has a neat
-property of picking up `rack.exception` from the Rack request env. Using the hooks in the render engine,
-you can add Sentry support by using the following module:
-
-```ruby
-module ImageViseSentrySupport
-  ImageVise::RenderEngine.prepend self
-
-  def setup_error_handling(rack_env)
-    @env = rack_env
-  end
-
-  def handle_request_error(err)
-    @env['rack.exception'] = err
-  end
-
-  def handle_generic_error(err)
-    @env['rack.exception'] = err
-  end
-end
-```
-
-For [Appsignal](https://appsignal.com) you can use the following module instead:
+a module into it that will intercept the errors. See error handling in `examples/` for more.
 
-```ruby
-module ImageViseAppsignal
-  ImageVise::RenderEngine.prepend self
-  
-  def setup_error_handling(rack_env)
-    txn = Appsignal::Transaction.current
-    txn.set_action('%s#%s' % [self.class, 'call'])
-  end
-
-  def handle_request_error(err)
-    Appsignal.add_exception(err)
-  end
+## Using forked child processes for RMagick tasks
 
-  def handle_generic_error(err)
-    Appsignal.add_exception(err)
-  end
-end
-```
+You can optionally set the `IMAGE_VISE_ENABLE_FORK` environment variable to `yes` 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).
 
-In both cases you need the overall Rack error handling middleware to be wrapping ImageVise, of course.
+So, this feature _does_ exist but your mileage may vary with regards to it's use.
 
 ## State
 

data/SECURITY.md

@@ -0,0 +1,32 @@
+# Security implications for ImageVise
+
+This lists out the implementation details of security-sensitive parts of ImageVise.
+
+## Protection of the URLs
+
+URLs are passed as Base64-encoded JSON. The JSON payload is signed using HMAC with SHA256. This should be
+sufficient to prevent too much probing. If this is a critical issue you need to put throttling in front of the application.
+For checking HMAC values `Rack::Utils.secure_compare` constant-time comparison is used.
+
+## Protection for remote URLs from HTTP(s) origins
+
+Only URLs referring to permitted hosts are going to be permitted for fetching. If there are no host added,
+any remote URL is going to cause an exception. No special verification for whether the upstream must be HTTP
+or HTTPS is performed at this time.
+
+## Protection for "file:/" URLs
+
+The file URLs are going to be decoded, and the path component will be matched against permitted _glob patterns._
+The matching takes links (hard and soft) into account, and uses Ruby's `File.fnmatch?` under the hood. The path
+is always expanded first using `File.expand_path`. The data is not read into ImageMagick from the original location,
+but gets copied into a tempfile first.
+
+## ImageMagick memory constraints
+
+ImageVise does not set RMagick limits by itself. You should
+[set them according to the RMagick documentation.](https://rmagick.github.io/magick.html#limit_resource)
+
+## Processing time constraints
+
+If you are using forking, there will be a timeout used for how long the forked child process may run,
+which is the default timeout used in ExceptionalFork.

data/examples/custom_image_operator.rb

@@ -0,0 +1,27 @@
+class MyBlur
+  # The constructor must accept keyword arguments if your operator accepts them
+  def initialize(radius:, sigma:)
+    @radius = radius.to_f
+    @sigma = sigma.to_f
+  end
+  
+  # Needed for the operator to be serialized to parameters
+  def to_h
+    {radius: @radius, sigma: @sigma}
+  end
+  
+  def apply!(magick_image) # The argument is a Magick::Image
+    # Apply the method to the function argument
+    blurred_image = magick_image.blur_image(@radius, @sigma)
+    
+    # Some methods (without !) return a new Magick::Image.
+    # That image has to be composited back into the original.
+    magick_image.composite!(blurred_image, Magick::CenterGravity, Magick::CopyCompositeOp)
+  ensure
+    # Make sure to explicitly destroy() all the intermediate images
+    ImageVise.destroy(blurred_image)
+  end
+end
+
+# This will also make `ImageVise::Pipeline` respond to `blur(radius:.., sigma:..)`
+ImageVise.add_operator 'my_blur', MyBlur

data/image_vise.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: image_vise 0.0.25 ruby lib
+# stub: image_vise 0.0.26 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "image_vise"
-  s.version = "0.0.25"
+  s.version = "0.0.26"
 
   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-18"
+  s.date = "2016-10-20"
   s.description = "Image processing via URLs"
   s.email = "me@julik.nl"
   s.extra_rdoc_files = [
@@ -19,11 +19,14 @@ Gem::Specification.new do |s|
     "README.md"
   ]
   s.files = [
+    "DEVELOPMENT.md",
     "Gemfile",
     "LICENSE.txt",
     "README.md",
     "Rakefile",
+    "SECURITY.md",
     "examples/config.ru",
+    "examples/custom_image_operator.rb",
     "examples/error_handline_appsignal.rb",
     "examples/error_handling_sentry.rb",
     "image_vise.gemspec",
@@ -72,12 +75,13 @@ Gem::Specification.new do |s|
     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<bundler>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
       s.add_development_dependency(%q<simplecov>, [">= 0"])
       s.add_development_dependency(%q<rack-cache>, [">= 0"])
       s.add_development_dependency(%q<strenv>, [">= 0"])
@@ -89,12 +93,13 @@ Gem::Specification.new do |s|
       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<bundler>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
       s.add_dependency(%q<simplecov>, [">= 0"])
       s.add_dependency(%q<rack-cache>, [">= 0"])
       s.add_dependency(%q<strenv>, [">= 0"])
@@ -107,12 +112,13 @@ Gem::Specification.new do |s|
       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<bundler>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
     s.add_dependency(%q<simplecov>, [">= 0"])
     s.add_dependency(%q<rack-cache>, [">= 0"])
     s.add_dependency(%q<strenv>, [">= 0"])

data/lib/image_vise/image_request.rb

@@ -9,14 +9,18 @@ class ImageVise::ImageRequest < Ks.strict(:src_url, :pipeline)
   def self.to_request(qs_params:, secrets:)
     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
+
+    # Decode Base64 first - this gives us a stable serialized form of the request parameters.
+    # The encoded parameters might _not_ include ==-padding at the end.
     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)
+    # Check the signature before decoding JSON (since we will be creating symbols)
+    unless valid_signature?(decoded_json, given_signature, secrets)
+      raise SignatureError, "Invalid or missing signature"
+    end
 
     # Decode the JSON
+    # (only AFTER the signature has been validated, so we can use symbol keys)
     params = JSON.parse(decoded_json, symbolize_names: true)
 
     # Pick up the URL and validate it
@@ -30,7 +34,8 @@ class ImageVise::ImageRequest < Ks.strict(:src_url, :pipeline)
 
   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)}
+    base64_enc = Base64.strict_encode64(payload).gsub(/\=+$/, '')
+    {q: base64_enc, sig: OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, signed_with_secret, payload)}
   end
 
   def to_h

data/lib/image_vise/render_engine.rb

@@ -43,17 +43,24 @@ class ImageVise::RenderEngine
     throw :__bail, response
   end
   
-  # The main entry point URL, at the index so that the Sinatra app can be used
-  # in-place of a Rails controller (as opposed to having to mount it at the root
-  # of the Rails app or having all the URLs refer to a subpath)
+  # The main entry point for the Rack app. Wraps a call to {#handle_request} in a `catch{}` block
+  # so that any method can abort the request by calling {#bail}
+  #
+  # @param env[Hash] the Rack env
+  # @return [Array] the Rack response
   def call(env)
     catch(:__bail) { handle_request(env) }
   end
   
+  # Hadles the Rack request. If one of the steps calls {#bail} the `:__bail` symbol will be
+  # thrown and the execution will abort. Any errors will cause either an error response in
+  # JSON format or an Exception will be raised (depending on the return value of `raise_exceptions?`)
+  #
+  # @param env[Hash] the Rack env
+  # @return [Array] the Rack response
   def handle_request(env)
     setup_error_handling(env)
-    render_destination_file = binary_tempfile
-    
+
     # Assume that if _any_ ETag is given the image is being requested anew as a refetch,
     # and the client already has it. Just respond with a 304.
     return [304, DEFAULT_HEADERS.dup, []] if env['HTTP_IF_NONE_MATCH']
@@ -61,9 +68,31 @@ class ImageVise::RenderEngine
     req = Rack::Request.new(env)
     bail(405, 'Only GET supported') unless req.get?
 
-    # Parse and reinstate the URL and pipeline
     image_request = ImageVise::ImageRequest.to_request(qs_params: req.params, secrets: ImageVise.secret_keys)
+    render_destination_file, render_file_type, etag = process_image_request(image_request) 
+    image_rack_response(render_destination_file, render_file_type, etag)
+  rescue *permanent_failures => e
+    handle_request_error(e)
+    http_status_code = e.respond_to?(:http_status) ? e.http_status : 422
+    raise_exception_or_error_response(e, http_status_code)
+  rescue Exception => e
+    if http_status_code = (e.respond_to?(:http_status) && e.http_status)
+      handle_request_error(e)
+      raise_exception_or_error_response(e, http_status_code)
+    else
+      handle_generic_error(e)
+      raise_exception_or_error_response(e, 500)
+    end
+  end
 
+  # Processes the ImageRequest object created from the request parameters,
+  # and returns a triplet of the File object containing the rendered image,
+  # the MagicBytes::FileType object of the render, and the cache ETag value
+  # representing the processing pipeline
+  #
+  # @param image_request[ImageVise::ImageRequest] the request for the image
+  # @return [Array<File, MagicBytes::FileType, String]
+  def process_image_request(image_request)
     # Recover the source image URL and the pipeline instructions (all the image ops)
     source_image_uri, pipeline = image_request.src_url, image_request.pipeline
     raise 'Image pipeline has no operators' if pipeline.empty?
@@ -81,21 +110,39 @@ class ImageVise::RenderEngine
     unless source_file_type_permitted?(source_file_type)
       raise UnsupportedInputFormat.new("Unsupported/unknown input file format .%s" % source_file_type.ext)
     end
-    
+
+    render_destination_file = Tempfile.new('imagevise-render').tap{|f| f.binmode }
+
     # Perform the processing
     if enable_forking?
       require 'exceptional_fork'
-      ExceptionalFork.fork_and_wait { apply_pipeline(source_file.path, pipeline, source_file_type, render_destination_file.path) }
+      ExceptionalFork.fork_and_wait do
+        apply_pipeline(source_file.path, pipeline, source_file_type, render_destination_file.path)
+      end
     else
       apply_pipeline(source_file.path, pipeline, source_file_type, render_destination_file.path)
     end
-    
+
     # Catch this one early
+    render_destination_file.rewind
     raise EmptyRender, "The rendered image was empty" if render_destination_file.size.zero?
 
-    render_destination_file.rewind
     render_file_type = detect_file_type(render_destination_file)
-
+    [render_destination_file, render_file_type, etag]
+  ensure
+    ImageVise.close_and_unlink(source_file)
+  end
+  
+  # Returns a Rack response triplet. Accepts the return value of
+  # `process_image_request` unsplatted, and returns a triplet that
+  # can be returned as a Rack response. The Rack response will contain
+  # an iterable body object that is designed to automatically delete
+  # the Tempfile it wraps on close.
+  #
+  # @param render_destination_file[File] the File handle to the rendered image
+  # @param render_file_type[MagicBytes::FileType] the rendered file type
+  # @param etag[String] the ETag for the response
+  def image_rack_response(render_destination_file, render_file_type, etag)
     response_headers = DEFAULT_HEADERS.merge({
       'Content-Type' => render_file_type.mime,
       'Content-Length' => '%d' % render_destination_file.size,
@@ -106,22 +153,13 @@ class ImageVise::RenderEngine
     # Wrap the body Tempfile with a self-closing response.
     # Once the response is read in full, the tempfile is going to be closed and unlinked.
     [200, response_headers, ImageVise::FileResponse.new(render_destination_file)]
-  rescue *permanent_failures => e
-    handle_request_error(e)
-    http_status_code = e.respond_to?(:http_status) ? e.http_status : 422
-    raise_exception_or_error_response(e, http_status_code)
-  rescue Exception => e
-    if http_status_code = (e.respond_to?(:http_status) && e.http_status)
-      handle_request_error(e)
-      raise_exception_or_error_response(e, http_status_code)
-    else
-      handle_generic_error(e)
-      raise_exception_or_error_response(e, 500)
-    end
-  ensure
-    ImageVise.close_and_unlink(source_file)
   end
-  
+
+  # Depending on `raise_exceptions?` will either raise the passed Exception,
+  # or force the application to return the error in the Rack response.
+  #
+  # @param exception[Exception] the error that has to be captured
+  # @param status_code[Fixnum] the HTTP status code
   def raise_exception_or_error_response(exception, status_code)
     if raise_exceptions? 
       raise exception
@@ -130,25 +168,37 @@ class ImageVise::RenderEngine
     end
   end
   
-  def binary_tempfile
-    Tempfile.new('imagevise-tmp').tap{|f| f.binmode }
-  end
-  
+  # Detects the file type of the given File and returns
+  # a MagicBytes::FileType object that contains the extension and
+  # the MIME type.
+  #
+  # @param tempfile[File] the file to perform detection on
+  # @return [MagicBytes::FileType] the detected file type
   def detect_file_type(tempfile)
     tempfile.rewind
-    MagicBytes.read_and_detect(tempfile)
+    MagicBytes.read_and_detect(tempfile).tap { tempfile.rewind }
   end
 
-  def source_file_type_permitted?(magick_bytes_file_info)
-    PERMITTED_SOURCE_FILE_EXTENSIONS.include?(magick_bytes_file_info.ext)
+  # Tells whether the given file type may be loaded into the image processor.
+  #
+  # @param magic_bytes_file_info[MagicBytes::FileType] the filetype
+  # @return [Boolean]
+  def source_file_type_permitted?(magic_bytes_file_info)
+    PERMITTED_SOURCE_FILE_EXTENSIONS.include?(magic_bytes_file_info.ext)
   end
 
-  def output_file_type_permitted?(magick_bytes_file_info)
-    PERMITTED_OUTPUT_FILE_EXTENSIONS.include?(magick_bytes_file_info.ext)
+  # Tells whether the given file type may be returned
+  # as the result of the render
+  #
+  # @param magic_bytes_file_info[MagicBytes::FileType] the filetype
+  # @return [Boolean]
+  def output_file_type_permitted?(magic_bytes_file_info)
+    PERMITTED_OUTPUT_FILE_EXTENSIONS.include?(magic_bytes_file_info.ext)
   end
 
   # Lists exceptions that should lead to the request being flagged
-  # as invalid (and not 5xx). Decent clients should _not_ retry those requests.
+  # as invalid (4xx as opposed to 5xx for a generic server error).
+  # Decent clients should _not_ retry those requests.
   def permanent_failures
     [
       Magick::ImageMagickError,
@@ -158,32 +208,56 @@ class ImageVise::RenderEngine
   end
   
   # Is meant to be overridden by subclasses,
-  # will be called at the start of each reauest
+  # will be called at the start of each request to set up the error handling
+  # library (Appsignal, Honeybadger, Sentry...)
+  #
+  # @param rack_env[Hash] the Rack env
+  # @return [void]
   def setup_error_handling(rack_env)
   end
 
   # Is meant to be overridden by subclasses,
   # will be called when a request fails due to a malformed query string,
-  # unrecognized signature or other client-induced problems
-  def handle_request_error(err)
+  # unrecognized signature or other client-induced problems. The method
+  # should _not_ re-raise the exception.
+  #
+  # @param exception[Exception] the exception to be handled
+  # @return [void]
+  def handle_request_error(exception)
   end
 
   # Is meant to be overridden by subclasses,
   # will be called when a request fails due to an error on the server
-  # (like an unexpected error in an image operator)
-  def handle_generic_error(err)
+  # (like an unexpected error in an image operator). The method
+  # should _not_ re-raise the exception.
+  #
+  # @param exception[Exception] the exception to be handled
+  # @return [void]
+  def handle_generic_error(exception)
   end
   
   # Tells whether the engine must raise the exceptions further up the Rack stack,
   # or they should be suppressed and a JSON response must be returned.
+  #
+  # @return [Boolean]
   def raise_exceptions?
     false
   end
   
+  # Tells whether image processing in a forked subproces should be turned on
+  #
+  # @return [Boolean]
   def enable_forking?
     ENV['IMAGE_VISE_ENABLE_FORK'] == 'yes'
   end
   
+  # Applies the given {ImageVise::Pipeline} to the image, and writes the render to
+  # the given path.
+  #
+  # @param source_file_path[String] the path to the file containing the source image
+  # @param pipeline[#apply!(Magick::Image)] the processing pipeline
+  # @param render_to_path[String] the path to write the rendered image to
+  # @return [void]
   def apply_pipeline(source_file_path, pipeline, source_file_type, render_to_path)
     render_file_type = source_file_type
     magick_image = Magick::Image.read(source_file_path)[0]

data/lib/image_vise.rb

@@ -8,7 +8,7 @@ require 'base64'
 require 'rack'
 
 class ImageVise
-  VERSION = '0.0.25'
+  VERSION = '0.0.26'
   S_MUTEX = Mutex.new
   private_constant :S_MUTEX
   
@@ -75,7 +75,7 @@ class ImageVise
     #
     # The query string elements can be then passed on to RenderEngine for validation and execution.
     #
-    # @yields {ImageVise::Pipeline}
+    # @yield {ImageVise::Pipeline}
     # @return [Hash]
     def image_params(src_url:, secret:)
       p = Pipeline.new

data/spec/image_vise/image_request_spec.rb

@@ -4,11 +4,10 @@ describe ImageVise::ImageRequest do
   it 'accepts a set of params and secrets, and returns a Pipeline' do
     img_params = {src_url: 'http://bucket.s3.aws.com/image.jpg', pipeline: [[:crop, {width: 10, height: 10, gravity: 's'}]]}
     img_params_json = JSON.dump(img_params)
+    
+    q = Base64.encode64(img_params_json)
     signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, 'this is a secret', img_params_json)
-    params = {
-      q: Base64.encode64(img_params_json),
-      sig: signature
-    }
+    params = {q: q, sig: signature}
 
     image_request = described_class.to_request(qs_params: params, secrets: ['this is a secret'])
     request_qs_params = image_request.to_query_string_params('this is a secret')
@@ -29,6 +28,17 @@ describe ImageVise::ImageRequest do
     expect(image_request.src_url).to be_kind_of(URI)
   end
 
+
+  it 'never apppends "="-padding to the Base64-encoded "q"' do
+    parametrized = double(to_params: {foo: 'bar'})
+    (1..12).each do |num_chars_in_url|
+      uri = URI('http://ex.com/%s'  % ('i' * num_chars_in_url))
+      image_request = described_class.new(src_url: uri, pipeline: parametrized)
+      q = image_request.to_query_string_params('password').fetch(:q)
+      expect(q).not_to include('=')
+    end
+  end
+
   describe 'fails with an invalid pipeline' do
     it 'when the pipe param is missing'
     it 'when the pipe param is empty'

data/spec/image_vise/render_engine_spec.rb

@@ -158,6 +158,25 @@ describe ImageVise::RenderEngine do
       expect(parsed_image.columns).to eq(10)
     end
 
+    it 'calls all of the internal methods during execution' do
+      uri = Addressable::URI.parse(public_url)
+      ImageVise.add_allowed_host!(uri.host)
+      ImageVise.add_secret_key!('l33tness')
+
+      p = ImageVise::Pipeline.new.geom(geometry_string: '512x335').fit_crop(width: 10, height: 10, gravity: 'c')
+      image_request = ImageVise::ImageRequest.new(src_url: uri.to_s, pipeline: p)
+      params = image_request.to_query_string_params('l33tness')
+
+      expect(app).to receive(:process_image_request).and_call_original
+      expect(app).to receive(:image_rack_response).and_call_original
+      expect(app).to receive(:source_file_type_permitted?).and_call_original
+      expect(app).to receive(:output_file_type_permitted?).and_call_original
+      expect(app).to receive(:enable_forking?).and_call_original
+
+      get '/', params
+      expect(last_response.status).to eq(200)
+    end
+    
     it 'picks the image from the filesystem if that is permitted' do
       uri = 'file://' + test_image_path
       ImageVise.allow_filesystem_source!(File.dirname(test_image_path) + '/*.*')

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: image_vise
 version: !ruby/object:Gem::Version
-  version: 0.0.25
+  version: 0.0.26
 platform: ruby
 authors:
 - Julik Tarkhanov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-18 00:00:00.000000000 Z
+date: 2016-10-20 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: patron
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +80,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -248,11 +262,14 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- DEVELOPMENT.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - examples/config.ru
+- examples/custom_image_operator.rb
 - examples/error_handline_appsignal.rb
 - examples/error_handling_sentry.rb
 - image_vise.gemspec