shrine 2.13.0 → 2.14.0

data/doc/multiple_files.md

@@ -36,9 +36,9 @@ attributes:
 Album.create(
   title: "My Album",
   photos_attributes: [
-    { image: File.open("image1.jpg", "rb") },
-    { image: File.open("image2.jpg", "rb") },
-    { image: File.open("image3.jpg", "rb") },
+    { image: File.open("image1.jpg", binmode: true) },
+    { image: File.open("image2.jpg", binmode: true) },
+    { image: File.open("image3.jpg", binmode: true) },
   ]
 )
 ```

data/doc/processing.md

@@ -71,7 +71,7 @@ class ImageUploader < Shrine
 
     original.close!
 
-    File.open(optimized_path, "rb")
+    File.open(optimized_path, binmode: true)
   end
 end
 ```

data/doc/retrieving_uploads.md

@@ -0,0 +1,184 @@
+# Retrieving Uploads
+
+Uploaded file content is typically retrieved from the storage using a
+`Shrine::UploadedFile` object. This guide explains the various methods of
+retrieving file content and how do they work.
+
+For context, `Shrine::UploadedFile` object is what is returned by the
+attachment reader method on the model instance (e.g. `photo.image`),
+`Shrine::Attacher#get` if you're using the attacher directly, or
+`Shrine#upload` if you're using the uploader directly.
+
+## IO-like interface
+
+In order for `Shrine::UploadedFile` objects to be uploadable to a storage, they
+too conform to Shrine's IO-like interface, meaning they implement `#read`,
+`#rewind`, `#eof?`, and `#close` matching the behaviour of the same methods on
+Ruby's IO class.
+
+```rb
+uploaded_file.eof?   # => false
+uploaded_file.read   # => "..."
+uploaded_file.eof?   # => true
+uploaded_file.rewind # rewinds the underlying IO object
+uploaded_file.eof?   # => false
+uploaded_file.close  # closes the underlying IO object (this should be called when you're done)
+```
+
+In reality these methods are simply delegated on the IO object returned by the
+`Storage#open` method of the underlying Shrine storage. For
+`Shrine::Storage::FileSystem` this IO object will be a `File` object, while for
+`Shrine::Storage::S3` (and most other remote storages) it will be a
+[`Down::ChunkedIO`] object. `Storage#open` is implicitly called when any of
+these IO methods are called for the first time.
+
+```rb
+uploaded_file.read(10) # calls `Storage#open` and assigns result to an instance variable
+uploaded_file.read(10)
+# ...
+```
+
+You can retrieve the underlying IO object returned by `Storage#open` with
+`#to_io`:
+
+```rb
+uploaded_file.to_io # the underlying IO object returned by `Storage#open`
+```
+
+## Opening
+
+The `Shrine::UploadedFile#open` method can be used to open the uploaded file
+explicitly:
+
+```rb
+uploaded_file.open # calls `Storage#open` and assigns result to an instance variable
+uploaded_file.read
+uploaded_file.close
+```
+
+This is useful if you want to control where `Storage#open` will be called. It's
+also useful if you want to pass additional parameters to `Storage#open`, which
+will depend on the storage. For example, if you're using S3 storage and
+server-side encryption, you can pass the necessary server-side-encryption
+parameters to `Shrine::Storage::S3#open`:
+
+```rb
+# server-side encryption parameters for S3 storage
+uploaded_file.open(
+ sse_customer_algorithm: "AES256",
+ sse_customer_key:       "secret_key",
+ sse_customer_key_md5:   "secret_key_md5",
+)
+```
+
+`Shrine::UploadedFile#open` also accepts a block, which will ensure that the
+underlying IO object is closed at the end of the block.
+
+```rb
+uploaded_file.open do
+  uploaded_file.read(1000)
+  # ...
+end # underlying IO object is closed
+```
+
+`Shrine::UploadedFile#open` will return the result of a given block.
+block. We can use that to safely retrieve the whole content of a file, without
+leaving any temporary files lying around.
+
+```rb
+content = uploaded_file.open(&:read) # open, read, and close
+content # uploaded file content
+```
+
+## Streaming
+
+The `Shrine::UploadedFile#stream` method can be used to stream uploaded file
+content to a writable destination object.
+
+```rb
+destination = StringIO.new # from the "stringio" standard library
+uploaded_file.stream(destination)
+destination.rewind
+
+destination # holds the file content
+```
+
+The destination object can be any object that responds to `#write` and returns
+number of bytes written, or a path string.
+
+`Shrine::UploadedFile#stream` will play nicely with
+`Shrine::UploadedFile#open`, meaning it will not re-open the uploaded file if
+it's already opened.
+
+```rb
+uploaded_file.open do
+  uploaded_file.stream(destination)
+end
+```
+
+Any additional parameters to `Shrine::UploadeFile#stream` are forwarded to
+`Storage#open`. For example, if you're using S3 storage, you can tell AWS S3 to
+use HTTP compression for the download request:
+
+```rb
+uploaded_file.stream(destination, response_content_encoding: "gzip")
+```
+
+If you want to stream uploaded file content to the response body in a Rack
+application (Rails, Sinatra, Roda etc), see the `rack_response` plugin.
+
+## Downloading
+
+The `Shrine::UploadedFile#download` method can be used to download uploaded
+file content do disk. Internally a temporary file will be created (using the
+`tempfile` standard library) and passed to `Shrine::UploadedFile#stream`. The
+return value is an open `Tempfile` object (a delegate of the `File` class).
+
+```rb
+tempfile = uploaded_file.download
+tempfile #=> #<Tempfile:...>
+
+tempfile.path   #=> "/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20181227-2915-m2l6c1"
+tempfile.read   #=> "..."
+tempfile.close! # close and unlink
+```
+
+Like `Shrine::UploadedFile#open`, `Shrine::UploadedFile#download` accepts a
+block as well. The `Tempfile` object is yielded to the block, and after the
+block finishes it's automatically closed and deleted.
+
+```rb
+uploaded_file.download do |tempfile|
+  tempfile.path   #=> "/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20181227-2915-m2l6c1"
+  tempfile.read   #=> "..."
+  # ...
+end # tempfile is closed and deleted
+```
+
+Since `Shrine::UploadedFile#download` internally uses
+`Shrine::UploadedFile#stream`, it plays nicely with `Shrine::UploadedFile#open`
+as well, meaning it will only open the uploaded file if it's not already
+opened.
+
+```rb
+uploaded_file.open do
+  tempfile = uploaded_file.download
+  # ...
+end
+```
+
+Any options passed to `Shrine::UploadedFile#download` are forwarded to
+`Storage#open` (unless the uploaded file was already opened, in which case
+`Storage#open` was already called). For example, if you're using S3 storage,
+you can tell AWS S3 to use HTTP compression for the download request:
+
+```rb
+uploaded_file.download(response_content_encoding: "gzip")
+```
+
+Every time `Shrine::UploadedFile#download` is called, it will make a new copy
+of the uploaded file content. If you plan to retrieve uploaded file content
+multiple times for the same `Shrine::UploadedFile` instance, consider using the
+`tempfile` plugin.
+
+[`Down::ChunkedIO`]: https://github.com/janko-m/down#streaming

