shrine 2.4.1 → 2.5.0

data/lib/shrine/plugins/versions.rb

@@ -12,22 +12,27 @@ class Shrine
     #     plugin :processing
     #
     #     process(:store) do |io, context|
-    #       size_700 = resize_to_limit(io.download, 700, 700)
-    #       size_500 = resize_to_limit(size_700,    500, 500)
-    #       size_300 = resize_to_limit(size_500,    300, 300)
+    #       original = io.download
     #
-    #       {large: size_700, medium: size_500, small: size_300}
+    #       size_800 = resize_to_limit!(original, 800, 800)
+    #       size_500 = resize_to_limit(size_800,  500, 500)
+    #       size_300 = resize_to_limit(size_500,  300, 300)
+    #
+    #       {large: size_800, medium: size_500, small: size_300}
     #     end
     #
+    # You probably want to load the `delete_raw` plugin to automatically
+    # delete processed files after they have been uploaded.
+    #
     # Now when you access the stored attachment through the model, a hash of
     # uploaded files will be returned:
     #
-    #     JSON.parse(user.avatar_data) #=>
-    #     # {
-    #     #   "large"  => {"id" => "lg043.jpg", "storage" => "store", "metadata" => {...}},
-    #     #   "medium" => {"id" => "kd9fk.jpg", "storage" => "store", "metadata" => {...}},
-    #     #   "small"  => {"id" => "932fl.jpg", "storage" => "store", "metadata" => {...}},
-    #     # }
+    #     user.avatar_data #=>
+    #     # '{
+    #     #   "large": {"id":"lg043.jpg", "storage":"store", "metadata":{...}},
+    #     #   "medium": {"id":"kd9fk.jpg", "storage":"store", "metadata":{...}},
+    #     #   "small": {"id":"932fl.jpg", "storage":"store", "metadata":{...}}
+    #     # }'
     #
     #     user.avatar #=>
     #     # {
@@ -36,43 +41,50 @@ class Shrine
     #     #   :small =>  #<Shrine::UploadedFile @data={"id"=>"932fl.jpg", ...}>,
     #     # }
     #
-    #     # With the store_dimensions plugin
-    #     user.avatar[:large].width  #=> 700
-    #     user.avatar[:medium].width #=> 500
-    #     user.avatar[:small].width  #=> 300
+    #     user.avatar[:medium]     #=> #<Shrine::UploadedFile>
+    #     user.avatar[:medium].url #=> "/uploads/store/lg043.jpg"
     #
-    # You probably want to load the `delete_raw` plugin to automatically
-    # delete processed files after they have been uploaded.
+    # The plugin also extends the `Attacher#url` to accept versions:
+    #
+    #     user.avatar_url(:large)
+    #     user.avatar_url(:small, download: true) # with URL options
     #
     # ## Original file
     #
-    # If you want to keep the original file, you can forward it as is without
-    # explicitly downloading it (since `Shrine::UploadedFile` itself is an
-    # IO-like object), which might avoid downloading depending on the storage:
+    # If you want to keep the original file, you can include the original
+    # `Shrine::UploadedFile` object as one of the versions:
     #
     #     process(:store) do |io, context|
     #       # processing thumbnail
     #       {original: io, thumbnail: thumbnail}
     #     end
     #
+    # If both temporary and permanent storage are Amazon S3, the cached original
+    # will simply be copied over to permanent storage (without any downloading
+    # and reuploading), so in these cases the performance impact of storing the
+    # original file in addition to processed versions is neglibible.
+    #
     # ## Fallbacks
     #
-    # The plugin also extends the `<attachmen>_url` method to accept versions,
-    # and adds automatic fallbacks:
+    # If versions are processed in a background job, there will be a period
+    # where the user will browse the site before versions have finished
+    # processing. In this period `Attacher#url` will by default fall back to
+    # the original file.
     #
-    #     user.avatar_url(:medium)
+    #     user.avatar #=> #<Shrine::UploadedFile>
+    #     user.avatar_url(:large) # falls back to `user.avatar_url`
     #
-    #     # returns URL of that version if versions have been created,
-    #     # otherwise returns original URL if attachment exists,
-    #     # otherwise returns nil
+    # This behaviour is convenient if you want to gracefully degrade to the
+    # cached file until the background job has finished processing. However, if
+    # you would rather provide your own default URLs for versions, you can
+    # disable this fallback:
     #
-    # This behaviour is convenient when using background jobs, as it allows you
-    # to gracefully degrade before the background job finishes.
+    #     plugin :versions, fallback_to_original: false
     #
-    # If you already have some versions processed in the foreground when a
-    # background job is kicked off (with the `recache` plugin), the
-    # `<attachment>_url` method won't know which version to use as a fallback.
-    # In that case you can specify `:fallbacks` when loading the plugin:
+    # If you already have some versions processed in the foreground after a
+    # background job is kicked off (with the `recache` plugin), you can have
+    # URLs for versions that are yet to be processed fall back to existing
+    # versions:
     #
     #     plugin :versions, fallbacks: {
     #       :thumb_2x => :thumb,
@@ -84,22 +96,17 @@ class Shrine
     #     user.avatar_url(:thumb_2x) # returns :thumb URL until :thumb_2x becomes available
     #     user.avatar_url(:large_2x) # returns :large URL until :large_2x becomes available
     #
-    # Any additional options will be properly forwarded to the underlying
-    # storage:
-    #
-    #     user.avatar_url(:medium, download: true)
-    #
     # ## Context
     #
