shrine 2.19.4 → 3.4.0

data/lib/shrine.rb

@@ -1,40 +1,32 @@
 # frozen_string_literal: true
 
-require "shrine/version"
 require "shrine/uploaded_file"
 require "shrine/attacher"
 require "shrine/attachment"
 require "shrine/plugins"
+require "shrine/version"
 
 require "securerandom"
 require "json"
 require "tempfile"
 require "logger"
 
-# Core class that represents uploader.
-# Base implementation is defined in InstanceMethods and ClassMethods.
+# Core class that handles uploading files to specified storage.
 class Shrine
   # A generic exception used by Shrine.
-  class Error < StandardError; end
+  class Error < StandardError
+  end
 
   # Raised when a file is not a valid IO.
   class InvalidFile < Error
     def initialize(io, missing_methods)
-      super "#{io.inspect} is not a valid IO object (it doesn't respond to \
-        #{missing_methods.map{|m, _|"##{m}"}.join(", ")})"
+      super "#{io.inspect} is not a valid IO object (it doesn't respond to #{missing_methods.map{|m, _|"##{m}"}.join(", ")})"
     end
   end
 
-  # Methods which an object has to respond to in order to be considered
-  # an IO object, along with their arguments.
-  IO_METHODS = {
-    read:   [:length, :outbuf],
-    eof?:   [],
-    rewind: [],
-    size:   [],
-    close:  [],
-  }
-  deprecate_constant(:IO_METHODS)
+  # Raised by the storage in the #open method.
+  class FileNotFound < Error
+  end
 
   @opts = {}
   @storages = {}
@@ -54,12 +46,7 @@ class Shrine
     # 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(:@opts, deep_dup(opts))
       subclass.instance_variable_set(:@storages, storages.dup)
 
       file_class = Class.new(self::UploadedFile)
@@ -81,9 +68,9 @@ class Shrine
     #
     #     Shrine.plugin MyPlugin
     #     Shrine.plugin :my_plugin
-    def plugin(plugin, *args, &block)
+    def plugin(plugin, *args, **kwargs, &block)
       plugin = Plugins.load_plugin(plugin) if plugin.is_a?(Symbol)
-      plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
+      Plugins.load_dependencies(plugin, self, *args, **kwargs, &block)
       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)
@@ -92,7 +79,7 @@ class Shrine
       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)
+      Plugins.configure(plugin, self, *args, **kwargs, &block)
       plugin
     end
 
@@ -108,8 +95,8 @@ class Shrine
     #     class Photo
     #       include Shrine::Attachment(:image) # creates a Shrine::Attachment object
     #     end
-    def Attachment(name, *args)
-      self::Attachment.new(name, *args)
+    def Attachment(name, **args)
+      self::Attachment.new(name, **args)
     end
     alias attachment Attachment
     alias [] Attachment
@@ -117,25 +104,26 @@ class Shrine
     # Uploads the file to the specified storage. It delegates to `Shrine#upload`.
     #
     #     Shrine.upload(io, :store) #=> #<Shrine::UploadedFile>
-    def upload(io, storage, context = {})
-      new(storage).upload(io, context)
+    def upload(io, storage, **options)
+      new(storage).upload(io, **options)
     end
 
     # Instantiates a Shrine::UploadedFile from a hash, and optionally
     # yields the returned object.
     #
-    #     data = {"storage" => "cache", "id" => "abc123.jpg", "metadata" => {}}
+    #     data = { "storage" => "cache", "id" => "abc123.jpg", "metadata" => {} }
     #     Shrine.uploaded_file(data) #=> #<Shrine::UploadedFile>
-    def uploaded_file(object, &block)
+    def uploaded_file(object)
       case object
       when String
-        uploaded_file(JSON.parse(object), &block)
+        uploaded_file(JSON.parse(object))
       when Hash
-        uploaded_file(self::UploadedFile.new(object), &block)
+        object = JSON.parse(object.to_json) if object.keys.grep(Symbol).any? # deep stringify keys
+        self::UploadedFile.new(object)
       when self::UploadedFile
-        object.tap { |f| yield(f) if block_given? }
+        object
       else
-        raise Error, "cannot convert #{object.inspect} to a #{self}::UploadedFile"
+        fail ArgumentError, "cannot convert #{object.inspect} to a #{self}::UploadedFile"
       end
     end
 
@@ -169,27 +157,39 @@ class Shrine
     def deprecation(message)
       Shrine.logger.warn "SHRINE DEPRECATION WARNING: #{message}"
     end