data/lib/shrine.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
 require "shrine/version"
+require "shrine/uploaded_file"
+require "shrine/attacher"
+require "shrine/attachment"
+require "shrine/plugins"
 
 require "securerandom"
 require "json"
 require "tempfile"
 
+# Core class that represents uploader.
+# Base implementation is defined in InstanceMethods and ClassMethods.
 class Shrine
   # A generic exception used by Shrine.
   class Error < StandardError; end
@@ -27,960 +33,322 @@ class Shrine
     size:   [],
     close:  [],
   }
-  deprecate_constant(:IO_METHODS) if RUBY_VERSION > "2.3"
-
-  # Core class that represents a file uploaded to a storage. The instance
-  # methods for this class are added by Shrine::Plugins::Base::FileMethods, the
-  # class methods are added by Shrine::Plugins::Base::FileClassMethods.
-  class UploadedFile
-    @shrine_class = ::Shrine
-  end
-
-  # Core class which creates attachment modules for specified attribute names
-  # that are included into model classes. The instance methods for this class
-  # are added by Shrine::Plugins::Base::AttachmentMethods, the class methods
-  # are added by Shrine::Plugins::Base::AttachmentClassMethods.
-  class Attachment < Module
-    @shrine_class = ::Shrine
-  end
-
-  # Core class which handles attaching files to model instances. The instance
-  # methods for this class are added by Shrine::Plugins::Base::AttacherMethods,
-  # the class methods are added by Shrine::Plugins::Base::AttacherClassMethods.
-  class Attacher
-    @shrine_class = ::Shrine
-  end
+  deprecate_constant(:IO_METHODS)
 
   @opts = {}
   @storages = {}
 
