activestorage 0.1 → 5.2.0.beta1

data/lib/active_storage/downloading.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Downloading
+    private
+      # Opens a new tempfile in #tempdir and copies blob data into it. Yields the tempfile.
+      def download_blob_to_tempfile # :doc:
+        Tempfile.open("ActiveStorage", tempdir) do |file|
+          download_blob_to file
+          yield file
+        end
+      end
+
+      # Efficiently downloads blob data into the given file.
+      def download_blob_to(file) # :doc:
+        file.binmode
+        blob.download { |chunk| file.write(chunk) }
+        file.rewind
+      end
+
+      # Returns the directory in which tempfiles should be opened. Defaults to +Dir.tmpdir+.
+      def tempdir # :doc:
+        Dir.tmpdir
+      end
+  end
+end

data/lib/active_storage/engine.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_storage"
+
+require "active_storage/previewer/pdf_previewer"
+require "active_storage/previewer/video_previewer"
+
+require "active_storage/analyzer/image_analyzer"
+require "active_storage/analyzer/video_analyzer"
+
+module ActiveStorage
+  class Engine < Rails::Engine # :nodoc:
+    isolate_namespace ActiveStorage
+
+    config.active_storage = ActiveSupport::OrderedOptions.new
+    config.active_storage.previewers = [ ActiveStorage::Previewer::PDFPreviewer, ActiveStorage::Previewer::VideoPreviewer ]
+    config.active_storage.analyzers  = [ ActiveStorage::Analyzer::ImageAnalyzer, ActiveStorage::Analyzer::VideoAnalyzer ]
+
+    config.eager_load_namespaces << ActiveStorage
+
+    initializer "active_storage.configs" do
+      config.after_initialize do |app|
+        ActiveStorage.logger     = app.config.active_storage.logger || Rails.logger
+        ActiveStorage.queue      = app.config.active_storage.queue
+        ActiveStorage.previewers = app.config.active_storage.previewers || []
+        ActiveStorage.analyzers  = app.config.active_storage.analyzers || []
+      end
+    end
+
+    initializer "active_storage.attached" do
+      require "active_storage/attached"
+
+      ActiveSupport.on_load(:active_record) do
+        extend ActiveStorage::Attached::Macros
+      end
+    end
+
+    initializer "active_storage.verifier" do
+      config.after_initialize do |app|
+        ActiveStorage.verifier = app.message_verifier("ActiveStorage")
+      end
+    end
+
+    initializer "active_storage.services" do
+      config.to_prepare do
+        if config_choice = Rails.configuration.active_storage.service
+          configs = Rails.configuration.active_storage.service_configurations ||= begin
+            config_file = Pathname.new(Rails.root.join("config/storage.yml"))
+            raise("Couldn't find Active Storage configuration in #{config_file}") unless config_file.exist?
+
+            require "yaml"
+            require "erb"
+
+            YAML.load(ERB.new(config_file.read).result) || {}
+          rescue Psych::SyntaxError => e
+            raise "YAML syntax error occurred while parsing #{config_file}. " \
+                  "Please note that YAML must be consistently indented using spaces. Tabs are not allowed. " \
+                  "Error: #{e.message}"
+          end
+
+          ActiveStorage::Blob.service =
+            begin
+              ActiveStorage::Service.configure config_choice, configs
+            rescue => e
+              raise e, "Cannot load `Rails.config.active_storage.service`:\n#{e.message}", e.backtrace
+            end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/gem_version.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  # Returns the version of the currently loaded Active Storage as a <tt>Gem::Version</tt>.
+  def self.gem_version
+    Gem::Version.new VERSION::STRING
+  end
+
+  module VERSION
+    MAJOR = 5
+    MINOR = 2
+    TINY  = 0
+    PRE   = "beta1"
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
+  end
+end

