dynamic_image 3.0.9 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33ad9b707b455fded33a4b6860ce21d85e53ee88041ccb5f078beba0c850148b
-  data.tar.gz: 79d19fbda9f9a90fa26dc421cf13fab00cb7d90251076bb27e6b316fddc4529a
+  metadata.gz: f7d6b0fd60017fe14ffc6a01f99519802232b8bba0f94b756c9026cdf57c6897
+  data.tar.gz: 2c0c56a8b4505684e883fd5b74985b69ac9e6f190a41477087fa4f62827eedb8
 SHA512:
-  metadata.gz: 9eacc78569bb34efb9ae84381b1c96966e834cd9a9ff82968dcdf9aa690286a1192e3f13db1c899f4e31f93c15f293d673d9bf1fdf13e48a828e8ad0c8a27acf
-  data.tar.gz: 1d47d899162e89321605adb632193c0a0cdace30b48b3feae2c61967e68b2fee92a66a009b7baf7c1e078b3a9ab09afc8529fc58f16105510cce80cdddf657cf
+  metadata.gz: 75c4599b900f98fa6c51adc140650b400ba19f7749e89e06d06b8ce580e61db32a3b7e3890cc35023c80b7b77da89400c1a74fa41e926e5ea0bd7cc516148ef6
+  data.tar.gz: 7a8573f7eb274a4f24842490ef296f50f750ba187f5a49b896b42fa0d4722fa255ed811151517c5d024094512e08c716855a4780050b22c04ef26ebbf6546174

data/README.md

