shrine 2.2.0 → 2.3.0

data/lib/shrine/plugins/activerecord.rb

@@ -2,7 +2,7 @@ require "active_record"
 
 class Shrine
   module Plugins
-    # The activerecord plugin extends the "attachment" interface with support
+    # The `activerecord` plugin extends the "attachment" interface with support
     # for ActiveRecord.
     #
     #     plugin :activerecord
@@ -27,7 +27,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:
@@ -78,36 +78,34 @@ class Shrine
 
           return unless model < ::ActiveRecord::Base
 
-          if shrine_class.opts[:activerecord_validations]
-            model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              validate do
-                #{@name}_attacher.errors.each do |message|
-                  errors.add(:#{@name}, message)
-                end
-              end
-            RUBY
-          end
+          opts = shrine_class.opts
 
-          if shrine_class.opts[:activerecord_callbacks]
-            model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              before_save do
-                #{@name}_attacher.save if #{@name}_attacher.attached?
+          model.class_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:activerecord_validations]
+            validate do
+              #{@name}_attacher.errors.each do |message|
+                errors.add(:#{@name}, message)
               end
+            end
+          RUBY
 
-              after_commit on: [:create, :update] do
-                #{@name}_attacher.finalize if #{@name}_attacher.attached?
-              end
+          model.class_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:activerecord_callbacks]
+            before_save do
+              #{@name}_attacher.save if #{@name}_attacher.attached?
+            end
 
-              after_commit on: [:destroy] do
-                #{@name}_attacher.destroy
-              end
-            RUBY
-          end
+            after_commit on: [:create, :update] do
+              #{@name}_attacher.finalize if #{@name}_attacher.attached?
+            end
+
+            after_commit on: [:destroy] do
+              #{@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.where(id: record_id).first
         end
@@ -116,13 +114,6 @@ class Shrine
       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 ::ActiveRecord::RecordNotFound
-        end
-
         # Saves the record after assignment, skipping validations.
         def update(uploaded_file)
           super

data/lib/shrine/plugins/add_metadata.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The metadata plugin provides a convenient method for extracting and
+    # The `add_metadata` plugin provides a convenient method for extracting and
     # adding custom metadata values.
     #
     #     plugin :add_metadata

data/lib/shrine/plugins/backgrounding.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The backgrounding plugin enables you to remove processing/storing/deleting
+    # The `backgrounding` plugin enables you to remove processing/storing/deleting
     # of files from record's lifecycle, and put them into background jobs.
     # This is generally useful if you're doing processing and/or your store is
     # something other than Storage::FileSystem.
@@ -38,7 +38,7 @@ class Shrine
     # any other backgrounding library. This setup will work globally for all
     # uploaders.
     #
-    # The backgrounding plugin affects the `Shrine::Attacher` in a way that
+    # The `backgrounding` plugin affects the `Shrine::Attacher` in a way that
     # `#_promote` and `#_delete` spawn background jobs, while `#promote` and
     # `#delete!` are always synchronous:
     #
@@ -81,7 +81,7 @@ class Shrine
     #
     # If you're generating versions, and you want to process some versions in
     # the foreground before kicking off a background job, you can use the
-    # recache plugin.
+    # `recache` plugin.
     module Backgrounding
       module AttacherClassMethods
         # If block is passed in, stores it to be called on promotion. Otherwise
@@ -127,8 +127,12 @@ class Shrine
         def load(data)
           record_class, record_id = data["record"]
           record_class = Object.const_get(record_class)
-          record = find_record(record_class, record_id) ||
-            record_class.new.tap { |object| object.id = record_id }
+
+          record   = find_record(record_class, record_id)
+          record ||= record_class.new.tap do |instance|
+            # so that the id is always included in file deletion logs
+            instance.singleton_class.send(:define_method, :id) { record_id }
+          end
 
           name = data["name"].to_sym
 
