activestorage 0.1 → 5.2.0.beta1

data/lib/active_storage/analyzer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_storage/downloading"
+
+module ActiveStorage
+  # This is an abstract base class for analyzers, which extract metadata from blobs. See
+  # ActiveStorage::Analyzer::ImageAnalyzer for an example of a concrete subclass.
+  class Analyzer
+    include Downloading
+
+    attr_reader :blob
+
+    # Implement this method in a concrete subclass. Have it return true when given a blob from which
+    # the analyzer can extract metadata.
+    def self.accept?(blob)
+      false
+    end
+
+    def initialize(blob)
+      @blob = blob
+    end
+
+    # Override this method in a concrete subclass. Have it return a Hash of metadata.
+    def metadata
+      raise NotImplementedError
+    end
+
+    private
+      def logger
+        ActiveStorage.logger
+      end
+  end
+end

data/lib/active_storage/analyzer/image_analyzer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  # Extracts width and height in pixels from an image blob.
+  #
+  # Example:
+  #
+  #   ActiveStorage::Analyzer::ImageAnalyzer.new(blob).metadata
+  #   # => { width: 4104, height: 2736 }
+  #
+  # This analyzer relies on the third-party {MiniMagick}[https://github.com/minimagick/minimagick] gem. MiniMagick requires
+  # the {ImageMagick}[http://www.imagemagick.org] system library. These libraries are not provided by Rails; you must
+  # install them yourself to use this analyzer.
+  class Analyzer::ImageAnalyzer < Analyzer
+    def self.accept?(blob)
+      blob.image?
+    end
+
+    def metadata
+      read_image do |image|
+        { width: image.width, height: image.height }
+      end
+    rescue LoadError
+      logger.info "Skipping image analysis because the mini_magick gem isn't installed"
+      {}
+    end
+
+    private
+      def read_image
+        download_blob_to_tempfile do |file|
+          require "mini_magick"
+          yield MiniMagick::Image.new(file.path)
+        end
+      end
+  end
+end

data/lib/active_storage/analyzer/null_analyzer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  class Analyzer::NullAnalyzer < Analyzer # :nodoc:
+    def self.accept?(blob)
+      true
+    end
+
+    def metadata
+      {}
+    end
+  end
+end

data/lib/active_storage/analyzer/video_analyzer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/compact"
+
+module ActiveStorage
+  # Extracts the following from a video blob:
+  #
+  # * Width (pixels)
+  # * Height (pixels)
+  # * Duration (seconds)
+  # * Angle (degrees)
+  # * Aspect ratio
+  #
+  # Example:
+  #
+  #   ActiveStorage::VideoAnalyzer.new(blob).metadata
+  #   # => { width: 640, height: 480, duration: 5.0, angle: 0, aspect_ratio: [4, 3] }
+  #
+  # This analyzer requires the {ffmpeg}[https://www.ffmpeg.org] system library, which is not provided by Rails. You must
+  # install ffmpeg yourself to use this analyzer.
+  class Analyzer::VideoAnalyzer < Analyzer
+    def self.accept?(blob)
+      blob.video?
+    end
+
+    def metadata
+      { width: width, height: height, duration: duration, angle: angle, aspect_ratio: aspect_ratio }.compact
+    end
+
+    private
+      def width
+        Integer(video_stream["width"]) if video_stream["width"]
+      end
+
+      def height
+        Integer(video_stream["height"]) if video_stream["height"]
+      end
+
+      def duration
+        Float(video_stream["duration"]) if video_stream["duration"]
+      end
+
+      def angle
+        Integer(tags["rotate"]) if tags["rotate"]
+      end
+
+      def aspect_ratio
+        if descriptor = video_stream["display_aspect_ratio"]
+          descriptor.split(":", 2).collect(&:to_i)
+        end
+      end
+
+
+      def tags
+        @tags ||= video_stream["tags"] || {}
+      end
+
+      def video_stream
+        @video_stream ||= streams.detect { |stream| stream["codec_type"] == "video" } || {}
+      end
+
+      def streams
+        probe["streams"] || []
+      end
+
+      def probe
+        download_blob_to_tempfile { |file| probe_from(file) }
+      end
+
+      def probe_from(file)
+        IO.popen([ "ffprobe", "-print_format", "json", "-show_streams", "-v", "error", file.path ]) do |output|
+          JSON.parse(output.read)
+        end
+      rescue Errno::ENOENT
+        logger.info "Skipping video analysis because ffmpeg isn't installed"
+        {}
+      end
+  end
+end