-    # The `context` will now also include the version name, which you can use
-    # when generating a location or a default URL:
+    # The version name will be available via `:version` when generating
+    # location or a default URL.
     #
     #     def generate_location(io, context)
     #       "uploads/#{context[:version]}-#{super}"
     #     end
     #
-    #     plugin :default_url do |context|
-    #       "/images/defaults/#{context[:version]}.jpg"
+    #     Attacher.default_url do |options|
+    #       "/images/defaults/#{options[:version]}.jpg"
     #     end
     #
     # [image_processing]: https://github.com/janko-m/image_processing
@@ -114,6 +121,7 @@ class Shrine
 
         uploader.opts[:version_names] = opts.fetch(:names, uploader.opts[:version_names])
         uploader.opts[:version_fallbacks] = opts.fetch(:fallbacks, uploader.opts.fetch(:version_fallbacks, {}))
+        uploader.opts[:versions_fallback_to_original] = opts.fetch(:fallback_to_original, uploader.opts.fetch(:versions_fallback_to_original, true))
       end
 
       module ClassMethods
@@ -163,6 +171,10 @@ class Shrine
         def _store(io, context)
           if (hash = io).is_a?(Hash)
             raise Error, ":location is not applicable to versions" if context.key?(:location)
+            if duplicates = hash.keys.group_by{|k| hash[k]}.values.reject(&:one?).first
+              raise Error, "The following version keys point to the same IO object: #{duplicates.inspect}. Shrine cannot upload the same IO object multiple times."
+            end
+
             hash.inject({}) do |result, (name, version)|
               result.update(name => _store(version, version: name, **context))
             end
@@ -186,29 +198,39 @@ class Shrine
         # Smart versioned URLs, which include the version name in the default
         # URL, and properly forwards any options to the underlying storage.
         def url(version = nil, **options)
-          if get.is_a?(Hash)
+          attachment = get
+
+          if attachment.is_a?(Hash)
             if version
-              if file = get[version]
-                file.url(**options)
+              if attachment.key?(version)
+                attachment[version].url(**options)
               elsif fallback = shrine_class.version_fallbacks[version]
                 url(fallback, **options)
               else
                 default_url(**options, version: version)
               end
             else
-              raise Error, "must call #{name}_url with the name of the version"
+              raise Error, "must call Shrine::Attacher#url with the name of the version"
             end
           else
-            if get || version.nil?
-              super(**options)
+            if version
+              if attachment && fallback_to_original?
+                attachment.url(**options)
+              else
+                default_url(**options, version: version)
+              end
             else
-              default_url(**options, version: version)
+              super(**options)
             end
           end
         end
 
         private
 
+        def fallback_to_original?
+          shrine_class.opts[:versions_fallback_to_original]
+        end
+
         def assign_cached(value)
           cached_file = uploaded_file(value)
           warn "Assigning cached hash of files is deprecated for security reasons and will be removed in Shrine 3." if cached_file.is_a?(Hash)

data/lib/shrine/storage/file_system.rb

@@ -42,8 +42,8 @@ class Shrine
     # ## Clearing cache
     #
     # If you're using FileSystem as cache, you will probably want to
-    # periodically delete old files which aren't used anymore. You can put
-    # the following in a periodic Rake task:
+    # periodically delete old files which aren't used anymore. You can run
+    # something like this periodically:
     #
     #     file_system = Shrine.storages[:cache]
     #     file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
@@ -187,7 +187,7 @@ class Shrine
         if name == :download
           warn "Shrine::Storage::FileSystem#download is deprecated and will be removed in Shrine 3."
           require "down"
-          open(id) { |file| Down.copy_to_tempfile(id, file) }
+          open(*args) { |file| Down.copy_to_tempfile(*args, file) }
         else
           super
         end

data/lib/shrine/storage/linter.rb

@@ -85,7 +85,7 @@ class Shrine
         storage.delete(id)
         error :delete, "file still #exists? after deleting" if storage.exists?(id)
         begin
-          storage.delete(SecureRandom.hex)
+          storage.delete(id)
         rescue => exception
           error :delete, "shouldn't fail if the file doesn't exist, but raised #{exception.class}"
         end

data/lib/shrine/storage/s3.rb

@@ -39,7 +39,7 @@ class Shrine
     # [copying] and [presigning].
     #
     # You can also generate upload options per upload with the `upload_options`
-    # plugin:
+    # plugin
     #
     #     class MyUploader < Shrine
     #       plugin :upload_options, store: ->(io, context) do
@@ -51,9 +51,13 @@ class Shrine
     #       end
     #     end
     #
-    # Note that, unlike the `:upload_options` storage option, the
-    # `upload_options` plugin won't forward the given options for generating
-    # presigns, since presigns are generated using the storage directly.
+    # or when using the uploader directly
+    #
+    #     uploader.upload(file, upload_options: {acl: "public-read"})
+    #
+    # Note that, unlike the `:upload_options` storage option, upload options
+    # given on the uploader level won't be forwarded for generating presigns,
+    # since presigns are generated using the storage directly.
     #
     # ## URL options
     #

data/lib/shrine/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-17 00:00:00.000000000 Z
+date: 2016-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -301,6 +301,7 @@ files:
 - doc/design.md
 - doc/direct_s3.md
 - doc/migrating_storage.md
+- doc/multiple_files.md
 - doc/paperclip.md
 - doc/refile.md
 - doc/regenerating_versions.md