shrine 2.2.0 → 2.3.0

data/lib/shrine/plugins/download_endpoint.rb

@@ -3,14 +3,14 @@ require "down"
 
 class Shrine
   module Plugins
-    # The download_endpoint plugin provides a [Roda] endpoint for downloading
+    # The `download_endpoint` plugin provides a Rack endpoint for downloading
     # uploaded files from specified storages. This can be useful when files
     # from your storages aren't accessible over URL (e.g. database storages) or
-    # if you want to authenticate your downloads.
+    # if you want to authenticate your downloads. It requires the [Roda] gem.
     #
     #     plugin :download_endpoint, storages: [:store], prefix: "attachments"
     #
-    # After loading the plugin the endpoint should be mounted:
+    # After loading the plugin the endpoint can be mounted:
     #
     #     Rails.appliations.routes.draw do
     #       mount Shrine::DownloadEndpoint => "/attachments"

data/lib/shrine/plugins/dynamic_storage.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The dynamic_storage plugin allows you to register a storage using a
+    # The `dynamic_storage` plugin allows you to register a storage using a
     # regex, and evaluate the storage class dynamically depending on the regex.
     #
     # Example:
@@ -16,7 +16,7 @@ class Shrine
     # saves files to the bucket "foo". The block is yielded an instance of
     # `MatchData`.
     #
-    # This can be useful in combination with the default_storage plugin.
+    # This can be useful in combination with the `default_storage` plugin.
     module DynamicStorage
       module ClassMethods
         def dynamic_storages

data/lib/shrine/plugins/hooks.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The hooks plugin allows you to trigger some code around
+    # The `hooks` plugin allows you to trigger some code around
     # processing/storing/deleting of each file.
     #
     #     plugin :hooks

data/lib/shrine/plugins/included.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The included plugin allows you to hook up to the `.included` hook of the
+    # The `included` plugin allows you to hook up to the `.included` hook of the
     # attachment module, and call additional methods on the model which includes
     # it.
     #
@@ -10,9 +10,8 @@ class Shrine
     #       end
     #     end
     #
-    # The block is evaluated in the context of the model via `instance_exec`.
-    # This means you cannot use keywords like `def`, instead you should use the
-    # metaprogramming equivalents like `define_method`.
+    # If you want to define additional methods on the model, it's recommended
+    # to use the `module_include` plugin instead.
     module Included
       def self.configure(uploader, &block)
         uploader.opts[:included_block] = block

data/lib/shrine/plugins/keep_files.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The keep_files plugin gives you the ability to prevent files from being
+    # The `keep_files` plugin gives you the ability to prevent files from being
     # deleted. This functionality is useful when implementing soft deletes, or
     # when implementing some kind of [event store] where you need to track
     # history.

data/lib/shrine/plugins/logging.rb

@@ -4,7 +4,7 @@ require "json"
 
 class Shrine
   module Plugins
-    # The logging plugin logs any storing/processing/deleting that is performed.
+    # The `logging` plugin logs any storing/processing/deleting that is performed.
     #
     #     plugin :logging
     #

data/lib/shrine/plugins/module_include.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The module_include plugin allows you to extend Shrine's core classes for
+    # The `module_include` plugin allows you to extend Shrine's core classes for
     # the given uploader with modules/methods.
     #
     #     plugin :module_include

data/lib/shrine/plugins/moving.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The moving plugin will *move* files to storages instead of copying them,
+    # The `moving` plugin will *move* files to storages instead of copying them,
     # when the storage supports it. For FileSystem this will issue a `mv`
     # command, which is instantaneous regardless of the filesize, so in that
     # case loading this plugin can significantly speed up the attachment
@@ -29,6 +29,7 @@ class Shrine
           end
         end
 
+        # Generates upload options and calls `#move` on the storage.
         def move(io, context)
           location = context[:location]
           metadata = context[:metadata]
@@ -37,14 +38,18 @@ class Shrine
           storage.move(io, location, shrine_metadata: metadata, **upload_options)
         end
 
-        def movable?(io, context)
-          storage.respond_to?(:move) && storage.movable?(io, context[:location])
-        end
-
+        # Returns true if file should be moved and is movable.
         def move?(io, context)
+          return false if context[:move] == false
           moving_storage? && movable?(io, context)
         end
 
+        # Returns true if storage can move this file.
+        def movable?(io, context)
+          storage.respond_to?(:move) && storage.movable?(io, context[:location])
+        end
+
+        # Returns true if file should be moved.
         def moving_storage?
           opts[:moving_storages].nil? ||
           opts[:moving_storages].include?(storage_key)

data/lib/shrine/plugins/multi_delete.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The multi_delete plugins allows you to leverage your storage's multi
+    # The `multi_delete` plugins allows you to leverage your storage's multi
     # delete capabilities.
     #
     #     plugin :multi_delete
