dynamic_image 3.0.8 → 3.1.0

data/lib/dynamic_image/schema.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Schema
+  #
+  # The database schema {DynamicImage::Model} expects on the table holding the image.
+  #
+  # DynamicImage doesn't own that table. Unlike +dynamic_image_variants+, which has a fixed name and an engine
+  # migration, the image table is created in the application by the +dynamic_image:resource+ generator, under
+  # whatever name the application picked, and there may be more than one. This is the single definition of what it
+  # should contain.
+  #
+  # @see DynamicImage::Model
+  module Schema
+    # The expected columns, in the order they should appear in a migration. Each is described by its migration type
+    # and whether it accepts +NULL+.
+    #
+    # +frame_count+ and +alpha+ are nullable. NULL means the image predates them being recorded, which is not the
+    # same as knowing the image is a still or opaque.
+    #
+    # @return [Hash{Symbol => Hash}]
+    ATTRIBUTES = {
+      content_hash: { type: :string, null: false },
+      content_type: { type: :string, null: false },
+      content_length: { type: :integer, null: false },
+      filename: { type: :string, null: false },
+      colorspace: { type: :string, null: false },
+      real_width: { type: :integer, null: false },
+      real_height: { type: :integer, null: false },
+      frame_count: { type: :integer, null: true },
+      alpha: { type: :boolean, null: true },
+      crop_width: { type: :integer, null: true },
+      crop_height: { type: :integer, null: true },
+      crop_start_x: { type: :integer, null: true },
+      crop_start_y: { type: :integer, null: true },
+      crop_gravity_x: { type: :integer, null: true },
+      crop_gravity_y: { type: :integer, null: true }
+    }.freeze
+
+    # The expected indexes.
+    #
+    # @return [Array<Hash>]
+    INDEXES = [
+      { columns: %i[content_hash], unique: false }
+    ].freeze
+  end
+end

data/lib/dynamic_image/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DynamicImage
-  VERSION = "3.0.8"
+  VERSION = "3.1.0"
 end

data/lib/dynamic_image.rb

@@ -4,22 +4,82 @@ require "dis"
 require "vector2d"
 require "vips"
 
+require "dynamic_image/backfill"
 require "dynamic_image/belongs_to"
+require "dynamic_image/breakpoints"
 require "dynamic_image/controller"
 require "dynamic_image/digest_verifier"
 require "dynamic_image/engine"
 require "dynamic_image/errors"
 require "dynamic_image/format"
+require "dynamic_image/format_negotiator"
 require "dynamic_image/helper"
 require "dynamic_image/image_processor"
 require "dynamic_image/image_reader"
 require "dynamic_image/image_sizing"
-require "dynamic_image/jobs"
 require "dynamic_image/metadata"
 require "dynamic_image/model"
+require "dynamic_image/picture"
+require "dynamic_image/picture/format_policy"
 require "dynamic_image/processed_image"
+require "dynamic_image/ratio"
 require "dynamic_image/routing"
+require "dynamic_image/schema"
 
+# A Rails engine for image uploads. Rather than creating a pre-defined set of images when a file is uploaded, it
+# stores the original file and generates images on demand. It handles cropping, resizing, format and colorspace
+# conversion, and stores each processed size as a variant.
+#
+# Include {DynamicImage::Model} in the model holding the image and {DynamicImage::Controller} in the controller
+# serving it, then declare the routes with {DynamicImage::Routing#image_resources}. Views render images through the
+# helpers in {DynamicImage::Helper}, which sign the URLs.
+#
+# Files are stored with Dis, and processing is done with libvips.
+#
+# @see DynamicImage::Model
+# @see DynamicImage::Controller
+# @see DynamicImage::Helper
+# @see DynamicImage::ImageSizing
+# @see DynamicImage::ProcessedImage
 module DynamicImage
+  # The formats anything that renders images will understand. Fallback images in a <tt>picture</tt> are negotiated
+  # from this list, and it is the default for {DynamicImage.mailer_formats}.
+  #
+  # @return [Array<Symbol>] the format names, most preferred first
+  COMPATIBLE_FORMATS = %i[jpeg png gif].freeze
+
+  # Verifies the HMAC digests embedded in image URLs. Set by the engine from the application's key generator, which
+  # derives it from <tt>secret_key_base</tt>.
+  #
+  # @return [DynamicImage::DigestVerifier]
   cattr_accessor :digest_verifier
