activestorage 6.0.0

data/app/models/active_storage/blob/analyzable.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "active_storage/analyzer/null_analyzer"
+
+module ActiveStorage::Blob::Analyzable
+  # Extracts and stores metadata from the file associated with this blob using a relevant analyzer. Active Storage comes
+  # with built-in analyzers for images and videos. See ActiveStorage::Analyzer::ImageAnalyzer and
+  # ActiveStorage::Analyzer::VideoAnalyzer for information about the specific attributes they extract and the third-party
+  # libraries they require.
+  #
+  # To choose the analyzer for a blob, Active Storage calls +accept?+ on each registered analyzer in order. It uses the
+  # first analyzer for which +accept?+ returns true when given the blob. If no registered analyzer accepts the blob, no
+  # metadata is extracted from it.
+  #
+  # In a Rails application, add or remove analyzers by manipulating +Rails.application.config.active_storage.analyzers+
+  # in an initializer:
+  #
+  #   # Add a custom analyzer for Microsoft Office documents:
+  #   Rails.application.config.active_storage.analyzers.append DOCXAnalyzer
+  #
+  #   # Remove the built-in video analyzer:
+  #   Rails.application.config.active_storage.analyzers.delete ActiveStorage::Analyzer::VideoAnalyzer
+  #
+  # Outside of a Rails application, manipulate +ActiveStorage.analyzers+ instead.
+  #
+  # You won't ordinarily need to call this method from a Rails application. New blobs are automatically and asynchronously
+  # analyzed via #analyze_later when they're attached for the first time.
+  def analyze
+    update! metadata: metadata.merge(extract_metadata_via_analyzer)
+  end
+
+  # Enqueues an ActiveStorage::AnalyzeJob which calls #analyze.
+  #
+  # This method is automatically called for a blob when it's attached for the first time. You can call it to analyze a blob
+  # again (e.g. if you add a new analyzer or modify an existing one).
+  def analyze_later
+    ActiveStorage::AnalyzeJob.perform_later(self)
+  end
+
+  # Returns true if the blob has been analyzed.
+  def analyzed?
+    analyzed
+  end
+
+  private
+    def extract_metadata_via_analyzer
+      analyzer.metadata.merge(analyzed: true)
+    end
+
+    def analyzer
+      analyzer_class.new(self)
+    end
+
+    def analyzer_class
+      ActiveStorage.analyzers.detect { |klass| klass.accept?(self) } || ActiveStorage::Analyzer::NullAnalyzer
+    end
+end

data/app/models/active_storage/blob/identifiable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActiveStorage::Blob::Identifiable
+  def identify
+    unless identified?
+      update! content_type: identify_content_type, identified: true
+      update_service_metadata
+    end
+  end
+
+  def identified?
+    identified
+  end
+
+  private
+    def identify_content_type
+      Marcel::MimeType.for download_identifiable_chunk, name: filename.to_s, declared_type: content_type
+    end
+
+    def download_identifiable_chunk
+      if byte_size.positive?
+        service.download_chunk key, 0...4.kilobytes
+      else
+        ""
+      end
+    end
+
+    def update_service_metadata
+      service.update_metadata key, service_metadata if service_metadata.any?
+    end
+end

