shrine 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2156db4347bf54e372dd3865a117b38e14638419
-  data.tar.gz: 6fc29c5c7837f3355240b85ff313579b35953a62
+  metadata.gz: b6ffc195c54c2afa0b36d184a94e44f5e8e110bb
+  data.tar.gz: '026928b32cef34807152c6999cee6e5f2f94ef81'
 SHA512:
-  metadata.gz: 634e5d0bec22737521cef1b2b7eab82871e3be1d13988a171a6686e3f3885d2514531ede958ca757dc9a84c526b049f9d2bb5bccb4119f4c8c090a1272ba88c7
-  data.tar.gz: bfa00d5f2ae6ca28e66cb0e26872cfb127fe00e13b12bf0eddd9965b295a5ea4b7418bf1d74f4e3deb059aa8a66d3262b120f968b369d71f675a3c5b9d265c4f
+  metadata.gz: b520588785bf8fb1145500fe7a5819685d3a1ec00773c9bf124a7e4b8c0a6c4f5400e0389910741db02aaf58a591df263ba8e305f9112ed83bda997d6b6dbed5
+  data.tar.gz: a993d56594c2ea0b8c31f5c8bf84416358da9bdda4ede5c5353ba8be89d8cb5058f05dc97eedaf9a63efcf592c9354006fd4b402bc65399d989933aceb6e4a5c

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2016 Janko Marohnić
+Copyright (c) 2015-2017 Janko Marohnić
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -762,6 +762,14 @@ step in the default synchronous workflow.
 Shrine.plugin :upload_endpoint
 ```
 ```rb
+# config.ru (Rack)
+map "/images/upload" do
+  run ImageUploader.upload_endpoint(:cache)
+end
+
+# OR
+
+# config/routes.rb (Rails)
 Rails.application.routes.draw do
   mount ImageUploader.upload_endpoint(:cache) => "/images/upload"
 end

data/doc/direct_s3.md

@@ -94,6 +94,14 @@ route, so we just need to mount it in our application:
 Shrine.plugin :presign_endpoint
 ```
 ```rb
+# config.ru (Rack)
+map "/presign" do
+  run Shrine.presign_endpoint(:cache)
+end
+
+# OR
+
+# config/routes.rb (Rails)
 Rails.application.routes.draw do
   mount Shrine.presign_endpoint(:cache) => "/presign"
 end

data/doc/regenerating_versions.md

@@ -43,7 +43,7 @@ User.paged_each do |user|
   if attacher.stored? && !attachment.is_a?(Hash)
     file = some_processing(attachment.download)
     thumb = attacher.store!(file, version: :thumb)
-    attacher.swap({original: avatar, thumb: thumb})
+    attacher.swap({original: attachment, thumb: thumb})
   end
 end
 ```

data/lib/shrine.rb

@@ -28,11 +28,11 @@ class Shrine
   # 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  => [],
+    read:   [:length, :outbuf],
+    eof?:   [],
+    rewind: [],
+    size:   [],
+    close:  [],
   }
 
   # Core class that represents a file uploaded to a storage. The instance
@@ -250,7 +250,7 @@ class Shrine
         # location.
         def generate_location(io, context = {})
           extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
-          extension ||= File.extname(extract_filename(io).to_s)
+          extension ||= File.extname(extract_filename(io).to_s).downcase
           basename  = generate_uid(io)
 
           basename + extension.to_s
@@ -280,7 +280,7 @@ class Shrine
         # 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." unless opts.key?(:mime_type_analyzer)
+            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
@@ -760,7 +760,8 @@ class Shrine
         # The extension derived from #id if present, otherwise from
         # #original_filename.
         def extension
-          File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
+          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.
@@ -781,8 +782,8 @@ class Shrine
         #     uploaded_file.open do |io|
         #       puts io.read # prints the content of the file
         #     end
-        def open
-          @io = storage.open(id)
+        def open(*args)
+          @io = storage.open(id, *args)
           yield @io
         ensure
           @io.close if @io
@@ -791,12 +792,12 @@ class Shrine
 
         # Calls `#download` on the storage if the storage implements it,
         # otherwise uses #open to stream the underlying IO to a Tempfile.
