cloudinary 1.9.1 → 1.20.0

data/lib/cloudinary/utils.rb

@@ -1,4 +1,6 @@
 # Copyright Cloudinary
+
+# frozen_string_literal: true
 require 'digest/sha1'
 require 'zlib'
 require 'uri'
@@ -6,6 +8,7 @@ require 'aws_cf_signer'
 require 'json'
 require 'cgi'
 require 'cloudinary/auth_token'
+require 'cloudinary/responsive'
 
 class Cloudinary::Utils
   # @deprecated Use Cloudinary::SHARED_CDN
@@ -23,30 +26,172 @@ class Cloudinary::Utils
     "*" => 'mul',
     "/" => 'div',
     "+" => 'add',
-    "-" => 'sub'
+    "-" => 'sub',
+    "^" => 'pow'
   }
 
   PREDEFINED_VARS = {
     "aspect_ratio"         => "ar",
+    "aspectRatio"          => "ar",
     "current_page"         => "cp",
+    "currentPage"          => "cp",
     "face_count"           => "fc",
+    "faceCount"            => "fc",
     "height"               => "h",
     "initial_aspect_ratio" => "iar",
+    "initialAspectRatio"   => "iar",
+    "trimmed_aspect_ratio" => "tar",
+    "trimmedAspectRatio"   => "tar",
     "initial_height"       => "ih",
+    "initialHeight"        => "ih",
     "initial_width"        => "iw",
+    "initialWidth"         => "iw",
     "page_count"           => "pc",
+    "pageCount"            => "pc",
     "page_x"               => "px",
+    "pageX"                => "px",
     "page_y"               => "py",
+    "pageY"                => "py",
     "tags"                 => "tags",
-    "width"                => "w"
+    "initial_duration"     => "idu",
+    "initialDuration"      => "idu",
+    "duration"             => "du",
+    "width"                => "w",
+    "illustration_score"   => "ils",
+    "illustrationScore"    => "ils",
+    "context"              => "ctx"
+  }
+
+  SIMPLE_TRANSFORMATION_PARAMS = {
+    :ac => :audio_codec,
+    :af => :audio_frequency,
+    :br => :bit_rate,
+    :cs => :color_space,
+    :d  => :default_image,
+    :dl => :delay,
+    :dn => :density,
+    :du => :duration,
+    :eo => :end_offset,
+    :f  => :fetch_format,
+    :g  => :gravity,
+    :ki => :keyframe_interval,
+    :p  => :prefix,
+    :pg => :page,
+    :so => :start_offset,
+    :sp => :streaming_profile,
+    :vc => :video_codec,
+    :vs => :video_sampling
+  }.freeze
+
+  URL_KEYS = %w[
+      api_secret
+      auth_token
+      cdn_subdomain
+      cloud_name
+      cname
+      format
+      private_cdn
+      resource_type
+      secure
+      secure_cdn_subdomain
+      secure_distribution
+      shorten
+      sign_url
+      ssl_detected
+      type
+      url_suffix
+      use_root_path
+      version
+  ].map(&:to_sym)
+
+
+  TRANSFORMATION_PARAMS = %w[
+      angle
+      aspect_ratio
+      audio_codec
+      audio_frequency
+      background
+      bit_rate
+      border
+      color
+      color_space
+      crop
+      custom_function
+      default_image
+      delay
+      density
+      dpr
+      duration
+      effect
+      end_offset
+      fetch_format
+      flags
+      fps
+      gravity
+      height
+      if
+      keyframe_interval
+      offset
+      opacity
+      overlay
+      page
+      prefix
+      quality
+      radius
+      raw_transformation
+      responsive_width
+      size
+      start_offset
+      streaming_profile
+      transformation
+      underlay
+      variables
+      video_codec
+      video_sampling
+      width
+      x
+      y
+      zoom
+  ].map(&:to_sym)
+
+  REMOTE_URL_REGEX = %r(^ftp:|^https?:|^s3:|^gs:|^data:([\w-]+\/[\w-]+(\+[\w-]+)?)?(;[\w-]+=[\w-]+)*;base64,([a-zA-Z0-9\/+\n=]+)$)
+
+  LONG_URL_SIGNATURE_LENGTH = 32
+  SHORT_URL_SIGNATURE_LENGTH = 8
+
+  UPLOAD_PREFIX = 'https://api.cloudinary.com'
+
+  ALGO_SHA1 = :sha1
+  ALGO_SHA256 = :sha256
+
+  ALGORITHM_SIGNATURE = {
+    ALGO_SHA1 => Digest::SHA1,
+    ALGO_SHA256 => Digest::SHA256,
   }