data/app/models/active_storage/blob/representable.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ActiveStorage::Blob::Representable
+  extend ActiveSupport::Concern
+
+  included do
+    has_one_attached :preview_image
+  end
+
+  # Returns an ActiveStorage::Variant instance with the set of +transformations+ provided. This is only relevant for image
+  # files, and it allows any image to be transformed for size, colors, and the like. Example:
+  #
+  #   avatar.variant(resize_to_limit: [100, 100]).processed.service_url
+  #
+  # This will create and process a variant of the avatar blob that's constrained to a height and width of 100px.
+  # Then it'll upload said variant to the service according to a derivative key of the blob and the transformations.
+  #
+  # Frequently, though, you don't actually want to transform the variant right away. But rather simply refer to a
+  # specific variant that can be created by a controller on-demand. Like so:
+  #
+  #   <%= image_tag Current.user.avatar.variant(resize_to_limit: [100, 100]) %>
+  #
+  # This will create a URL for that specific blob with that specific variant, which the ActiveStorage::RepresentationsController
+  # can then produce on-demand.
+  #
+  # Raises ActiveStorage::InvariableError if ImageMagick cannot transform the blob. To determine whether a blob is
+  # variable, call ActiveStorage::Blob#variable?.
+  def variant(transformations)
+    if variable?
+      ActiveStorage::Variant.new(self, transformations)
+    else
+      raise ActiveStorage::InvariableError
+    end
+  end
+
+  # Returns true if ImageMagick can transform the blob (its content type is in +ActiveStorage.variable_content_types+).
+  def variable?
+    ActiveStorage.variable_content_types.include?(content_type)
+  end
+
+
+  # Returns an ActiveStorage::Preview instance with the set of +transformations+ provided. A preview is an image generated
+  # from a non-image blob. Active Storage comes with built-in previewers for videos and PDF documents. The video previewer
+  # extracts the first frame from a video and the PDF previewer extracts the first page from a PDF document.
+  #
+  #   blob.preview(resize_to_limit: [100, 100]).processed.service_url
+  #
+  # Avoid processing previews synchronously in views. Instead, link to a controller action that processes them on demand.
+  # Active Storage provides one, but you may want to create your own (for example, if you need authentication). Here’s
+  # how to use the built-in version:
+  #
+  #   <%= image_tag video.preview(resize_to_limit: [100, 100]) %>
+  #
+  # This method raises ActiveStorage::UnpreviewableError if no previewer accepts the receiving blob. To determine
+  # whether a blob is accepted by any previewer, call ActiveStorage::Blob#previewable?.
+  def preview(transformations)
+    if previewable?
+      ActiveStorage::Preview.new(self, transformations)
+    else
+      raise ActiveStorage::UnpreviewableError
+    end
+  end
+
+  # Returns true if any registered previewer accepts the blob. By default, this will return true for videos and PDF documents.
+  def previewable?
+    ActiveStorage.previewers.any? { |klass| klass.accept?(self) }
+  end
+
+
+  # Returns an ActiveStorage::Preview for a previewable blob or an ActiveStorage::Variant for a variable image blob.
+  #
+  #   blob.representation(resize_to_limit: [100, 100]).processed.service_url
+  #
+  # Raises ActiveStorage::UnrepresentableError if the receiving blob is neither variable nor previewable. Call
+  # ActiveStorage::Blob#representable? to determine whether a blob is representable.
+  #
+  # See ActiveStorage::Blob#preview and ActiveStorage::Blob#variant for more information.
+  def representation(transformations)
+    case
+    when previewable?
+      preview transformations
+    when variable?
+      variant transformations
+    else
+      raise ActiveStorage::UnrepresentableError
+    end
+  end
+
+  # Returns true if the blob is variable or previewable.
+  def representable?
+    variable? || previewable?
+  end
+end

data/app/models/active_storage/current.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ActiveStorage::Current < ActiveSupport::CurrentAttributes #:nodoc:
+  attribute :host
+end