-        def download
+        def download(*args)
           if storage.respond_to?(:download)
-            storage.download(id)
+            storage.download(id, *args)
           else
             tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
-            open { |io| IO.copy_stream(io, tempfile.path) }
+            open(*args) { |io| IO.copy_stream(io, tempfile.path) }
             tempfile.tap(&:open)
           end
         end

data/lib/shrine/plugins/activerecord.rb

@@ -58,13 +58,13 @@ class Shrine
     # and options, which allows them to be internationalized together with
     # other ActiveRecord validation messages.
     #
-    # class MyUploader < Shrine
-    #   plugin :validation_helpers
+    #     class MyUploader < Shrine
+    #       plugin :validation_helpers
     #
-    #   Attacher.validate do
-    #     validate_max_size 256 * 1024**2, message: ->(max) { [:max_size, max: max] }
-    #   end
-    # end
+    #       Attacher.validate do
+    #         validate_max_size 256 * 1024**2, message: ->(max) { [:max_size, max: max] }
+    #       end
+    #     end
     #
     # If you want to validate presence of the attachment, you can do it
     # directly on the model.

data/lib/shrine/plugins/default_url.rb

@@ -50,7 +50,7 @@ class Shrine
           if default_url_block
             instance_exec(options, &default_url_block)
           elsif shrine_class.opts[:default_url]
-            shrine_class.opts[:default_url].call(context.merge(options){|k,old,new|old})
+            shrine_class.opts[:default_url].call(context.merge(options){|k, old, new| old})
           end
         end
 

data/lib/shrine/plugins/determine_mime_type.rb

@@ -80,12 +80,16 @@ class Shrine
         # Determines the MIME type of the IO object by calling the specified
         # analyzer.
         def determine_mime_type(io)
-          analyzer = opts[:mime_type_analyzer]
-          analyzer = mime_type_analyzers[analyzer] if analyzer.is_a?(Symbol)
-          args     = [io, mime_type_analyzers].take(analyzer.arity.abs)
+          if opts[:mime_type_analyzer] == :default
+            mime_type = io.content_type if io.respond_to?(:content_type)
+          else
+            analyzer = opts[:mime_type_analyzer]
+            analyzer = mime_type_analyzers[analyzer] if analyzer.is_a?(Symbol)
+            args     = [io, mime_type_analyzers].take(analyzer.arity.abs)
 
-          mime_type = analyzer.call(*args)
-          io.rewind
+            mime_type = analyzer.call(*args)
+            io.rewind
+          end
 
           mime_type
         end
@@ -144,29 +148,30 @@ class Shrine
         def extract_with_file(io)
           require "open3"
 
-          cmd     = %W[file --mime-type --brief -]
-          options = { stdin_data: io.read(MAGIC_NUMBER), binmode: true }
+          Open3.popen3(*%W[file --mime-type --brief -]) do |stdin, stdout, stderr, thread|
+            begin
+              IO.copy_stream(io, stdin.binmode)
+            rescue Errno::EPIPE
+            end
+            stdin.close
 
-          begin
-            stdout, stderr, status = Open3.capture3(*cmd, options)
-          rescue Errno::ENOENT
-            raise Error, "The `file` command-line tool is not installed"
-          end
+            status = thread.value
 
-          raise Error, stderr unless status.success?
-          $stderr.print(stderr)
+            raise Error, stderr.read unless status.success?
+            $stderr.print(stderr.read)
 
-          stdout.strip
+            stdout.read.strip
+          end
+        rescue Errno::ENOENT
+          raise Error, "The `file` command-line tool is not installed"
         end
 
         def extract_with_filemagic(io)
           require "filemagic"
 
-          filemagic = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
-          mime_type = filemagic.buffer(io.read(MAGIC_NUMBER))
-          filemagic.close
-
-          mime_type
+          FileMagic.open(FileMagic::MAGIC_MIME_TYPE) do |filemagic|
+            filemagic.buffer(io.read(MAGIC_NUMBER))
+          end
         end
 
         def extract_with_mimemagic(io)

