imgix 3.1.0 → 3.3.1

data/imgix.gemspec

@@ -13,6 +13,13 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/imgix/imgix-rb'
   spec.license       = 'MIT'
 
+  spec.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/imgix/imgix-rb/issues',
+    'changelog_uri'     => 'https://github.com/imgix/imgix-rb/blob/main/CHANGELOG.md',
+    'documentation_uri' => "https://www.rubydoc.info/gems/imgix/#{spec.version}",
+    'source_code_uri'   => "https://github.com/imgix/imgix-rb/tree/#{spec.version}"
+  }
+
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})

data/lib/imgix.rb

@@ -6,22 +6,46 @@ require 'imgix/path'
 
 module Imgix
   # regex pattern used to determine if a domain is valid
-  DOMAIN_REGEX = /^(?:[a-z\d\-_]{1,62}\.){0,125}(?:[a-z\d](?:\-(?=\-*[a-z\d])|[a-z]|\d){0,62}\.)[a-z\d]{1,63}$/i
+  DOMAIN_REGEX = /^(?:[a-z\d\-_]{1,62}\.){0,125}(?:[a-z\d](?:\-(?=\-*[a-z\d])|[a-z]|\d){0,62}\.)[a-z\d]{1,63}$/i.freeze
+
+  # determines the growth rate when building out srcset pair widths
+  DEFAULT_WIDTH_TOLERANCE = 0.08
+
+  # the default minimum srcset width
+  MIN_WIDTH = 100
+
+  # the default maximum srcset width, also the max width supported by imgix
+  MAX_WIDTH = 8192
 
   # returns an array of width values used during scrset generation