@@ -136,6 +140,7 @@ class Shrine
             shrine_class = Object.const_get(data["shrine_class"])
             attacher = shrine_class::Attacher.new(record, name)
           else
+            # anonymous uploader class, try to retrieve attacher from record
             attacher = record.send("#{name}_attacher")
           end
 
@@ -150,8 +155,8 @@ class Shrine
           if background_promote = shrine_class.opts[:backgrounding_promote]
             data = self.class.dump(self).merge(
               "attachment" => uploaded_file.to_json,
-              "phase"      => (action.to_s if action),
               "action"     => (action.to_s if action),
+              "phase"      => (action.to_s if action), # legacy
             )
             instance_exec(data, &background_promote)
           else
@@ -165,8 +170,8 @@ class Shrine
           if background_delete = shrine_class.opts[:backgrounding_delete]
             data = self.class.dump(self).merge(
               "attachment" => uploaded_file.to_json,
-              "phase"      => (action.to_s if action),
               "action"     => (action.to_s if action),
+              "phase"      => (action.to_s if action), # legacy
             )
             instance_exec(data, &background_delete)
             uploaded_file
@@ -185,6 +190,13 @@ class Shrine
             "shrine_class" => shrine_class.name,
           }
         end
+
+        # Updates with the new file only if the attachment hasn't changed.
+        def swap(new_file)
+          reloaded = self.class.find_record(record.class, record.id)
+          return if reloaded.nil? || self.class.new(reloaded, name).read != read
+          super
+        end
       end
     end
 

data/lib/shrine/plugins/backup.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The backup plugin allows you to automatically back up stored files to
+    # The `backup` plugin allows you to automatically back up stored files to
     # an additional storage.
     #
     #     storages[:backup_store] = Shrine::Storage::S3.new(options)
@@ -64,7 +64,7 @@ class Shrine
 
         # Upload the stored file to the backup storage.
         def store_backup!(stored_file)
-          options = _equalize_phase_and_action(action: :backup)
+          options = _equalize_phase_and_action(action: :backup, move: false)
           backup_store.upload(stored_file, context.merge(options))
         end
 

data/lib/shrine/plugins/cached_attachment_data.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The cached_attachment_data plugin adds the ability to retain the cached
+    # The `cached_attachment_data` plugin adds the ability to retain the cached
     # file across form redisplays, which means the file doesn't have to be
     # reuploaded in case of validation errors.
     #

data/lib/shrine/plugins/copy.rb

@@ -0,0 +1,52 @@
+class Shrine
+  module Plugins
+    # The `copy` plugin allows copying attachment from one record to another.
+    #
+    #     plugin :copy
+    #
+    # It adds a `Attacher#copy` method, which accepts another attacher, and
+    # copies the attachment from it:
+    #
+    #     photo.image_attacher.copy(other_photo.image_attacher)
+    #
+    # This method will automatically be called when the record is duplicated:
+    #
+    #     duplicated_photo = photo.dup
+    #     duplicated_photo.image #=> #<Shrine::UploadedFile>
+    #     duplicated_photo.image != photo.image
+    module Copy
+      module AttachmentMethods
+        def initialize(*)
+          super
+
+          module_eval <<-RUBY
+            def initialize_copy(record)
+              super
+              @#{@name}_attacher = nil # reload the attacher
+              self.#{@name}_data = nil # remove original attachment
+              #{@name}_attacher.copy(record.#{@name}_attacher)
+            end
+          RUBY
+        end
+      end
+
+      module AttacherMethods
+        def copy(attacher)
+          options = {action: :copy, move: false}
+
+          if attacher.cached?
+            copied_attachment = cache!(attacher.get, **options)
+          elsif attacher.stored?
+            copied_attachment = store!(attacher.get, **options)
+          else
+            copied_attachment = nil
+          end
+
+          set(copied_attachment)
+        end
+      end
+    end
+
+    register_plugin(:copy, Copy)
+  end
+end