+
+  def self.extract_config_params(options)
+      options.select{|k,v| URL_KEYS.include?(k)}
+  end
+
+  def self.extract_transformation_params(options)
+    options.select{|k,v| TRANSFORMATION_PARAMS.include?(k)}
+  end
+
+  def self.chain_transformation(options, *transformation)
+    base_options = extract_config_params(options)
+    transformation = transformation.reject(&:nil?)
+    base_options[:transformation] = build_array(extract_transformation_params(options)).concat(transformation)
+    base_options
+  end
+
+
   # Warning: options are being destructively updated!
   def self.generate_transformation_string(options={}, allow_implicit_crop_mode = false)
     # allow_implicit_crop_mode was added to support height and width parameters without specifying a crop mode.
     # This only apply to this (cloudinary_gem) SDK
 
     if options.is_a?(Array)
-      return options.map{|base_transformation| generate_transformation_string(base_transformation.clone, allow_implicit_crop_mode)}.join("/")
+      return options.map{|base_transformation| generate_transformation_string(base_transformation.clone, allow_implicit_crop_mode)}.reject(&:blank?).join("/")
     end
 
     symbolize_keys!(options)
@@ -102,9 +247,14 @@ class Cloudinary::Utils
       options[:start_offset], options[:end_offset] = split_range options.delete(:offset)
     end
 
+    fps = options.delete(:fps)
+    fps = fps.join('-') if fps.is_a? Array
+
     overlay = process_layer(options.delete(:overlay))
     underlay = process_layer(options.delete(:underlay))
     ifValue = process_if(options.delete(:if))
+    custom_function = process_custom_function(options.delete(:custom_function))
+    custom_pre_function = process_custom_pre_function(options.delete(:custom_pre_function))
 
     params = {
       :a   => normalize_expression(angle),
@@ -116,11 +266,13 @@ class Cloudinary::Utils
       :dpr => normalize_expression(dpr),
       :e   => normalize_expression(effect),
       :fl  => flags,
+      :fn  => custom_function || custom_pre_function,
+      :fps => fps,
       :h   => normalize_expression(height),
       :l  => overlay,
       :o => normalize_expression(options.delete(:opacity)),
       :q => normalize_expression(options.delete(:quality)),
-      :r => normalize_expression(options.delete(:radius)),
+      :r => process_radius(options.delete(:radius)),
       :t   => named_transformation,
       :u  => underlay,
       :w   => normalize_expression(width),
@@ -128,26 +280,7 @@ class Cloudinary::Utils
       :y => normalize_expression(options.delete(:y)),
       :z => normalize_expression(options.delete(:zoom))
     }
-    {
-      :ac => :audio_codec,
-      :af => :audio_frequency,
-      :br => :bit_rate,
-      :cs => :color_space,
-      :d  => :default_image,
-      :dl => :delay,
-      :dn => :density,
-      :du => :duration,
-      :eo => :end_offset,
-      :f  => :fetch_format,
-      :g  => :gravity,
-      :ki => :keyframe_interval,
-      :p  => :prefix,
-      :pg => :page,
-      :so => :start_offset,
-      :sp => :streaming_profile,
-      :vc => :video_codec,
-      :vs => :video_sampling
-    }.each do
+    SIMPLE_TRANSFORMATION_PARAMS.each do
       |param, option|
       params[param] = options.delete(option)
     end
@@ -197,22 +330,20 @@ class Cloudinary::Utils
   # Translates the condition if provided.
   # @return [string] "if_" + ifValue
   # @private
-  def self.process_if(ifValue)
-    if ifValue
-      ifValue = normalize_expression(ifValue)
-
-      ifValue = "if_" + ifValue
-    end
+  def self.process_if(if_value)
+    "if_" + normalize_expression(if_value) unless if_value.to_s.empty?
   end
 