data/lib/active_storage/attached.rb

@@ -1,32 +1,38 @@
-require "active_storage/blob"
-require "active_storage/attachment"
+# frozen_string_literal: true
 
+require "action_dispatch"
 require "action_dispatch/http/upload"
 require "active_support/core_ext/module/delegation"
 
-class ActiveStorage::Attached
-  attr_reader :name, :record
+module ActiveStorage
+  # Abstract base class for the concrete ActiveStorage::Attached::One and ActiveStorage::Attached::Many
+  # classes that both provide proxy access to the blob association for a record.
+  class Attached
+    attr_reader :name, :record, :dependent
 
-  def initialize(name, record)
-    @name, @record = name, record
-  end
+    def initialize(name, record, dependent:)
+      @name, @record, @dependent = name, record, dependent
+    end
 
-  private
-    def create_blob_from(attachable)
-      case attachable
-      when ActiveStorage::Blob
-        attachable
-      when ActionDispatch::Http::UploadedFile
-        ActiveStorage::Blob.create_after_upload! \
-          io: attachable.open,
-          filename: attachable.original_filename,
-          content_type: attachable.content_type
-      when Hash
-        ActiveStorage::Blob.create_after_upload!(attachable)
-      else
-        nil
+    private
+      def create_blob_from(attachable)
+        case attachable
+        when ActiveStorage::Blob
+          attachable
+        when ActionDispatch::Http::UploadedFile, Rack::Test::UploadedFile
+          ActiveStorage::Blob.create_after_upload! \
+            io: attachable.open,
+            filename: attachable.original_filename,
+            content_type: attachable.content_type
+        when Hash
+          ActiveStorage::Blob.create_after_upload!(attachable)
+        when String
+          ActiveStorage::Blob.find_signed(attachable)
+        else
+          nil
+        end
       end
-    end
+  end
 end
 
 require "active_storage/attached/one"

data/lib/active_storage/attached/macros.rb

@@ -1,23 +1,96 @@
-module ActiveStorage::Attached::Macros
-  def has_one_attached(name, dependent: :purge_later)
-    define_method(name) do
-      instance_variable_get("@active_storage_attached_#{name}") || 
-        instance_variable_set("@active_storage_attached_#{name}", ActiveStorage::Attached::One.new(name, self))
-    end
+# frozen_string_literal: true
 
-    if dependent == :purge_later
-      before_destroy { public_send(name).purge_later }
-    end
-  end
+module ActiveStorage
+  # Provides the class-level DSL for declaring that an Active Record model has attached blobs.
+  module Attached::Macros
+    # Specifies the relation between a single attachment and the model.
+    #
+    #   class User < ActiveRecord::Base
+    #     has_one_attached :avatar
+    #   end
+    #
+    # There is no column defined on the model side, Active Storage takes
+    # care of the mapping between your records and the attachment.
+    #
+    # To avoid N+1 queries, you can include the attached blobs in your query like so:
+    #
+    #   User.with_attached_avatar
+    #
+    # Under the covers, this relationship is implemented as a +has_one+ association to a
+    # ActiveStorage::Attachment record and a +has_one-through+ association to a
+    # ActiveStorage::Blob record. These associations are available as +avatar_attachment+
+    # and +avatar_blob+. But you shouldn't need to work with these associations directly in
+    # most circumstances.
+    #
+    # The system has been designed to having you go through the ActiveStorage::Attached::One
+    # proxy that provides the dynamic proxy to the associations and factory methods, like +attach+.
+    #
+    # If the +:dependent+ option isn't set, the attachment will be purged
+    # (i.e. destroyed) whenever the record is destroyed.
+    def has_one_attached(name, dependent: :purge_later)
+      class_eval <<-CODE, __FILE__, __LINE__ + 1
+        def #{name}
+          @active_storage_attached_#{name} ||= ActiveStorage::Attached::One.new("#{name}", self, dependent: #{dependent == :purge_later ? ":purge_later" : "false"})
+        end
+
+        def #{name}=(attachable)
+          #{name}.attach(attachable)
+        end
+      CODE
+
+      has_one :"#{name}_attachment", -> { where(name: name) }, class_name: "ActiveStorage::Attachment", as: :record
+      has_one :"#{name}_blob", through: :"#{name}_attachment", class_name: "ActiveStorage::Blob", source: :blob
 
