dynamic_image 3.0.9 → 3.1.0

data/lib/dynamic_image/breakpoints.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Breakpoints
+  #
+  # Computes the candidate widths for a +srcset+, given the widest the image can be rendered at.
+  #
+  # A range steps down geometrically from the available width, an array lists the widths outright, and a single
+  # number gives one candidate.
+  #
+  # @example
+  #   DynamicImage::Breakpoints.new(320..3200).widths(2000)
+  #   # => [370, 520, 720, 1020, 1420, 2000]
+  #
+  #   DynamicImage::Breakpoints.new([400, 800, 1600]).widths(1000)
+  #   # => [400, 800]
+  #
+  # @see DynamicImage::Picture
+  class Breakpoints
+    # Candidate widths are snapped down to a multiple of this, so that images of similar size share widths.
+    SNAP = 10
+
+    # @!attribute [r] spec
+    #   @return [Range, Array<Integer>, Integer]
+    # @!attribute [r] step
+    #   @return [Float] the ratio between two candidates
+    attr_reader :spec, :step
+
+    # @param spec [Range, Array<Integer>, Integer, nil] the breakpoint spec. Defaults to
+    #   {DynamicImage.default_breakpoints}.
+    # @param step [Numeric, nil] the ratio between two candidates in a range. Defaults to
+    #   {DynamicImage.breakpoint_step}.
+    # @raise [ArgumentError] if the step or range would never terminate
+    def initialize(spec = nil, step: nil)
+      @spec = spec.nil? ? DynamicImage.default_breakpoints : spec
+      @step = (step || DynamicImage.breakpoint_step).to_f
+      validate!
+    end
+
+    # Returns the candidate widths, smallest first.
+    #
+    # The largest candidate is always the available width, whether or not it falls inside the range. An image narrower
+    # than the range gets a single candidate.
+    #
+    # @param available [Integer] the widest the image can be rendered at, as returned by
+    #   {DynamicImage::ImageSizing#available_width}
+    # @return [Array<Integer>]
+    # @raise [ArgumentError] if the spec isn't understood
+    def widths(available)
+      available = available.to_i
+      return [] unless available.positive?
+
+      case spec
+      when Range then stepped(available)
+      when Array then fixed(available)
+      when Integer then [spec]
+      else unknown_spec!
+      end
+    end
+
+    private
+
+    def fixed(available)
+      widths = spec.map(&:to_i).select { _1 <= available }.uniq.sort
+      widths.any? ? widths : [available]
+    end
+
+    def stepped(available)
+      top = [available, spec.end || available].min.to_f
+      rest = Enumerator.produce(top / step) { _1 / step }
+                       .take_while { _1 >= spec.begin }
+
+      [top, *rest].map { snap(_1) }.reverse.uniq
+    end
+
+    def snap(width)
+      [(width / SNAP).floor * SNAP, 1].max
+    end
+
+    def unknown_spec!
+      raise ArgumentError,
+            "breakpoints must be a Range, Array or Integer, " \
+            "got #{spec.class}"
+    end
+
+    def validate!
+      raise ArgumentError, "step must be greater than 1" unless step > 1
+      return unless spec.is_a?(Range) && spec.begin.nil?
+
+      raise ArgumentError, "breakpoints range must have a beginning"
+    end
+  end
+end

data/lib/dynamic_image/controller.rb

@@ -3,14 +3,37 @@
 module DynamicImage
   # = DynamicImage Controller
   #