@@ -11,7 +11,7 @@ class Shrine
     #
     # Now if you're using Storage::S3, deleting an array of files will issue a
     # single HTTP request. Some other storages may support multi deletes as
-    # well. The versions plugin uses this plugin for deleting multiple versions
+    # well. The `versions` plugin uses this plugin for deleting multiple versions
     # at once.
     module MultiDelete
       module InstanceMethods

data/lib/shrine/plugins/parallelize.rb

@@ -2,8 +2,8 @@ require "thread"
 
 class Shrine
   module Plugins
-    # The parallelize plugin parallelizes uploads and deletes when handling
-    # versions, using threads.
+    # The `parallelize` plugin parallelizes uploads and deletes of multiple
+    # versions using threads.
     #
     #     plugin :parallelize
     #

data/lib/shrine/plugins/parsed_json.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The parsed_json plugin is suitable for the case when your framework is
+    # The `parsed_json` plugin is suitable for the case when your framework is
     # automatically parsing JSON query parameters, allowing you to assign
     # cached files with hashes/arrays.
     #

data/lib/shrine/plugins/pretty_location.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The pretty_location plugin attempts to generate a nicer folder structure
+    # The `pretty_location` plugin attempts to generate a nicer folder structure
     # for uploaded files.
     #
     #     plugin :pretty_location

data/lib/shrine/plugins/processing.rb

@@ -1,25 +1,27 @@
 class Shrine
   module Plugins
-    # The process plugin allows you to declaratively define
-    # file processing for specified actions, allowing you to transform
+    # The `processing` plugin allows you to declaratively define file processing
+    # for specified actions.
     #
-    #     def process(io, context)
-    #       if context[:action] == :store
-    #         # ...
-    #       end
-    #     end
-    #
-    # into
+    #     plugin :processing
     #
     #     process(:store) do |io, context|
     #       # ...
     #     end
     #
+    # The `io` is the original file, while the `context` contains some
+    # additional information about the upload. The result of the processing
+    # block should be an IO-like object, which will continue being uploaded
+    # instead of the original.
+    #
     # The declarations are additive and inherited, so for the same action you
     # can declare multiple blocks, and they will be performed in the same order,
     # where output from previous will be input to next. You can return `nil`
     # in any block to signal that no processing was performed and that the
     # original file should be used.
+    #
+    # If you want the result of processing to be multiple files, use the
+    # `versions` plugin.
     module Processing
       def self.configure(uploader)
         uploader.opts[:processing] = {}

data/lib/shrine/plugins/rack_file.rb

@@ -2,7 +2,7 @@ require "forwardable"
 
 class Shrine
   module Plugins
-    # The rack_file plugin enables models to accept Rack file hashes as
+    # The `rack_file` plugin enables models to accept Rack file hashes as
     # attachments.
     #
     #     rack_file #=>

data/lib/shrine/plugins/recache.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The recache plugin allows you to process your attachment after
+    # The `recache` plugin allows you to process your attachment after
     # validations succeed, but before the attachment is promoted. This is
     # useful for example when you want to generate some versions upfront (so
     # the user immediately sees them) and other versions you want to generate
@@ -16,14 +16,24 @@ class Shrine
     #     process(:store) do |io, context|
     #       # perform more expensive processing
     #     end
+    #
+    # Recaching will be automatically triggered in a "before save" callback,
+    # but if you're using the attacher directly, you can call it manually:
+    #
+    #     attacher.recache if attacher.attached?
     module Recache
       module AttacherMethods
         def save
-          if get && cache.uploaded?(get)
-            _set cache!(get, action: :recache)
-          end
+          recache
           super
         end
+
+        def recache
+          if cached?
+            recached = cache!(get, action: :recache)
+            _set(recached)
+          end
+        end
       end
     end
 

data/lib/shrine/plugins/remote_url.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The remote_url plugin allows you to attach files from a remote location.
+    # The `remote_url` plugin allows you to attach files from a remote location.
     #
     #     plugin :remote_url, max_size: 20*1024*1024
     #

data/lib/shrine/plugins/remove_attachment.rb

@@ -1,13 +1,13 @@
 class Shrine
   module Plugins
-    # The remove_attachment plugin allows you to delete attachments through
+    # The `remove_attachment` plugin allows you to delete attachments through
     # checkboxes on the web form.
     #
     #     plugin :remove_attachment
     #
     # If for example your attachment is called "avatar", this plugin will add
     # `#remove_avatar` and `#remove_avatar=` methods to your model. This allows
-    # you to easily enable deleting attached files through the form:
+    # you to easily delete attached files through the form:
     #
     #     <%= form_for @user do |f| %>
     #       <%= f.hidden_field :avatar, value: @user.avatar_data %>
