shrine 2.18.1 → 2.19.0

data/doc/storage/file_system.md

@@ -11,7 +11,7 @@ storage.url("image.jpg") #=> "/uploads/image.jpg"
 ```
 
 This storage will upload all files to "public/uploads", and the URLs of the
-uploaded files will start with "/uploads/*". This way you can use FileSystem
+uploaded files will start with "/uploads/\*". This way you can use FileSystem
 for both cache and store, one having the prefix "uploads/cache" and other
 "uploads/store". If you're uploading files to the `public` directory itself,
 you need to set `:prefix` to `"/"`:
@@ -29,12 +29,6 @@ storage = Shrine::Storage::FileSystem.new(Dir.tmpdir)
 storage.url("image.jpg") #=> "/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/image.jpg"
 ```
 
-In general you can always retrieve path to the file using `#path`:
-
-```rb
-storage.path("image.jpg") #=> #<Pathname:public/image.jpg>
-```
-
 ## Host
 
 It's generally a good idea to serve your files via a CDN, so an additional
@@ -58,6 +52,28 @@ storage.url("image.jpg", host: "http://943.23.43.1")
 #=> "http://943.23.43.1/opt/files/image.jpg"
 ```
 
+## Moving
+
+If you're uploading files on disk and want to improve performance, you can tell
+the `FileSystem#upload` method to **move** files instead of copying them:
+
+```rb
+storage.upload(file, "/path/to/destination", move: true) # performs the `mv` command
+
+File.exist?(file.path) #=> false
+```
+
+If you want to make this option default, you can use the
+[`upload_options`][upload_options] plugin.
+
+## Path
+
+You can retrieve path to the file using `#path`:
+
+```rb
+storage.path("image.jpg") #=> #<Pathname:public/image.jpg>
+```
+
 ## Clearing cache
 
 If you're using FileSystem as cache, you will probably want to periodically
@@ -66,7 +82,7 @@ periodically:
 
 ```rb
 file_system = Shrine.storages[:cache]
-file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+file_system.clear! { |path| path.mtime < Time.now - 7*24*60*60 } # delete files older than 1 week
 ```
 
 ## Permissions
@@ -94,3 +110,5 @@ use it for cache, since Heroku wipes this directory between app restarts. This
 also means that deploying the app can cancel someone's uploading if you're
 using backgrounding. Also, by default you cannot generate URLs to files in the
 "tmp" directory, but you can with the `download_endpoint` plugin.
+
+[upload_options]: /doc/plugins/upload_options.md#readme

data/doc/testing.md

@@ -54,14 +54,14 @@ Shrine.storages = {
 }
 ```
 
-If you're using AWS S3 storage, you can use [Minio] (explained below) instead
+If you're using AWS S3 storage, you can use [MinIO] (explained below) instead
 of S3, both in test and development environment. Alternatively, you can [stub
 aws-sdk-s3 requests][aws-sdk-ruby stubs] in tests.
 
-### Minio
+### MinIO
 
-[Minio] is an open source object storage server with AWS S3 compatible API which
-you can run locally. The advantage of using Minio for your development and test
+[MinIO] is an open source object storage server with AWS S3 compatible API which
+you can run locally. The advantage of using MinIO for your development and test
 environments is that all AWS S3 functionality should still continue to work,
 including direct uploads, so you don't need to update your code.
 
@@ -71,17 +71,17 @@ If you're on a Mac you can install it with Homebrew:
 $ brew install minio/stable/minio
 ```
 
-Afterwards you can start the Minio server and give it a directory where it will
+Afterwards you can start the MinIO server and give it a directory where it will
 store the data:
 
 ```
 $ minio server data/
 ```
 
-This command will print out the credentials for the running Minio server, as
-well as a link to the Minio web interface. Follow that link and create a new
+This command will print out the credentials for the running MinIO server, as
+well as a link to the MinIO web interface. Follow that link and create a new
 bucket. Once you've done that, you can configure `Shrine::Storage::S3` to use