-  # Generating images is rather expensive, so all requests must be
-  # signed with a HMAC digest in order to avoid denial of service attacks.
-  # The methods in +DynamicImage::Helper+ handles this transparently.
-  # As a bonus, this also prevents unauthorized URL enumeration.
+  # Serves images. Include it in a controller and define a +model+ method returning the class to serve, then declare
+  # the routes with {DynamicImage::Routing#image_resources}.
+  #
+  #   class ImagesController < ApplicationController
+  #     include DynamicImage::Controller
+  #
+  #     private
+  #
+  #     def model
+  #       Image
+  #     end
+  #   end
+  #
+  # Generating images is expensive, so every request must be signed with an HMAC digest. This protects against
+  # denial of service attacks and URL enumeration. The helpers in {DynamicImage::Helper} sign the URLs they build.
+  #
+  # Responses are cached for a year and answer +If-Modified-Since+. The URL carries a timestamp, so a changed image
+  # is a changed URL.
+  #
+  # @see DynamicImage::Helper
+  # @see DynamicImage::Routing
   module Controller
     extend ActiveSupport::Concern
     include Dis::Controller
 
+    # Formats +show+ and +uncropped+ will render.
+    PROCESSED_FORMATS = %i[gif jpeg jpg jxl png tiff webp].freeze
+
+    # Additional formats +original+ and +download+ will serve.
+    STORED_FORMATS = (PROCESSED_FORMATS + %i[avif bmp heic]).freeze
+
     included do
       before_action :verify_signed_params
       before_action :find_record
@@ -18,32 +41,50 @@ module DynamicImage
       helper_method :requested_size
     end
 
-    # Renders the image.
+    # Renders the image, cropped and resized to the requested size.
+    #
+    # Responds to the image formats, and to HTML with a page showing the image and its metadata.
+    #
+    # @return [void]
     def show
       render_image(format: requested_format)
     end
 
     # Same as +show+, but renders the image without any pre-cropping applied.
+    #
+    # @return [void]
     def uncropped
       render_image(format: requested_format, uncropped: true)
     end
 
     # Renders the original image data, without any processing.
+    #
+    # @return [void]
     def original
       render_raw_image
     end
 
+    # Same as +original+, but served as an attachment so the browser downloads the file rather than displaying it.
+    #
+    # @return [void]
     def download
       render_raw_image(disposition: "attachment")
     end
 
     # Returns the requested size as a vector.
+    #
+    # @return [Vector2d] the size from the URL
     def requested_size
       Vector2d.parse(params[:size])
     end
 
     private
 
+    # Override in your controller to return the class being served. Required.
+    #
+    # @!method model
+    #   @return [Class] the model class
+
     def cache_expiration_header
       return unless response.status == 200
 
@@ -51,10 +92,13 @@ module DynamicImage
       expires_in 1.year, public: true
     end
 
+    # Finds the record being served. Override to scope the lookup.
     def find_record
       @record = model.find(params[:id])
     end
 
+    # The filename the image is served as, the record's own filename with the extension of the rendered format.
+    # Override to name downloads something else.
     def filename(format = nil)
       if format.is_a?(DynamicImage::Format)
         File.basename(@record.filename, ".*") + format.extension
@@ -85,7 +129,7 @@ module DynamicImage
           render(template: "dynamic_image/images/show",
                  layout: false, locals: { options: })
         end
-        format.any(:gif, :jpeg, :jpg, :png, :tiff, :webp) do
+        format.any(*PROCESSED_FORMATS) do
           process_and_send(@record, options)
         end
       end
@@ -95,7 +139,7 @@ module DynamicImage
       return unless stale?(@record)
 
       respond_to do |format|