data/app/models/active_storage/filename.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Encapsulates a string representing a filename to provide convenient access to parts of it and sanitization.
+# A Filename instance is returned by ActiveStorage::Blob#filename, and is comparable so it can be used for sorting.
+class ActiveStorage::Filename
+  include Comparable
+
+  class << self
+    # Returns a Filename instance based on the given filename. If the filename is a Filename, it is
+    # returned unmodified. If it is a String, it is passed to ActiveStorage::Filename.new.
+    def wrap(filename)
+      filename.kind_of?(self) ? filename : new(filename)
+    end
+  end
+
+  def initialize(filename)
+    @filename = filename
+  end
+
+  # Returns the part of the filename preceding any extension.
+  #
+  #   ActiveStorage::Filename.new("racecar.jpg").base # => "racecar"
+  #   ActiveStorage::Filename.new("racecar").base     # => "racecar"
+  #   ActiveStorage::Filename.new(".gitignore").base  # => ".gitignore"
+  def base
+    File.basename @filename, extension_with_delimiter
+  end
+
+  # Returns the extension of the filename (i.e. the substring following the last dot, excluding a dot at the
+  # beginning) with the dot that precedes it. If the filename has no extension, an empty string is returned.
+  #
+  #   ActiveStorage::Filename.new("racecar.jpg").extension_with_delimiter # => ".jpg"
+  #   ActiveStorage::Filename.new("racecar").extension_with_delimiter     # => ""
+  #   ActiveStorage::Filename.new(".gitignore").extension_with_delimiter  # => ""
+  def extension_with_delimiter
+    File.extname @filename
+  end
+
+  # Returns the extension of the filename (i.e. the substring following the last dot, excluding a dot at
+  # the beginning). If the filename has no extension, an empty string is returned.
+  #
+  #   ActiveStorage::Filename.new("racecar.jpg").extension_without_delimiter # => "jpg"
+  #   ActiveStorage::Filename.new("racecar").extension_without_delimiter     # => ""
+  #   ActiveStorage::Filename.new(".gitignore").extension_without_delimiter  # => ""
+  def extension_without_delimiter
+    extension_with_delimiter.from(1).to_s
+  end
+
+  alias_method :extension, :extension_without_delimiter
+
+  # Returns the sanitized filename.
+  #
+  #   ActiveStorage::Filename.new("foo:bar.jpg").sanitized # => "foo-bar.jpg"
+  #   ActiveStorage::Filename.new("foo/bar.jpg").sanitized # => "foo-bar.jpg"
+  #
+  # Characters considered unsafe for storage (e.g. \, $, and the RTL override character) are replaced with a dash.
+  def sanitized
+    @filename.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "�").strip.tr("\u{202E}%$|:;/\t\r\n\\", "-")
+  end
+
+  # Returns the sanitized version of the filename.
+  def to_s
+    sanitized.to_s
+  end
+
+  def as_json(*)
+    to_s
+  end
+
+  def to_json
+    to_s
+  end
+
+  def <=>(other)
+    to_s.downcase <=> other.to_s.downcase
+  end
+end