data/lib/active_storage/log_subscriber.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/log_subscriber"
+
+module ActiveStorage
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    def service_upload(event)
+      message = "Uploaded file to key: #{key_in(event)}"
+      message += " (checksum: #{event.payload[:checksum]})" if event.payload[:checksum]
+      info event, color(message, GREEN)
+    end
+
+    def service_download(event)
+      info event, color("Downloaded file from key: #{key_in(event)}", BLUE)
+    end
+
+    def service_delete(event)
+      info event, color("Deleted file from key: #{key_in(event)}", RED)
+    end
+
+    def service_exist(event)
+      debug event, color("Checked if file exists at key: #{key_in(event)} (#{event.payload[:exist] ? "yes" : "no"})", BLUE)
+    end
+
+    def service_url(event)
+      debug event, color("Generated URL for file at key: #{key_in(event)} (#{event.payload[:url]})", BLUE)
+    end
+
+    def logger
+      ActiveStorage.logger
+    end
+
+    private
+      def info(event, colored_message)
+        super log_prefix_for_service(event) + colored_message
+      end
+
+      def debug(event, colored_message)
+        super log_prefix_for_service(event) + colored_message
+      end
+
+      def log_prefix_for_service(event)
+        color "  #{event.payload[:service]} Storage (#{event.duration.round(1)}ms) ", CYAN
+      end
+
+      def key_in(event)
+        event.payload[:key]
+      end
+  end
+end
+
+ActiveStorage::LogSubscriber.attach_to :active_storage

data/lib/active_storage/previewer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_storage/downloading"
+
+module ActiveStorage
+  # This is an abstract base class for previewers, which generate images from blobs. See
+  # ActiveStorage::Previewer::PDFPreviewer and ActiveStorage::Previewer::VideoPreviewer for examples of
+  # concrete subclasses.
+  class Previewer
+    include Downloading
+
+    attr_reader :blob
+
+    # Implement this method in a concrete subclass. Have it return true when given a blob from which
+    # the previewer can generate an image.
+    def self.accept?(blob)
+      false
+    end
+
+    def initialize(blob)
+      @blob = blob
+    end
+
+    # Override this method in a concrete subclass. Have it yield an attachable preview image (i.e.
+    # anything accepted by ActiveStorage::Attached::One#attach).
+    def preview
+      raise NotImplementedError
+    end
+
+    private
+      # Executes a system command, capturing its binary output in a tempfile. Yields the tempfile.
+      #
+      # Use this method to shell out to a system library (e.g. mupdf or ffmpeg) for preview image
+      # generation. The resulting tempfile can be used as the +:io+ value in an attachable Hash:
+      #
+      #   def preview
+      #     download_blob_to_tempfile do |input|
+      #       draw "my-drawing-command", input.path, "--format", "png", "-" do |output|
+      #         yield io: output, filename: "#{blob.filename.base}.png", content_type: "image/png"
+      #       end
+      #     end
+      #   end
+      #
+      # The output tempfile is opened in the directory returned by ActiveStorage::Downloading#tempdir.
+      def draw(*argv) # :doc:
+        Tempfile.open("ActiveStorage", tempdir) do |file|
+          capture(*argv, to: file)
+          yield file
+        end
+      end
+
+      def capture(*argv, to:)
+        to.binmode
+        IO.popen(argv) { |out| IO.copy_stream(out, to) }
+        to.rewind
+      end
+  end
+end

data/lib/active_storage/previewer/pdf_previewer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  class Previewer::PDFPreviewer < Previewer
+    def self.accept?(blob)
+      blob.content_type == "application/pdf"
+    end
+
+    def preview
+      download_blob_to_tempfile do |input|
+        draw "mutool", "draw", "-F", "png", "-o", "-", input.path, "1" do |output|
+          yield io: output, filename: "#{blob.filename.base}.png", content_type: "image/png"
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/previewer/video_previewer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  class Previewer::VideoPreviewer < Previewer
+    def self.accept?(blob)
+      blob.video?
+    end
+
+    def preview
+      download_blob_to_tempfile do |input|
+        draw_relevant_frame_from input do |output|
+          yield io: output, filename: "#{blob.filename.base}.png", content_type: "image/png"
+        end
+      end
+    end
+
+    private
+      def draw_relevant_frame_from(file, &block)
+        draw "ffmpeg", "-i", file.path, "-y", "-vcodec", "png",
+          "-vf", "thumbnail", "-vframes", "1", "-f", "image2", "-", &block
+      end
+  end
+end

data/lib/active_storage/service.rb

@@ -1,34 +1,122 @@
-# Abstract class serving as an interface for concrete services.
-class ActiveStorage::Service
-  class ActiveStorage::IntegrityError < StandardError; end
+# frozen_string_literal: true
 