@@ -16,8 +16,7 @@ class Shrine
     #     <% end %>
     #
     # Now when the checkbox is ticked and the form is submitted, the attached
-    # file will be removed. Note that the "remove_avatar" field needs to be
-    # declared somewhere after the hidden field.
+    # file will be removed.
     module RemoveAttachment
       module AttachmentMethods
         def initialize(*)

data/lib/shrine/plugins/remove_invalid.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The remove_invalid plugin automatically deletes a cached file if it was
+    # The `remove_invalid` plugin automatically deletes a cached file if it was
     # invalid and deassigns it from the record.
     #
     #     plugin :remove_invalid

data/lib/shrine/plugins/restore_cached_data.rb

@@ -1,11 +1,18 @@
 class Shrine
   module Plugins
-    # The restore_cached_data plugin ensures the cached file metadata hasn't
-    # been tampered with, which can be done by modifying the hidden field
-    # before submitting the form. The cached file's metadata will be
-    # reextracted during assignment and replaced with potentially tampered one.
+    # The `restore_cached_data` plugin re-extracts cached file's metadata on
+    # assignment. This happens when an uploaded file is retained on validation
+    # errors, or when assigning direct uploaded files. In both cases you
+    # usually want to re-extract metadata on the server side, mainly to prevent
+    # tempering, but also in case of direct uploads to obtain metadata that
+    # couldn't be extracted on the client side.
     #
     #     plugin :restore_cached_data
+    #
+    # This will give an opened `UploadedFile` for metadata extraction. For
+    # remote storages this will make an HTTP request, and since metadata is
+    # typically found in the beginning of the file, Shrine will download only
+    # the amount of bytes necessary for extracting the metadata.
     module RestoreCachedData
       module AttacherMethods
         private

data/lib/shrine/plugins/sequel.rb

@@ -2,7 +2,7 @@ require "sequel"
 
 class Shrine
   module Plugins
-    # The sequel plugin extends the "attachment" interface with support for
+    # The `sequel` plugin extends the "attachment" interface with support for
     # Sequel.
     #
     #     plugin :sequel
@@ -20,7 +20,7 @@ class Shrine
     # you should first disable transactions for those tests.
     #
     # If you want to put promoting/deleting into a background job, see the
-    # backgrounding plugin.
+    # `backgrounding` plugin.
     #
     # Since attaching first saves the record with a cached attachment, then
     # saves again with a stored attachment, you can detect this in callbacks:
@@ -73,69 +73,58 @@ class Shrine
 
           return unless model < ::Sequel::Model
 
-          if shrine_class.opts[:sequel_validations]
-            module_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def validate
-                super
-                #{@name}_attacher.errors.each do |message|
-                  errors.add(:#{@name}, message)
-                end
-              end
-            RUBY
-          end
+          opts = shrine_class.opts
 
-          if shrine_class.opts[:sequel_callbacks]
-            module_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def before_save
-                super
-                #{@name}_attacher.save if #{@name}_attacher.attached?
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:sequel_validations]
+            def validate
+              super
+              #{@name}_attacher.errors.each do |message|
+                errors.add(:#{@name}, message)
               end
+            end
+          RUBY
 
-              def after_commit
-                super
-                #{@name}_attacher.finalize if #{@name}_attacher.attached?
-              end
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:sequel_callbacks]
+            def before_save
+              super
+              #{@name}_attacher.save if #{@name}_attacher.attached?
+            end
 
-              def after_destroy_commit
-                super
-                #{@name}_attacher.destroy
-              end
-            RUBY
-          end
+            def after_commit
+              super
+              #{@name}_attacher.finalize if #{@name}_attacher.attached?
+            end
+
+            def after_destroy_commit
+              super
+              #{@name}_attacher.destroy
+            end
+          RUBY
         end
       end
 
       module AttacherClassMethods
-        # Needed by the backgrounding plugin.
+        # Needed by the `backgrounding` plugin.
         def find_record(record_class, record_id)
           record_class.with_pk(record_id)
         end
       end
 
       module AttacherMethods
-        private
-
-        # Proceeds with updating the record unless the attachment has changed.
-        def swap(uploaded_file)
-          return if record.send(:"#{name}_data") != record.reload.send(:"#{name}_data")
-          super
-        rescue ::Sequel::NoExistingObject
-        rescue ::Sequel::Error => error
-          raise unless error.message == "Record not found" # prior to version 4.28
-        end
-
-        # Saves the record after assignment, skipping validations.
-        def update(uploaded_file)
-          super
-          record.save(validate: false)
-        end
-
         # Support for Postgres JSON columns.
         def read
           value = super
           value = value.to_hash if value.respond_to?(:to_hash)
           value
         end
+
+        private
+
+        # Saves the record after assignment, skipping validations.
+        def update(uploaded_file)
+          super
+          record.save_changes(validate: false)
+        end
       end
     end