-  def has_many_attached(name, dependent: :purge_later)
-    define_method(name) do
-      instance_variable_get("@active_storage_attached_#{name}") || 
-        instance_variable_set("@active_storage_attached_#{name}", ActiveStorage::Attached::Many.new(name, self))
+      scope :"with_attached_#{name}", -> { includes("#{name}_attachment": :blob) }
+
+      if dependent == :purge_later
+        before_destroy { public_send(name).purge_later }
+      end
     end
 
-    if dependent == :purge_later
-      before_destroy { public_send(name).purge_later }
+    # Specifies the relation between multiple attachments and the model.
+    #
+    #   class Gallery < ActiveRecord::Base
+    #     has_many_attached :photos
+    #   end
+    #
+    # There are no columns defined on the model side, Active Storage takes
+    # care of the mapping between your records and the attachments.
+    #
+    # To avoid N+1 queries, you can include the attached blobs in your query like so:
+    #
+    #   Gallery.where(user: Current.user).with_attached_photos
+    #
+    # Under the covers, this relationship is implemented as a +has_many+ association to a
+    # ActiveStorage::Attachment record and a +has_many-through+ association to a
+    # ActiveStorage::Blob record. These associations are available as +photos_attachments+
+    # and +photos_blobs+. But you shouldn't need to work with these associations directly in
+    # most circumstances.
+    #
+    # The system has been designed to having you go through the ActiveStorage::Attached::Many
+    # proxy that provides the dynamic proxy to the associations and factory methods, like +#attach+.
+    #
+    # If the +:dependent+ option isn't set, all the attachments will be purged
+    # (i.e. destroyed) whenever the record is destroyed.
+    def has_many_attached(name, dependent: :purge_later)
+      class_eval <<-CODE, __FILE__, __LINE__ + 1
+        def #{name}
+          @active_storage_attached_#{name} ||= ActiveStorage::Attached::Many.new("#{name}", self, dependent: #{dependent == :purge_later ? ":purge_later" : "false"})
+        end
+
+        def #{name}=(attachables)
+          #{name}.attach(attachables)
+        end
+      CODE
+
+      has_many :"#{name}_attachments", -> { where(name: name) }, as: :record, class_name: "ActiveStorage::Attachment"
+      has_many :"#{name}_blobs", through: :"#{name}_attachments", class_name: "ActiveStorage::Blob", source: :blob
+
+      scope :"with_attached_#{name}", -> { includes("#{name}_attachments": :blob) }
+
+      if dependent == :purge_later
+        before_destroy { public_send(name).purge_later }
+      end
     end
   end
 end

data/lib/active_storage/attached/many.rb

@@ -1,31 +1,63 @@
-class ActiveStorage::Attached::Many < ActiveStorage::Attached
-  delegate_missing_to :attachments
+# frozen_string_literal: true
 
-  def attachments
-    @attachments ||= ActiveStorage::Attachment.where(record_gid: record.to_gid.to_s, name: name)
-  end
+module ActiveStorage
+  # Decorated proxy object representing of multiple attachments to a model.
+  class Attached::Many < Attached
+    delegate_missing_to :attachments
 
-  def attach(*attachables)
-    @attachments = attachments | Array(attachables).flatten.collect do |attachable|
-      ActiveStorage::Attachment.create!(record_gid: record.to_gid.to_s, name: name, blob: create_blob_from(attachable))
+    # Returns all the associated attachment records.
+    #
+    # All methods called on this proxy object that aren't listed here will automatically be delegated to +attachments+.
+    def attachments
+      record.public_send("#{name}_attachments")
     end
-  end
 
-  def attached?
-    attachments.any?
-  end
+    # Associates one or several attachments with the current record, saving them to the database.
+    #
+    #   document.images.attach(params[:images]) # Array of ActionDispatch::Http::UploadedFile objects
+    #   document.images.attach(params[:signed_blob_id]) # Signed reference to blob from direct upload
+    #   document.images.attach(io: File.open("/path/to/racecar.jpg"), filename: "racecar.jpg", content_type: "image/jpg")
+    #   document.images.attach([ first_blob, second_blob ])
+    def attach(*attachables)
+      attachables.flatten.collect do |attachable|
+        if record.new_record?
+          attachments.build(record: record, blob: create_blob_from(attachable))
+        else
+          attachments.create!(record: record, blob: create_blob_from(attachable))
+        end
+      end
+    end
 