-  def self.configure(service, **options)
-    begin
-      require "active_storage/service/#{service.to_s.downcase}_service"
-      ActiveStorage::Service.const_get(:"#{service}Service").new(**options)
-    rescue LoadError => e
-      puts "Couldn't configure service: #{service} (#{e.message})"
+require "active_storage/log_subscriber"
+
+module ActiveStorage
+  class IntegrityError < StandardError; end
+
+  # Abstract class serving as an interface for concrete services.
+  #
+  # The available services are:
+  #
+  # * +Disk+, to manage attachments saved directly on the hard drive.
+  # * +GCS+, to manage attachments through Google Cloud Storage.
+  # * +S3+, to manage attachments through Amazon S3.
+  # * +AzureStorage+, to manage attachments through Microsoft Azure Storage.
+  # * +Mirror+, to be able to use several services to manage attachments.
+  #
+  # Inside a Rails application, you can set-up your services through the
+  # generated <tt>config/storage.yml</tt> file and reference one
+  # of the aforementioned constant under the +service+ key. For example:
+  #
+  #   local:
+  #     service: Disk
+  #     root: <%= Rails.root.join("storage") %>
+  #
+  # You can checkout the service's constructor to know which keys are required.
+  #
+  # Then, in your application's configuration, you can specify the service to
+  # use like this:
+  #
+  #   config.active_storage.service = :local
+  #
+  # If you are using Active Storage outside of a Ruby on Rails application, you
+  # can configure the service to use like this:
+  #
+  #   ActiveStorage::Blob.service = ActiveStorage::Service.configure(
+  #     :Disk,
+  #     root: Pathname("/foo/bar/storage")
+  #   )
+  class Service
+    extend ActiveSupport::Autoload
+    autoload :Configurator
+
+    class_attribute :url_expires_in, default: 5.minutes
+
+    class << self
+      # Configure an Active Storage service by name from a set of configurations,
+      # typically loaded from a YAML file. The Active Storage engine uses this
+      # to set the global Active Storage service when the app boots.
+      def configure(service_name, configurations)
+        Configurator.build(service_name, configurations)
+      end
+
+      # Override in subclasses that stitch together multiple services and hence
+      # need to build additional services using the configurator.
+      #
+      # Passes the configurator and all of the service's config as keyword args.
+      #
+      # See MirrorService for an example.
+      def build(configurator:, service: nil, **service_config) #:nodoc:
+        new(**service_config)
+      end
     end
-  end
 
+    # Upload the +io+ to the +key+ specified. If a +checksum+ is provided, the service will
+    # ensure a match when the upload has completed or raise an ActiveStorage::IntegrityError.
+    def upload(key, io, checksum: nil)
+      raise NotImplementedError
+    end
 
-  def upload(key, io, checksum: nil)
-    raise NotImplementedError
-  end
+    # Return the content of the file at the +key+.
+    def download(key)
+      raise NotImplementedError
+    end
 
-  def download(key)
-    raise NotImplementedError
-  end
+    # Delete the file at the +key+.
+    def delete(key)
+      raise NotImplementedError
+    end
 
-  def delete(key)
-    raise NotImplementedError
-  end
+    # Return +true+ if a file exists at the +key+.
+    def exist?(key)
+      raise NotImplementedError
+    end
 
-  def exist?(key)
-    raise NotImplementedError
-  end
+    # Returns a signed, temporary URL for the file at the +key+. The URL will be valid for the amount
+    # of seconds specified in +expires_in+. You most also provide the +disposition+ (+:inline+ or +:attachment+),
+    # +filename+, and +content_type+ that you wish the file to be served with on request.
+    def url(key, expires_in:, disposition:, filename:, content_type:)
+      raise NotImplementedError
+    end
+
+    # Returns a signed, temporary URL that a direct upload file can be PUT to on the +key+.
+    # The URL will be valid for the amount of seconds specified in +expires_in+.
+    # You most also provide the +content_type+, +content_length+, and +checksum+ of the file
+    # that will be uploaded. All these attributes will be validated by the service upon upload.
+    def url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:)
+      raise NotImplementedError
+    end
+
+    # Returns a Hash of headers for +url_for_direct_upload+ requests.
+    def headers_for_direct_upload(key, filename:, content_type:, content_length:, checksum:)
+      {}
+    end
+
+    private
+      def instrument(operation, key, payload = {}, &block)
+        ActiveSupport::Notifications.instrument(
+          "service_#{operation}.active_storage",
+          payload.merge(key: key, service: service_name), &block)
+      end
+
+      def service_name
+        # ActiveStorage::Service::DiskService => Disk
+        self.class.name.split("::").third.remove("Service")
+      end
 
