activestorage 0.1 → 5.2.0.beta1

data/app/models/active_storage/filename.rb

@@ -0,0 +1,73 @@
+# 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
+
+  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
+
+  def parameters
+    Parameters.new self
+  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/filename/parameters.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class ActiveStorage::Filename::Parameters
+  attr_reader :filename
+
+  def initialize(filename)
+    @filename = filename
+  end
+
+  def combined
+    "#{ascii}; #{utf8}"
+  end
+
+  TRADITIONAL_ESCAPED_CHAR = /[^ A-Za-z0-9!#$+.^_`|~-]/
+
+  def ascii
+    'filename="' + percent_escape(I18n.transliterate(filename.sanitized), TRADITIONAL_ESCAPED_CHAR) + '"'
+  end
+
+  RFC_5987_ESCAPED_CHAR = /[^A-Za-z0-9!#$&+.^_`|~-]/
+
+  def utf8
+    "filename*=UTF-8''" + percent_escape(filename.sanitized, RFC_5987_ESCAPED_CHAR)
+  end
+
+  def to_s
+    combined
+  end
+
+  private
+    def percent_escape(string, pattern)
+      string.gsub(pattern) do |char|
+        char.bytes.map { |byte| "%%%02X" % byte }.join
+      end
+    end
+end

data/app/models/active_storage/preview.rb

@@ -0,0 +1,90 @@
+# 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:
+#
+# * {ffmpeg}[https://www.ffmpeg.org]
+# * {mupdf}[https://mupdf.com]
+#
+# 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: "100x100").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,86 @@
+# frozen_string_literal: true
+
+# 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 {MiniMagick}[https://github.com/minimagick/minimagick] for the actual transformations
+# of the file, so you must add <tt>gem "mini_magick"</tt> to your Gemfile if you wish to use variants.
+#
+# Note that to create a variant it's necessary to download the entire blob file from the service and load it
+# into memory. The larger the image, the more memory is used. 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::VariantsController.
+#
+# 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 url_for(Current.user.avatar.variant(resize: "100x100")) %>
+#
+# This will create a URL for that specific blob with that specific variant, which the ActiveStorage::VariantsController
+# 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: "100x100").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.
+#
+# A list of all possible transformations is available at https://www.imagemagick.org/script/mogrify.php. You can
+# combine as many as you like freely:
+#
+#   avatar.variant(resize: "100x100", monochrome: true, flip: "-90")
+class ActiveStorage::Variant
+  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::VariantsController, which in turn will use this +service_call+ method
+  # for its redirection.
+  def service_url(expires_in: service.url_expires_in, disposition: :inline)
+    service.url key, expires_in: expires_in, disposition: disposition, filename: blob.filename, content_type: blob.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
+      service.upload key, transform(service.download(blob.key))
+    end
+
+    def transform(io)
+      require "mini_magick"
+      File.open MiniMagick::Image.read(io).tap { |image| variation.transform(image) }.path
+    end
+end

data/app/models/active_storage/variation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# A set of transformations that can be applied to a blob to create a variant. This class is exposed via
+# the ActiveStorage::Blob#variant method and should rarely be used directly.
+#
+# In case you do need to use this directly, it's instantiated using a hash of transformations where
+# the key is the command and the value is the arguments. Example:
+#
+#   ActiveStorage::Variation.new(resize: "100x100", monochrome: true, trim: true, rotate: "-90")
+#
+# A list of all possible transformations is available at https://www.imagemagick.org/script/mogrify.php.
+class ActiveStorage::Variation
+  attr_reader :transformations
+
+  class << self
+    # Returns a Variation instance based on the given variator. If the variator is a Variation, it is
+    # returned unmodified. If it is a String, it is passed to ActiveStorage::Variation.decode. Otherwise,
+    # it is assumed to be a transformations Hash and is passed directly to the constructor.
+    def wrap(variator)
+      case variator
+      when self
+        variator
+      when String
+        decode variator
+      else
+        new variator
+      end
+    end
+
+    # Returns a Variation instance with the transformations that were encoded by +encode+.
+    def decode(key)
+      new ActiveStorage.verifier.verify(key, purpose: :variation)
+    end
+
+    # Returns a signed key for the +transformations+, which can be used to refer to a specific
+    # variation in a URL or combined key (like <tt>ActiveStorage::Variant#key</tt>).
+    def encode(transformations)
+      ActiveStorage.verifier.generate(transformations, purpose: :variation)
+    end
+  end
+
+  def initialize(transformations)
+    @transformations = transformations
+  end
+
+  # Accepts an open MiniMagick image instance, like what's returned by <tt>MiniMagick::Image.read(io)</tt>,
+  # and performs the +transformations+ against it. The transformed image instance is then returned.
+  def transform(image)
+    transformations.each do |(method, argument)|
+      if eligible_argument?(argument)
+        image.public_send(method, argument)
+      else
+        image.public_send(method)
+      end
+    end
+  end
+
+  # Returns a signed key for all the +transformations+ that this variation was instantiated with.
+  def key
+    self.class.encode(transformations)
+  end
+
+  private
+    def eligible_argument?(argument)
+      argument.present? && argument != true
+    end
+end

data/config/routes.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  get "/rails/active_storage/blobs/:signed_id/*filename" => "active_storage/blobs#show", as: :rails_service_blob, internal: true
+
+  direct :rails_blob do |blob, options|
+    route_for(:rails_service_blob, blob.signed_id, blob.filename, options)
+  end
+
+  resolve("ActiveStorage::Blob")       { |blob, options| route_for(:rails_blob, blob) }
+  resolve("ActiveStorage::Attachment") { |attachment, options| route_for(:rails_blob, attachment.blob, options) }
+
+
+  get "/rails/active_storage/variants/:signed_blob_id/:variation_key/*filename" => "active_storage/variants#show", as: :rails_blob_variation, internal: true
+
+  direct :rails_variant do |variant, options|
+    signed_blob_id = variant.blob.signed_id
+    variation_key  = variant.variation.key
+    filename       = variant.blob.filename
+
+    route_for(:rails_blob_variation, signed_blob_id, variation_key, filename, options)
+  end
+
+  resolve("ActiveStorage::Variant") { |variant, options| route_for(:rails_variant, variant, options) }
+
+
+  get "/rails/active_storage/previews/:signed_blob_id/:variation_key/*filename" => "active_storage/previews#show", as: :rails_blob_preview, internal: true
+
+  direct :rails_preview do |preview, options|
+    signed_blob_id = preview.blob.signed_id
+    variation_key  = preview.variation.key
+    filename       = preview.blob.filename
+
+    route_for(:rails_blob_preview, signed_blob_id, variation_key, filename, options)
+  end
+
+  resolve("ActiveStorage::Preview") { |preview, options| route_for(:rails_preview, preview, options) }
+
+
+  get  "/rails/active_storage/disk/:encoded_key/*filename" => "active_storage/disk#show", as: :rails_disk_service, internal: true
+  put  "/rails/active_storage/disk/:encoded_token" => "active_storage/disk#update", as: :update_rails_disk_service, internal: true
+  post "/rails/active_storage/direct_uploads" => "active_storage/direct_uploads#create", as: :rails_direct_uploads, internal: true
+end

data/lib/active_storage.rb

@@ -1,9 +1,44 @@
+# frozen_string_literal: true
+
+#--
+# Copyright (c) 2017 David Heinemeier Hansson
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
 require "active_record"
-require "active_storage/railtie" if defined?(Rails)
+require "active_support"
+require "active_support/rails"
+require "active_storage/version"
 
 module ActiveStorage
   extend ActiveSupport::Autoload
 
-  autoload :Blob
+  autoload :Attached
   autoload :Service
+  autoload :Previewer
+  autoload :Analyzer
+
+  mattr_accessor :logger
+  mattr_accessor :verifier
+  mattr_accessor :queue
+  mattr_accessor :previewers, default: []
+  mattr_accessor :analyzers, default: []
 end