-  EXP_REGEXP = Regexp.new(PREDEFINED_VARS.keys.join("|")+'|('+CONDITIONAL_OPERATORS.keys.reverse.map { |k| Regexp.escape(k) }.join('|')+')(?=[ _])')
+  EXP_REGEXP = Regexp.new('(\$_*[^_ ]+)|(?<!\$)('+PREDEFINED_VARS.keys.join("|")+')'+'|('+CONDITIONAL_OPERATORS.keys.reverse.map { |k| Regexp.escape(k) }.join('|')+')(?=[ _])')
   EXP_REPLACEMENT = PREDEFINED_VARS.merge(CONDITIONAL_OPERATORS)
 
   def self.normalize_expression(expression)
-    if expression =~ /^!.+!$/ # quoted string
+    if expression.nil?
+      nil
+    elsif expression.is_a?( String) && expression =~ /^!.+!$/ # quoted string
       expression
     else
-      expression.to_s.gsub(EXP_REGEXP,EXP_REPLACEMENT).gsub(/[ _]+/, "_")
+      expression.to_s.gsub(EXP_REGEXP) { |match| EXP_REPLACEMENT[match] || match }.gsub(/[ _]+/, "_")
     end
   end
 
@@ -230,9 +361,13 @@ class Cloudinary::Utils
        text_style    = nil
        components    = []
 
-       unless public_id.blank?
-         public_id = public_id.gsub("/", ":")
-         public_id = "#{public_id}.#{format}" unless format.nil?
+       if public_id.present?
+          if type == "fetch" && public_id.match(%r(^https?:/)i)
+            public_id = Base64.urlsafe_encode64(public_id)
+          else
+            public_id = public_id.gsub("/", ":")
+            public_id = "#{public_id}.#{format}" if format
+          end
        end
 
        if text.blank? && resource_type != "text"
@@ -275,6 +410,17 @@ class Cloudinary::Utils
   end
   private_class_method :process_layer
 