data/app/models/active_storage/preview.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Some non-image blobs can be previewed: that is, they can be presented as images. A video blob can be previewed by
+# extracting its first frame, and a PDF blob can be previewed by extracting its first page.
+#
+# A previewer extracts a preview image from a blob. Active Storage provides previewers for videos and PDFs:
+# ActiveStorage::Previewer::VideoPreviewer and ActiveStorage::Previewer::PDFPreviewer. Build custom previewers by
+# subclassing ActiveStorage::Previewer and implementing the requisite methods. Consult the ActiveStorage::Previewer
+# documentation for more details on what's required of previewers.
+#
+# To choose the previewer for a blob, Active Storage calls +accept?+ on each registered previewer in order. It uses the
+# first previewer for which +accept?+ returns true when given the blob. In a Rails application, add or remove previewers
+# by manipulating +Rails.application.config.active_storage.previewers+ in an initializer:
+#
+#   Rails.application.config.active_storage.previewers
+#   # => [ ActiveStorage::Previewer::PDFPreviewer, ActiveStorage::Previewer::VideoPreviewer ]
+#
+#   # Add a custom previewer for Microsoft Office documents:
+#   Rails.application.config.active_storage.previewers << DOCXPreviewer
+#   # => [ ActiveStorage::Previewer::PDFPreviewer, ActiveStorage::Previewer::VideoPreviewer, DOCXPreviewer ]
+#
+# Outside of a Rails application, modify +ActiveStorage.previewers+ instead.
+#
+# The built-in previewers rely on third-party system libraries. Specifically, the built-in video previewer requires
+# {FFmpeg}[https://www.ffmpeg.org]. Two PDF previewers are provided: one requires {Poppler}[https://poppler.freedesktop.org],
+# and the other requires {muPDF}[https://mupdf.com] (version 1.8 or newer). To preview PDFs, install either Poppler or muPDF.
+#
+# These libraries are not provided by Rails. You must install them yourself to use the built-in previewers. Before you
+# install and use third-party software, make sure you understand the licensing implications of doing so.
+class ActiveStorage::Preview
+  class UnprocessedError < StandardError; end
+
+  attr_reader :blob, :variation
+
+  def initialize(blob, variation_or_variation_key)
+    @blob, @variation = blob, ActiveStorage::Variation.wrap(variation_or_variation_key)
+  end
+
+  # Processes the preview if it has not been processed yet. Returns the receiving Preview instance for convenience:
+  #
+  #   blob.preview(resize_to_limit: [100, 100]).processed.service_url
+  #
+  # Processing a preview generates an image from its blob and attaches the preview image to the blob. Because the preview
+  # image is stored with the blob, it is only generated once.
+  def processed
+    process unless processed?
+    self
+  end
+
+  # Returns the blob's attached preview image.
+  def image
+    blob.preview_image
+  end
+
+  # Returns the URL of the preview's variant on the service. Raises ActiveStorage::Preview::UnprocessedError if the
+  # preview has not been processed yet.
+  #
+  # This method synchronously processes a variant of the preview image, so do not call it in views. Instead, generate
+  # a stable URL that redirects to the short-lived URL returned by this method.
+  def service_url(**options)
+    if processed?
+      variant.service_url(options)
+    else
+      raise UnprocessedError
+    end
+  end
+
+  private
+    def processed?
+      image.attached?
+    end
+
+    def process
+      previewer.preview { |attachable| image.attach(attachable) }
+    end
+
+    def variant
+      ActiveStorage::Variant.new(image, variation).processed
+    end
+
+
+    def previewer
+      previewer_class.new(blob)
+    end
+
+    def previewer_class
+      ActiveStorage.previewers.detect { |klass| klass.accept?(blob) }
+    end
+end