@@ -1,38 +1,26 @@
 [![Version](https://img.shields.io/gem/v/dynamic_image.svg?style=flat)](https://rubygems.org/gems/dynamic_image)
-![Build](https://github.com/elektronaut/dynamic_image/workflows/Build/badge.svg)
+[![Build](https://github.com/elektronaut/dynamic_image/actions/workflows/build.yml/badge.svg)](https://github.com/elektronaut/dynamic_image/actions/workflows/build.yml)
 
 # DynamicImage
 
-Need to handle image uploads in your Rails app?
-Give DynamicImage a try.
+A Rails engine for image uploads.
 
 Rather than creating a pre-defined set of images when a file is
 uploaded, DynamicImage stores the original file and generates images
 on demand. It handles cropping, resizing, format and colorspace
 conversion.
 
-Supported formats at the moment are JPEG, PNG, GIF, BMP, WebP and TIFF.
-BMP, WebP and TIFF images will automatically be converted to JPG. CMYK
-images will be converted to RGB, and RGB images will be converted to the sRGB
-colorspace for consistent appearance in all browsers.
-
 DynamicImage is built on [Dis](https://github.com/elektronaut/dis)
 and [ruby-vips](https://github.com/libvips/ruby-vips).
 
-All URLs are signed with a HMAC to protect against denial of service
-and enumeration attacks.
-
-## Requirements
-
-* Rails 5+
-* Ruby 2.7+
-* libvips 8.8+
-
-## Documentation
+## Installation
 
-[Documentation is available on RubyDoc.info](http://rdoc.info/gems/dynamic_image)
+DynamicImage requires [libvips](https://www.libvips.org), which is
+available from most package managers.
 
-## Installation
+```sh
+brew install vips
+```
 
 Add the gem to your Gemfile and run `bundle install`.
 
@@ -40,102 +28,440 @@ Add the gem to your Gemfile and run `bundle install`.
 gem "dynamic_image", "~> 3.0"
 ```
 
-Run the `dis:install` generator to set up your storage.
+Run the `dis:install` generator to set up your storage. Files are stored
+in `db/dis` by default; edit the generated initializer to change that.
+See the [Dis](https://github.com/elektronaut/dis) documentation for the
+options.
 
 ```sh
 bin/rails generate dis:install
 ```
 
-You can edit the generated initializer to configure your storage, by default it
-will store files in `db/dis`. See the
-[Dis](https://github.com/elektronaut/dis) documentation for more
-information.
+## Getting started
 
-## Creating your resource
+### Creating your resource
 
-Run the `dynamic_image:resource` generator to create your resource.
+The `dynamic_image:resource` generator creates an `Image` model and a
+controller, along with a migration and the necessary routes. The
+migration creates the table for your resource, plus the table
+DynamicImage uses to cache processed images.
 
 ```sh
 bin/rails generate dynamic_image:resource image
+bin/rails db:migrate
 ```
 
-This will create an `Image` model and a controller, along with a migration and
-the necessary routes.
-
-Note that in this case, the route with collide with any static images stored
-in `public/images`. You can customize the path if you want in the route
-declaration.
+The generated route collides with any static images stored in
+`public/images`. Customize the path in the route declaration if that's a
+problem.
 
 ```ruby
 image_resources :images, path: "dynamic_images/:digest(/:size)"
 ```
 
-## Storing an image
+<details>
+<summary>Setting the model up by hand</summary>
+
+Include `DynamicImage::Model` and provide these columns. The first four
+are required by Dis, the rest hold the image metadata and crop.
+
+```ruby
+create_table :images do |t|
+  t.string  :content_hash, null: false
+  t.string  :content_type, null: false
+  t.integer :content_length, null: false
+  t.string  :filename, null: false
+  t.string  :colorspace, null: false
+  t.integer :real_width, null: false
+  t.integer :real_height, null: false
+  t.integer :frame_count
+  t.boolean :alpha
+  t.integer :crop_width, :crop_height
+  t.integer :crop_start_x, :crop_start_y
+  t.integer :crop_gravity_x, :crop_gravity_y
+  t.timestamps
+end
+
+add_index :images, :content_hash
+```
+
+The controller needs `DynamicImage::Controller` and a `model` method
+telling it which class to serve.
+
+```ruby
+class ImagesController < ApplicationController
+  include DynamicImage::Controller
+
+  private
+
+  def model
+    Image
+  end
+end
+```
+
+</details>
+
+### Storing an image
 
-To save an image, simply assign the file attribute to your uploaded file.
+To save an image, assign the uploaded file to the `file` attribute.
 
 ```ruby
-image_params = params.require(:image).permit(:file)
-Image.create(image_params)
+Image.create(params.expect(image: [:file]))
 ```
 
-## Rendering images in your views
+The image is parsed and validated when the record is saved. Dimensions,
+colorspace and content type are read from the file itself, so anything
+the client claims about the upload is ignored. If the file isn't a
+readable image in a supported format, the record is invalid and an error
+is added to `data`.
 
-You should use the provided helpers for displaying images, this will ensure
-that the generated URLs are properly signed and timestamped.
+### Associating images with other models
 
-To display the image at it's original size, use `dynamic_image_tag` without
-any options.
+`belongs_to_image` works like `belongs_to` and takes the same options.
+In addition to a record, it accepts an uploaded file directly and
+creates the image record for you, so a file can be posted straight to
+the parent model.
+
+```ruby
+class User < ActiveRecord::Base
+  belongs_to_image :avatar, class_name: "Image"
+  validates_associated :avatar
+end
+```
 
 ```erb
-<%= dynamic_image_tag(image) %>
+<%= form_with(model: user) do |f| %>
+  <%= f.file_field :avatar %>
+<% end %>
 ```
 
-To resize it, specify a max size. This will scale the image down to fit, but
-no cropping will occur.
+```ruby
+User.create(params.expect(user: [:name, :avatar]))
+```
+
+`validates_associated` is optional, but without it an invalid upload is
+silently dropped when the parent is saved. Like `belongs_to`, the
+association is required by default; pass `optional: true` if the image
+is allowed to be missing.
+
+## Image URLs
+
+`dynamic_image_path` and `dynamic_image_url` act pretty much like
+regular URL helpers, and take the sizing options below.
 
 ```erb
-<%= dynamic_image_tag(image, size: "400x400") %>
+<%= link_to "See image", dynamic_image_path(image, size: "400x400") %>
 ```
 
-Setting `crop: true` will crop the image to the exact size.
+Every URL is signed and timestamped, so they can only be built
+server-side. See [signed URLs](#signed-urls) for why.
+
+### Sizing options
+
+Every helper that renders or links to a processed image takes the same
+sizing options.
+
+* `:size` - Desired image size, as `"{width}x{height}"`. The image is
+  scaled to fit within the size, preserving the aspect ratio. Omit
+  either dimension (`"400x"` or `"x400"`) for a fixed width or height.
+* `:crop` - Crop the image to the exact size instead of fitting it.
+  Both dimensions are required.
+* `:upscale` - By default, images are never scaled up, only down. Pass
+  `upscale: true` to allow the image to be scaled beyond its own size.
+* `:format` - Render the image in a different format. See
+  [Formats](#formats).
+
+### Other versions of the image
+
+Three variations are available. `uncropped` has `_tag`, `_path` and
+`_url` helpers; `original` and `download` have `_path` and `_url`.
+`uncropped` takes the sizing options; `original` and `download` serve
+the stored file untouched and ignore them.
+
+* `original_dynamic_image_path` links to the file exactly as it was
+  uploaded, with no processing at all.
+* `download_dynamic_image_path` serves the original as an attachment,
+  prompting a download.
+* `uncropped_dynamic_image_tag` renders the image with any pre-cropping
+  ignored.
+
+```erb
+<%= link_to "Download", download_dynamic_image_path(image) %>
+```
+
+## Displaying images
+
+`dynamic_image_tag` renders an `img`, taking the sizing options above
+plus any HTML attributes.
 
 ```erb
+<%= dynamic_image_tag(image) %>
+<%= dynamic_image_tag(image, size: "400x400") %>
 <%= dynamic_image_tag(image, size: "400x400", crop: true) %>
 ```
 
-Omitting either dimension will render the image at an exact width or height.
+### Alt text
+
+The `alt` attribute is resolved from `DynamicImage::Model#alt_text`. The
+column isn't added by default, either create it yourself, or override the
+method. Alternatively, pass the `alt` option to the helper.
 
 ```erb
-<%= dynamic_image_tag(image, size: "400x") %>
+<%= dynamic_image_tag(image, alt: "A description") %>
+<%= dynamic_image_tag(image, alt: "") %>
 ```
 
-`dynamic_image_path` and `dynamic_image_url` act pretty much like regular URL
-helpers.
+### Responsive images
+
+`dynamic_picture_tag` renders a `picture` element covering a range of
+widths using `srcset`.
 
 ```erb
-<%= link_to "See image", dynamic_image_path(image) %>
+<%= dynamic_picture_tag(image, sizes: "50vw", alt: "A description") %>
 ```
 
-## Caching
+```html
+<picture>
+  <source type="image/webp"
+          srcset="/images/… 420w, /images/… 590w, /images/… 830w, …"
+          sizes="50vw">
+  <img src="/images/…/1200x800/….jpg" width="1200" height="800"
+       alt="A description">
+</picture>
+```
 
-Generating images on the fly is expensive. This is less of a problem
-in development mode, as DynamicImage respects the If-Modified-Since
-header. In production, you should absolutely cache the results.
+Note that there is no `size:` option here. Instead, pass a `ratio:`
+when you want the image cropped. In addition to the `"16:9"` example
+below, it also accepts rationals and floats.
 
-DynamicImage doesn't do any caching on it's own, but it is designed to
-play well with others. Here's a few options:
+```erb
+<%= dynamic_picture_tag(image, ratio: "16:9", sizes: "50vw") %>
+```
 
-* [CloudFlare](https://www.cloudflare.com)
-* [Rack::Cache](http://rtomayko.github.io/rack-cache/)
-* [actionpack-page_caching](https://github.com/rails/actionpack-page_caching)
+#### Image breakpoints
 
-It's perfectly safe to cache images indefinitely. The URL is
-timestamped, and will change if the object changes.
+The `srcset` sizes are computed per image based on its own width,
+stepping down geometrically in intervals, configured by `step:`.
+The default configuration yields roughly 7 variants across the range,
+depending on the original size.
 
-## License
+```ruby
+DynamicImage.default_breakpoints    = 320..3200
+DynamicImage.breakpoint_step        = 1.4
+DynamicImage.picture_fallback_width = 1200
+```
+
+If you'd rather have fixed widths, change the range to an array:
+
+```ruby
+DynamicImage.default_breakpoints = [400, 800, 1200]
+```
+
+All three options can be overridden per call.
+
+```erb
+<%= dynamic_picture_tag(image, sizes: "50vw",
+                        breakpoints: 320..1600, step: 1.25) %>
+<%= dynamic_picture_tag(image, sizes: "50vw", breakpoints: [400, 800, 1200]) %>
+<%= dynamic_picture_tag(logo, sizes: "120px", breakpoints: 240) %>
+```
+
+#### Media queries
+
+`dynamic_picture_source_tag` renders a single `source`, so you can
+compose a `picture` by hand when you want different crops depending on
+media queries.
+
+```erb
+<picture>
+  <%= dynamic_picture_source_tag(image, ratio: "21:9",
+                                 media: "(min-width: 1000px)") %>
+  <%= dynamic_picture_source_tag(image, ratio: "1:1") %>
+  <%= dynamic_image_tag(image, size: "1200x1200", crop: true, alt: "…") %>
+</picture>
+```
+
+## Formats
 
-Copyright 2006-2016 Inge Jørgensen
+Supported formats are JPEG, PNG, GIF, WebP, JPEG XL and TIFF.
+BMP, HEIC and AVIF can also be uploaded, but aren't supported for output.
+
+The preferred format lists are configurable, sorted most preferred format
+first:
+
+```ruby
+DynamicImage.default_formats = %i[jpeg png gif webp]
+DynamicImage.mailer_formats = %i[jpeg png gif]
+```
+
+Unless the source format matches the preferred formats, it will
+be converted to the most appropriate format. For instance, a HEIC from
+a phone will be served as either JPEG or PNG, depending on if it's
+transparent or not.
+
+Pass `format:` to override the defaults.
+
+```erb
+<%= dynamic_image_tag(image, size: "400x400", format: %i[jpeg png gif]) %>
+<%= dynamic_image_tag(image, size: "400x400", format: :jxl) %>
+```
+
+For consistent appearance, all images are converted to the sRGB colorspace.
+Any embedded color profiles will be taken into account when doing so.
+
+## Working with images
+
+### Cropping
+
+Images can be pre-cropped by setting `crop_width`, `crop_height`,
+`crop_start_x` and `crop_start_y`. The crop is applied to every rendered
+version of the image, except the ones served by the `original` and
+`uncropped` actions.
+
+```ruby
+image.update(
+  crop_start_x: 15,
+  crop_start_y: 20,
+  crop_width: 300,
+  crop_height: 200
+)
+image.size      # => Vector2d(300, 200)
+image.real_size # => Vector2d(500, 400)
+```
+
+By default, images are cropped from the center. Set `crop_gravity_x` and
+`crop_gravity_y` to set a different focal point. When cropping,
+DynamicImage will attempt to keep this pixel as close to the center as
+possible without zooming in.
+
+The crop gravity is relative to the original image, so that the crop size
+can change without moving the focal point.
+
+```ruby
+image.update(crop_gravity_x: 120, crop_gravity_y: 80)
+```
+
+### Transforming the stored image
+
+Rendering never modifies the stored file, but `rotate` and `resize` do.
+Both write a new file and update the stored dimensions, and neither
+saves the record for you.
+
+```ruby
+image.rotate(90)
+image.resize(Vector2d.new(800, 800))
+image.save
+```
+
+`rotate` turns the image, taking the crop along with it. The angle must
+be a multiple of 90.
+
+`resize` scales the stored file down and replaces the original.
+
+### Outside of views
+
+The helpers cover rendering in HTML, but the classes underneath are
+public API and useful when you need dimensions or image data directly.
+
+#### Calculating sizes
+
+`DynamicImage::ImageSizing` can be used for size calculation.
+It takes the same options as the helpers.
+
+```ruby
+sizing = DynamicImage::ImageSizing.new(image) # a 1600x1000 image
+
+sizing.fit("400x400")             # => Vector2d(400.0, 250.0)
+sizing.fit("400x400", crop: true) # => Vector2d(400.0, 400.0)
+sizing.fit("2000x2000")           # => Vector2d(1600.0, 1000.0)
+```
+
+#### Processing images
+
+`DynamicImage::ProcessedImage` returns processed image data as a binary
+string.
+
+```ruby
+size = DynamicImage::ImageSizing.new(image).fit("800x800")
+data = DynamicImage::ProcessedImage.new(image, format: :jpg)
+                                   .cropped_and_resized(size)
+```
+
+The result is stored as a variant, so that subsequent calls are cheap.
+
+## How it works
+
+### Signed URLs
+
+All URLs are signed with a HMAC to protect against denial of service and
+enumeration attacks.
+
+The signing key is derived from your application's `secret_key_base`.
+Take care if you rotate it, this will invalidate every image URL you
+have generated. Plan for that if you rotate secrets.
+
+### Caching
+
+Generating images on the fly is expensive, so each processed size is
+stored as a variant, a separate record with its data in Dis, and reused
+on subsequent requests. Variants are discarded automatically when the
+image is replaced.
+
+Responses are served with a far-future `Cache-Control` header and
+respect `If-Modified-Since`, so they play well with an HTTP cache in
+front — [CloudFlare](https://www.cloudflare.com),
+[Rack::Cache](http://rtomayko.github.io/rack-cache/) or
+[actionpack-page_caching](https://github.com/rails/actionpack-page_caching),
+to name a few. It's perfectly safe to cache images indefinitely: the URL
+is timestamped, and will change if the object changes.
+
+## Upgrading
+
+DynamicImage can't migrate your image table for you: it's named whatever
+you called it, and you may have several. When a release changes the
+schema, you generate the migration. Most releases don't.
+
+### 3.1
+
+Uploaded WebP is now served as WebP instead of being converted to JPEG,
+so URLs and cached variants for WebP images change. Mailer views still
+get JPEG, PNG or GIF. Set `DynamicImage.default_formats` back to
+`%i[jpeg png gif]` to keep the old behaviour.
+
+This release also adds `frame_count` and `alpha`, and an index on
+`content_hash`. Run this once per image model.
+
+```sh
+bin/rails generate dynamic_image:upgrade Image
+bin/rails db:migrate
+bin/rails dynamic_image:backfill MODELS=Image
+```
+
+The backfill reads every image back from storage, so it takes a while on
+a large library. It's safe to interrupt and re-run, and it leaves
+`updated_at` alone, so existing URLs and cached variants stay valid.
+
+Two things to watch on a large table. `add_index` locks the table while
+it builds, so move it into its own migration with
+`algorithm: :concurrently`. And if your table was created by an older
+generator, its columns are all nullable and the generator will list the
+ones that should be `NOT NULL`; correcting them is optional and left to
+you, since `change_column_null` fails if any row holds a `NULL`.
+
+## Documentation
+
+See the [generated documentation on RubyDoc.info](https://www.rubydoc.info/gems/dynamic_image),
+and the [changelog](CHANGELOG.md) for release notes.
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/elektronaut/dynamic_image). See
+[CONTRIBUTING.md](CONTRIBUTING.md) for how to run the tests and how
+commits are formatted, and note that this project ships with a
+[code of conduct](CODE_OF_CONDUCT.md).
+
+## License
 
-DynamicImage is released under the
-[MIT License](http://www.opensource.org/licenses/MIT).
+Released under the [MIT License](MIT-LICENSE).

data/app/models/dynamic_image/variant.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module DynamicImage
+  # = DynamicImage Variant
+  #
+  # A cached rendering of an image at one size, crop and format. {DynamicImage::ProcessedImage} creates variants on
+  # demand and destroys them when the image they belong to changes or is destroyed, so there is rarely a reason to
+  # work with them directly.
+  #
+  # Data is stored in Dis under its own type, keeping it separate from the originals.
+  #
+  # @see DynamicImage::ProcessedImage
+  # @see DynamicImage::Model::Variants
   class Variant < ApplicationRecord
     include Dis::Model
 

data/lib/dynamic_image/backfill.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Backfill
+  #
+  # Fills in the metadata columns for records stored before those columns existed. The values are read back from
+  # the stored file.
+  #
+  # Records are written with +update_columns+, so no callbacks run and +updated_at+ is left alone.
+  # {DynamicImage::Model#to_param} fingerprints on +updated_at+, and touching it would invalidate every image URL
+  # and every cached variant.
+  #
+  #   DynamicImage::Backfill.new(Image).run
+  #
+  # @see DynamicImage::Schema
+  class Backfill
+    # The columns this fills in.
+    COLUMNS = %i[frame_count alpha].freeze
+
+    # @return [Class] the model being backfilled
+    attr_reader :model
+
+    # @return [Integer] records written
+    attr_reader :updated
+
+    # @return [Integer] records left alone, unreadable or missing
+    attr_reader :skipped
+
+    # @param model [Class] a model including {DynamicImage::Model}
+    def initialize(model)
+      @model = model
+      @updated = 0
+      @skipped = 0
+    end
+
+    # The records with a column still unset.
+    #
+    # @return [ActiveRecord::Relation] the pending records
+    def pending
+      COLUMNS.map { |column| model.where(column => nil) }.reduce(:or)
+    end
+
+    # Reads metadata for every pending record and fills the columns in.
+    #
+    # @yieldparam record [DynamicImage::Model] each record, after it has been processed
+    # @return [self]
+    # @raise [ArgumentError] if the table doesn't have the columns yet
+    def run
+      ensure_columns
+      pending.find_each do |record|
+        process(record)
+        yield(record) if block_given?
+      end
+      self
+    end
+
+    private
+
+    def ensure_columns
+      missing = COLUMNS.reject { |c| model.column_names.include?(c.to_s) }
+      return if missing.empty?
+
+      raise ArgumentError,
+            "#{model.table_name} has no #{missing.join(', ')} column. " \
+            "Run bin/rails generate dynamic_image:upgrade #{model.name}"
+    end
+
+    def process(record)
+      record.with_data_file { |path| apply(record, path) }
+    rescue Dis::Errors::NotFoundError
+      @skipped += 1
+    end
+
+    # Metadata reads lazily, so the values have to be resolved before the file goes out of scope. Written with
+    # update_columns so that no callbacks run.
+    def apply(record, path)
+      metadata = DynamicImage::Metadata.new(path)
+      return @skipped += 1 unless metadata.valid?
+
+      record.update_columns(frame_count: metadata.frame_count,
+                            alpha: metadata.alpha?)
+      @updated += 1
+    end
+  end
+end

data/lib/dynamic_image/belongs_to.rb

@@ -3,10 +3,32 @@
 module DynamicImage
   # = DynamicImage Belongs To
   #
+  # Extends ActiveRecord with {ClassMethods#belongs_to_image}, an association that accepts an uploaded file in place
+  # of a record.
+  #
+  # The engine mixes this into +ActiveRecord::Base+, so it is available in any model.
   module BelongsTo
     extend ActiveSupport::Concern
 
     module ClassMethods
+      # Declares an association to an image. Behaves like +belongs_to+ and takes the same arguments, with one
+      # addition: assigning anything that isn't a {DynamicImage::Model} builds the associated record from it,
+      # treating it as an uploaded file. A file can therefore be posted straight to the parent model.
+      #
+      # The image is built, not saved, and is written when the parent is. Add +validates_associated+ if an invalid
+      # upload should invalidate the parent; without it the assignment is silently dropped on save.
+      #
+      # @param name [Symbol] the name of the association
+      # @param scope [Proc, nil] an optional scope, as +belongs_to+
+      # @return [void]
+      #
+      # @example
+      #   class User < ActiveRecord::Base
+      #     belongs_to_image :avatar, class_name: "Image"
+      #     validates_associated :avatar
+      #   end
+      #
+      #   User.create(avatar: params[:file])
       def belongs_to_image(name, scope = nil, **)
         belongs_to(name, scope, **)