data/lib/shrine/plugins/data_uri.rb

@@ -3,7 +3,7 @@ require "stringio"
 
 class Shrine
   module Plugins
-    # The data_uri plugin enables you to upload files as [data URIs].
+    # The `data_uri` plugin enables you to upload files as [data URIs].
     # This plugin is useful for example when using [HTML5 Canvas].
     #
     #     plugin :data_uri

data/lib/shrine/plugins/default_storage.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The default_storage plugin enables you to change which storages are going
+    # The `default_storage` plugin enables you to change which storages are going
     # to be used for this uploader's attacher (the default is `:cache` and
     # `:store`).
     #
@@ -8,7 +8,7 @@ class Shrine
     #
     # You can also pass a block and choose the values depending on the record
     # values and the name of the attachment. This is useful if you're using the
-    # dynamic_storage plugin. Example:
+    # `dynamic_storage` plugin. Example:
     #
     #     plugin :default_storage, store: ->(record, name) { :"store_#{record.username}" }
     module DefaultStorage

data/lib/shrine/plugins/default_url.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The default_url plugin allows setting the URL which will be returned when
+    # The `default_url` plugin allows setting the URL which will be returned when
     # the attachment is missing.
     #
     #     plugin :default_url do |context|

data/lib/shrine/plugins/default_url_options.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The default_url_options plugin allows you to specify URL options that
+    # The `default_url_options` plugin allows you to specify URL options that
     # will be applied by default for uploaded files of specified storages.
     #
     #     plugin :default_url_options, store: {download: true}

data/lib/shrine/plugins/delete_promoted.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The delete_promoted plugin deletes files that have been promoted, after
+    # The `delete_promoted` plugin deletes files that have been promoted, after
     # the record is saved. This means that cached files handled by the attacher
     # will automatically get deleted once they're uploaded to store. This also
     # applies to any other uploaded file passed to `Attacher#promote`.

data/lib/shrine/plugins/delete_raw.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The delete_raw plugin will automatically delete raw files that have been
+    # The `delete_raw` plugin will automatically delete raw files that have been
     # uploaded. This is especially useful when doing processing, to ensure that
     # temporary files have been deleted after upload.
     #

data/lib/shrine/plugins/determine_mime_type.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The determine_mime_type plugin stores the actual MIME type of the
+    # The `determine_mime_type` plugin stores the actual MIME type of the
     # uploaded file.
     #
     #     plugin :determine_mime_type
@@ -37,7 +37,8 @@ class Shrine
     #   "Content-Type" request header, which might not hold the actual MIME type
     #   of the file.
     #
-    # If none of these quite suit your needs, you can build a custom analyzer:
+    # Not all analyzers can recognize all types of files. For those cases you
+    # can build your own analyzer, where you can reuse built-in analyzers:
     #
     #     plugin :determine_mime_type, analyzer: ->(io, analyzers) do
     #       analyzers[:mimemagic].call(io) || analyzers[:file].call(io)

data/lib/shrine/plugins/direct_upload.rb

@@ -3,8 +3,8 @@ require "json"
 
 class Shrine
   module Plugins
-    # The direct_upload plugin provides a [Roda] endpoint which can be used for
-    # uploading individual files asynchronously.
+    # The `direct_upload` plugin provides a Rack endpoint which can be used for
+    # uploading individual files asynchronously. It requires the [Roda] gem.
     #
     #     plugin :direct_upload
     #
@@ -27,7 +27,7 @@ class Shrine
     # Now your application will get `POST /images/cache/upload` and `GET
     # /images/cache/presign` routes. Whether you upload files to your app or to
     # to a 3rd-party service, you'll probably want to use a JavaScript file
-    # upload library like [jQuery-File-Upload] or [Dropzone].
+    # upload library like [jQuery-File-Upload], [Dropzone] or [FineUploader].
     #
     # ## Uploads
     #