-  def url(key, expires_in:, disposition:, filename:)
-    raise NotImplementedError
+      def content_disposition_with(type: "inline", filename:)
+        (type.to_s.presence_in(%w( attachment inline )) || "inline") + "; #{filename.parameters}"
+      end
   end
 end

data/lib/active_storage/service/azure_storage_service.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/bytes"
+require "azure/storage"
+require "azure/storage/core/auth/shared_access_signature"
+
+module ActiveStorage
+  # Wraps the Microsoft Azure Storage Blob Service as an Active Storage service.
+  # See ActiveStorage::Service for the generic API documentation that applies to all services.
+  class Service::AzureStorageService < Service
+    attr_reader :client, :path, :blobs, :container, :signer
+
+    def initialize(path:, storage_account_name:, storage_access_key:, container:)
+      @client = Azure::Storage::Client.create(storage_account_name: storage_account_name, storage_access_key: storage_access_key)
+      @signer = Azure::Storage::Core::Auth::SharedAccessSignature.new(storage_account_name, storage_access_key)
+      @blobs = client.blob_client
+      @container = container
+      @path = path
+    end
+
+    def upload(key, io, checksum: nil)
+      instrument :upload, key, checksum: checksum do
+        begin
+          blobs.create_block_blob(container, key, io, content_md5: checksum)
+        rescue Azure::Core::Http::HTTPError
+          raise ActiveStorage::IntegrityError
+        end
+      end
+    end
+
+    def download(key, &block)
+      if block_given?
+        instrument :streaming_download, key do
+          stream(key, &block)
+        end
+      else
+        instrument :download, key do
+          _, io = blobs.get_blob(container, key)
+          io.force_encoding(Encoding::BINARY)
+        end
+      end
+    end
+
+    def delete(key)
+      instrument :delete, key do
+        begin
+          blobs.delete_blob(container, key)
+        rescue Azure::Core::Http::HTTPError
+          false
+        end
+      end
+    end
+
+    def exist?(key)
+      instrument :exist, key do |payload|
+        answer = blob_for(key).present?
+        payload[:exist] = answer
+        answer
+      end
+    end
+
+    def url(key, expires_in:, filename:, disposition:, content_type:)
+      instrument :url, key do |payload|
+        base_url = url_for(key)
+        generated_url = signer.signed_uri(
+          URI(base_url), false,
+          permissions: "r",
+          expiry: format_expiry(expires_in),
+          content_disposition: content_disposition_with(type: disposition, filename: filename),
+          content_type: content_type
+        ).to_s
+
+        payload[:url] = generated_url
+
+        generated_url
+      end
+    end
+
+    def url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:)
+      instrument :url, key do |payload|
+        base_url = url_for(key)
+        generated_url = signer.signed_uri(URI(base_url), false, permissions: "rw",
+          expiry: format_expiry(expires_in)).to_s
+
+        payload[:url] = generated_url
+
+        generated_url
+      end
+    end
+
+    def headers_for_direct_upload(key, content_type:, checksum:, **)
+      { "Content-Type" => content_type, "Content-MD5" => checksum, "x-ms-blob-type" => "BlockBlob" }
+    end
+
+    private
+      def url_for(key)
+        "#{path}/#{container}/#{key}"
+      end
+
+      def blob_for(key)
+        blobs.get_blob_properties(container, key)
+      rescue Azure::Core::Http::HTTPError
+        false
+      end
+
+      def format_expiry(expires_in)
+        expires_in ? Time.now.utc.advance(seconds: expires_in).iso8601 : nil
+      end
+
+      # Reads the object for the given key in chunks, yielding each to the block.
+      def stream(key)
+        blob = blob_for(key)
+
+        chunk_size = 5.megabytes
+        offset = 0
+
+        while offset < blob.properties[:content_length]
+          _, chunk = blobs.get_blob(container, key, start_range: offset, end_range: offset + chunk_size - 1)
+          yield chunk.force_encoding(Encoding::BINARY)
+          offset += chunk_size
+        end
+      end
+  end
+end