+
+  # The formats a view accepts when it doesn't pass <tt>format:</tt>. Also decides what
+  # {DynamicImage::Model#safe_content_type} considers safe.
+  #
+  # @return [Array<Symbol>] the format names, most preferred first
+  mattr_accessor :default_formats, default: %i[jpeg png gif webp]
+
+  # The formats a mailer view accepts when it doesn't pass <tt>format:</tt>.
+  #
+  # @return [Array<Symbol>] the format names, most preferred first
+  mattr_accessor :mailer_formats, default: COMPATIBLE_FORMATS
+
+  # The breakpoints responsive images are rendered at. This can be a range, an array of explicit widths, or a single
+  # width.
+  #
+  # @return [Range, Array<Integer>, Integer]
+  # @see DynamicImage::Breakpoints
+  mattr_accessor :default_breakpoints, default: 320..3200
+
+  # The ratio between two breakpoints. Lower means a closer fit to what the browser needs, at the price of more
+  # variants to generate and store.
+  #
+  # @return [Float]
+  mattr_accessor :breakpoint_step, default: 1.4
+
+  # The width of the fallback image in a <tt>picture</tt> element.
+  #
+  # @return [Integer]
+  mattr_accessor :picture_fallback_width, default: 1200
 end

data/lib/rails/generators/dynamic_image/resource/USAGE

@@ -0,0 +1,17 @@
+Description:
+    Creates a DynamicImage resource: a model including
+    DynamicImage::Model, a controller including DynamicImage::Controller,
+    a migration with the columns DynamicImage needs, and an
+    image_resources route.
+
+    Additional attributes are passed through to the migration, so a
+    resource can carry fields of its own.
+
+Example:
+    bin/rails generate dynamic_image:resource image
+
+        creates an Image model, an ImagesController and a migration.
+
+    bin/rails generate dynamic_image:resource photo caption:string
+
+        adds a caption column to the migration.

data/lib/rails/generators/dynamic_image/resource/resource_generator.rb

@@ -2,22 +2,60 @@
 
 require "rails/generators"
 require "rails/generators/rails/resource/resource_generator"
+require "rails/generators/active_record/migration"
+
+require "dynamic_image/schema"
 
 module DynamicImage
+  # Generators for setting up DynamicImage in an application.
   module Generators
+    # Creates a DynamicImage resource: a model including {DynamicImage::Model}, a controller including
+    # {DynamicImage::Controller}, a migration with the columns DynamicImage needs, and an +image_resources+ route.
+    #
+    #   bin/rails generate dynamic_image:resource image
+    #
+    # Additional attributes are passed through to the migration, letting a resource carry fields of its own.
+    #
+    #   bin/rails generate dynamic_image:resource photo caption:string
+    #
+    # The migration is rendered from {DynamicImage::Schema}. The Active Record generator can't express nullability
+    # or indexes through its +name:type+ arguments.
     class ResourceGenerator < Rails::Generators::ResourceGenerator
-      desc "Creates a DynamicImage resource"
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
 
       def initialize(args, *options)
-        super(inject_dynamic_image_attributes(args), *options)
+        @orm_args = args
+        super
+      end
+
+      no_commands do
+        # Thor consumes the raw arguments while parsing, so {#initialize} keeps a copy for the ORM generator.
+        def invoke_orm_generator(orm)
+          invoke(orm, @orm_args, options.merge("migration" => false))
+        end
+      end
+
+      # The ORM generator would write its own migration, which can't carry nullability or indexes. Invoke it with
+      # +migration: false+ and render {#create_dynamic_image_migration} instead.
+      hook_for :orm, required: true, in: :rails, as: :model do |instance, orm|
+        instance.invoke_orm_generator(orm)
+      end
+
+      def create_dynamic_image_migration
+        migration_template(
+          "create_table_migration.rb",
+          File.join(db_migrate_path, "create_#{table_name}.rb")
+        )
       end
 
       def add_controller_extension