-your Minio server:
+your MinIO server:
 
 ```rb
 Shrine::Storage::S3.new(
@@ -94,7 +94,7 @@ Shrine::Storage::S3.new(
 )
 ```
 
-The `:endpoint` option will make aws-sdk-s3 point all URLs to your Minio server
+The `:endpoint` option will make aws-sdk-s3 point all URLs to your MinIO server
 (instead of `s3.amazonaws.com`), and `:force_path_style` tells it not to use
 subdomains when generating URLs.
 
@@ -285,4 +285,4 @@ isolation.
 [Rack::Test]: https://github.com/brynary/rack-test
 [Rack::TestApp]: https://github.com/kwatch/rack-test_app
 [aws-sdk-ruby stubs]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/ClientStubs.html
-[Minio]: https://minio.io
+[MinIO]: https://min.io/

data/lib/shrine.rb

@@ -9,6 +9,7 @@ require "shrine/plugins"
 require "securerandom"
 require "json"
 require "tempfile"
+require "logger"
 
 # Core class that represents uploader.
 # Base implementation is defined in InstanceMethods and ClassMethods.
@@ -37,6 +38,8 @@ class Shrine
 
   @opts = {}
   @storages = {}
+  @logger = Logger.new(STDOUT)
+  @logger.formatter = -> (*, message) { "#{message}\n" }
 
   module ClassMethods
     # Generic options for this class, plugins store their options here.
@@ -45,6 +48,9 @@ class Shrine
     # A hash of storages with their symbol identifiers.
     attr_accessor :storages
 
+    # A logger instance.
+    attr_accessor :logger
+
     # When inheriting Shrine, copy the instance variables into the subclass,
     # and create subclasses of core classes.
     def inherited(subclass)
@@ -100,7 +106,7 @@ class Shrine
     # model class. Example:
     #
     #     class Photo
-    #       include Shrine.attachment(:image) # creates a Shrine::Attachment object
+    #       include Shrine::Attachment(:image) # creates a Shrine::Attachment object
     #     end
     def Attachment(name, *args)
       self::Attachment.new(name, *args)
@@ -154,9 +160,14 @@ class Shrine
       end
     end
 
-    # Prints a deprecation warning to standard error.
+    # Prints a warning to the logger.
+    def warn(message)
+      Shrine.logger.warn "SHRINE WARNING: #{message}"
+    end
+
+    # Prints a deprecation warning to the logger.
     def deprecation(message)
-      warn "SHRINE DEPRECATION WARNING: #{message}"
+      Shrine.logger.warn "SHRINE DEPRECATION WARNING: #{message}"
     end
   end
 
@@ -233,11 +244,7 @@ class Shrine
     # 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
+      basic_location(io)
     end
 
     # Extracts filename, size and MIME type from the file, which is later
@@ -264,7 +271,7 @@ class Shrine
     # 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."
+        Shrine.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
@@ -283,7 +290,7 @@ class Shrine
       _enforce_io(io)
 
       metadata = get_metadata(io, context)
-      metadata = metadata.merge(context[:metadata]) if context[:metadata]
+      metadata = metadata.merge(context[:metadata]) if context[:metadata].is_a?(Hash)
 
       location = get_location(io, context.merge(metadata: metadata))
 
@@ -329,6 +336,15 @@ class Shrine
       process(io, context)
     end
 
+    # Generates a basic location for an uploaded file
+    def basic_location(io)
+      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
+
     # 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)
@@ -339,10 +355,12 @@ class Shrine
     # 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)
+      if io.is_a?(UploadedFile) && context[:metadata] != true
         io.metadata.dup
-      else
+      elsif context[:metadata] != false
         extract_metadata(io, context)
+      else
+        {}
       end
     end
 
@@ -360,9 +378,7 @@ class Shrine
       SecureRandom.hex
     end
   end
-end
 
-[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)
+  extend ClassMethods
+  include InstanceMethods
 end

