fileboy 0.2.0 → 0.3.0

data/lib/fileboy/transforms.rb

@@ -1,20 +1,97 @@
 module Fileboy
   # Builds the value of the `transform` query parameter on image URLs, for example
-  # `resize:300x_~fit:cover;format:webp;quality:75`. It only emits what the Fileboy image service
-  # understands: resize, format, quality, background and invert.
+  # `resize:300x_~fit:cover;format:webp;quality:75`. Every transform the Fileboy image service
+  # supports can be built here; see https://fileboy.io/docs/delivery/image-transforms.
   module Transforms
     FITS = %w[contain cover fill inside outside].freeze
     POSITIONS = %w[top-left top top-right left center right bottom-left bottom bottom-right].freeze
-    FORMATS = %w[jpeg jpg png bmp tiff tif webp].freeze
-    TYPES = %w[resize format quality background invert].freeze
+    FORMATS = %w[auto jpeg jpg png bmp tiff tif webp avif json].freeze
+    # The formats a resize can convert to: every format except json, which only the format
+    # transform takes (it answers with the image's details as JSON instead of an image).
+    RESIZE_FORMATS = (FORMATS - %w[json]).freeze
+    FLIPS = %w[x y xy].freeze
+    FONTS = %w[sans sans-bold sans-italic mono mono-bold].freeze
+    ALIGNS = %w[left center right].freeze
+    TYPES = %w[
+      resize resizeAR crop smartCrop format quality background invert rotate flip blur sharpen
+      saturate grayscale brightness contrast hue gamma sepia tint opacity pixelate radius pad
+      border dpr strip trim lossless overlay text palette
+    ].freeze
+    # Transforms that belong to the main chain, never an overlay's own.
+    NOT_IN_OVERLAY = %w[format quality dpr strip lossless background overlay text palette].freeze
+    FILE_ID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+    PALETTE_OUTPUTS = %w[json css].freeze
+    PALETTE_PREFIX = /\A[A-Za-z][A-Za-z0-9_-]{0,31}\z/
+
+    HEX = /\A([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\z/i
+    HEX_CALL = /\Ahex\(([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\)\z/i
+    RGB = /\Argb\((\d{1,3}),(\d{1,3}),(\d{1,3})\)\z/
+    RGBA = /\Argba\((\d{1,3}),(\d{1,3}),(\d{1,3}),(0|1|0?\.\d+|1\.0+)\)\z/
+    # The CSS colour names the image service understands, plus transparent.
+    CSS_COLORS = %w[
+      aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue
+      blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk
+      crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki
+      darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen
+      darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue
+      dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite
+      gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki
+      lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan
+      lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen
+      lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen
+      magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen
+      mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream
+      mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid
+      palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum
+      powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown
+      seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen
+      steelblue tan teal thistle tomato transparent turquoise violet wheat white whitesmoke yellow
+      yellowgreen
+    ].freeze
+
+    # type => [query name, option key, minimum, exclusive minimum]
+    AMOUNTS = {
+      "blur" => ["blur", :amount, 0, nil],
+      "saturate" => ["saturate", :amount, 0, nil],
+      "brightness" => ["brightness", :amount, nil, nil],
+      "contrast" => ["contrast", :amount, nil, nil],
+      "hue" => ["hue", :degrees, nil, nil],
+      "gamma" => ["gamma", :value, nil, 0],
+      "opacity" => ["opacity", :amount, 0, nil],
+      "dpr" => ["dpr", :ratio, nil, 0]
+    }.freeze
+    OPTIONAL_AMOUNTS = { "sharpen" => :amount, "sepia" => :amount }.freeze
+    FLAGS = %w[invert grayscale strip lossless].freeze
 
     module_function
 
     # @param transforms [Array<Hash>, Hash, String, nil]
     #   * an Array of hashes like `{ type: :resize, width: 300, fit: :cover }`, applied in order
     #   * a Hash of `name => value`, like `{ resize: "300x_", format: "webp", quality: 75 }`
+    #     (`true` adds a transform with no value, like `{ grayscale: true }`)
     #   * a String, passed through untouched
     # @return [String] the query value, or "" when there is nothing to apply
+    # Escapes a transform string for the +transform+ query value. Characters that mean something in
+    # a URL (+, &, #, %, spaces and anything outside ASCII) are percent-encoded, so "1.0e+21" is not
+    # read as "1.0e 21"; the transform syntax (: ; ~ , @ ( )) is left as it is, so ordinary URLs
+    # stay readable and unchanged.
+    def encode_query(transform)
+      transform.to_s.gsub(/[^A-Za-z0-9_.\-~:;,@()!*']/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
+    end
+
+    # Encodes the text of a text layer. Everything but letters, digits, -, _ and . is
+    # percent-encoded, so the transform syntax (; ~ : ( )) and % can appear in the text.
+    # encode_query then encodes the % again for the URL, which the image service expects.
+    def encode_text(text)
+      s = text.to_s
+      s = s.encoding == Encoding::BINARY ? s.dup.force_encoding(Encoding::UTF_8) : s.encode(Encoding::UTF_8)
+      raise InvalidArgumentError, "text is not valid Unicode" unless s.valid_encoding?
+
+      s.b.gsub(/[^A-Za-z0-9_.\-]/n) { |c| format("%%%02X", c.ord) }
+    rescue EncodingError
+      raise InvalidArgumentError, "text is not valid Unicode"
+    end
+
     def build(transforms)
       case transforms
       when nil then ""
@@ -27,7 +104,7 @@ module Fileboy
     end
 
     def shorthand(name, value)
-      return nil if value.nil? || value.to_s.empty?
+      return nil if value.nil? || value == false || value.to_s.empty?
       return name.to_s if value == true
 
       "#{name}:#{value}"
@@ -38,11 +115,18 @@ module Fileboy
       type = t[:type].to_s
       raise InvalidArgumentError, "Unknown transform #{type.inspect}. Use one of: #{TYPES.join(', ')}" unless TYPES.include?(type)
 
-      send("build_#{type}", t)
-    end
+      return type if FLAGS.include?(type)
+
+      if AMOUNTS.key?(type)
+        name, key, min, above = AMOUNTS[type]
+        return "#{name}:#{num(t[key], name, min: min, above: above)}"
+      end
+      if OPTIONAL_AMOUNTS.key?(type)
+        key = OPTIONAL_AMOUNTS[type]
+        return t[key].nil? ? type : "#{type}:#{num(t[key], type, min: 0)}"
+      end
 
-    def build_invert(_t)
-      "invert"
+      send("build_#{type.gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }}", t)
     end
 
     def build_format(t)
@@ -72,13 +156,270 @@ module Fileboy
       end
 
       out = "resize:#{width || '_'}x#{height || '_'}"
+      out += fit_options(t)
+      out += "~format:#{choice(t[:format], RESIZE_FORMATS, 'resize format')}" if t[:format]
+      unless t[:focus].nil?
+        focus = t[:focus].respond_to?(:to_h) ? symbolize(t[:focus]) : {}
+        raise InvalidArgumentError, "resize focus must be { x: ..., y: ... }" unless focus.key?(:x) && focus.key?(:y)
+
+        out += "~focus:#{length(focus[:x], 'focus x')},#{length(focus[:y], 'focus y')}"
+      end
+      upscale = t[:upscale]
+      unless upscale.nil? || upscale == true || upscale == false
+        raise InvalidArgumentError, "resize upscale must be true or false (got #{upscale.inspect})"
+      end
+
+      # Never make the image bigger than it is.
+      out += "~upscale:false" if upscale == false
+      out
+    end
+
+    def fit_options(t)
+      out = ""
       out += "~position:#{position(t[:position])}" if t[:position]
       out += "~fit:#{choice(t[:fit], FITS, 'fit')}" if t[:fit]
       out += "~background:#{color(t[:background])}" if t[:background]
-      out += "~format:#{format_name(t[:format])}" if t[:format]
       out
     end
 
+    def build_resize_a_r(t)
+      ratio = t[:ratio]
+      raise InvalidArgumentError, "resizeAR needs a ratio like [16, 9]" unless ratio.is_a?(Array) && ratio.size == 2
+
+      "resizeAR:#{num(ratio[0], 'resizeAR ratio', above: 0)}x#{num(ratio[1], 'resizeAR ratio', above: 0)}" + fit_options(t)
+    end
+
+    def build_crop(t)
+      raise InvalidArgumentError, "crop needs a width and a height" if t[:width].nil? || t[:height].nil?
+
+      out = "crop:#{length(t[:width], 'crop width')}x#{length(t[:height], 'crop height')}"
+      if !t[:left].nil? || !t[:top].nil?
+        # An omitted side is centred.
+        left = t[:left].nil? ? "50pc" : length(t[:left], "crop left")
+        top = t[:top].nil? ? "50pc" : length(t[:top], "crop top")
+        out += "@#{left},#{top}"
+      elsif t[:position]
+        out += "~position:#{position(t[:position])}"
+      end
+      out
+    end
+
+    def build_smart_crop(t)
+      "smartCrop:#{whole(t[:width], 'smartCrop width', 1)}x#{whole(t[:height], 'smartCrop height', 1)}"
+    end
+
+    def build_rotate(t)
+      out = "rotate:#{num(t[:angle], 'rotate angle')}"
+      out += "~background:#{color(t[:background])}" if t[:background]
+      out
+    end
+
+    def build_flip(t)
+      "flip:#{choice(t[:direction], FLIPS, 'flip direction')}"
+    end
+
+    def build_tint(t)
+      "tint:#{color(t[:color])}"
+    end
+
+    def build_pixelate(t)
+      "pixelate:#{whole(t[:size], 'pixelate size', 1)}"
+    end
+
+    def build_radius(t)
+      r = t[:radius]
+      out = "radius:#{r.to_s == 'max' ? 'max' : whole(r, 'radius')}"
+      out += "~background:#{color(t[:background])}" if t[:background]
+      out
+    end
+
+    def build_pad(t)
+      values = Array(t[:padding])
+      values = [nil] if values.empty?
+      unless [1, 2, 4].include?(values.size)
+        raise InvalidArgumentError, "pad takes 1, 2 or 4 numbers: all, [vertical, horizontal] or [top, right, bottom, left]"
+      end
+
+      out = "pad:#{values.map { |v| whole(v, 'pad') }.join(',')}"
+      out += "~background:#{color(t[:background])}" if t[:background]
+      out
+    end
+
+    def build_border(t)
+      out = "border:#{whole(t[:width], 'border width')}"
+      out += "~color:#{color(t[:color])}" if t[:color]
+      out
+    end
+
+    def build_trim(t)
+      out = "trim"
+      out += ":#{num(t[:threshold], 'trim threshold', min: 0)}" unless t[:threshold].nil?
+      out += "~color:#{color(t[:color])}" if t[:color]
+      out
+    end
+
+    def build_overlay(t)
+      file = t[:file]
+      unless file.is_a?(String) && file.match?(FILE_ID)
+        raise InvalidArgumentError, "overlay file must be the id of an image file in the same app"
+      end
+
+      out = "overlay:#{file.downcase}"
+      out += "~width:#{positive_length(t[:width], 'overlay width')}" unless t[:width].nil?
+      out += "~height:#{positive_length(t[:height], 'overlay height')}" unless t[:height].nil?
+      out += placement(t)
+      unless t[:transforms].nil?
+        inner = t[:transforms]
+        raise InvalidArgumentError, "overlay transforms must be a list of transforms" unless inner.is_a?(Array) && !inner.empty?
+
+        parts = inner.map do |sub|
+          s = symbolize(sub)
+          type = s[:type].to_s
+          raise InvalidArgumentError, "#{type} cannot be used in an overlay's transforms; put it in the main list" if NOT_IN_OVERLAY.include?(type)
+          raise InvalidArgumentError, "an overlay's transforms cannot set a format" if type == "resize" && s[:format]
+
+          build_one(s)
+        end
+        out += "~transform:(#{parts.join(';')})"
+      end
+      out
+    end
+
+    def build_palette(t)
+      out = "palette"
+      output = t[:output].nil? ? "json" : choice(t[:output], PALETTE_OUTPUTS, "palette output")
+      out += ":#{output}" unless t[:output].nil?
+      unless t[:colors].nil?
+        unless t[:colors].is_a?(Integer) && t[:colors].between?(0, 16)
+          raise InvalidArgumentError, "palette colors must be a whole number from 0 to 16"
+        end
+
+        out += "~colors:#{t[:colors]}"
+      end
+      unless t[:prefix].nil?
+        raise InvalidArgumentError, "palette prefix only applies to output \"css\"" unless output == "css"
+        unless t[:prefix].to_s.match?(PALETTE_PREFIX)
+          raise InvalidArgumentError, "palette prefix must be a letter then up to 31 letters, digits, - or _"
+        end
+
+        out += "~prefix:#{t[:prefix]}"
+      end
+      out
+    end
+
+    def build_text(t)
+      text = t[:text]
+      raise InvalidArgumentError, "text needs something to write" unless text.is_a?(String) && !text.strip.empty?
+
+      out = "text:#{encode_text(text)}"
+      out += "~font:#{choice(t[:font], FONTS, 'font')}" if t[:font]
+      out += "~size:#{positive_length(t[:size], 'text size')}" unless t[:size].nil?
+      out += "~color:#{color(t[:color])}" if t[:color]
+      out += "~background:#{color(t[:background])}" if t[:background]
+      out += "~padding:#{whole(t[:padding], 'text padding')}" unless t[:padding].nil?
+      out += "~wrap:#{positive_length(t[:wrap], 'text wrap')}" unless t[:wrap].nil?
+      out += "~align:#{choice(t[:align], ALIGNS, 'align')}" if t[:align]
+      out + placement(t)
+    end
+
+    # Where and how an overlay or text layer is drawn.
+    def placement(t)
+      kind = t[:type]
+      out = ""
+      out += "~position:#{position(t[:position])}" if t[:position]
+      out += "~x:#{offset(t[:x], "#{kind} x")}" unless t[:x].nil?
+      out += "~y:#{offset(t[:y], "#{kind} y")}" unless t[:y].nil?
+      unless t[:opacity].nil?
+        value = num(t[:opacity], "#{kind} opacity", min: 0)
+        raise InvalidArgumentError, "#{kind} opacity must be from 0 to 100" if t[:opacity] > 100
+
+        out += "~opacity:#{value}"
+      end
+      out += "~rotate:#{num(t[:rotate], "#{kind} rotate")}" unless t[:rotate].nil?
+      tile = t[:tile]
+      raise InvalidArgumentError, "#{kind} tile must be true or false (got #{tile.inspect})" unless [nil, true, false].include?(tile)
+
+      out += "~tile:true" if tile
+      unless t[:gap].nil?
+        raise InvalidArgumentError, "#{kind} gap only works with tile: true" unless tile
+
+        out += "~gap:#{length(t[:gap], "#{kind} gap")}"
+      end
+      out
+    end
+
+    # Whole pixels, which may be negative, or a percentage from -100 to 100.
+    def offset(value, label)
+      pc = nil
+      if value.is_a?(Hash)
+        h = symbolize(value)
+        pc = h[:pc] if h.key?(:pc)
+      elsif value.is_a?(String) && value.match?(/(pc|%)\z/)
+        str = value.sub(/(pc|%)\z/, "")
+        raise InvalidArgumentError, "#{label} #{value.inspect} is not a percentage" unless str.match?(/\A-?\d+(\.\d+)?\z/)
+
+        pc = str.include?(".") ? str.to_f : str.to_i
+      end
+      unless pc.nil?
+        unless (pc.is_a?(Integer) || pc.is_a?(Float)) && pc.between?(-100, 100)
+          raise InvalidArgumentError, "#{label} percentage must be from -100 to 100"
+        end
+
+        return "#{num(pc, label)}pc"
+      end
+      raise InvalidArgumentError, "#{label} must be a whole number of pixels or a percentage (got #{value.inspect})" unless value.is_a?(Integer)
+
+      value.to_s
+    end
+
+    def positive_length(value, label)
+      s = length(value, label)
+      raise InvalidArgumentError, "#{label} must be more than 0" unless s.to_f.positive?
+
+      s
+    end
+
+    # A number as the image service writes it: whole numbers without a decimal point.
+    def num(value, label, min: nil, above: nil)
+      unless (value.is_a?(Integer) || value.is_a?(Float)) && value.finite?
+        raise InvalidArgumentError, "#{label} must be a number (got #{value.inspect})"
+      end
+      raise InvalidArgumentError, "#{label} must be at least #{min}" if min && value < min
+      raise InvalidArgumentError, "#{label} must be more than #{above}" if above && value <= above
+
+      value.is_a?(Float) && value == value.floor ? value.to_i.to_s : value.to_s
+    end
+
+    def whole(value, label, min = 0)
+      unless value.is_a?(Integer) && value >= min
+        raise InvalidArgumentError, "#{label} must be a whole number of at least #{min} (got #{value.inspect})"
+      end
+
+      value.to_s
+    end
+
+    # Pixels as a whole number, or a percentage as `{ pc: 50 }` or "50pc" / "50%".
+    def length(value, label)
+      pc = nil
+      if value.is_a?(Hash)
+        h = symbolize(value)
+        pc = h[:pc] if h.key?(:pc)
+      elsif value.is_a?(String) && value.match?(/(pc|%)\z/)
+        str = value.sub(/(pc|%)\z/, "")
+        raise InvalidArgumentError, "#{label} #{value.inspect} is not a percentage" unless str.match?(/\A\d+(\.\d+)?\z/)
+
+        pc = str.include?(".") ? str.to_f : str.to_i
+      end
+      unless pc.nil?
+        unless (pc.is_a?(Integer) || pc.is_a?(Float)) && pc.between?(0, 100)
+          raise InvalidArgumentError, "#{label} percentage must be from 0 to 100"
+        end
+
+        return "#{num(pc, label)}pc"
+      end
+      whole(value, label)
+    end
+
     # "right top", "top right" and "top-right" all mean the same corner, which the image service
     # spells top-right (vertical word first).
     def position(value)
@@ -98,15 +439,21 @@ module Fileboy
       v
     end
 
-    # "#fff", "#ffffff" and "#ffffff80" become hex(...). Anything already in hex(...) form is kept.
+    # "#fff", "#ffffff" and "#ffffff80" become hex(...); hex(...) is kept; rgb(...), rgba(...) and
+    # CSS colour names like "white" are passed on.
     def color(value)
-      s = value.to_s
-      return s if s.match?(/\Ahex\(([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\)\z/i)
+      s = value.to_s.strip
+      return s if s.match?(HEX_CALL)
 
       hex = s.delete_prefix("#")
-      raise InvalidArgumentError, "Colours must be hex, like #ff8800 (got #{value.inspect})" unless hex.match?(/\A([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\z/i)
+      return "hex(#{hex})" if hex.match?(HEX)
+
+      compact = s.gsub(/\s+/, "").downcase
+      rgb = compact.match(RGB) || compact.match(RGBA)
+      return compact if rgb && rgb.captures.first(3).all? { |c| c.to_i <= 255 }
+      return s.downcase if CSS_COLORS.include?(s.downcase)
 
-      "hex(#{hex})"
+      raise InvalidArgumentError, "Colours must be hex like #ff8800, rgb(...), rgba(...) or a CSS colour name (got #{value.inspect})"
     end
 
     def symbolize(hash)

data/lib/fileboy/version.rb

@@ -1,3 +1,3 @@
 module Fileboy
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/fileboy.rb

@@ -5,6 +5,7 @@ require "fileboy/file_data"
 require "fileboy/transforms"
 require "fileboy/token"
 require "fileboy/webhook"
+require "fileboy/signing"
 require "fileboy/client"
 
 # Official Ruby client for Fileboy (https://fileboy.io).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fileboy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - CD2 Solutions
@@ -68,6 +68,7 @@ files:
 - lib/fileboy/errors.rb
 - lib/fileboy/file_data.rb
 - lib/fileboy/mime.rb
+- lib/fileboy/signing.rb
 - lib/fileboy/token.rb
 - lib/fileboy/transforms.rb
 - lib/fileboy/version.rb