-  def purge
-    if attached?
-      attachments.each(&:purge)
-      @attachments = nil
+    # Returns true if any attachments has been made.
+    #
+    #   class Gallery < ActiveRecord::Base
+    #     has_many_attached :photos
+    #   end
+    #
+    #   Gallery.new.photos.attached? # => false
+    def attached?
+      attachments.any?
+    end
+
+    # Deletes associated attachments without purging them, leaving their respective blobs in place.
+    def detach
+      attachments.destroy_all if attached?
+    end
+
+    # Directly purges each associated attachment (i.e. destroys the blobs and
+    # attachments and deletes the files on the service).
+    def purge
+      if attached?
+        attachments.each(&:purge)
+        attachments.reload
+      end
     end
-  end
 
-  def purge_later
-    if attached?
-      attachments.each(&:purge_later)
-      @attachments = nil
+    # Purges each associated attachment through the queuing system.
+    def purge_later
+      if attached?
+        attachments.each(&:purge_later)
+      end
     end
   end
 end

data/lib/active_storage/attached/one.rb

@@ -1,29 +1,83 @@
-class ActiveStorage::Attached::One < ActiveStorage::Attached
-  delegate_missing_to :attachment
+# frozen_string_literal: true
 
-  def attachment
-    @attachment ||= ActiveStorage::Attachment.find_by(record_gid: record.to_gid.to_s, name: name)
-  end
+module ActiveStorage
+  # Representation of a single attachment to a model.
+  class Attached::One < Attached
+    delegate_missing_to :attachment
 
-  def attach(attachable)
-    @attachment = ActiveStorage::Attachment.create!(record_gid: record.to_gid.to_s, name: name, blob: create_blob_from(attachable))
-  end
+    # Returns the associated attachment record.
+    #
+    # You don't have to call this method to access the attachment's methods as
+    # they are all available at the model level.
+    def attachment
+      record.public_send("#{name}_attachment")
+    end
 
-  def attached?
-    attachment.present?
-  end
+    # Associates a given attachment with the current record, saving it to the database.
+    #
+    #   person.avatar.attach(params[:avatar]) # ActionDispatch::Http::UploadedFile object
+    #   person.avatar.attach(params[:signed_blob_id]) # Signed reference to blob from direct upload
+    #   person.avatar.attach(io: File.open("/path/to/face.jpg"), filename: "face.jpg", content_type: "image/jpg")
+    #   person.avatar.attach(avatar_blob) # ActiveStorage::Blob object
+    def attach(attachable)
+      if attached? && dependent == :purge_later
+        replace attachable
+      else
+        write_attachment build_attachment_from(attachable)
+      end
+    end
 
-  def purge
-    if attached?
-      attachment.purge
-      @attachment = nil
+    # Returns +true+ if an attachment has been made.
+    #
+    #   class User < ActiveRecord::Base
+    #     has_one_attached :avatar
+    #   end
+    #
+    #   User.new.avatar.attached? # => false
+    def attached?
+      attachment.present?
     end
-  end
 
-  def purge_later
-    if attached?
-      attachment.purge_later
-      @attachment = nil
+    # Deletes the attachment without purging it, leaving its blob in place.
+    def detach
+      if attached?
+        attachment.destroy
+        write_attachment nil
+      end
     end
+
+    # Directly purges the attachment (i.e. destroys the blob and
+    # attachment and deletes the file on the service).
+    def purge
+      if attached?
+        attachment.purge
+        write_attachment nil
+      end
+    end
+
+    # Purges the attachment through the queuing system.
+    def purge_later
+      if attached?
+        attachment.purge_later
+      end
+    end
+
+    private
+      def replace(attachable)
+        blob.tap do
+          transaction do
+            detach
+            write_attachment build_attachment_from(attachable)
+          end
+        end.purge_later
+      end
+
+      def build_attachment_from(attachable)
+        ActiveStorage::Attachment.new(record: record, name: name, blob: create_blob_from(attachable))
+      end
+
+      def write_attachment(attachment)
+        record.public_send("#{name}_attachment=", attachment)
+      end
   end
 end