-        format.any(:gif, :jpeg, :jpg, :png, :tiff, :webp) do
+        format.any(*STORED_FORMATS) do
           send_dis_data(@record,
                         filename:,
                         content_type: @record.content_type,

data/lib/dynamic_image/digest_verifier.rb

@@ -3,33 +3,44 @@
 module DynamicImage
   # = DynamicImage Digest Verifier
   #
-  # ==== Usage
+  # Signs and verifies the digests embedded in image URLs. The engine sets up the instance the application uses and
+  # exposes it as <tt>DynamicImage.digest_verifier</tt>. The helpers sign with it and the controller verifies with
+  # it, so there is rarely a reason to use this directly.
   #
-  #   verifier = DynamicImage::DigestVerifier.new("super secret!")
+  # Adapted from +ActiveSupport::MessageVerifier+, without the handling for arbitrary data structures and without
+  # shipping the serialized data to the client.
   #
+  # @example
+  #   verifier = DynamicImage::DigestVerifier.new("super secret!")
   #   digest = verifier.generate("foo")
   #
-  #   digest.verify("foo", digest)
+  #   verifier.verify("foo", digest)
   #   # => true
-  #   digest.verify("bar", digest)
+  #   verifier.verify("bar", digest)
   #   # => raises DynamicImage::Errors::InvalidSignature
-  #
-  # Credit where credit is due: adapted and simplified from
-  # +ActiveSupport::MessageVerifier+, since we don't need to handle
-  # arbitrary data structures and ship the serialized data to the client.
   class DigestVerifier
+    # @param secret [String] the secret to sign with
+    # @param options [Hash]
+    # @option options [String] :digest the OpenSSL digest to use, defaults to "SHA1"
     def initialize(secret, options = {})
       @secret = secret
       @digest = options[:digest] || "SHA1"
     end
 
     # Generates a digest for a string.
+    #
+    # @param data [String] the string to sign
+    # @return [String] the hex digest
     def generate(data)
       generate_digest(data)
     end
 
     # Verifies that <tt>digest</tt> is valid for <tt>data</tt>.
-    # Raises a +DynamicImage::Errors::InvalidSignature+ error if not.
+    #
+    # @param data [String] the signed string
+    # @param digest [String] the digest to check against
+    # @return [true] if the digest is valid
+    # @raise [DynamicImage::Errors::InvalidSignature] if it isn't
     def verify(data, digest)
       return true if valid_digest?(data, digest)
 

data/lib/dynamic_image/engine.rb

@@ -18,10 +18,13 @@ module DynamicImage
     end
 
     initializer "dynamic_image.mime_types" do
+      Mime::Type.register "image/avif", :avif
       Mime::Type.register "image/bmp", :bmp
       Mime::Type.register "image/gif", :gif
+      Mime::Type.register "image/heic", :heic, %w[image/heif]
       Mime::Type.register "image/jpeg", :jpg
       Mime::Type.register "image/jpeg", :jpeg
+      Mime::Type.register "image/jxl", :jxl
       Mime::Type.register "image/png", :png
       Mime::Type.register "image/tiff", :tiff
       Mime::Type.register "image/webp", :webp

data/lib/dynamic_image/errors.rb

@@ -1,19 +1,49 @@
 # frozen_string_literal: true
 
 module DynamicImage
+  # = DynamicImage Errors
+  #
+  # All errors raised by DynamicImage inherit from {DynamicImage::Errors::Error}, so a single rescue covers them all.
   module Errors
+    # Base class for all DynamicImage errors.
     class Error < StandardError; end
 
+    # Raised when processing is attempted on a record that isn't a valid image, either because the data is unreadable
+    # or because the record fails validation.
+    #
+    # @see DynamicImage::ProcessedImage#normalized
     class InvalidImage < DynamicImage::Errors::Error; end
 
+    # Raised when reading data that isn't in a format DynamicImage recognizes. The format is read from the header,
+    # not from any declared content type.
+    #
+    # @see DynamicImage::ImageReader#read
     class InvalidHeader < DynamicImage::Errors::Error; end
 
+    # Raised when the digest in a request doesn't match the parameters. Rescued as <tt>:unauthorized</tt>, so
+    # Rails renders it as 401.
+    #
+    # Expired and hand-edited URLs both produce this.
+    #
+    # @see DynamicImage::DigestVerifier#verify
     class InvalidSignature < DynamicImage::Errors::Error; end
 
+    # Raised when cropping is requested without both dimensions, as in <tt>size: "400x", crop: true</tt>. There is no
+    # way to crop to an exact size when one of them is unknown.
+    #
+    # @see DynamicImage::ImageSizing#fit
     class InvalidSizeOptions < DynamicImage::Errors::Error; end
 
+    # Raised when a transformation can't be applied, either because a rotation isn't a multiple of 90 degrees or
+    # because a crop falls outside the image.
+    #
+    # @see DynamicImage::ImageProcessor::Transform
     class InvalidTransformation < DynamicImage::Errors::Error; end
 
+    # Raised when a request is missing a parameter needed to verify the signature. Like {InvalidSignature}, this is
+    # what a malformed URL produces.
+    #
+    # @see DynamicImage::Controller
     class ParameterMissing < DynamicImage::Errors::Error; end
   end
 end

data/lib/dynamic_image/format.rb

@@ -1,71 +1,170 @@
 # frozen_string_literal: true
 
 module DynamicImage
+  # = DynamicImage Format
+  #
+  # A registry of the image formats DynamicImage understands. Each format knows its content types, extensions, the
+  # magic bytes that identify it, the options it is saved with, and whether it can hold more than one frame.
+  #
+  # Formats are looked up by name, by content type, or by sniffing the first bytes of a file. Uploads are always
+  # identified by sniffing, never by the content type the client claims.
+  #
+  # @example
+  #   DynamicImage::Format.find("jpg")           # => the JPEG format
+  #   DynamicImage::Format.content_type("image/png")
+  #   DynamicImage::Format.sniff(File.binread(path, 32))
   class Format
-    attr_reader :name, :animated, :content_types, :extensions, :magic_bytes,
-                :save_options, :signature
+    # @!attribute [r] name
+    #   @return [String] the format name, such as "JPEG"
+    # @!attribute [r] animated
+    #   @return [Boolean] whether the format holds more than one frame
+    # @!attribute [r] alpha
+    #   @return [Boolean] whether the format holds an alpha channel
+    # @!attribute [r] content_types
+    #   @return [Array<String>] the content types, canonical one first
+    # @!attribute [r] extensions
+    #   @return [Array<String>] the file extensions, preferred one first
+    # @!attribute [r] magic_bytes
+    #   @return [Array<String>] byte sequences identifying the format
+    # @!attribute [r] offset
+    #   @return [Integer] where in the header the magic bytes sit
+    # @!attribute [r] save_options
+    #   @return [Hash] options passed to vips when writing
+    # @!attribute [r] signature
+    #   @return [Proc, nil] an extra check against the header, for when
+    #     the magic bytes alone are ambiguous
+    attr_reader :name, :animated, :alpha, :content_types, :extensions,
+                :magic_bytes, :offset, :save_options, :signature
 
+    # @param name [String] the format name
+    # @param options [Hash] the format definition, as passed to {Format.register}
+    # @see Format.register
     def initialize(name, options)
       options = default_options.merge(options)
 
       @name = name
       @animated = options[:animated]
+      @alpha = options[:alpha]
       @content_types = Array(options[:content_type])
       @extensions = Array(options[:extension])
-      @magic_bytes = options[:magic_bytes].map do |s|
-        s.dup.force_encoding("binary")
-      end
+      @magic_bytes = options[:magic_bytes].map(&:b)
+      @offset = options[:offset]
       @signature = options[:signature]
       @save_options = options[:save_options]
     end
 
+    # Returns true if the format supports multiple frames.
+    #
+    # @return [Boolean]
     def animated?
       animated
     end
 
+    # Returns true if the format supports an alpha channel.
+    #
+    # @return [Boolean]
+    def alpha?
+      alpha
+    end
+
+    # Returns true if the given header belongs to this format.
+    #
+    # @param bytes [String] the first bytes of the file
+    # @return [Boolean]
     def matches?(bytes)
-      return false unless magic_bytes.any? { |b| bytes.start_with?(b) }
+      header = bytes.to_s[offset..].to_s
+      return false unless magic_bytes.any? { |b| header.start_with?(b) }
 
       signature.nil? || signature.call(bytes)
     end
 
+    # The canonical content type.
+    #
+    # @return [String]
     def content_type
       content_types.first
     end
 
+    # The preferred file extension, leading dot included.
+    #
+    # @return [String]
     def extension
       extensions.first
     end
 
+    # The canonical content type as a Mime::Type.
+    #
+    # @return [Mime::Type]
+    def mime_type
+      Mime::Type.lookup(content_type)
+    end
+
     class << self
+      # Finds the format for a content type.
+      #
+      # @param type [String] the content type
+      # @return [DynamicImage::Format, nil]
       def content_type(type)
         formats.filter { |f| f.content_types.include?(type) }.first
       end
 
+      # Every content type of every registered format.
+      #
+      # @return [Array<String>]
       def content_types
         formats.flat_map(&:content_types)
       end
 
+      # Finds a format by name. Case insensitive, and "JPG" is understood as an alias for "JPEG".
+      #
+      # @param name [String, Symbol] the format name
+      # @return [DynamicImage::Format, nil]
       def find(name)
         key = name.to_s.upcase
         key = "JPEG" if key == "JPG"
         registered_formats[key]
       end
 
+      # All registered formats.
+      #
+      # @return [Array<DynamicImage::Format>]
       def formats
         registered_formats.map { |_, f| f }
       end
 
+      # Registers a format.
+      #
+      # Each option sets the attribute of the same name, except +content_type+ and +extension+, which are singular
+      # here and accept either one value or a list. Anything left out falls back to {Format#default_options}.
+      #
+      # @param name [String] the format name, uppercase by convention
+      # @param opts [Hash] the format definition
+      # @return [DynamicImage::Format] the registered format
       def register(name, **opts)
         registered_formats[name] = new(name, opts)
       end
 
+      # Identifies a format from the first bytes of a file.
+      #
+      # @param bytes [String, nil] the file header
+      # @return [DynamicImage::Format, nil] the format, if recognized
       def sniff(bytes)
         return unless bytes
 
         formats.find { |format| format.matches?(bytes) }
       end
 
+      # The brands declared by an ISO base media file, major brand first, followed by the compatible brands. Empty for
+      # anything that isn't an +ftyp+ box.
+      #
+      # @param bytes [String] the file header
+      # @return [Array<String>]
+      def iso_brands(bytes)
+        return [] unless bytes.to_s.bytesize >= 12 && bytes[4, 4] == "ftyp".b
+
+        [bytes[8, 4]] + bytes[16...bytes.unpack1("N")].to_s.scan(/.{4}/m)
+      end
+
       private
 
       def registered_formats
@@ -73,11 +172,25 @@ module DynamicImage
       end
     end
 
+    # Defaults every format definition is merged over.
+    #
+    # @return [Hash]
     def default_options
-      { animated: false, content_type: [], extension: [], magic_bytes: [],
-        signature: nil, save_options: {} }
+      { animated: false, alpha: false, content_type: [], extension: [],
+        magic_bytes: [], offset: 0, signature: nil, save_options: {} }
     end
 
+    register(
+      "AVIF",
+      animated: true,
+      alpha: true,
+      content_type: %w[image/avif],
+      extension: %w[.avif],
+      offset: 4,
+      magic_bytes: %w[ftyp],
+      signature: ->(bytes) { iso_brands(bytes).intersect?(%w[avif avis]) }
+    )
+
     register(
       "BMP",
       content_type: %w[image/bmp],
@@ -88,11 +201,27 @@ module DynamicImage
     register(
       "GIF",
       animated: true,
+      alpha: true,
       content_type: %w[image/gif],
       extension: %w[.gif],
       magic_bytes: %w[GIF87a GIF89a]
     )
 
+    register(
+      "HEIC",
+      animated: true,
+      alpha: true,
+      content_type: %w[image/heic image/heif],
+      extension: %w[.heic .heif],
+      offset: 4,
+      magic_bytes: %w[ftyp],
+      signature: lambda { |bytes|
+        iso_brands(bytes).intersect?(
+          %w[heic heix hevc hevx heim heis hevm hevs mif1 msf1]
+        )
+      }
+    )
+
     register(
       "JPEG",
       content_type: %w[image/jpeg image/pjpeg],
@@ -101,8 +230,18 @@ module DynamicImage
       save_options: { Q: 90, strip: true, background: [255.0, 255.0, 255.0] }
     )
 
+    register(
+      "JXL",
+      alpha: true,
+      content_type: %w[image/jxl],
+      extension: %w[.jxl],
+      magic_bytes: ["\xff\x0a", "\x00\x00\x00\x0cJXL \r\n\x87\n"],
+      save_options: { Q: 75, effort: 3, strip: true }
+    )
+
     register(
       "PNG",
+      alpha: true,
       content_type: %w[image/png],
       extension: %w[.png],
       magic_bytes: ["\x89\x50\x4e\x47\x0d\x0a\x1a\x0a"]
@@ -110,6 +249,7 @@ module DynamicImage
 
     register(
       "TIFF",
+      alpha: true,
       content_type: %w[image/tiff],
       extension: %w[.tiff .tif],
       magic_bytes: ["\x49\x49\x2a\x00", "\x4d\x4d\x00\x2a"]
@@ -118,6 +258,7 @@ module DynamicImage
     register(
       "WEBP",
       animated: true,
+      alpha: true,
       content_type: %w[image/webp],
       extension: %w[.webp],
       magic_bytes: ["\x52\x49\x46\x46"],

data/lib/dynamic_image/format_negotiator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Format Negotiator
+  #
+  # Picks the format to render an image in, given the formats the consumer accepts.
+  #
+  # An acceptable source format is used as-is. Otherwise the image is transcoded to the candidate that keeps the
+  # most of it: animation is preserved before transparency, and a constraint no candidate can satisfy is dropped
+  # instead of vetoing the next one.
+  #
+  # Selection is keyed on the properties the image has, not on what its format is capable of. A photograph uploaded
+  # as WebP renders as JPEG, not as a 256 colour GIF.
+  #
+  # Images stored before +frame_count+ and +alpha+ existed have neither, and an unacceptable source format resolves
+  # to JPEG.
+  #
+  # @example
+  #   DynamicImage::FormatNegotiator.new(image).negotiate(%i[jpeg png gif])
+  #   # => the PNG format
+  #
+  # @see DynamicImage::Format
+  class FormatNegotiator
+    FALLBACK = "JPEG"
+
+    # @!attribute [r] record
+    #   @return [DynamicImage::Model]
+    attr_reader :record
+
+    # @param record [DynamicImage::Model] the image
+    def initialize(record)
+      @record = record
+    end
+
+    # Returns the format to render in.
+    #
+    # @param accepted [Array<Symbol, String>] the acceptable format names, most preferred first. Unrecognized names
+    #   are ignored.
+    # @return [DynamicImage::Format]
+    def negotiate(accepted)
+      candidates = Array(accepted).filter_map { |name| Format.find(name) }
+      source(candidates) || transcode(candidates) || Format.find(FALLBACK)
+    end
+
+    private
+
+    def source(candidates)
+      candidates.find { |f| f.content_types.include?(record.content_type) }
+    end
+
+    def transcode(candidates)
+      return unless known?
+
+      candidates = narrow(candidates, :animated?) if animated?
+      candidates = narrow(candidates, :alpha?) if alpha?
+      candidates.first
+    end
+
+    def narrow(candidates, capability)
+      supported = candidates.select(&capability)
+      supported.any? ? supported : candidates
+    end
+
+    def frame_count
+      record.frame_count if record.has_attribute?(:frame_count)
+    end
+
+    def alpha
+      record.alpha if record.has_attribute?(:alpha)
+    end
+
+    def known?
+      !frame_count.nil? && !alpha.nil?
+    end
+
+    def animated?
+      frame_count.to_i > 1
+    end
+
+    def alpha?
+      alpha ? true : false
+    end
+  end
+end