data/lib/shrine/plugins/direct_upload.rb

@@ -194,6 +194,7 @@ class Shrine
       # with the file upload and returns the uploaded file as JSON.
       class App < Roda
         plugin :default_headers, "Content-Type"=>"application/json"
+        plugin :placeholder_string_matchers if Gem::Version.new(Roda::RodaVersion) >= Gem::Version.new("3.0.0")
 
         route do |r|
           r.on ":storage" do |storage_key|
@@ -257,7 +258,7 @@ class Shrine
             presign_location.call(request)
           else
             extension = request.params["extension"]
-            extension.prepend(".") if extension && !extension.start_with?('.')
+            extension.prepend(".") if extension && !extension.start_with?(".")
             uploader.send(:generate_uid, nil) + extension.to_s
           end
         end

data/lib/shrine/plugins/download_endpoint.rb

@@ -15,7 +15,15 @@ class Shrine
     # After loading the plugin the endpoint should be mounted on the specified
     # prefix:
     #
-    #     Rails.appliations.routes.draw do
+    #     # config.ru (Rack)
+    #     map "/attachments" do
+    #       run Shrine.download_endpoint
+    #     end
+    #
+    #     # OR
+    #
+    #     # config/routes.rb (Rails)
+    #     Rails.application.routes.draw do
     #       mount Shrine.download_endpoint => "/attachments"
     #     end
     #
@@ -160,8 +168,9 @@ class Shrine
 
         def stream_file(data)
           uploaded_file = get_uploaded_file(data)
+          range         = env["HTTP_RANGE"]
 
-          status, headers, body = uploaded_file.to_rack_response(disposition: disposition)
+          status, headers, body = uploaded_file.to_rack_response(disposition: disposition, range: range)
           headers["Cache-Control"] = "max-age=#{365*24*60*60}" # cache for a year
 
           request.halt [status, headers, body]

data/lib/shrine/plugins/logging.rb