data/app/models/active_storage/variant.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+# Image blobs can have variants that are the result of a set of transformations applied to the original.
+# These variants are used to create thumbnails, fixed-size avatars, or any other derivative image from the
+# original.
+#
+# Variants rely on {ImageProcessing}[https://github.com/janko-m/image_processing] gem for the actual transformations
+# of the file, so you must add <tt>gem "image_processing"</tt> to your Gemfile if you wish to use variants. By
+# default, images will be processed with {ImageMagick}[http://imagemagick.org] using the
+# {MiniMagick}[https://github.com/minimagick/minimagick] gem, but you can also switch to the
+# {libvips}[http://jcupitt.github.io/libvips/] processor operated by the {ruby-vips}[https://github.com/jcupitt/ruby-vips]
+# gem).
+#
+#   Rails.application.config.active_storage.variant_processor
+#   # => :mini_magick
+#
+#   Rails.application.config.active_storage.variant_processor = :vips
+#   # => :vips
+#
+# Note that to create a variant it's necessary to download the entire blob file from the service. Because of this process,
+# you also want to be considerate about when the variant is actually processed. You shouldn't be processing variants inline
+# in a template, for example. Delay the processing to an on-demand controller, like the one provided in
+# ActiveStorage::RepresentationsController.
+#
+# To refer to such a delayed on-demand variant, simply link to the variant through the resolved route provided
+# by Active Storage like so:
+#
+#   <%= image_tag Current.user.avatar.variant(resize_to_limit: [100, 100]) %>
+#
+# This will create a URL for that specific blob with that specific variant, which the ActiveStorage::RepresentationsController
+# can then produce on-demand.
+#
+# When you do want to actually produce the variant needed, call +processed+. This will check that the variant
+# has already been processed and uploaded to the service, and, if so, just return that. Otherwise it will perform
+# the transformations, upload the variant to the service, and return itself again. Example:
+#
+#   avatar.variant(resize_to_limit: [100, 100]).processed.service_url
+#
+# This will create and process a variant of the avatar blob that's constrained to a height and width of 100.
+# Then it'll upload said variant to the service according to a derivative key of the blob and the transformations.
+#
+# You can combine any number of ImageMagick/libvips operations into a variant, as well as any macros provided by the
+# ImageProcessing gem (such as +resize_to_limit+):
+#
+#   avatar.variant(resize_to_limit: [800, 800], monochrome: true, rotate: "-90")
+#
+# Visit the following links for a list of available ImageProcessing commands and ImageMagick/libvips operations:
+#
+# * {ImageProcessing::MiniMagick}[https://github.com/janko-m/image_processing/blob/master/doc/minimagick.md#methods]
+# * {ImageMagick reference}[https://www.imagemagick.org/script/mogrify.php]
+# * {ImageProcessing::Vips}[https://github.com/janko-m/image_processing/blob/master/doc/vips.md#methods]
+# * {ruby-vips reference}[http://www.rubydoc.info/gems/ruby-vips/Vips/Image]
+class ActiveStorage::Variant
+  WEB_IMAGE_CONTENT_TYPES = %w[ image/png image/jpeg image/jpg image/gif ]
+
+  attr_reader :blob, :variation
+  delegate :service, to: :blob
+
+  def initialize(blob, variation_or_variation_key)
+    @blob, @variation = blob, ActiveStorage::Variation.wrap(variation_or_variation_key)
+  end
+
+  # Returns the variant instance itself after it's been processed or an existing processing has been found on the service.
+  def processed
+    process unless processed?
+    self
+  end
+
+  # Returns a combination key of the blob and the variation that together identifies a specific variant.
+  def key
+    "variants/#{blob.key}/#{Digest::SHA256.hexdigest(variation.key)}"
+  end
+
+  # Returns the URL of the variant on the service. This URL is intended to be short-lived for security and not used directly
+  # with users. Instead, the +service_url+ should only be exposed as a redirect from a stable, possibly authenticated URL.
+  # Hiding the +service_url+ behind a redirect also gives you the power to change services without updating all URLs. And
+  # it allows permanent URLs that redirect to the +service_url+ to be cached in the view.
+  #
+  # Use <tt>url_for(variant)</tt> (or the implied form, like +link_to variant+ or +redirect_to variant+) to get the stable URL
+  # for a variant that points to the ActiveStorage::RepresentationsController, which in turn will use this +service_call+ method
+  # for its redirection.
+  def service_url(expires_in: ActiveStorage.service_urls_expire_in, disposition: :inline)
+    service.url key, expires_in: expires_in, disposition: disposition, filename: filename, content_type: content_type
+  end
+
+  # Returns the receiving variant. Allows ActiveStorage::Variant and ActiveStorage::Preview instances to be used interchangeably.
+  def image
+    self
+  end
+
+  private
+    def processed?
+      service.exist?(key)
+    end
+
+    def process
+      blob.open do |image|
+        transform(image) { |output| upload(output) }
+      end
+    end
+
+    def transform(image, &block)
+      variation.transform(image, format: format, &block)
+    end
+
+    def upload(file)
+      service.upload(key, file)
+    end
+
+
+    def specification
+      @specification ||=
+        if WEB_IMAGE_CONTENT_TYPES.include?(blob.content_type)
+          Specification.new \
+            filename: blob.filename,
+            content_type: blob.content_type,
+            format: nil
+        else
+          Specification.new \
+            filename: ActiveStorage::Filename.new("#{blob.filename.base}.png"),
+            content_type: "image/png",
+            format: "png"
+        end
+    end
+
+    delegate :filename, :content_type, :format, to: :specification
+
+    class Specification < OpenStruct; end
+end