@@ -89,21 +89,24 @@ class Shrine
     #
     #     plugin :direct_upload, presign_location: ->(request) { "${filename}" }
     #
-    # This presign route internally calls `#presign` on the storage, which also
-    # accepts some service-specific options. You can generate these additional
-    # options per-request with `:presign_options`:
+    # This presign route internally calls `#presign` on the storage, and many
+    # storages accept additional service-specific options. You can generate
+    # these additional options per-request through `:presign_options`:
     #
     #     plugin :direct_upload, presign_options: {acl: "public-read"}
     #
     #     plugin :direct_upload, presign_options: ->(request) do
-    #       options = {}
-    #       options[:content_length_range] = 0..(5*1024*1024)       # limit the filesize to 5 MB
-    #       options[:content_type] = request.params["content_type"] # use "content_type" query parameter
-    #       options
+    #       filename = request.params["filename"].inspect
+    #
+    #       {
+    #         content_length_range: 0..(10*1024*1024),                 # limit filesize to 10MB
+    #         content_disposition: "attachment; filename=#{filename}", # download with original filename
+    #       }
     #     end
     #
     # Both `:presign_location` and `:presign_options` in their block versions
-    # are yielded an instance of [`Roda::Request`].
+    # are yielded an instance of [Roda request], which is a subclass of
+    # `Rack::Request`.
     #
     # See the [Direct Uploads to S3] guide for further instructions on how to
     # hook the presigned uploads to a form.
@@ -117,27 +120,36 @@ class Shrine
     #
     # ## Allowed storages
     #
-    # While Shrine only accepts cached attachments on form submits (for security
-    # reasons), you can use this endpoint to upload files to any storage, just
-    # add it to allowed storages:
+    # By default only uploads to `:cache` are allowed, to prevent the
+    # possibility of having orphan files in your main storage. But you can
+    # allow more storages:
     #
     #     plugin :direct_upload, allowed_storages: [:cache, :store]
     #
     # ## Customizing endpoint
     #
-    # Since the endpoint is a [Roda] app, it can be easily customized via
-    # plugins:
+    # Since the endpoint is a [Roda] app, it is very customizable. For example,
+    # you can add a Rack middleware to change the response status and headers:
+    #
+    #     class ShrineUploadMiddleware
+    #       def initialize(app)
+    #         @app = app
+    #       end
     #
-    #     class MyUploader
-    #       class UploadEndpoint
-    #         plugin :hooks
+    #       def call(env)
+    #         result = @app.call(env)
     #
-    #         after do |response|
-    #           # ...
+    #         if result[0] == 200 && env["PATH_INFO"].end_with?("upload")
+    #           result[0] = 201
+    #           result[1]["Location"] = Shrine.uploaded_file(result[2].first).url
     #         end
+    #
+    #         result
     #       end
     #     end
     #
+    #     Shrine::UploadEndpoint.use ShrineUploadMiddleware
+    #
     # Upon subclassing uploader the upload endpoint is also subclassed. You can
     # also call the plugin again in an uploader subclass to change its
     # configuration.
@@ -145,9 +157,8 @@ class Shrine
     # [Roda]: https://github.com/jeremyevans/roda
     # [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
     # [Dropzone]: https://github.com/enyo/dropzone
-    # [supports]: https://github.com/blueimp/jQuery-File-Upload/wiki/Options#progress
-    # ["accept" attribute]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-accept
-    # [`Roda::RodaRequest`]: http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/RequestMethods.html
+    # [FineUploader]: https://github.com/FineUploader/fine-uploader
+    # [Roda request]: http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/RequestMethods.html
     # [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
     module DirectUpload
       def self.load_dependencies(uploader, *)
@@ -202,6 +213,7 @@ class Shrine
               options = get_presign_options
 
               presign_data = generate_presign(location, options)
+              response.headers["Cache-Control"] = "no-store"
 
               json presign_data
             end