-  # Module in which all Shrine plugins should be stored. Also contains logic
-  # for registering and loading plugins.
-  module Plugins
-    @plugins = {}
-
-    # If the registered plugin already exists, use it. Otherwise, require it
-    # and return it. This raises a LoadError if such a plugin doesn't exist,
-    # or a Shrine::Error if it exists but it does not register itself
-    # correctly.
-    def self.load_plugin(name)
-      unless plugin = @plugins[name]
-        require "shrine/plugins/#{name}"
-        raise Error, "plugin #{name} did not register itself correctly in Shrine::Plugins" unless plugin = @plugins[name]
-      end
-      plugin
-    end
-
-    # Register the given plugin with Shrine, so that it can be loaded using
-    # `Shrine.plugin` with a symbol. Should be used by plugin files. Example:
-    #
-    #     Shrine::Plugins.register_plugin(:plugin_name, PluginModule)
-    def self.register_plugin(name, mod)
-      @plugins[name] = mod
-    end
-
-    # The base plugin for Shrine, implementing all default functionality.
-    # Methods are put into a plugin so future plugins can easily override
-    # them and call `super` to get the default behavior.
-    module Base
-      module ClassMethods
-        # Generic options for this class, plugins store their options here.
-        attr_reader :opts
-
-        # A hash of storages with their symbol identifiers.
-        attr_accessor :storages
-
-        # When inheriting Shrine, copy the instance variables into the subclass,
-        # and create subclasses of core classes.
-        def inherited(subclass)
-          subclass.instance_variable_set(:@opts, opts.dup)
-          subclass.opts.each do |key, value|
-            if value.is_a?(Enumerable) && !value.frozen?
-              subclass.opts[key] = value.dup
-            end
-          end
-          subclass.instance_variable_set(:@storages, storages.dup)
-
-          file_class = Class.new(self::UploadedFile)
-          file_class.shrine_class = subclass
-          subclass.const_set(:UploadedFile, file_class)
-
-          attachment_class = Class.new(self::Attachment)
-          attachment_class.shrine_class = subclass
-          subclass.const_set(:Attachment, attachment_class)
-
-          attacher_class = Class.new(self::Attacher)
-          attacher_class.shrine_class = subclass
-          subclass.const_set(:Attacher, attacher_class)
-        end
-
-        # Load a new plugin into the current class. A plugin can be a module
-        # which is used directly, or a symbol representing a registered plugin
-        # which will be required and then loaded.
-        #
-        #     Shrine.plugin MyPlugin
-        #     Shrine.plugin :my_plugin
-        def plugin(plugin, *args, &block)
-          plugin = Plugins.load_plugin(plugin) if plugin.is_a?(Symbol)
-          plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
-          self.include(plugin::InstanceMethods) if defined?(plugin::InstanceMethods)
-          self.extend(plugin::ClassMethods) if defined?(plugin::ClassMethods)
-          self::UploadedFile.include(plugin::FileMethods) if defined?(plugin::FileMethods)
-          self::UploadedFile.extend(plugin::FileClassMethods) if defined?(plugin::FileClassMethods)
-          self::Attachment.include(plugin::AttachmentMethods) if defined?(plugin::AttachmentMethods)
-          self::Attachment.extend(plugin::AttachmentClassMethods) if defined?(plugin::AttachmentClassMethods)
-          self::Attacher.include(plugin::AttacherMethods) if defined?(plugin::AttacherMethods)
-          self::Attacher.extend(plugin::AttacherClassMethods) if defined?(plugin::AttacherClassMethods)
-          plugin.configure(self, *args, &block) if plugin.respond_to?(:configure)
-          plugin
-        end
-
-        # Retrieves the storage under the given identifier (can be a Symbol or
-        # a String), and raises Shrine::Error if the storage is missing.
-        def find_storage(name)
-          storages.each { |key, value| return value if key.to_s == name.to_s }
-          raise Error, "storage #{name.inspect} isn't registered on #{self}"
-        end
-
-        # Generates an instance of Shrine::Attachment to be included in the
-        # model class. Example:
-        #
-        #     class Photo
-        #       include Shrine.attachment(:image) # creates a Shrine::Attachment object
-        #     end
-        def attachment(name, *args)
-          self::Attachment.new(name, *args)
-        end
-        alias [] attachment
-
-        # Instantiates a Shrine::UploadedFile from a hash, and optionally
-        # yields the returned object.
-        #
-        #     data = {"storage" => "cache", "id" => "abc123.jpg", "metadata" => {}}
-        #     Shrine.uploaded_file(data) #=> #<Shrine::UploadedFile>
-        def uploaded_file(object, &block)
-          case object
-          when String
-            uploaded_file(JSON.parse(object), &block)
-          when Hash
-            uploaded_file(self::UploadedFile.new(object), &block)
-          when self::UploadedFile
-            object.tap { |f| yield(f) if block_given? }
-          else
-            raise Error, "cannot convert #{object.inspect} to a #{self}::UploadedFile"
-          end
-        end
-
-        # Temporarily converts an IO-like object into a file. If the input IO
-        # object is already a file, it simply yields it to the block, otherwise
-        # it copies IO content into a Tempfile object which is then yielded and
-        # afterwards deleted.
-        #
-        #     Shrine.with_file(io) { |file| file.path }
-        def with_file(io)
-          if io.respond_to?(:path)
-            yield io
-          elsif io.is_a?(UploadedFile)
-            io.download { |tempfile| yield tempfile }
-          else
-            Tempfile.create("shrine-file", binmode: true) do |file|
-              IO.copy_stream(io, file.path)
-              io.rewind
-
-              yield file
-            end
-          end
-        end
-
-        # Prints a deprecation warning to standard error.
-        def deprecation(message)
-          warn "SHRINE DEPRECATION WARNING: #{message}"
-        end
-      end
-
-      module InstanceMethods
-        # The symbol identifier for the storage used by the uploader.
-        attr_reader :storage_key
-
-        # The storage object used by the uploader.
-        attr_reader :storage
-
-        # Accepts a storage symbol registered in `Shrine.storages`.
-        def initialize(storage_key)
-          @storage = self.class.find_storage(storage_key)
-          @storage_key = storage_key.to_sym
-        end
-
-        # The class-level options hash. This should probably not be modified at
-        # the instance level.
-        def opts
-          self.class.opts
-        end
-
-        # The main method for uploading files. Takes an IO-like object and an
-        # optional context hash (used internally by Shrine::Attacher). It calls
-        # user-defined #process, and afterwards it calls #store. The `io` is
-        # closed after upload.
-        def upload(io, context = {})
-          io = processed(io, context) || io
-          store(io, context)
-        end
-
-        # User is expected to perform processing inside this method, and
-        # return the processed files. Returning nil signals that no proccessing
-        # has been done and that the original file should be used.
-        #
-        #     class ImageUploader < Shrine
-        #       def process(io, context)
-        #         # do processing and return processed files
-        #       end
-        #     end
-        def process(io, context = {})
-        end
-
-        # Uploads the file and returns an instance of Shrine::UploadedFile. By
-        # default the location of the file is automatically generated by
-        # \#generate_location, but you can pass in `:location` to upload to
-        # a specific location.
-        #
-        #     uploader.store(io)
-        def store(io, context = {})
-          _store(io, context)
-        end
-
-        # Returns true if the storage of the given uploaded file matches the
-        # storage of this uploader.
-        def uploaded?(uploaded_file)
-          uploaded_file.storage_key == storage_key.to_s
-        end
-
-        # Deletes the given uploaded file and returns it.
-        def delete(uploaded_file, context = {})
-          _delete(uploaded_file, context)
-          uploaded_file
-        end
-
-        # Generates a unique location for the uploaded file, preserving the
-        # file extension. Can be overriden in uploaders for generating custom
-        # location.
-        def generate_location(io, context = {})
-          extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
-          extension ||= File.extname(extract_filename(io).to_s).downcase
-          basename    = generate_uid(io)
-
-          basename + extension
-        end
-
-        # Extracts filename, size and MIME type from the file, which is later
-        # accessible through UploadedFile#metadata.
-        def extract_metadata(io, context = {})
-          {
-            "filename"  => extract_filename(io),
-            "size"      => extract_size(io),
-            "mime_type" => extract_mime_type(io),
-          }
-        end
-
-        private
-
-        # Attempts to extract the appropriate filename from the IO object.
-        def extract_filename(io)
-          if io.respond_to?(:original_filename)
-            io.original_filename
-          elsif io.respond_to?(:path)
-            File.basename(io.path)
-          end
-        end
-
-        # Attempts to extract the MIME type from the IO object.
-        def extract_mime_type(io)
-          if io.respond_to?(:content_type)
-            warn "The \"mime_type\" Shrine metadata field will be set from the \"Content-Type\" request header, which might not hold the actual MIME type of the file. It is recommended to load the determine_mime_type plugin which determines MIME type from file content."
-            io.content_type
-          end
-        end
-
-        # Extracts the filesize from the IO object.
-        def extract_size(io)
-          io.size if io.respond_to?(:size)
-        end
-
-        # It first asserts that `io` is a valid IO object. It then extracts
-        # metadata and generates the location, before calling the storage to
-        # upload the IO object, passing the extracted metadata and location.
-        # Finally it returns a Shrine::UploadedFile object which represents the
-        # file that was uploaded.
-        def _store(io, context)
-          _enforce_io(io)
-
-          metadata = get_metadata(io, context)
-          metadata = metadata.merge(context[:metadata]) if context[:metadata]
-
-          location = get_location(io, context.merge(metadata: metadata))
+  module ClassMethods
+    # Generic options for this class, plugins store their options here.
+    attr_reader :opts
 