+
+    private
+
+    # Deep duplicates a nested hash of options.
+    def deep_dup(collection)
+      duplicate_collection = collection.dup
+
+      if duplicate_collection.is_a?(Hash)
+        duplicate_collection.each do |key, value|
+          duplicate_collection[key] = deep_dup(value) if value.is_a?(Enumerable)
+        end
+      end
+
+      duplicate_collection
+    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`.
     #
     #     Shrine.new(:store)
     def initialize(storage_key)
-      @storage = self.class.find_storage(storage_key)
       @storage_key = storage_key.to_sym
+
+      storage # ensure storage is registered
     end
 
-    # The class-level options hash. This should probably not be modified at
-    # the instance level.
-    def opts
-      self.class.opts
+    # Returns the storage object referenced by the identifier.
+    def storage
+      self.class.find_storage(storage_key)
     end
 
     # The main method for uploading files. Takes an IO-like object and an
@@ -201,55 +201,31 @@ class Shrine
     #   uploader.upload(io, metadata: { "foo" => "bar" })           # add metadata
     #   uploader.upload(io, location: "path/to/file")               # specify location
     #   uploader.upload(io, upload_options: { acl: "public-read" }) # add upload options
-    def upload(io, context = {})
-      io = processed(io, context) || io
-      store(io, context)
-    end
+    def upload(io, **options)
+      _enforce_io(io)
 
-    # 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
+      metadata = get_metadata(io, **options)
+      location = get_location(io, **options, metadata: metadata)
 
-    # 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
+      _upload(io, **options, location: location, metadata: metadata)
 
-    # 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
+      self.class::UploadedFile.new(
+        id:       location,
+        storage:  storage_key,
+        metadata: metadata,
+      )
     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 = {})
-      basic_location(io, metadata: context[:metadata] || {})
+    def generate_location(io, metadata: {}, **options)
+      basic_location(io, metadata: metadata)
     end
 
     # Extracts filename, size and MIME type from the file, which is later
     # accessible through UploadedFile#metadata.
-    def extract_metadata(io, context = {})
+    def extract_metadata(io, **options)
       {
         "filename"  => extract_filename(io),
         "size"      => extract_size(io),
@@ -257,8 +233,21 @@ class Shrine
       }
     end
 
+    # The class-level options hash. This should probably not be modified at
+    # the instance level.
+    def opts
+      self.class.opts
+    end
+
     private
 
+    def _upload(io, location:, metadata:, upload_options: {}, close: true, delete: false, **)
+      storage.upload(io, location, shrine_metadata: metadata, **upload_options)
+    ensure
+      io.close             if close
+      File.unlink(io.path) if delete && io.respond_to?(:path) && File.exist?(io.path)
+    end
+
     # Attempts to extract the appropriate filename from the IO object.
     def extract_filename(io)
       if io.respond_to?(:original_filename)
@@ -281,87 +270,35 @@ class Shrine
       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].is_a?(Hash)
-
-      location = get_location(io, context.merge(metadata: metadata))
-
-      put(io, context.merge(location: location, metadata: metadata))
-
-      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
-
     # Generates a basic location for an uploaded file
     def basic_location(io, metadata:)
       extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
-      extension ||= File.extname(extract_filename(io).to_s).downcase
+      extension ||= File.extname(metadata["filename"].to_s).downcase
       basename    = generate_uid(io)
 
       basename + extension
     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) && context[:metadata] != true
-        io.metadata.dup
-      elsif context[:metadata] != false
-        extract_metadata(io, context)
+    def get_metadata(io, metadata: nil, **options)
+      if io.is_a?(UploadedFile) && metadata != true
+        result = io.metadata.dup
+      elsif metadata != false
+        result = extract_metadata(io, **options)
       else
-        {}
+        result = {}
       end
+
+      result = result.merge(metadata) if metadata.is_a?(Hash)
+      result
+    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, location: nil, **options)
+      location ||= generate_location(io, **options)
+      location or fail Error, "location generated for #{io.inspect} was nil"
     end
 
     # Asserts that the object is a valid IO object, specifically that it

data/shrine.gemspec

@@ -26,26 +26,24 @@ direct uploads for fully asynchronous user experience.
     "bug_tracker_uri"   => "https://github.com/shrinerb/shrine/issues",
     "changelog_uri"     => "https://github.com/shrinerb/shrine/blob/master/CHANGELOG.md",
     "documentation_uri" => "https://shrinerb.com",
-    "mailing_list_uri"  => "https://groups.google.com/forum/#!forum/ruby-shrine",
+    "mailing_list_uri"  => "https://discourse.shrinerb.com",
     "source_code_uri"   => "https://github.com/shrinerb/shrine",
   }
 
   gem.files        = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*.rb", "shrine.gemspec", "doc/**/*.md"]
   gem.require_path = "lib"
 
-  gem.add_dependency "down", ">= 4.1", "< 6"
+  gem.add_dependency "down", "~> 5.1"
   gem.add_dependency "content_disposition", "~> 1.0"
 
   # general testing helpers
   gem.add_development_dependency "rake", ">= 11.1"
   gem.add_development_dependency "minitest", "~> 5.8"
-  gem.add_development_dependency "minitest-hooks", "~> 1.3"
-  gem.add_development_dependency "mocha", "~> 1.4"
-  gem.add_development_dependency "shrine-memory", ">= 0.2.2"
+  gem.add_development_dependency "mocha", "~> 1.11"
 
   # for endpoint plugins
   gem.add_development_dependency "rack", "~> 2.0"
-  gem.add_development_dependency "http-form_data", "~> 2.0"
+  gem.add_development_dependency "http-form_data", "~> 2.2"
   gem.add_development_dependency "rack-test_app"
 
   # for determine_mime_type plugin
@@ -63,15 +61,16 @@ direct uploads for fully asynchronous user experience.
   gem.add_development_dependency "ruby-vips", "~> 2.0" unless ENV["CI"]
 
   # for S3 storage
-  gem.add_development_dependency "aws-sdk-s3", "~> 1.16"
+  gem.add_development_dependency "aws-sdk-s3", "~> 1.69"
   gem.add_development_dependency "aws-sdk-core", "~> 3.23"
+  gem.add_development_dependency "rexml"
 
   # for instrumentation plugin
   gem.add_development_dependency "dry-monitor"
-  gem.add_development_dependency "activesupport", "~> 5.2.0"
+  gem.add_development_dependency "activesupport", RUBY_VERSION >= "2.5" ? "~> 6.0" : "~> 5.2"
 
   # for ORM plugins
   gem.add_development_dependency "sequel"
-  gem.add_development_dependency "activerecord", "~> 5.2.0"
-  gem.add_development_dependency "sqlite3", "~> 1.3.6" unless RUBY_ENGINE == "jruby"
+  gem.add_development_dependency "activerecord", RUBY_VERSION >= "2.5" ? "~> 6.0" : "~> 5.2"
+  gem.add_development_dependency "sqlite3", "~> 1.4" unless RUBY_ENGINE == "jruby"
 end