data/lib/shrine/attacher.rb

@@ -267,5 +267,8 @@ class Shrine
         options
       end
     end
+
+    extend ClassMethods
+    include InstanceMethods
   end
 end

data/lib/shrine/attachment.rb

@@ -93,5 +93,8 @@ class Shrine
         self.class.shrine_class
       end
     end
+
+    extend ClassMethods
+    include InstanceMethods
   end
 end

data/lib/shrine/plugins/add_metadata.rb

@@ -7,12 +7,12 @@ class Shrine
     # [doc/plugins/add_metadata.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/add_metadata.md
     module AddMetadata
       def self.configure(uploader)
-        uploader.opts[:metadata] ||= []
+        uploader.opts[:add_metadata_definitions] ||= []
       end
 
       module ClassMethods
-        def add_metadata(name = nil, **options, &block)
-          opts[:metadata] << [name, options, block]
+        def add_metadata(name = nil, &block)
+          opts[:add_metadata_definitions] << [name, block]
 
           metadata_method(name) if name
         end
@@ -24,7 +24,7 @@ class Shrine
         private
 
         def _metadata_method(name)
-          self::UploadedFile.send(:define_method, name) do
+          FileMethods.send(:define_method, name) do
             metadata[name.to_s]
           end
         end
@@ -43,28 +43,24 @@ class Shrine
         private
 
         def extract_custom_metadata(io, context)
-          opts[:metadata].each do |name, options, block|
-            result   = instance_exec(io, context, &block)
-            metadata = {}
+          opts[:add_metadata_definitions].each do |name, block|
+            result = instance_exec(io, context, &block)
 
             if name
-              metadata[name.to_s] = result
+              context[:metadata].merge! name.to_s => result
             else
-              metadata.merge!(result) if result
+              context[:metadata].merge! result.transform_keys(&:to_s) if result
             end
 
-            # convert symbol keys to strings
-            metadata.keys.each do |key|
-              metadata[key.to_s] = metadata.delete(key) if key.is_a?(Symbol)
-            end
-
-            context[:metadata].merge!(metadata)
-
             # rewind between metadata blocks
             io.rewind
           end
         end
       end
+
+      module FileMethods
+        # methods will be dynamically defined here through `Shrine.add_metadata`
+      end
     end
 
     register_plugin(:add_metadata, AddMetadata)

data/lib/shrine/plugins/backup.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+Shrine.deprecation("The backup plugin has been deprecated, the new preferred way to implement mirroring is via the instrumentation plugin – see https://github.com/shrinerb/shrine/wiki/Mirroring-Uploads. The backup plugin will be removed in Shrine 3.")
+
 class Shrine
   module Plugins
     # Documentation lives in [doc/plugins/backup.md] on GitHub.

data/lib/shrine/plugins/copy.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+Shrine.deprecation("The copy plugin is deprecated and will be removed in Shrine 3.")
+
 class Shrine
   module Plugins
     # Documentation lives in [doc/plugins/copy.md] on GitHub.

data/lib/shrine/plugins/data_uri.rb

@@ -20,11 +20,24 @@ class Shrine
       CONTENT_SEPARATOR    = /,/
       DEFAULT_CONTENT_TYPE = "text/plain"
 
+      LOG_SUBSCRIBER = -> (event) do
+        Shrine.logger.info "Data URI (#{event.duration}ms) – #{{
+          uploader: event[:uploader],
+        }.inspect}"
+      end
+
       def self.configure(uploader, opts = {})
-        uploader.opts[:data_uri_filename] = opts.fetch(:filename, uploader.opts[:data_uri_filename])
-        uploader.opts[:data_uri_error_message] = opts.fetch(:error_message, uploader.opts[:data_uri_error_message])
+        uploader.opts[:data_uri] ||= { log_subscriber: LOG_SUBSCRIBER }
+        uploader.opts[:data_uri].merge!(opts)
+
+        if uploader.opts[:data_uri][:filename]
+          Shrine.deprecation("The :filename option is deprecated for the data_uri plugin, and will be removed in Shrine 3. Use the infer_extension plugin instead.")
+        end
 