+  # Parse radius options
+  # @return [string] radius transformation string
+  # @private
+  def self.process_radius(radius)
+    if radius.is_a?(Array) && !radius.length.between?(1, 4)
+      raise(CloudinaryException, "Invalid radius parameter")
+    end
+    Array(radius).map { |r| normalize_expression(r) }.join(":")
+  end
+  private_class_method :process_radius
+
   LAYER_KEYWORD_PARAMS =[
     [:font_weight     ,"normal"],
     [:font_style      ,"normal"],
@@ -295,6 +441,10 @@ class Cloudinary::Utils
     keywords.push("letter_spacing_#{letter_spacing}") unless letter_spacing.blank?
     line_spacing = layer[:line_spacing]
     keywords.push("line_spacing_#{line_spacing}") unless line_spacing.blank?
+    font_antialiasing = layer[:font_antialiasing]
+    keywords.push("antialias_#{font_antialiasing}") unless font_antialiasing.blank?
+    font_hinting = layer[:font_hinting]
+    keywords.push("hinting_#{font_hinting}") unless font_hinting.blank?
     if !font_size.blank? || !font_family.blank? || !keywords.empty?
       raise(CloudinaryException, "Must supply font_family for text in overlay/underlay") if font_family.blank?
       raise(CloudinaryException, "Must supply font_size for text in overlay/underlay") if font_size.blank?
@@ -308,9 +458,9 @@ class Cloudinary::Utils
     params_to_sign.map{|k,v| [k.to_s, v.is_a?(Array) ? v.join(",") : v]}.reject{|k,v| v.nil? || v == ""}.sort_by(&:first).map{|k,v| "#{k}=#{v}"}.join("&")
   end
 
-  def self.api_sign_request(params_to_sign, api_secret)
+  def self.api_sign_request(params_to_sign, api_secret, signature_algorithm = nil)
     to_sign = api_string_to_sign(params_to_sign)
-    Digest::SHA1.hexdigest("#{to_sign}#{api_secret}")
+    hash("#{to_sign}#{api_secret}", signature_algorithm, :hexdigest)
   end
 
   # Returns a JSON array as String.
@@ -348,13 +498,14 @@ class Cloudinary::Utils
   # Warning: options are being destructively updated!
   def self.unsigned_download_url(source, options = {})
 
+    patch_fetch_format(options)
     type = options.delete(:type)
 
-    options[:fetch_format] ||= options.delete(:format) if type.to_s == "fetch"
     transformation = self.generate_transformation_string(options)
 
     resource_type = options.delete(:resource_type)
     version = options.delete(:version)
+    force_version = config_option_consume(options, :force_version, true)
     format = options.delete(:format)
     cloud_name = config_option_consume(options, :cloud_name) || raise(CloudinaryException, "Must supply cloud_name in tag or in configuration")
 
@@ -374,6 +525,8 @@ class Cloudinary::Utils
     url_suffix = options.delete(:url_suffix)
     use_root_path = config_option_consume(options, :use_root_path)
     auth_token = config_option_consume(options, :auth_token)
+    long_url_signature = config_option_consume(options, :long_url_signature)
+    signature_algorithm = config_option_consume(options, :signature_algorithm)
     unless auth_token == false
       auth_token = Cloudinary::AuthToken.merge_auth_token(Cloudinary.config.auth_token, auth_token)
     end
@@ -405,14 +558,23 @@ class Cloudinary::Utils
     resource_type, type = finalize_resource_type(resource_type, type, url_suffix, use_root_path, shorten)
     source, source_to_sign = finalize_source(source, format, url_suffix)
 
-    version ||= 1 if source_to_sign.include?("/") and !source_to_sign.match(/^v[0-9]+/) and !source_to_sign.match(/^https?:\//)
+    if version.nil? && force_version &&
+         source_to_sign.include?("/") &&
+         !source_to_sign.match(/^v[0-9]+/) &&
+         !source_to_sign.match(/^https?:\//)
+      version = 1
+    end
     version &&= "v#{version}"
 
     transformation = transformation.gsub(%r(([^:])//), '\1/')
     if sign_url && ( !auth_token || auth_token.empty?)
+      raise(CloudinaryException, "Must supply api_secret") if (secret.nil? || secret.empty?)
       to_sign = [transformation, sign_version && version, source_to_sign].reject(&:blank?).join("/")
       to_sign = fully_unescape(to_sign)
-      signature = 's--' + Base64.urlsafe_encode64(Digest::SHA1.digest(to_sign + secret))[0,8] + '--'
+      signature_algorithm = long_url_signature ? ALGO_SHA256 : signature_algorithm
+      hash = hash("#{to_sign}#{secret}", signature_algorithm)
+      signature = Base64.urlsafe_encode64(hash)
+      signature = "s--#{signature[0, long_url_signature ? LONG_URL_SIGNATURE_LENGTH : SHORT_URL_SIGNATURE_LENGTH ]}--"
     end
 
     prefix = unsigned_download_url_prefix(source, cloud_name, private_cdn, cdn_subdomain, secure_cdn_subdomain, cname, secure, secure_distribution)
@@ -432,7 +594,7 @@ class Cloudinary::Utils
       source = smart_escape(source)
       source_to_sign = source
     else
-      source = smart_escape(URI.decode(source))
+      source = smart_escape(smart_unescape(source))
       source_to_sign = source
       unless url_suffix.blank?
         raise(CloudinaryException, "url_suffix should not include . or /") if url_suffix.match(%r([\./]))
@@ -528,18 +690,31 @@ class Cloudinary::Utils
     prefix
   end
 
+  # Creates a base URL for the cloudinary api
+  #
+  # @param [Object] path  Resource name
+  # @param [Hash] options Additional options
+  #
+  # @return [String]
+  def self.base_api_url(path, options = {})
+    cloudinary = options[:upload_prefix] || Cloudinary.config.upload_prefix || UPLOAD_PREFIX
+    cloud_name = options[:cloud_name] || Cloudinary.config.cloud_name || raise(CloudinaryException, 'Must supply cloud_name')
+
+    [cloudinary, 'v1_1', cloud_name, path].join('/')
+  end
+
   def self.cloudinary_api_url(action = 'upload', options = {})
-    cloudinary = options[:upload_prefix] || Cloudinary.config.upload_prefix || "https://api.cloudinary.com"
-    cloud_name = options[:cloud_name] || Cloudinary.config.cloud_name || raise(CloudinaryException, "Must supply cloud_name")
-    resource_type = options[:resource_type] || "image"
-    return [cloudinary, "v1_1", cloud_name, resource_type, action].join("/")
+    resource_type = options[:resource_type] || 'image'
+
+    base_api_url([resource_type, action], options)
   end
 
   def self.sign_request(params, options={})
     api_key = options[:api_key] || Cloudinary.config.api_key || raise(CloudinaryException, "Must supply api_key")
     api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise(CloudinaryException, "Must supply api_secret")
+    signature_algorithm = options[:signature_algorithm]
     params = params.reject{|k, v| self.safe_blank?(v)}
-    params[:signature] = Cloudinary::Utils.api_sign_request(params, api_secret)
+    params[:signature] = api_sign_request(params, api_secret, signature_algorithm)
     params[:api_key] = api_key
     params
   end
@@ -603,6 +778,18 @@ class Cloudinary::Utils
     download_archive_url(options.merge(:target_format => "zip"))
   end
 
+  # Creates and returns a URL that when invoked creates an archive of a folder.
+  #
+  # @param [Object] folder_path Full path (from the root) of the folder to download.
+  # @param [Hash] options       Additional options.
+  #
+  # @return [String]
+  def self.download_folder(folder_path, options = {})
+    resource_type = options[:resource_type] || "all"
+
+    download_archive_url(options.merge(:resource_type => resource_type, :prefixes => folder_path))
+  end
+
   def self.signed_download_url(public_id, options = {})
     aws_private_key_path = options[:aws_private_key_path] || Cloudinary.config.aws_private_key_path
     if aws_private_key_path
@@ -636,13 +823,18 @@ class Cloudinary::Utils
     "#{public_id}#{ext}"
   end
 
-  # Based on CGI::unescape. In addition does not escape / :
+  # Based on CGI::escape. In addition does not escape / :
   def self.smart_escape(string, unsafe = /([^a-zA-Z0-9_.\-\/:]+)/)
     string.gsub(unsafe) do |m|
       '%' + m.unpack('H2' * m.bytesize).join('%').upcase
     end
   end
 
+  # Based on CGI::unescape. In addition keeps '+' character as is
+  def self.smart_unescape(string)
+    CGI.unescape(string.sub('+', '%2B'))
+  end
+
   def self.random_public_id
     sr = defined?(ActiveSupport::SecureRandom) ? ActiveSupport::SecureRandom : SecureRandom
     sr.base64(20).downcase.gsub(/[^a-z0-9]/, "").sub(/^[0-9]+/, '')[0,20]
@@ -710,7 +902,7 @@ class Cloudinary::Utils
     end
   end
 
-  IMAGE_FORMATS = %w(ai bmp bpg djvu eps eps3 flif gif hdp hpx ico j2k jp2 jpc jpe jpg miff pdf png psd svg tif tiff wdp webp zip )
+  IMAGE_FORMATS = %w(ai bmp bpg djvu eps eps3 flif gif hdp hpx ico j2k jp2 jpc jpe jpeg jpg miff pdf png psd svg tif tiff wdp webp zip )
 
   AUDIO_FORMATS = %w(aac aifc aiff flac m4a mp3 ogg wav)
 
@@ -730,10 +922,8 @@ class Cloudinary::Utils
     case
     when self.supported_format?(format, IMAGE_FORMATS)
       'image'
-    when self.supported_format?(format, VIDEO_FORMATS)
+    when self.supported_format?(format, VIDEO_FORMATS), self.supported_format?(format, AUDIO_FORMATS)
       'video'
-    when self.supported_format?(format, AUDIO_FORMATS)
-      'audio'
     else
       'raw'
     end
@@ -741,7 +931,8 @@ class Cloudinary::Utils
 
   def self.config_option_consume(options, option_name, default_value = nil)
     return options.delete(option_name) if options.include?(option_name)
-    return Cloudinary.config.send(option_name) || default_value
+    option_value = Cloudinary.config.send(option_name)
+    option_value.nil? ? default_value : option_value
   end
 
   def self.as_bool(value)
@@ -750,7 +941,7 @@ class Cloudinary::Utils
     when String then value.downcase == "true" || value == "1"
     when TrueClass then true
     when FalseClass then false
-    when Fixnum then value != 0
+    when Integer then value != 0
     when Symbol then value == :true
     else
       raise "Invalid boolean value #{value} of type #{value.class}"
@@ -827,6 +1018,7 @@ class Cloudinary::Utils
       :keep_derived=>Cloudinary::Utils.as_safe_bool(options[:keep_derived]),
       :tags=>options[:tags] && Cloudinary::Utils.build_array(options[:tags]),
       :public_ids=>options[:public_ids] && Cloudinary::Utils.build_array(options[:public_ids]),
+      :fully_qualified_public_ids=>options[:fully_qualified_public_ids] && Cloudinary::Utils.build_array(options[:fully_qualified_public_ids]),
       :prefixes=>options[:prefixes] && Cloudinary::Utils.build_array(options[:prefixes]),
       :expires_at=>options[:expires_at],
       :transformations => build_eager(options[:transformations]),
@@ -968,4 +1160,82 @@ class Cloudinary::Utils
   end
   private_class_method :process_video_params
 
+  def self.process_custom_pre_function(param)
+    value = process_custom_function(param)
+    value ? "pre:#{value}" : nil
+  end
+
+  def self.process_custom_function(param)
+    return param unless param.is_a? Hash
+
+    function_type = param[:function_type]
+    source = param[:source]
+
+    source = Base64.urlsafe_encode64(source) if function_type == "remote"
+    "#{function_type}:#{source}"
+  end
+
+  #
+  # Handle the format parameter for fetch urls
+  # @private
+  # @param options url and transformation options. This argument may be changed by the function!
+  #
+  def self.patch_fetch_format(options={})
+    if options[:type] === :fetch
+      format_arg = options.delete(:format)
+      options[:fetch_format] ||= format_arg
+    end
+  end
+
+  def self.is_remote?(url)
+    REMOTE_URL_REGEX === url
+  end
+
+  # The returned url should allow downloading the backedup asset based on the version and asset id
+  #
+  # asset and version id are returned with resource(<PUBLIC_ID1>, { versions: true })
+  #
+  # @param [String] asset_id   Asset identifier
+  # @param [String] version_id Specific version of asset to download
+  # @param [Hash] options      Additional options
+  #
+  # @return [String] An url for downloading a file
+  def self.download_backedup_asset(asset_id, version_id, options = {})
+    params = Cloudinary::Utils.sign_request({
+      :timestamp => (options[:timestamp] || Time.now.to_i),
+      :asset_id => asset_id,
+      :version_id => version_id
+    }, options)
+
+    "#{Cloudinary::Utils.base_api_url("download_backup", options)}?#{Cloudinary::Utils.hash_query_params((params))}"
+  end
+
+  # Format date in a format accepted by the usage API (e.g., 31-12-2020) if
+  # passed value is of type Date, otherwise return the string representation of
+  # the input.
+  #
+  # @param [Date|Object] date
+  # @return [String]
+  def self.to_usage_api_date_format(date)
+    if date.is_a?(Date)
+      date.strftime('%d-%m-%Y')
+    else
+      date.to_s
+    end
+  end
+
+  # Computes hash from input string using specified algorithm.
+  #
+  # @param [String] input                   String which to compute hash from
+  # @param [String|nil] signature_algorithm Algorithm to use for computing hash
+  # @param [Symbol] hash_method             Hash method applied to a signature algorithm (:digest or :hexdigest)
+  #
+  # @return [String] Computed hash value
+  def self.hash(input, signature_algorithm = nil, hash_method = :digest)
+    signature_algorithm ||= Cloudinary.config.signature_algorithm || ALGO_SHA1
+    algorithm = ALGORITHM_SIGNATURE[signature_algorithm] || raise("Unsupported algorithm '#{signature_algorithm}'")
+    algorithm.public_send(hash_method, input)
+  end
+
+  private_class_method :hash
 end