@@ -103,9 +103,9 @@ class Shrine
           _log(
             action:       action,
             phase:        context[:action],
-            uploader:     self.class,
+            uploader:     self.class.to_s,
             attachment:   context[:name],
-            record_class: (context[:record].class if context[:record]),
+            record_class: (context[:record].class.to_s if context[:record]),
             record_id:    (context[:record].id if context[:record].respond_to?(:id)),
             files:        (action == "process" ? [count(input), count(result)] : count(result)),
             duration:     ("%.2f" % duration).to_f,
@@ -135,7 +135,7 @@ class Shrine
 
         def _log_message_json(data)
           data[:files] = Array(data[:files]).join("-")
-          data.to_json
+          JSON.generate(data)
         end
 
         def _log_message_heroku(data)

data/lib/shrine/plugins/metadata_attributes.rb

@@ -1,15 +1,13 @@
 class Shrine
   module Plugins
     # The `metadata_attributes` plugin allows you to sync attachment metadata
-    # to additional record attributes.
+    # to additional record attributes. You can provide a hash of mappings to
+    # the plugin call itself or the `Attacher.metadata_attributes` method:
     #
+    #     plugin :metadata_attributes, :size => :size, :mime_type => :type
+    #     # or
     #     plugin :metadata_attributes
-    #
-    # It provides `Attacher.metadata_attributes` method which allows you to
-    # specify mappings between metadata fields on the attachment and attribute
-    # names on the record.
-    #
-    #     Attacher.metadata_attributes :size => :size, :mime_type => :type
+    #     Attacher.metadata_attributes, :size => :size, :mime_type => :type
     #
     # The above configuration will sync `size` metadata field to
     # `<attachment>_size` record attribute, and `mime_type` metadata field to
@@ -25,11 +23,22 @@ class Shrine
     #     user.avatar_size #=> nil
     #     user.avatar_type #=> nil
     #
+    # If you want to specify the full record attribute name, pass the record
+    # attribute name as a string instead of a symbol.
+    #
+    #     Attacher.metadata_attributes, :filename => "original_filename"
+    #
+    #     # ...
+    #
+    #     photo.image = image
+    #     photo.original_filename #=> "nature.jpg"
+    #
     # If any corresponding metadata attribute doesn't exist on the record, that
     # metadata sync will be silently skipped.
     module MetadataAttributes
-      def self.configure(uploader)
+      def self.configure(uploader, mappings = {})
         uploader.opts[:metadata_attributes_mappings] ||= {}
+        uploader.opts[:metadata_attributes_mappings].merge!(mappings)
       end
 
       module AttacherClassMethods
@@ -44,12 +53,14 @@ class Shrine
           cached_file = get
 
           shrine_class.opts[:metadata_attributes_mappings].each do |source, destination|
-            next unless record.respond_to?(:"#{name}_#{destination}=")
+            attribute_name = destination.is_a?(Symbol) ? :"#{name}_#{destination}" : :"#{destination}"
+
+            next unless record.respond_to?(:"#{attribute_name}=")
 
             if cached_file
-              record.send(:"#{name}_#{destination}=", cached_file.metadata[source.to_s])
+              record.send(:"#{attribute_name}=", cached_file.metadata[source.to_s])
             else
-              record.send(:"#{name}_#{destination}=", nil)
+              record.send(:"#{attribute_name}=", nil)
             end
           end
         end

data/lib/shrine/plugins/presign_endpoint.rb

@@ -13,27 +13,32 @@ class Shrine
     #
     #     plugin :presign_endpoint
     #
-    # The plugin adds a `Shrine.presign_endpoint` method which accepts a
-    # storage identifier and returns a Rack application that accepts GET
-    # requests and generates a presign for the specified storage.
+    # The plugin adds a `Shrine.presign_endpoint` method which, given a storage
+    # identifier, returns a Rack application that accepts GET requests and
+    # generates a presign for the specified storage. You can run this Rack
+    # application inside your app:
     #
-    #     Shrine.presign_endpoint(:cache) # rack app
-    #
-    # Asynchronous upload is typically meant to replace the caching phase in
-    # the default synchronous workflow, so we want to generate parameters for
-    # uploads to the temporary (`:cache`) storage.
+    #     # config.ru (Rack)
+    #     map "/images/presign" do
+    #       run ImageUploader.presign_endpoint(:cache)
+    #     end
     #
-    # We can mount the returned Rack application inside our application:
+    #     # OR
     #
+    #     # config/routes.rb (Rails)
     #     Rails.application.routes.draw do
-    #       mount Shrine.presign_endpoint(:cache) => "/presign"
+    #       mount ImageUploader.presign_endpoint(:cache) => "/images/presign"
     #     end
     #
+    # Asynchronous upload is typically meant to replace the caching phase in
+    # the default synchronous workflow, so we want to generate parameters for
+    # uploads to the temporary (`:cache`) storage.
+    #
     # The above will create a `GET /presign` endpoint, which generates presign
     # URL, fields, and headers using the specified storage, and returns it in
     # JSON format.
     #
-    #     # GET /presign
+    #     # GET /images/presign
     #     {
     #       "url": "https://my-bucket.s3-eu-west-1.amazonaws.com",
     #       "fields": {
@@ -57,7 +62,7 @@ class Shrine
     # By default the generated location won't have any file extension, but you
     # can specify one by sending the `filename` query parameter:
     #
-    #     GET /presign?filename=nature.jpg
+    #     GET /images/presign?filename=nature.jpg
     #
     # It's also possible to customize how the presign location is generated:
     #
@@ -107,6 +112,9 @@ class Shrine
     #
     #     Shrine.presign_endpoint(:cache, presign_location: "${filename}")
     #
+    # [FineUploader]: https://github.com/FineUploader/fine-uploader
+    # [Dropzone]: https://github.com/enyo/dropzone
+    # [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
     # [Amazon S3]: https://aws.amazon.com/s3/
     # [Google Cloud Storage]: https://cloud.google.com/storage/
     # [Microsoft Azure Storage]: https://azure.microsoft.com/en-us/services/storage/

data/lib/shrine/plugins/rack_response.rb

@@ -13,7 +13,13 @@ class Shrine
     #
     #     status, headers, body = uploaded_file.to_rack_response
     #     status  #=> 200
-    #     headers #=> {"Content-Length" => "100", "Content-Type" => "text/plain", "Content-Disposition" => "inline; filename=\"file.txt\""}
+    #     headers #=>
+    #     # {
+    #     #   "Content-Length"      => "100",
+    #     #   "Content-Type"        => "text/plain",
+    #     #   "Content-Disposition" => "inline; filename=\"file.txt\"",
+    #     #   "Accept-Ranges"       => "bytes"
+    #     # }
     #     body    # object that responds to #each and #close
     #
     # An example how this can be used in a Rails controller:
@@ -29,30 +35,49 @@ class Shrine
     #       end
     #     end
     #
+    # ## Disposition
+    #
     # By default the "Content-Disposition" header will use the `inline`
     # disposition, but you can change it to `attachment` if you don't want the
     # file to be rendered inside the browser:
     #
     #     status, headers, body = uploaded_file.to_rack_response(disposition: "attachment")
     #     headers["Content-Disposition"] #=> "attachment; filename=\"file.txt\""
+    #
+    # ## Range
+    #
+    # [Partial responses][range requests] are also supported via the `:range`
+    # parameter, which accepts a value of the `Range` request header.
+    #
+    #     env["HTTP_RANGE"] #=> "bytes=100-200"
+    #     status, headers, body = uploaded_file.to_rack_response(range: env["HTTP_RANGE"])
+    #     status                    #=> 206
+    #     headers["Content-Length"] #=> "101"
+    #     headers["Content-Range"]  #=> "bytes 100-200/1000"
+    #     body                      # partial content
+    #
+    # [range requests]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
     module RackResponse
       module FileMethods
         # Returns a Rack response triple for the uploaded file.
-        def to_rack_response(disposition: "inline")
-          status  = 200
-          headers = rack_headers(disposition: disposition)
-          body    = rack_body
+        def to_rack_response(disposition: "inline", range: false)
+          range = parse_http_range(range) if range
+
+          status  = range ? 206 : 200
+          headers = rack_headers(disposition: disposition, range: range)
+          body    = rack_body(range: range)
 
           [status, headers, body]
         end
 
         private
 
-        # Returns a hash of "Content-Length", "Content-Type", and
+        # Returns a hash of "Content-Length", "Content-Type" and
         # "Content-Disposition" headers, whose values are extracted from
-        # metadata.
-        def rack_headers(disposition:)
-          length   = size || io.size
+        # metadata. Also returns the correct "Content-Range" header on ranged
+        # requests.
+        def rack_headers(disposition:, range: false)
+          length   = range ? range.end - range.begin + 1 : size || io.size
           type     = mime_type || Rack::Mime.mime_type(".#{extension}")
           filename = original_filename || id.split("/").last
 
@@ -60,22 +85,65 @@ class Shrine
           headers["Content-Length"]      = length.to_s if length
           headers["Content-Type"]        = type
           headers["Content-Disposition"] = "#{disposition}; filename=\"#{filename}\""
+          headers["Content-Range"]       = "bytes #{range.begin}-#{range.end}/#{size||io.size}" if range
+          headers["Accept-Ranges"]       = "bytes" unless range == false
 
           headers
         end
 
         # Returns an object that responds to #each and #close, which yields
         # contents of the file.
-        def rack_body
-          chunks = Enumerator.new do |yielder|
-            if io.respond_to?(:each_chunk) # Down::ChunkedIO
-              io.each_chunk { |chunk| yielder << chunk }
+        def rack_body(range: nil)
+          if range
+            body = enum_for(:read_partial_chunks, range)
+          else
+            body = enum_for(:read_chunks)
+          end
+
+          Rack::BodyProxy.new(body) { io.close }
+        end
+
+        # Yields reasonably sized chunks of uploaded file's partial content
+        # specified by the given index range.
+        def read_partial_chunks(range)
+          bytes_read = 0
+
+          read_chunks do |chunk|
+            chunk_range = bytes_read..(bytes_read + chunk.bytesize - 1)
+
+            if chunk_range.begin >= range.begin && chunk_range.end <= range.end
+              yield chunk
+            elsif chunk_range.end >= range.begin || chunk_range.end <= range.end
+              requested_range_begin = [chunk_range.begin, range.begin].max - bytes_read
+              requested_range_end   = [chunk_range.end, range.end].min - bytes_read
+
+              yield chunk.byteslice(requested_range_begin..requested_range_end)
             else
-              yielder << io.read(16*1024) until io.eof?
+              # skip chunk
             end
+
+            bytes_read += chunk.bytesize
+          end
+        end
+
+        # Yields reasonably sized chunks of uploaded file's content.
+        def read_chunks
+          if io.respond_to?(:each_chunk) # Down::ChunkedIO
+            io.each_chunk { |chunk| yield chunk }
+          else
+            yield io.read(16*1024) until io.eof?
+          end
+        end
+
+        # Parses the value of a "Range" HTTP header.
+        def parse_http_range(range_header)
+          if Rack.release >= "2.0"
+            ranges = Rack::Utils.get_byte_ranges(range_header, size || io.size)
+          else
+            ranges = Rack::Utils.byte_ranges({"HTTP_RANGE" => range_header}, size || io.size)
           end
 
-          Rack::BodyProxy.new(chunks) { io.close }
+          ranges.first if ranges && ranges.one?
         end
       end
     end

data/lib/shrine/plugins/signature.rb

@@ -29,24 +29,14 @@ class Shrine
     #       calculate_signature(io, :md5) if context[:action] == :cache
     #     end
     #
-    # The following hashing algorithms are supported:
-    #
-    # * `sha1`
-    # * `sha256`
-    # * `sha384`
-    # * `sha512`
-    # * `md5`
-    # * `crc32`
+    # The following hashing algorithms are supported: SHA1, SHA256, SHA384,
+    # SHA512, MD5, and CRC32.
     #
     # You can also choose which format will the calculated hash be encoded in:
     #
-    #     Shrine.calculate_signature(io, :md5, format: :hex)
-    #
-    # The following encoding formats are supported:
+    #     Shrine.calculate_signature(io, :sha256, format: :hex)
     #
-    # * `none`
-    # * `hex` (default)
-    # * `base64`
+    # The supported encoding formats are `hex` (default), `base64`, and `none`.
     module Signature
       module ClassMethods
         # Calculates `algorithm` hash of the contents of the IO object, and

data/lib/shrine/plugins/upload_endpoint.rb

@@ -11,25 +11,27 @@ class Shrine
     #
     #     plugin :upload_endpoint
     #
-    # The plugin adds a `Shrine.upload_endpoint` method which accepts a storage
-    # identifier and returns a Rack application that accepts multipart POST
-    # requests, and uploads received files to the specified storage.
-    #
-    #     Shrine.upload_endpoint(:cache) # rack app
-    #
-    # Asynchronous upload is typically meant to replace the caching phase in
-    # the default synchronous workflow, so we want the uploads to go to
-    # temporary (`:cache`) storage.
+    # The plugin adds a `Shrine.upload_endpoint` method which, given a storage
+    # identifier, returns a Rack application that accepts multipart POST
+    # requests, and uploads received files to the specified storage. You can
+    # run this Rack application inside your app:
+    #
+    #     # config.ru (Rack)
+    #     map "/images/upload" do
+    #       run ImageUploader.upload_endpoint(:cache)
+    #     end
     #
-    # When we want to mount the Rack application to our app, it's recommended
-    # to generate endpoints for specific uploaders. This is because different
-    # uploaders may have different uploading logic, and this also allows
-    # customizing the upload endpoint per uploader.
+    #     # OR
     #
+    #     # config/routes.rb (Rails)
     #     Rails.application.routes.draw do
     #       mount ImageUploader.upload_endpoint(:cache) => "/images/upload"
     #     end
     #
+    # Asynchronous upload is typically meant to replace the caching phase in
+    # the default synchronous workflow, so we want the uploads to go to
+    # temporary (`:cache`) storage.
+    #
     # The above will create a `POST /images/upload` endpoint, which uploads the
     # file received in the `file` param using `ImageUploader`, and returns a
     # JSON representation of the uploaded file.

data/lib/shrine/storage/file_system.rb

@@ -106,9 +106,9 @@ class Shrine
 
         if prefix
           @prefix = Pathname(relative(prefix))
-          @directory = Pathname(directory).join(@prefix)
+          @directory = Pathname(directory).join(@prefix).expand_path
         else
-          @directory = Pathname(directory)
+          @directory = Pathname(directory).expand_path
         end
 
         @host = host

data/lib/shrine/storage/s3.rb

@@ -1,9 +1,11 @@
+require "shrine"
 begin
   require "aws-sdk-s3"
   if Gem::Version.new(Aws::S3::GEM_VERSION) < Gem::Version.new("1.2.0")
     raise "Shrine::Storage::S3 requires aws-sdk-s3 version 1.2.0 or above"
   end
 rescue LoadError
+  Shrine.deprecation("Using aws-sdk 2.x is deprecated and support for it will be removed in Shrine 3, use the new aws-sdk-s3 gem instead.")
   require "aws-sdk"
   Aws.eager_autoload!(services: ["S3"])
 end
@@ -20,7 +22,7 @@ class Shrine
     #
     # It is initialized with the following 4 required options:
     #
-    #     storage = Shrine::Storage::S3.new(
+    #     s3 = Shrine::Storage::S3.new(
     #       access_key_id: "abc",
     #       secret_access_key: "xyz",
     #       region: "eu-west-1",
@@ -29,15 +31,15 @@ class Shrine
     #
     # The storage exposes the underlying Aws objects:
     #
-    #     storage.client #=> #<Aws::S3::Client>
-    #     storage.client.access_key_id #=> "abc"
-    #     storage.client.secret_access_key #=> "xyz"
-    #     storage.client.region #=> "eu-west-1"
+    #     s3.client #=> #<Aws::S3::Client>
+    #     s3.client.access_key_id #=> "abc"
+    #     s3.client.secret_access_key #=> "xyz"
+    #     s3.client.region #=> "eu-west-1"
     #
-    #     storage.bucket #=> #<Aws::S3::Bucket>
-    #     storage.bucket.name #=> "my-app"
+    #     s3.bucket #=> #<Aws::S3::Bucket>
+    #     s3.bucket.name #=> "my-app"
     #
-    #     storage.object("key") #=> #<Aws::S3::Object>
+    #     s3.object("key") #=> #<Aws::S3::Object>
     #
     # ## Prefix
     #
@@ -84,22 +86,27 @@ class Shrine
     # This storage supports various URL options that will be forwarded from
     # uploaded file.
     #
-    #     uploaded_file.url(public: true)   # public URL without signed parameters
-    #     uploaded_file.url(download: true) # forced download URL
+    #     s3.url(public: true)   # public URL without signed parameters
+    #     s3.url(download: true) # forced download URL
     #
     # All other options are forwarded to the aws-sdk-s3 gem:
     #
-    #     uploaded_file.url(expires_in: 15)
-    #     uploaded_file.url(virtual_host: true)
+    #     s3.url(expires_in: 15)
+    #     s3.url(virtual_host: true)
     #
     # ## CDN
     #
     # If you're using a CDN with S3 like Amazon CloudFront, you can specify
     # the `:host` option to `#url`:
     #
-    #     uploaded_file.url("image.jpg", host: "http://abc123.cloudfront.net")
+    #     s3.url("image.jpg", host: "http://abc123.cloudfront.net")
     #     #=> "http://abc123.cloudfront.net/image.jpg"
     #
+    # You have the `:host` option passed automatically for every URL with the
+    # `default_url_options` plugin.
+    #
+    #     plugin :default_url_options, store: { host: "http://abc123.cloudfront.net" }
+    #
     # ## Accelerate endpoint
     #
     # To use Amazon S3's [Transfer Acceleration] feature, you can change the
@@ -147,6 +154,11 @@ class Shrine
     # delete old files which aren't used anymore. S3 has a built-in way to do
     # this, read [this article][object lifecycle] for instructions.
     #
+    # Alternatively you can periodically call the `#clear!` method:
+    #
+    #     # deletes all objects that were uploaded more than 7 days ago
+    #     s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 }
+    #
     # [uploading]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#put-instance_method
     # [copying]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#copy_from-instance_method
     # [presigning]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
@@ -234,19 +246,25 @@ class Shrine
         end
       end
 
-      # Downloads the file from S3, and returns a `Tempfile`.
-      def download(id)
+      # Downloads the file from S3, and returns a `Tempfile`. And additional
+      # options are forwarded to [`Aws::S3::Object#get`].
+      #
+      # [`Aws::S3::Object#get`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#get-instance_method
+      def download(id, **options)
         tempfile = Tempfile.new(["shrine-s3", File.extname(id)], binmode: true)
-        (object = object(id)).get(response_target: tempfile)
+        (object = object(id)).get(response_target: tempfile, **options)
         tempfile.singleton_class.instance_eval { attr_accessor :content_type }
         tempfile.content_type = object.content_type
         tempfile.tap(&:open)
       end
 
-      # Returns a `Down::ChunkedIO` object representing the S3 object.
-      def open(id)
+      # Returns a `Down::ChunkedIO` object representing the S3 object. Any
+      # additional options are forwarded to [`Aws::S3::Object#get`].
+      #
+      # [`Aws::S3::Object#get`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#get-instance_method
+      def open(id, **options)
         object = object(id)
-        io = Down::ChunkedIO.new(chunks: object.enum_for(:get), data: {object: object})
+        io = Down::ChunkedIO.new(chunks: object.enum_for(:get, **options), data: { object: object })
         io.size = object.content_length
         io
       end
@@ -309,24 +327,32 @@ class Shrine
         object(id).presigned_post(options)
       end
 
-      # Deletes the file from S3.
+      # Deletes the file from the storage.
       def delete(id)
         object(id).delete
       end
 
-      # This is called when multiple files are being deleted at once. Issues a
-      # single MULTI DELETE command for each 1000 objects (S3 delete limit).
+      # Deletes multiple files at once from the storage.
       def multi_delete(ids)
-        ids.each_slice(1000) do |ids_batch|
-          delete_params = {objects: ids_batch.map { |id| {key: object(id).key} }}
-          bucket.delete_objects(delete: delete_params)
-        end
+        objects_to_delete = ids.map { |id| object(id) }
+        delete_objects(objects_to_delete)
       end
 
-      # Deletes all files from the storage.
-      def clear!
-        objects = bucket.object_versions(prefix: prefix)
-        objects.respond_to?(:batch_delete!) ? objects.batch_delete! : objects.delete
+      # If block is given, deletes all objects from the storage for which the
+      # block evaluates to true. Otherwise deletes all objects from the storage.
+      #
+      #     s3.clear!
+      #     # or
+      #     s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 }
+      def clear!(&block)
+        objects_to_delete = Enumerator.new do |yielder|
+          bucket.objects(prefix: prefix).each do |object|
+            condition = block.call(object) if block
+            yielder << object unless condition == false
+          end
+        end
+
+        delete_objects(objects_to_delete)
       end
 
       # Returns an `Aws::S3::Object` for the given id.
@@ -379,6 +405,15 @@ class Shrine
         io.storage.client.config.access_key_id == client.config.access_key_id
       end
 
+      # Deletes all objects in fewest requests possible (S3 only allows 1000
+      # objects to be deleted at once).
+      def delete_objects(objects)
+        objects.each_slice(1000) do |objects_batch|
+          delete_params = { objects: objects_batch.map { |object| { key: object.key } } }
+          bucket.delete_objects(delete: delete_params)
+        end
+      end
+
       # Upload requests will fail if filename has non-ASCII characters, because
       # of how S3 generates signatures, so we URI-encode them. Most browsers
       # should automatically URI-decode filenames when downloading.

data/lib/shrine/version.rb

@@ -5,10 +5,10 @@ class Shrine
 
   module VERSION
     MAJOR = 2
-    MINOR = 7
+    MINOR = 8
     TINY  = 0
     PRE   = nil
 
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-11 00:00:00.000000000 Z
+date: 2017-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down