-          put(io, context.merge(location: location, metadata: metadata))
+    # A hash of storages with their symbol identifiers.
+    attr_accessor :storages
 
-          self.class.uploaded_file(
-            "id"       => location,
-            "storage"  => storage_key.to_s,
-            "metadata" => metadata,
-          )
-        end
-
-        # Delegates to #remove.
-        def _delete(uploaded_file, context)
-          remove(uploaded_file, context)
-        end
-
-        # Delegates to #copy.
-        def put(io, context)
-          copy(io, context)
-        end
-
-        # Calls `#upload` on the storage, passing to it the location, metadata
-        # and any upload options. The storage might modify the location or
-        # metadata that were passed in. The uploaded IO is then closed.
-        def copy(io, context)
-          location       = context[:location]
-          metadata       = context[:metadata]
-          upload_options = context[:upload_options] || {}
-
-          storage.upload(io, location, shrine_metadata: metadata, **upload_options)
-        ensure
-          io.close rescue nil
-        end
-
-        # Delegates to `UploadedFile#delete`.
-        def remove(uploaded_file, context)
-          uploaded_file.delete
-        end
-
-        # Delegates to #process.
-        def processed(io, context)
-          process(io, context)
-        end
-
-        # Retrieves the location for the given IO and context. First it looks
-        # for the `:location` option, otherwise it calls #generate_location.
-        def get_location(io, context)
-          location = context[:location] || generate_location(io, context)
-          location or raise Error, "location generated for #{io.inspect} was nil (context = #{context})"
-        end
-
-        # If the IO object is a Shrine::UploadedFile, it simply copies over its
-        # metadata, otherwise it calls #extract_metadata.
-        def get_metadata(io, context)
-          if io.is_a?(UploadedFile)
-            io.metadata.dup
-          else
-            extract_metadata(io, context)
-          end
-        end
-
-        # Asserts that the object is a valid IO object, specifically that it
-        # responds to `#read`, `#eof?`, `#rewind`, `#size` and `#close`. If the
-        # object doesn't respond to one of these methods, a Shrine::InvalidFile
-        # error is raised.
-        def _enforce_io(io)
-          missing_methods = %i[read eof? rewind close].select { |m| !io.respond_to?(m) }
-          raise InvalidFile.new(io, missing_methods) if missing_methods.any?
-        end
-
-        # Generates a unique identifier that can be used for a location.
-        def generate_uid(io)
-          SecureRandom.hex
+    # When inheriting Shrine, copy the instance variables into the subclass,
+    # and create subclasses of core classes.
+    def inherited(subclass)
+      subclass.instance_variable_set(:@opts, opts.dup)
+      subclass.opts.each do |key, value|
+        if value.is_a?(Enumerable) && !value.frozen?
+          subclass.opts[key] = value.dup
         end
       end
+      subclass.instance_variable_set(:@storages, storages.dup)
 
-      module AttachmentClassMethods
-        # Returns the Shrine class that this attachment class is
-        # namespaced under.
-        attr_accessor :shrine_class
+      file_class = Class.new(self::UploadedFile)
+      file_class.shrine_class = subclass
+      subclass.const_set(:UploadedFile, file_class)
 