-        Shrine.deprecation("The :filename option is deprecated for the data_uri plugin, and will be removed in Shrine 3. Use the infer_extension plugin instead.") if opts[:filename]
+        # instrumentation plugin integration
+        if uploader.respond_to?(:subscribe)
+          uploader.subscribe(:data_uri, &uploader.opts[:data_uri][:log_subscriber])
+        end
       end
 
       module ClassMethods
@@ -36,20 +49,25 @@ class Shrine
         #     io.size         #=> 21
         #     io.read         # decoded content
         def data_uri(uri, filename: nil)
-          info = parse_data_uri(uri)
+          instrument_data_uri(uri) do
+            info = parse_data_uri(uri)
+            create_data_file(info, filename: filename)
+          end
+        end
 
+        private
+
+        def create_data_file(info, filename: nil)
           content_type = info[:content_type] || DEFAULT_CONTENT_TYPE
           content      = info[:base64] ? Base64.decode64(info[:data]) : CGI.unescape(info[:data])
-          filename     = opts[:data_uri_filename].call(content_type) if opts[:data_uri_filename]
+          filename     = opts[:data_uri][:filename].call(content_type) if opts[:data_uri][:filename]
 
-          data_file = DataFile.new(content, content_type: content_type, filename: filename)
+          data_file = Shrine::DataFile.new(content, content_type: content_type, filename: filename)
           info[:data].clear
 
           data_file
         end
 
-        private
-
         def parse_data_uri(uri)
           scanner = StringScanner.new(uri)
           scanner.scan(DATA_REGEXP) or raise ParseError, "data URI has invalid format"
@@ -60,6 +78,13 @@ class Shrine
 
           { content_type: media_type, base64: !!base64, data: content }
         end
+
+        # Sends a `data_uri.shrine` event for instrumentation plugin.
+        def instrument_data_uri(uri, &block)
+          return yield unless respond_to?(:instrument)
+
+          instrument(:data_uri, data_uri: uri, &block)
+        end
       end
 
       module AttachmentMethods
@@ -87,7 +112,7 @@ class Shrine
           data_file = shrine_class.data_uri(uri)
           assign(data_file, **options)
         rescue ParseError => error
-          message = shrine_class.opts[:data_uri_error_message] || error.message
+          message = shrine_class.opts[:data_uri][:error_message] || error.message
           message = message.call(uri) if message.respond_to?(:call)
           errors.replace [message]
           @data_uri = uri
@@ -118,30 +143,33 @@ class Shrine
           result
         end
       end
+    end
 
-      class DataFile
-        attr_reader :content_type, :original_filename
-
-        def initialize(content, content_type: nil, filename: nil)
-          @content_type      = content_type
-          @original_filename = filename
-          @io                = StringIO.new(content)
-        end
+    register_plugin(:data_uri, DataUri)
+  end
 
-        def to_io
-          @io
-        end
+  class DataFile
+    attr_reader :content_type, :original_filename
 
-        extend Forwardable
-        delegate [:read, :size, :rewind, :eof?] => :@io
+    def initialize(content, content_type: nil, filename: nil)
+      @content_type      = content_type
+      @original_filename = filename
+      @io                = StringIO.new(content)
+    end
 
-        def close
-          @io.close
-          @io.string.clear # deallocate string
-        end
-      end
+    def to_io
+      @io
     end
 
-    register_plugin(:data_uri, DataUri)
+    extend Forwardable
+    delegate [:read, :size, :rewind, :eof?] => :@io
+
+    def close
+      @io.close
+      @io.string.clear # deallocate string
+    end
   end
+
+  Plugins::DataUri.const_set(:DataFile, DataFile)
+  Plugins::DataUri.deprecate_constant(:DataFile)
 end