-        inject_into_file(
+        inject_into_class(
           File.join("app/controllers",
                     class_path,
                     "#{file_name.pluralize}_controller.rb"),
-          after: "ApplicationController\n"
+          "#{class_name.pluralize}Controller"
         ) do
           "  include DynamicImage::Controller\n\n  private\n\n  " \
             "def model\n    #{class_name}\n  end\n"
@@ -25,9 +63,9 @@ module DynamicImage
       end
 
       def add_model_extension
-        inject_into_file(
+        inject_into_class(
           File.join("app/models", class_path, "#{file_name}.rb"),
-          after: "ActiveRecord::Base\n"
+          class_name
         ) do
           "  include DynamicImage::Model\n"
         end
@@ -43,23 +81,21 @@ module DynamicImage
 
       private
 
-      def inject_dynamic_image_attributes(args)
-        if args.any?
-          [args[0]] + dynamic_image_attributes + args[1..args.length]
-        else
-          args
-        end
+      def schema_attributes
+        DynamicImage::Schema::ATTRIBUTES
+      end
+
+      def schema_indexes
+        DynamicImage::Schema::INDEXES
+      end
+
+      def index_columns(index)
+        columns = index[:columns]
+        columns.length == 1 ? columns.first.inspect : columns.inspect
       end
 
-      def dynamic_image_attributes
-        %w[content_hash:string content_type:string
-           content_length:integer
-           filename:string
-           colorspace:string
-           real_width:integer real_height:integer
-           crop_width:integer crop_height:integer
-           crop_start_x:integer crop_start_y:integer
-           crop_gravity_x:integer crop_gravity_y:integer]
+      def attributes_with_index
+        attributes.select { |a| !a.reference? && a.has_index? }
       end
     end
   end

data/lib/rails/generators/dynamic_image/resource/templates/create_table_migration.rb.tt

@@ -0,0 +1,32 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %><%= primary_key_type %> do |t|
+<% schema_attributes.each do |name, column| -%>
+      t.<%= column[:type] %> :<%= name %><%= ", null: false" unless column[:null] %>
+<% end -%>
+<% attributes.each do |attribute| -%>
+<% if attribute.password_digest? -%>
+      t.string :password_digest<%= attribute.inject_options %>
+<% elsif attribute.token? -%>
+      t.string :<%= attribute.name %><%= attribute.inject_options %>
+<% elsif attribute.reference? -%>
+      t.<%= attribute.type %> :<%= attribute.name %><%= attribute.inject_options %><%= foreign_key_type %>
+<% elsif !attribute.virtual? -%>
+      t.<%= attribute.type %> :<%= attribute.name %><%= attribute.inject_options %>
+<% end -%>
+<% end -%>
+
+      t.timestamps
+    end
+<% schema_indexes.each do |index| -%>
+
+    add_index :<%= table_name %>, <%= index_columns(index) %><%= ", unique: true" if index[:unique] %>
+<% end -%>
+<% attributes.select(&:token?).each do |attribute| -%>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>, unique: true
+<% end -%>
+<% attributes_with_index.each do |attribute| -%>
+    add_index :<%= table_name %>, :<%= attribute.index_name %><%= attribute.inject_index_options %>
+<% end -%>
+  end
+end

data/lib/rails/generators/dynamic_image/upgrade/USAGE

@@ -0,0 +1,17 @@
+Description:
+    Brings an existing DynamicImage table up to date with the schema the
+    installed version of the gem expects. Compares the table against
+    DynamicImage::Schema and writes a migration containing only what is
+    missing. If nothing is missing, no migration is written.
+
+    Only additive changes are generated. Columns are added nullable, and
+    columns whose nullability differs from the expected schema are
+    reported rather than altered: change_column_null fails on existing
+    NULLs, and only you can know whether the data allows it.
+
+    Run it once per DynamicImage model.
+
+Example:
+    bin/rails generate dynamic_image:upgrade Image
+
+        creates db/migrate/XXX_add_frame_count_and_alpha_to_images.rb

data/lib/rails/generators/dynamic_image/upgrade/templates/upgrade_migration.rb.tt

@@ -0,0 +1,10 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+<% missing_columns.each do |name, column| -%>
+    add_column :<%= table_name %>, :<%= name %>, :<%= column[:type] %>
+<% end -%>
+<% missing_indexes.each do |index| -%>
+    add_index :<%= table_name %>, <%= index_columns(index) %><%= ", unique: true" if index[:unique] %>
+<% end -%>
+  end
+end

data/lib/rails/generators/dynamic_image/upgrade/upgrade_generator.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/named_base"
+require "rails/generators/active_record/migration"
+
+require "dynamic_image/schema"
+
+module DynamicImage
+  module Generators
+    # Brings an existing table up to date with {DynamicImage::Schema}.
+    #
+    #   bin/rails generate dynamic_image:upgrade Image
+    #
+    # The migration is derived from the difference between the table and the schema, so running the generator
+    # again once the migration has been applied writes nothing. An application several releases behind gets a single
+    # migration with everything it's missing.
+    #
+    # Only additive changes are generated. Columns are added nullable, and nullability differences are reported
+    # instead of altered: +change_column_null+ fails on existing NULLs, and the generator can't know whether the
+    # data allows it.
+    class UpgradeGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_upgrade_migration
+        if missing_columns.empty? && missing_indexes.empty?
+          say_status(:identical, "#{table_name} is up to date", :blue)
+          return
+        end
+
+        migration_template("upgrade_migration.rb",
+                           File.join(db_migrate_path, "#{migration_name}.rb"))
+      end
+
+      def report_nullability
+        nullable_in_table.each do |name|
+          say_status(:warn,
+                     "#{table_name}.#{name} should be NOT NULL",
+                     :yellow)
+        end
+      end
+
+      def report_index_locking
+        return if missing_indexes.empty?
+
+        say_status(:warn,
+                   "adding an index locks the table while it builds",
+                   :yellow)
+      end
+
+      private
+
+      def model_class
+        @model_class ||= class_name.constantize
+      end
+
+      def table_name
+        model_class.table_name
+      end
+
+      def existing_columns
+        @existing_columns ||= model_class.columns.index_by { |c| c.name.to_sym }
+      end
+
+      def existing_indexes
+        @existing_indexes ||=
+          model_class.connection.indexes(table_name).map do |index|
+            Array(index.columns).map(&:to_sym)
+          end
+      end
+
+      def missing_columns
+        @missing_columns ||=
+          DynamicImage::Schema::ATTRIBUTES.reject do |name, _|
+            existing_columns.key?(name)
+          end
+      end
+
+      # An index whose leading columns match already answers the query, so only a missing prefix counts as missing.
+      def missing_indexes
+        @missing_indexes ||=
+          DynamicImage::Schema::INDEXES.reject do |index|
+            columns = index[:columns]
+            existing_indexes.any? { |e| e.first(columns.length) == columns }
+          end
+      end
+
+      def nullable_in_table
+        DynamicImage::Schema::ATTRIBUTES.filter_map do |name, column|
+          existing = existing_columns[name]
+          name if existing && !column[:null] && existing.null
+        end
+      end
+
+      def index_columns(index)
+        columns = index[:columns]
+        columns.length == 1 ? columns.first.inspect : columns.inspect
+      end
+
+      def migration_name
+        if missing_columns.any?
+          "add_#{missing_columns.keys.join('_and_')}_to_#{table_name}"
+        else
+          "add_dynamic_image_indexes_to_#{table_name}"
+        end
+      end
+    end
+  end
+end

data/lib/tasks/dynamic_image.rake

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+namespace :dynamic_image do
+  desc "Fill in metadata columns for images stored before they existed"
+  task backfill: :environment do
+    unless ENV["MODELS"]
+      puts "Usage: #{$PROGRAM_NAME} dynamic_image:backfill MODELS=Image"
+      exit
+    end
+
+    ENV["MODELS"].split(",").map(&:strip).map(&:constantize).each do |model|
+      backfill = DynamicImage::Backfill.new(model)
+      total = backfill.pending.count
+      puts "#{model.name}: #{total} #{'record'.pluralize(total)} to read"
+
+      processed = 0
+      backfill.run do
+        processed += 1
+        print("\r  #{processed}/#{total}") if (processed % 10).zero?
+      end
+
+      puts "\r  #{backfill.updated} updated, #{backfill.skipped} skipped"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dynamic_image
 version: !ruby/object:Gem::Version
-  version: 3.0.8
+  version: 3.1.0
 platform: ruby
 authors:
 - Inge Jørgensen
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -63,20 +63,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.2.1
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.2.1
+        version: '2.3'
 description: DynamicImage is a Rails plugin that simplifies image uploading and processing
 email:
 - inge@elektronaut.no
@@ -91,36 +85,53 @@ files:
 - app/views/dynamic_image/images/show.html.erb
 - db/migrate/20190620160500_create_dynamic_image_variants.rb
 - lib/dynamic_image.rb
+- lib/dynamic_image/backfill.rb
 - lib/dynamic_image/belongs_to.rb
+- lib/dynamic_image/breakpoints.rb
 - lib/dynamic_image/controller.rb
 - lib/dynamic_image/digest_verifier.rb
 - lib/dynamic_image/engine.rb
 - lib/dynamic_image/errors.rb
 - lib/dynamic_image/format.rb
+- lib/dynamic_image/format_negotiator.rb
 - lib/dynamic_image/helper.rb
+- lib/dynamic_image/helper/formats.rb
+- lib/dynamic_image/helper/pictures.rb
 - lib/dynamic_image/image_processor.rb
 - lib/dynamic_image/image_processor/colors.rb
 - lib/dynamic_image/image_processor/frames.rb
 - lib/dynamic_image/image_processor/transform.rb
 - lib/dynamic_image/image_reader.rb
 - lib/dynamic_image/image_sizing.rb
-- lib/dynamic_image/jobs.rb
-- lib/dynamic_image/jobs/create_variant.rb
 - lib/dynamic_image/metadata.rb
 - lib/dynamic_image/model.rb
 - lib/dynamic_image/model/dimensions.rb
 - lib/dynamic_image/model/transformations.rb
 - lib/dynamic_image/model/validations.rb
 - lib/dynamic_image/model/variants.rb
+- lib/dynamic_image/picture.rb
+- lib/dynamic_image/picture/format_policy.rb
 - lib/dynamic_image/processed_image.rb
+- lib/dynamic_image/ratio.rb
 - lib/dynamic_image/routing.rb
+- lib/dynamic_image/schema.rb
 - lib/dynamic_image/version.rb
+- lib/rails/generators/dynamic_image/resource/USAGE
 - lib/rails/generators/dynamic_image/resource/resource_generator.rb
+- lib/rails/generators/dynamic_image/resource/templates/create_table_migration.rb.tt
+- lib/rails/generators/dynamic_image/upgrade/USAGE
+- lib/rails/generators/dynamic_image/upgrade/templates/upgrade_migration.rb.tt
+- lib/rails/generators/dynamic_image/upgrade/upgrade_generator.rb
+- lib/tasks/dynamic_image.rake
 homepage: https://github.com/elektronaut/dynamic_image
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/elektronaut/dynamic_image/issues
+  changelog_uri: https://github.com/elektronaut/dynamic_image/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dynamic_image
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/elektronaut/dynamic_image
 rdoc_options: []
 require_paths:
 - lib
@@ -128,14 +139,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Rails plugin that simplifies image uploading and processing
 test_files: []

data/lib/dynamic_image/jobs/create_variant.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module DynamicImage
-  module Jobs
-    # = Create variant
-    #
-    # Creates an image variant.
-    class CreateVariant < ActiveJob::Base
-      queue_as :dis
-
-      discard_on Dis::Errors::NotFoundError
-
-      retry_on StandardError, attempts: 10, wait: :polynomially_longer
-
-      def perform(record, options, size)
-        size_v = Vector2d.parse(size)
-        DynamicImage::ProcessedImage.new(record, options)
-                                    .find_or_create_variant(size_v)
-      end
-    end
-  end
-end

data/lib/dynamic_image/jobs.rb

@@ -1,3 +0,0 @@
-# frozen_string_literal: true
-
-require "dynamic_image/jobs/create_variant"