-        # Since Attachment is anonymously subclassed when Shrine is subclassed,
-        # and then assigned to a constant of the Shrine subclass, make inspect
-        # reflect the likely name for the class.
-        def inspect
-          "#{shrine_class.inspect}::Attachment"
-        end
-      end
-
-      module AttachmentMethods
-        # Instantiates an attachment module for a given attribute name, which
-        # can then be included to a model class. Second argument will be passed
-        # to an attacher module.
-        def initialize(name, **options)
-          @name    = name
-          @options = options
-
-          module_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def #{name}_attacher(options = {})
-              @#{name}_attacher   = nil if options.any?
-              @#{name}_attacher ||= (
-                attachments    = self.class.ancestors.grep(Shrine::Attachment)
-                attachment     = attachments.find { |mod| mod.attachment_name == :#{name} }
-                attacher_class = attachment.shrine_class::Attacher
-                options        = attachment.options.merge(options)
-
-                attacher_class.new(self, :#{name}, options)
-              )
-            end
-
-            def #{name}=(value)
-              #{name}_attacher.assign(value)
-            end
-
-            def #{name}
-              #{name}_attacher.get
-            end
-
-            def #{name}_url(*args)
-              #{name}_attacher.url(*args)
-            end
-          RUBY
-        end
+      attachment_class = Class.new(self::Attachment)
+      attachment_class.shrine_class = subclass
+      subclass.const_set(:Attachment, attachment_class)
 
-        # Returns name of the attachment this module provides.
-        def attachment_name
-          @name
-        end
+      attacher_class = Class.new(self::Attacher)
+      attacher_class.shrine_class = subclass
+      subclass.const_set(:Attacher, attacher_class)
+    end
 
-        # Returns options that are to be passed to the Attacher.
-        def options
-          @options
-        end
+    # Load a new plugin into the current class. A plugin can be a module
+    # which is used directly, or a symbol representing a registered plugin
+    # which will be required and then loaded.
+    #
+    #     Shrine.plugin MyPlugin
+    #     Shrine.plugin :my_plugin
+    def plugin(plugin, *args, &block)
+      plugin = Plugins.load_plugin(plugin) if plugin.is_a?(Symbol)
+      plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
+      self.include(plugin::InstanceMethods) if defined?(plugin::InstanceMethods)
+      self.extend(plugin::ClassMethods) if defined?(plugin::ClassMethods)
+      self::UploadedFile.include(plugin::FileMethods) if defined?(plugin::FileMethods)
+      self::UploadedFile.extend(plugin::FileClassMethods) if defined?(plugin::FileClassMethods)
+      self::Attachment.include(plugin::AttachmentMethods) if defined?(plugin::AttachmentMethods)
+      self::Attachment.extend(plugin::AttachmentClassMethods) if defined?(plugin::AttachmentClassMethods)
+      self::Attacher.include(plugin::AttacherMethods) if defined?(plugin::AttacherMethods)
+      self::Attacher.extend(plugin::AttacherClassMethods) if defined?(plugin::AttacherClassMethods)
+      plugin.configure(self, *args, &block) if plugin.respond_to?(:configure)
+      plugin
+    end
 
-        # Returns class name with attachment name included.
-        #
-        #     Shrine[:image].to_s #=> "#<Shrine::Attachment(image)>"
-        def to_s
-          "#<#{self.class.inspect}(#{attachment_name})>"
-        end
+    # Retrieves the storage under the given identifier (can be a Symbol or
+    # a String), and raises Shrine::Error if the storage is missing.
+    def find_storage(name)
+      storages.each { |key, value| return value if key.to_s == name.to_s }
+      raise Error, "storage #{name.inspect} isn't registered on #{self}"
+    end
 
-        # Returns class name with attachment name included.
-        #
-        #     Shrine[:image].inspect #=> "#<Shrine::Attachment(image)>"
-        def inspect
-          "#<#{self.class.inspect}(#{attachment_name})>"
-        end
+    # Generates an instance of Shrine::Attachment to be included in the
+    # model class. Example:
+    #
+    #     class Photo
+    #       include Shrine.attachment(:image) # creates a Shrine::Attachment object
+    #     end
+    def attachment(name, *args)
+      self::Attachment.new(name, *args)
+    end
+    alias [] attachment
 
-        # Returns the Shrine class that this attachment's class is namespaced
-        # under.
-        def shrine_class
-          self.class.shrine_class
-        end
+    # Instantiates a Shrine::UploadedFile from a hash, and optionally
+    # yields the returned object.
+    #
+    #     data = {"storage" => "cache", "id" => "abc123.jpg", "metadata" => {}}
+    #     Shrine.uploaded_file(data) #=> #<Shrine::UploadedFile>
+    def uploaded_file(object, &block)
+      case object
+      when String
+        uploaded_file(JSON.parse(object), &block)
+      when Hash
+        uploaded_file(self::UploadedFile.new(object), &block)
+      when self::UploadedFile
+        object.tap { |f| yield(f) if block_given? }
+      else
+        raise Error, "cannot convert #{object.inspect} to a #{self}::UploadedFile"
       end
+    end
 
-      module AttacherClassMethods
-        # Returns the Shrine class that this attacher class is namespaced
-        # under.
-        attr_accessor :shrine_class
-
-        # Since Attacher is anonymously subclassed when Shrine is subclassed,
-        # and then assigned to a constant of the Shrine subclass, make inspect
-        # reflect the likely name for the class.
-        def inspect
-          "#{shrine_class.inspect}::Attacher"
-        end
+    # Temporarily converts an IO-like object into a file. If the input IO
+    # object is already a file, it simply yields it to the block, otherwise
+    # it copies IO content into a Tempfile object which is then yielded and
+    # afterwards deleted.
+    #
+    #     Shrine.with_file(io) { |file| file.path }
+    def with_file(io)
+      if io.respond_to?(:path)
+        yield io
+      elsif io.is_a?(UploadedFile)
+        io.download { |tempfile| yield tempfile }
+      else
+        Tempfile.create("shrine-file", binmode: true) do |file|
+          IO.copy_stream(io, file.path)
+          io.rewind
 
-        # Block that is executed in context of Shrine::Attacher during
-        # validation. Example:
-        #
-        #     Shrine::Attacher.validate do
-        #       if get.size > 5*1024*1024
-        #         errors << "is too big (max is 5 MB)"
-        #       end
-        #     end
-        def validate(&block)
-          define_method(:validate_block, &block)
-          private :validate_block
+          yield file
         end
       end
+    end
 
-      module AttacherMethods
-        # Returns the uploader that is used for the temporary storage.
-        attr_reader :cache
-
-        # Returns the uploader that is used for the permanent storage.
-        attr_reader :store
-
-        # Returns the context that will be sent to the uploader when uploading
-        # and deleting. Can be modified with additional data to be sent to the
-        # uploader.
-        attr_reader :context
-
-        # Returns an array of validation errors created on file assignment in
-        # the `Attacher.validate` block.
-        attr_reader :errors
-
-        # Initializes the necessary attributes.
-        def initialize(record, name, cache: :cache, store: :store)
-          @cache   = shrine_class.new(cache)
-          @store   = shrine_class.new(store)
-          @context = {record: record, name: name}
-          @errors  = []
-        end
-
-        # Returns the model instance associated with the attacher.
-        def record; context[:record]; end
-
-        # Returns the attachment name associated with the attacher.
-        def name;   context[:name];   end
-
-        # Receives the attachment value from the form. It can receive an
-        # already cached file as a JSON string, otherwise it assumes that it's
-        # an IO object and uploads it to the temporary storage. The cached file
-        # is then written to the attachment attribute in the JSON format.
-        def assign(value, **options)
-          if value.is_a?(String)
-            return if value == "" || !cache.uploaded?(uploaded_file(value))
-            assign_cached(uploaded_file(value))
-          else
-            uploaded_file = cache!(value, action: :cache, **options) if value
-            set(uploaded_file)
-          end
-        end
-
-        # Accepts a Shrine::UploadedFile object and writes it to the attachment
-        # attribute. It then runs file validations, and records that the
-        # attachment has changed.
-        def set(uploaded_file)
-          file = get
-          @old = file unless uploaded_file == file
-          _set(uploaded_file)
-          validate
-        end
-
-        # Runs the validations defined by `Attacher.validate`.
-        def validate
-          errors.clear
-          validate_block if get
-        end
-
-        # Returns true if a new file has been attached.
-        def changed?
-          instance_variable_defined?(:@old)
-        end
-        alias attached? changed?
-
-        # Plugins can override this if they want something to be done before
-        # save.
-        def save
-        end
-
-        # Deletes the old file and promotes the new one. Typically this should
-        # be called after saving the model instance.
-        def finalize
-          return if !instance_variable_defined?(:@old)
-          replace
-          remove_instance_variable(:@old)
-          _promote(action: :store) if cached?
-        end
-
-        # Delegates to #promote, overriden for backgrounding.
-        def _promote(uploaded_file = get, **options)
-          promote(uploaded_file, **options)
-        end
-
-        # Uploads the cached file to store, and writes the stored file to the
-        # attachment attribute.
-        def promote(uploaded_file = get, **options)
-          stored_file = store!(uploaded_file, **options)
-          result = swap(stored_file) or _delete(stored_file, action: :abort)
-          result
-        end
-
-        # Calls #update, overriden in ORM plugins, and returns true if the
-        # attachment was successfully updated.
-        def swap(uploaded_file)
-          update(uploaded_file)
-          uploaded_file if uploaded_file == get
-        end
-
-        # Deletes the previous attachment that was replaced, typically called
-        # after the model instance is saved with the new attachment.
-        def replace
-          _delete(@old, action: :replace) if @old && !cache.uploaded?(@old)
-        end
-
-        # Deletes the current attachment, typically called after destroying the
-        # record.
-        def destroy
-          file = get
-          _delete(file, action: :destroy) if file && !cache.uploaded?(file)
-        end
-
-        # Delegates to #delete!, overriden for backgrounding.
-        def _delete(uploaded_file, **options)
-          delete!(uploaded_file, **options)
-        end
-
-        # Returns the URL to the attached file if it's present. It forwards any
-        # given URL options to the storage.
-        def url(**options)
-          get.url(**options) if read
-        end
-
-        # Returns true if attachment is present and cached.
-        def cached?
-          file = get
-          file && cache.uploaded?(file)
-        end
-
-        # Returns true if attachment is present and stored.
-        def stored?
-          file = get
-          file && store.uploaded?(file)
-        end
-
-        # Returns a Shrine::UploadedFile instantiated from the data written to
-        # the attachment attribute.
-        def get
-          uploaded_file(read) if read
-        end
-
-        # Reads from the `<attachment>_data` attribute on the model instance.
-        # It returns nil if the value is blank.
-        def read
-          value = record.send(data_attribute)
-          convert_after_read(value) unless value.nil? || value.empty?
-        end
-
-        # Uploads the file using the #cache uploader, passing the #context.
-        def cache!(io, **options)
-          Shrine.deprecation("Sending :phase to Attacher#cache! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
-          cache.upload(io, context.merge(_equalize_phase_and_action(options)))
-        end
+    # Prints a deprecation warning to standard error.
+    def deprecation(message)
+      warn "SHRINE DEPRECATION WARNING: #{message}"
+    end
+  end
 
-        # Uploads the file using the #store uploader, passing the #context.
-        def store!(io, **options)
-          Shrine.deprecation("Sending :phase to Attacher#store! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
-          store.upload(io, context.merge(_equalize_phase_and_action(options)))
-        end
+  module InstanceMethods
+    # The symbol identifier for the storage used by the uploader.
+    attr_reader :storage_key
 
-        # Deletes the file using the uploader, passing the #context.
-        def delete!(uploaded_file, **options)
-          Shrine.deprecation("Sending :phase to Attacher#delete! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
-          store.delete(uploaded_file, context.merge(_equalize_phase_and_action(options)))
-        end
+    # The storage object used by the uploader.
+    attr_reader :storage
 
-        # Enhances `Shrine.uploaded_file` with the ability to recognize uploaded
-        # files as JSON strings.
-        def uploaded_file(object, &block)
-          shrine_class.uploaded_file(object, &block)
-        end
-
-        # The name of the attribute on the model instance that is used to store
-        # the attachment data. Defaults to `<attachment>_data`.
-        def data_attribute
-          :"#{name}_data"
-        end
+    # Accepts a storage symbol registered in `Shrine.storages`.
+    def initialize(storage_key)
+      @storage = self.class.find_storage(storage_key)
+      @storage_key = storage_key.to_sym
+    end
 
-        # Returns the Shrine class that this attacher's class is namespaced
-        # under.
-        def shrine_class
-          self.class.shrine_class
-        end
+    # The class-level options hash. This should probably not be modified at
+    # the instance level.
+    def opts
+      self.class.opts
+    end
 
-        private
+    # The main method for uploading files. Takes an IO-like object and an
+    # optional context hash (used internally by Shrine::Attacher). It calls
+    # user-defined #process, and afterwards it calls #store. The `io` is
+    # closed after upload.
+    def upload(io, context = {})
+      io = processed(io, context) || io
+      store(io, context)
+    end
 
-        # Assigns a cached file.
-        def assign_cached(cached_file)
-          set(cached_file)
-        end
+    # User is expected to perform processing inside this method, and
+    # return the processed files. Returning nil signals that no proccessing
+    # has been done and that the original file should be used.
+    #
+    #     class ImageUploader < Shrine
+    #       def process(io, context)
+    #         # do processing and return processed files
+    #       end
+    #     end
+    def process(io, context = {})
+    end
 
-        # Writes the uploaded file to the attachment attribute. Overriden in ORM
-        # plugins to additionally save the model instance.
-        def update(uploaded_file)
-          _set(uploaded_file)
-        end
+    # Uploads the file and returns an instance of Shrine::UploadedFile. By
+    # default the location of the file is automatically generated by
+    # \#generate_location, but you can pass in `:location` to upload to
+    # a specific location.
+    #
+    #     uploader.store(io)
+    def store(io, context = {})
+      _store(io, context)
+    end
 
-        # Performs validation actually.
-        # This method is redefined with `Attacher.validate`.
-        def validate_block
-        end
+    # Returns true if the storage of the given uploaded file matches the
+    # storage of this uploader.
+    def uploaded?(uploaded_file)
+      uploaded_file.storage_key == storage_key.to_s
+    end
 
-        # Converts the UploadedFile to a data hash and writes it to the
-        # attribute.
-        def _set(uploaded_file)
-          data = convert_to_data(uploaded_file) if uploaded_file
-          write(data ? convert_before_write(data) : nil)
-        end
+    # Deletes the given uploaded file and returns it.
+    def delete(uploaded_file, context = {})
+      _delete(uploaded_file, context)
+      uploaded_file
+    end
 
-        # Writes to the `<attachment>_data` attribute on the model instance.
-        def write(value)
-          record.send(:"#{data_attribute}=", value)
-        end
+    # Generates a unique location for the uploaded file, preserving the
+    # file extension. Can be overriden in uploaders for generating custom
+    # location.
+    def generate_location(io, context = {})
+      extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
+      extension ||= File.extname(extract_filename(io).to_s).downcase
+      basename    = generate_uid(io)
 
-        # Returns the data hash of the given UploadedFile.
-        def convert_to_data(uploaded_file)
-          uploaded_file.data
-        end
+      basename + extension
+    end
 
-        # Returns the hash value dumped to JSON.
-        def convert_before_write(value)
-          value.to_json
-        end
+    # Extracts filename, size and MIME type from the file, which is later
+    # accessible through UploadedFile#metadata.
+    def extract_metadata(io, context = {})
+      {
+        "filename"  => extract_filename(io),
+        "size"      => extract_size(io),
+        "mime_type" => extract_mime_type(io),
+      }
+    end
 
-        # Returns the read value unchanged.
-        def convert_after_read(value)
-          value
-        end
+    private
 
-        # Temporary method used for transitioning from :phase to :action.
-        def _equalize_phase_and_action(options)
-          options[:phase]  = options[:action] if options.key?(:action)
-          options[:action] = options[:phase] if options.key?(:phase)
-          options
-        end
+    # Attempts to extract the appropriate filename from the IO object.
+    def extract_filename(io)
+      if io.respond_to?(:original_filename)
+        io.original_filename
+      elsif io.respond_to?(:path)
+        File.basename(io.path)
       end
+    end
 
-      module FileClassMethods
-        # Returns the Shrine class that this file class is namespaced under.
-        attr_accessor :shrine_class
-
-        # Since UploadedFile is anonymously subclassed when Shrine is subclassed,
-        # and then assigned to a constant of the Shrine subclass, make inspect
-        # reflect the likely name for the class.
-        def inspect
-          "#{shrine_class.inspect}::UploadedFile"
-        end
+    # Attempts to extract the MIME type from the IO object.
+    def extract_mime_type(io)
+      if io.respond_to?(:content_type) && io.content_type
+        warn "The \"mime_type\" Shrine metadata field will be set from the \"Content-Type\" request header, which might not hold the actual MIME type of the file. It is recommended to load the determine_mime_type plugin which determines MIME type from file content."
+        io.content_type.split(";").first # exclude media type parameters
       end
+    end
 
-      module FileMethods
-        # The hash of information which defines this uploaded file.
-        attr_reader :data
-
-        # Initializes the uploaded file with the given data hash.
-        def initialize(data)
-          raise Error, "#{data.inspect} isn't valid uploaded file data" unless data["id"] && data["storage"]
-
-          @data = data
-          @data["metadata"] ||= {}
-          storage # ensure storage is registered
-        end
-
-        # The location where the file was uploaded to the storage.
-        def id
-          @data.fetch("id")
-        end
-
-        # The string identifier of the storage the file is uploaded to.
-        def storage_key
-          @data.fetch("storage")
-        end
-
-        # A hash of file metadata that was extracted during upload.
-        def metadata
-          @data.fetch("metadata")
-        end
-
-        # The filename that was extracted from the uploaded file.
-        def original_filename
-          metadata["filename"]
-        end
-
-        # The extension derived from #id if present, otherwise it's derived
-        # from #original_filename.
-        def extension
-          result = File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
-          result.downcase if result
-        end
-
-        # The filesize of the uploaded file.
-        def size
-          (@io && @io.size) || (metadata["size"] && Integer(metadata["size"]))
-        end
-
-        # The MIME type of the uploaded file.
-        def mime_type
-          metadata["mime_type"]
-        end
-        alias content_type mime_type
-
-        # Calls `#open` on the storage to open the uploaded file for reading.
-        # Most storages will return a lazy IO object which dynamically
-        # retrieves file content from the storage as the object is being read.
-        #
-        # If a block is given, the opened IO object is yielded to the block,
-        # and at the end of the block it's automatically closed. In this case
-        # the return value of the method is the block return value.
-        #
-        # If no block is given, the opened IO object is returned.
-        #
-        #     uploaded_file.open #=> IO object returned by the storage
-        #     uploaded_file.read #=> "..."
-        #     uploaded_file.close
-        #
-        #     # or
-        #
-        #     uploaded_file.open { |io| io.read } # the IO is automatically closed
-        def open(*args)
-          @io.close if @io && !(@io.respond_to?(:closed?) && @io.closed?)
-          @io = storage.open(id, *args)
-
-          return @io unless block_given?
-
-          begin
-            yield @io
-          ensure
-            @io.close
-            @io = nil
-          end
-        end
-
-        # Calls `#download` on the storage if the storage implements it,
-        # otherwise streams content into a newly created Tempfile.
-        #
-        # If a block is given, the opened Tempfile object is yielded to the
-        # block, and at the end of the block it's automatically closed and
-        # deleted. In this case the return value of the method is the block
-        # return value.
-        #
-        # If no block is given, the opened Tempfile is returned.
-        #
-        #     uploaded_file.download
-        #     #=> #<File:/var/folders/.../20180302-33119-1h1vjbq.jpg>
-        #
-        #     # or
-        #
-        #     uploaded_file.download { |tempfile| tempfile.read } # tempfile is deleted
-        def download(*args)
-          if storage.respond_to?(:download)
-            tempfile = storage.download(id, *args)
-          else
-            tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
-            stream(tempfile, *args)
-            tempfile.open
-          end
-
-          block_given? ? yield(tempfile) : tempfile
-        ensure
-          tempfile.close! if ($! || block_given?) && tempfile
-        end
-
-        # Streams uploaded file content into the specified destination. The
-        # destination object is given directly to `IO.copy_stream`, so it can
-        # be either a path on disk or an object that responds to `#write`.
-        #
-        # If the uploaded file is already opened, it will be simply rewinded
-        # after streaming finishes. Otherwise the uploaded file is opened and
-        # then closed after streaming.
-        #
-        #     uploaded_file.stream(StringIO.new)
-        #     # or
-        #     uploaded_file.stream("/path/to/destination")
-        def stream(destination, *args)
-          if @io
-            IO.copy_stream(io, destination)
-            io.rewind
-          else
-            open(*args) { |io| IO.copy_stream(io, destination) }
-          end
-        end
-
-        # Part of complying to the IO interface. It delegates to the internally
-        # opened IO object.
-        def read(*args)
-          io.read(*args)
-        end
-
-        # Part of complying to the IO interface. It delegates to the internally
-        # opened IO object.
-        def eof?
-          io.eof?
-        end
-
-        # Part of complying to the IO interface. It delegates to the internally
-        # opened IO object.
-        def close
-          io.close if @io
-        end
-
-        # Part of complying to the IO interface. It delegates to the internally
-        # opened IO object.
-        def rewind
-          io.rewind
-        end
+    # Extracts the filesize from the IO object.
+    def extract_size(io)
+      io.size if io.respond_to?(:size)
+    end
 
-        # Calls `#url` on the storage, forwarding any given URL options.
-        def url(**options)
-          storage.url(id, **options)
-        end
+    # It first asserts that `io` is a valid IO object. It then extracts
+    # metadata and generates the location, before calling the storage to
+    # upload the IO object, passing the extracted metadata and location.
+    # Finally it returns a Shrine::UploadedFile object which represents the
+    # file that was uploaded.
+    def _store(io, context)
+      _enforce_io(io)
 
-        # Calls `#exists?` on the storage, which checks whether the file exists
-        # on the storage.
-        def exists?
-          storage.exists?(id)
-        end
+      metadata = get_metadata(io, context)
+      metadata = metadata.merge(context[:metadata]) if context[:metadata]
 
-        # Uploads a new file to this file's location and returns it.
-        def replace(io, context = {})
-          uploader.upload(io, context.merge(location: id))
-        end
+      location = get_location(io, context.merge(metadata: metadata))
 
-        # Calls `#delete` on the storage, which deletes the file from the
-        # storage.
-        def delete
-          storage.delete(id)
-        end
+      put(io, context.merge(location: location, metadata: metadata))
 
-        # Returns an opened IO object for the uploaded file.
-        def to_io
-          io
-        end
+      self.class.uploaded_file(
+        "id"       => location,
+        "storage"  => storage_key.to_s,
+        "metadata" => metadata,
+      )
+    end
 
-        # Returns the data hash in the JSON format. Suitable for storing in a
-        # database column or passing to a background job.
-        def to_json(*args)
-          data.to_json(*args)
-        end
+    # Delegates to #remove.
+    def _delete(uploaded_file, context)
+      remove(uploaded_file, context)
+    end
 
-        # Conform to ActiveSupport's JSON interface.
-        def as_json(*args)
-          data
-        end
+    # Delegates to #copy.
+    def put(io, context)
+      copy(io, context)
+    end
 
-        # Returns true if the other UploadedFile is uploaded to the same
-        # storage and it has the same #id.
-        def ==(other)
-          other.is_a?(self.class) &&
-          self.id == other.id &&
-          self.storage_key == other.storage_key
-        end
-        alias eql? ==
+    # Calls `#upload` on the storage, passing to it the location, metadata
+    # and any upload options. The storage might modify the location or
+    # metadata that were passed in. The uploaded IO is then closed.
+    def copy(io, context)
+      location       = context[:location]
+      metadata       = context[:metadata]
+      upload_options = context[:upload_options] || {}
+
+      storage.upload(io, location, shrine_metadata: metadata, **upload_options)
+    ensure
+      io.close rescue nil
+    end
 
-        # Enables using UploadedFile objects as hash keys.
-        def hash
-          [id, storage_key].hash
-        end
+    # Delegates to `UploadedFile#delete`.
+    def remove(uploaded_file, context)
+      uploaded_file.delete
+    end
 
-        # Returns an uploader object for the corresponding storage.
-        def uploader
-          shrine_class.new(storage_key)
-        end
+    # Delegates to #process.
+    def processed(io, context)
+      process(io, context)
+    end
 
-        # Returns the storage that this file was uploaded to.
-        def storage
-          shrine_class.find_storage(storage_key)
-        end
+    # Retrieves the location for the given IO and context. First it looks
+    # for the `:location` option, otherwise it calls #generate_location.
+    def get_location(io, context)
+      location = context[:location] || generate_location(io, context)
+      location or raise Error, "location generated for #{io.inspect} was nil (context = #{context})"
+    end
 
-        # Returns the Shrine class that this file's class is namespaced under.
-        def shrine_class
-          self.class.shrine_class
-        end
+    # If the IO object is a Shrine::UploadedFile, it simply copies over its
+    # metadata, otherwise it calls #extract_metadata.
+    def get_metadata(io, context)
+      if io.is_a?(UploadedFile)
+        io.metadata.dup
+      else
+        extract_metadata(io, context)
+      end
+    end
 
-        private
+    # Asserts that the object is a valid IO object, specifically that it
+    # responds to `#read`, `#eof?`, `#rewind`, `#size` and `#close`. If the
+    # object doesn't respond to one of these methods, a Shrine::InvalidFile
+    # error is raised.
+    def _enforce_io(io)
+      missing_methods = %i[read eof? rewind close].select { |m| !io.respond_to?(m) }
+      raise InvalidFile.new(io, missing_methods) if missing_methods.any?
+    end
 
-        # Returns an opened IO object for the uploaded file by calling `#open`
-        # on the storage.
-        def io
-          @io || open
-        end
-      end
+    # Generates a unique identifier that can be used for a location.
+    def generate_uid(io)
+      SecureRandom.hex
     end
   end
+end
 
-  extend Plugins::Base::ClassMethods
-  plugin Plugins::Base
+[Shrine, Shrine::UploadedFile, Shrine::Attacher, Shrine::Attachment].each do |core_class|
+  core_class.include core_class.const_get(:InstanceMethods)
+  core_class.extend core_class.const_get(:ClassMethods)
 end