-  TARGET_WIDTHS = lambda {
-    increment_percentage = 8
-    max_size = 8192
+  TARGET_WIDTHS = lambda { |tolerance, min, max|
+    increment_percentage = tolerance || DEFAULT_WIDTH_TOLERANCE
+
+    unless increment_percentage.is_a?(Numeric) && increment_percentage > 0
+      width_increment_error = 'error: `width_tolerance` must be a positive `Numeric` value'
+      raise ArgumentError, width_increment_error
+    end
+
+    max_size = max || MAX_WIDTH
     resolutions = []
-    prev = 100
+    prev = min || MIN_WIDTH
 
-    while(prev <= max_size)
+    while prev < max_size
       # ensures that each width is even
-      resolutions.push((2 * (prev / 2).round))
-      prev *= 1 + ((increment_percentage.to_f) / 100) * 2
+      resolutions.push(prev.round)
+      prev *= 1 + (increment_percentage * 2)
     end
 
     resolutions.push(max_size)
     return resolutions
   }
+
+  # hash of default quality parameter values mapped  by each dpr srcset entry
+  DPR_QUALITY = {
+    1 => 75,
+    2 => 50,
+    3 => 35,
+    4 => 23,
+    5 => 20
+  }.freeze
 end

data/lib/imgix/client.rb

@@ -7,54 +7,86 @@ require 'uri'
 
 module Imgix
   class Client
-    DEFAULTS = { use_https: true }
+    DEFAULTS = { use_https: true }.freeze
 
     def initialize(options = {})
       options = DEFAULTS.merge(options)
+      host, domain = options[:host], options[:domain]
+
+      host_deprecated = "Warning: The identifier `host' has been deprecated and " \
+        "will\nappear as `domain' in the next major version, e.g. " \
+        "`@host'\nbecomes `@domain', `options[:host]' becomes " \
+        "`options[:domain]'.\n"
+
+      if host
+        warn host_deprecated
+        @host = host
+      elsif domain
+        @host = domain
+      else
+        @host = host
+      end
 
-      @host = options[:host]
       validate_host!
+
       @secure_url_token = options[:secure_url_token]
       @api_key = options[:api_key]
       @use_https = options[:use_https]
       @include_library_param = options.fetch(:include_library_param, true)
-      @library = options.fetch(:library_param, "rb")
+      @library = options.fetch(:library_param, 'rb')
       @version = options.fetch(:library_version, Imgix::VERSION)
     end
 
     def path(path)
-      p = Path.new(prefix(path), @secure_url_token, path)
+      p = Path.new(new_prefix, @secure_url_token, path)
       p.ixlib("#{@library}-#{@version}") if @include_library_param
       p
     end
 
     def purge(path)
-      raise "Authentication token required" unless !!(@api_key)
-      url = prefix(path)+path
+      token_error = 'Authentication token required'
+      raise token_error if @api_key.nil?
+
+      url = new_prefix + path
       uri = URI.parse('https://api.imgix.com/v2/image/purger')
-      req = Net::HTTP::Post.new(uri.path, {"User-Agent" => "imgix #{@library}-#{@version}"})
+
+      user_agent = { 'User-Agent' => "imgix #{@library}-#{@version}" }
+
+      req = Net::HTTP::Post.new(uri.path, user_agent)
       req.basic_auth @api_key, ''
-      req.set_form_data({'url' => url})
+      req.set_form_data({ url: url })
+
       sock = Net::HTTP.new(uri.host, uri.port)
       sock.use_ssl = true
-      res = sock.start {|http| http.request(req) }
+      res = sock.start { |http| http.request(req) }
+
       res
     end
 
     def prefix(path)
+      msg = "Warning: `Client::prefix' will take zero arguments " \
+        "in the next major version.\n"
+      warn msg
+      new_prefix
+    end
+
+    def new_prefix
       "#{@use_https ? 'https' : 'http'}://#{@host}"
     end
 
     private
 
     def validate_host!
-      unless @host != nil
-        raise ArgumentError, "The :host option must be specified"
-      end
-      if @host.match(DOMAIN_REGEX) == nil
-        raise ArgumentError, "Domains must be passed in as fully-qualified domain names and should not include a protocol or any path element, i.e. \"example.imgix.net\"."
+      host_error = 'The :host option must be specified'
+      raise ArgumentError, host_error if @host.nil?
+
+      domain_error = 'Domains must be passed in as fully-qualified'\
+                     'domain names and should not include a protocol'\
+                     'or any path element, i.e. "example.imgix.net"'\
+
+      if @host.match(DOMAIN_REGEX).nil?
+        raise ArgumentError, domain_error
       end
     end
-    
   end
 end

data/lib/imgix/param_helpers.rb

@@ -3,6 +3,7 @@
 module Imgix
   module ParamHelpers
     def rect(position)
+      warn "Warning: `ParamHelpers.rect` has been deprecated and will be removed in the next major version.\n"
       @options[:rect] = position and return self if position.is_a?(String)
 
       @options[:rect] = [

data/lib/imgix/path.rb

@@ -10,26 +10,26 @@ module Imgix
     include ParamHelpers
 
     ALIASES = {
-      width:           :w,
-      height:          :h,
-      rotation:        :rot,
+      width: :w,
+      height: :h,
+      rotation: :rot,
       noise_reduction: :nr,
-      sharpness:       :sharp,
-      exposure:        :exp,
-      vibrance:        :vib,
-      saturation:      :sat,
-      brightness:      :bri,
-      contrast:        :con,
-      highlight:       :high,
-      shadow:          :shad,
-      gamma:           :gam,
-      pixelate:        :px,
-      halftone:        :htn,
-      watermark:       :mark,
-      text:            :txt,
-      format:          :fm,
-      quality:         :q
-    }
+      sharpness: :sharp,
+      exposure: :exp,
+      vibrance: :vib,
+      saturation: :sat,
+      brightness: :bri,
+      contrast: :con,
+      highlight: :high,
+      shadow: :shad,
+      gamma: :gam,
+      pixelate: :px,
+      halftone: :htn,
+      watermark: :mark,
+      text: :txt,
+      format: :fm,
+      quality: :q
+    }.freeze
 
     def initialize(prefix, secure_url_token, path = '/')
       @prefix = prefix
@@ -39,7 +39,7 @@ module Imgix
 
       @path = CGI.escape(@path) if /^https?/ =~ @path
       @path = "/#{@path}" if @path[0] != '/'
-      @target_widths = TARGET_WIDTHS.call
+      @target_widths = TARGET_WIDTHS.call(DEFAULT_WIDTH_TOLERANCE, MIN_WIDTH, MAX_WIDTH)
     end
 
     def to_url(opts = {})
@@ -53,12 +53,12 @@ module Imgix
       end
 
       @options = prev_options
-      return url
+      url
     end
 
     def defaults
       @options = {}
-      return self
+      self
     end
 
     def method_missing(method, *args, &block)
@@ -70,33 +70,44 @@ module Imgix
       end
 
       @options[key] = args.join(',')
-      return self
+      self
     end
 
     ALIASES.each do |from, to|
       define_method from do |*args|
+        warn "Warning: `Path.#{from}' has been deprecated and " \
+             "will be removed in the next major version (along " \
+             "with all parameter `ALIASES`).\n"
         self.send(to, *args)
       end
 
       define_method "#{from}=" do |*args|
+        warn "Warning: `Path.#{from}=' has been deprecated and " \
+             "will be removed in the next major version (along " \
+             "with all parameter `ALIASES`).\n"
         self.send("#{to}=", *args)
         return self
       end
     end
 
-    def to_srcset(params = {})
+    def to_srcset(options: {}, **params)
+      prev_options = @options.dup
       @options.merge!(params)
-      width = @options['w'.to_sym]
-      height = @options['h'.to_sym]
-      aspect_ratio = @options['ar'.to_sym]
 
-      if ((width) || (height && aspect_ratio))
-        build_dpr_srcset(@options)
-      else
-        build_srcset_pairs(@options)
-      end
+      width = @options[:w]
+      height = @options[:h]
+      aspect_ratio = @options[:ar]
+
+      srcset = if width || (height && aspect_ratio)
+                 build_dpr_srcset(options: options, params: @options)
+               else
+                 build_srcset_pairs(options: options, params: @options)
+               end
+
+      @options = prev_options
+      srcset
     end
-    
+
     private
 
     def signature
@@ -123,27 +134,87 @@ module Imgix
       query.length > 0
     end
 
-    def build_srcset_pairs(params = {})
+    def build_srcset_pairs(options:, params:)
       srcset = ''
-      for width in @target_widths do
-        currentParams = params || {}
-        currentParams['w'] = width
-        srcset += "#{to_url(currentParams)} #{width}w,\n"
+
+      widths = options[:widths] || []
+      width_tolerance = options[:width_tolerance] || DEFAULT_WIDTH_TOLERANCE
+      min_width = options[:min_width] || MIN_WIDTH
+      max_width = options[:max_width] || MAX_WIDTH
+
+      if !widths.empty?
+        validate_widths!(widths)
+        srcset_widths = widths
+      elsif width_tolerance != DEFAULT_WIDTH_TOLERANCE || min_width != MIN_WIDTH || max_width != MAX_WIDTH
+        validate_range!(min_width, max_width)
+        validate_width_tolerance!(width_tolerance)
+        srcset_widths = TARGET_WIDTHS.call(width_tolerance, min_width, max_width)
+      else
+        srcset_widths = @target_widths
+      end
+
+      for width in srcset_widths do
+        params[:w] = width
+        srcset += "#{to_url(params)} #{width}w,\n"
       end
 
-      return srcset[0..-3]
+      srcset[0..-3]
     end
 
-    def build_dpr_srcset(params = {})
+    def build_dpr_srcset(options:, params:)
       srcset = ''
-      target_ratios = [1,2,3,4,5]
-      url = to_url(params)
+
+      disable_variable_quality = options[:disable_variable_quality] || false
+      validate_variable_qualities!(disable_variable_quality)
+
+      target_ratios = [1, 2, 3, 4, 5]
+      quality = params[:q]
 
       for ratio in target_ratios do
-        srcset += "#{url} #{ratio}x,\n"
+        params[:dpr] = ratio
+
+        unless disable_variable_quality
+          params[:q] = quality || DPR_QUALITY[ratio]
+        end
+
+        srcset += "#{to_url(params)} #{ratio}x,\n"
       end
 
-      return srcset[0..-3]
+      srcset[0..-3]
+    end
+
+    def validate_width_tolerance!(width_tolerance)
+      width_increment_error = 'error: `width_tolerance` must be a positive `Numeric` value'
+
+      if !width_tolerance.is_a?(Numeric) || width_tolerance <= 0
+        raise ArgumentError, width_increment_error
+      end
+    end
+
+    def validate_widths!(widths)
+      widths_error = 'error: `widths` must be an array of positive `Numeric` values'
+      raise ArgumentError, widths_error unless widths.is_a?(Array)
+
+      all_positive_integers = widths.all? { |i| i.is_a?(Integer) && i > 0 }
+      raise ArgumentError, widths_error unless all_positive_integers
+    end
+
+    def validate_range!(min_srcset, max_srcset)
+      range_numeric_error = 'error: `min_width` and `max_width` must be positive `Numeric` values'
+      unless min_srcset.is_a?(Numeric) && max_srcset.is_a?(Numeric)
+        raise ArgumentError, range_numeric_error
+      end
+
+      unless min_srcset > 0 && max_srcset > 0
+        raise ArgumentError, range_numeric_error
+      end
+    end
+
+    def validate_variable_qualities!(disable_quality)
+      disable_quality_error = 'error: `disable_quality` must be a Boolean value'
+      unless disable_quality.is_a?(TrueClass) || disable_quality.is_a?(FalseClass)
+        raise ArgumentError, disable_quality_error
+      end
     end
   end
 end

data/lib/imgix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imgix
-  VERSION = '3.1.0'
+  VERSION = '3.3.1'
 end

data/test/units/param_helpers_test.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class ParamHelpers < Imgix::Test
+  def test_param_helpers_emits_dep_warning
+    host_warn = "Warning: The identifier `host' has been deprecated and " \
+                "will\nappear as `domain' in the next major version, e.g. " \
+                "`@host'\nbecomes `@domain', `options[:host]' becomes " \
+                "`options[:domain]'.\n"
+
+    assert_output(nil, host_warn) {
+        client = Imgix::Client.new(host: 'test.imgix.net')
+
+        rect_warn = "Warning: `ParamHelpers.rect` has been deprecated and " \
+                    "will be removed in the next major version.\n"
+
+        assert_output(nil, rect_warn){
+            client.path('/images/demo.png').rect(x: 0, y: 50, width: 200, height: 300)
+        }
+    }
+  end
+end

data/test/units/path_test.rb

@@ -3,6 +3,27 @@
 require 'test_helper'
 
 class PathTest < Imgix::Test
+  def test_prefix_with_arg_warns
+    prefix_warn = "Warning: `Client::prefix' will take zero arguments " \
+      "in the next major version.\n"
+
+    assert_output(nil, prefix_warn) {
+      Imgix::Client.new(
+        domain: 'test.imgix.net',
+        include_library_param: false
+      ).prefix("")
+    }
+
+    # `new_prefix' is a placeholder until the bump, when it will become
+    # `prefix`.
+    assert_output(nil, nil) {
+      Imgix::Client.new(
+        domain: 'test.imgix.net',
+        include_library_param: false
+      ).new_prefix
+    }
+  end
+
   def test_creating_a_path
     path = client.path('/images/demo.png')
     assert_equal 'https://demo.imgix.net/images/demo.png?s=2c7c157eaf23b06a0deb2f60b81938c4', path.to_url
@@ -14,7 +35,12 @@ class PathTest < Imgix::Test
   def test_signing_path_with_param
     url = 'https://demo.imgix.net/images/demo.png?w=200&s=da421114ca238d1f4a927b889f67c34e'
     path = client.path('/images/demo.png')
-    path.width = 200
+
+    assert_output(nil, "Warning: `Path.width=' has been deprecated and " \
+      "will be removed in the next major version (along " \
+      "with all parameter `ALIASES`).\n") {
+        path.width = 200
+    }
 
     assert_equal url, path.to_url
 
@@ -22,13 +48,23 @@ class PathTest < Imgix::Test
     assert_equal url, path.to_url(w: 200)
 
     path = client.path('/images/demo.png')
-    assert_equal url, path.width(200).to_url
+
+    assert_output(nil, "Warning: `Path.width' has been deprecated and " \
+      "will be removed in the next major version (along " \
+      "with all parameter `ALIASES`).\n") {
+        assert_equal url, path.width(200).to_url
+    }
   end
 
   def test_resetting_defaults
     url = 'https://demo.imgix.net/images/demo.png?w=200&s=da421114ca238d1f4a927b889f67c34e'
     path = client.path('/images/demo.png')
-    path.height = 300
+    
+    assert_output(nil, "Warning: `Path.height=' has been deprecated and " \
+      "will be removed in the next major version (along " \
+      "with all parameter `ALIASES`).\n") {
+        path.height = 300
+    }
 
     assert_equal url, path.defaults.to_url(w: 200)
   end
@@ -40,7 +76,21 @@ class PathTest < Imgix::Test
     assert_equal url, path.to_url(h: 200, w: 200)
 
     path = client.path('/images/demo.png')
-    assert_equal url, path.height(200).width(200).to_url
+
+    assert_output(nil, "Warning: `Path.height' has been deprecated and " \
+      "will be removed in the next major version (along " \
+      "with all parameter `ALIASES`).\n") {
+        path.height(200)
+    }
+
+
+    assert_output(nil, "Warning: `Path.width' has been deprecated and " \
+      "will be removed in the next major version (along " \
+      "with all parameter `ALIASES`).\n") {
+        path.width(200)
+    }
+
+    assert_equal url, path.to_url
   end
 
   def test_path_with_multi_value_param_safely_encoded