shrine 3.0.0.alpha → 3.0.0.beta

data/doc/plugins/remote_url.md

@@ -7,40 +7,58 @@ location.
 plugin :remote_url, max_size: 20*1024*1024
 ```
 
-If for example your attachment is called "avatar", this plugin will add
-`#avatar_remote_url` and `#avatar_remote_url=` methods to your model.
+The plugin will add the `#<name>_remote_url` writer to your model, which
+downloads the remote file and uploads it to temporary storage.
 
 ```rb
-user.avatar #=> nil
-user.avatar_remote_url = "http://example.com/cool-image.png"
-user.avatar #=> #<Shrine::UploadedFile>
-
-user.avatar.mime_type         #=> "image/png"
-user.avatar.size              #=> 43423
-user.avatar.original_filename #=> "cool-image.png"
+photo.image_remote_url = "http://example.com/cool-image.png"
+photo.image.mime_type         #=> "image/png"
+photo.image.size              #=> 43423
+photo.image.original_filename #=> "cool-image.png"
 ```
 
-You can also use `#remote_url=` and `#remote_url` methods directly on the
-`Shrine::Attacher`:
+If you're using `Shrine::Attacher` directly, you can use
+`Attacher#assign_remote_url`:
 
 ```rb
-attacher.remote_url = "http://example.com/cool-image.png"
+attacher.assign_remote_url("http://example.com/cool-image.png")
+attacher.file.mime_type         #=> "image/png"
+attacher.file.size              #=> 43423
+attacher.file.original_filename #=> "cool-image.png"
 ```
 
+## Downloading
+
 By default, the file will be downloaded using `Down.download` from the [Down]
-gem. This will use the `Down::NetHttp` backend by default, which is a wrapper
+gem. This will use the [Down::NetHttp] backend by default, which is a wrapper
 around [open-uri].
 
-## Dynamic options
-
-You can dynamically pass options to the downloader by using
-`Attacher#assign_remote_url`:
+You can pass options to the downloader via the `:downloader` option:
 
 ```rb
 attacher.assign_remote_url(url, downloader: { 'Authorization' => 'Basic ...' })
 ```
 
-You can also pass any other `Shrine#upload` options:
+You can also change the downloader:
+
+```rb
+# Gemfile
+gem "http"
+```
+```rb
+require "down/http"
+
+down = Down::Http.new do |client|
+  client.follow(max_hops: 2).timeout(connect: 2, read: 2)
+end
+
+plugin :remote_url, downloader: down.method(:download), ...
+```
+
+## Uploader options
+
+Any additional options passed to `Attacher#assign_remote_url` will be forwarded
+to `Attacher#assign` (and `Shrine#upload`):
 
 ```rb
 attacher.assign_remote_url(url, metadata: { "mime_type" => "text/plain" })
@@ -63,28 +81,6 @@ you don't want to limit the maximum file size, you can set `:max_size` to nil:
 plugin :remote_url, max_size: nil
 ```
 
-## Custom downloader
-
-If you want to customize how the file is downloaded, you can override the
-`:downloader` parameter and provide your own implementation. For example, you
-can use the [http.rb] Down backend for downloading:
-
-```rb
-# Gemfile
-gem "http"
-```
-```rb
-require "down/http"
-
-down = Down::Http.new do |client|
-  client
-    .follow(max_hops: 2)
-    .timeout(connect: 2, read: 2)
-end
-
-plugin :remote_url, max_size: 20*1024*1024, downloader: down.method(:download)
-```
-
 ## Errors
 
 If download errors, the error is rescued and a validation error is added equal
@@ -103,11 +99,10 @@ file ID, and pair that with the `backgrounding` plugin.
 
 ## File extension
 
-When attaching from a remote URL, the uploaded file location will have the
-extension inferred from the URL. However, some URLs might not have an
-extension, in which case the uploaded file location also won't have the
-extension. If you want the upload location to always have an extension, you can
-load the `infer_extension` plugin to infer it from the MIME type.
+When attaching from a remote URL, the uploaded file location will inherit the
+extension from the URL. However, some URLs might not have an extension. To
+handle this case, you can use the `infer_extension` plugin to infer the
+extension from the MIME type.
 
 ```rb
 plugin :infer_extension
@@ -158,6 +153,7 @@ plugin :remote_url, log_subscriber: nil
 
 [remote_url]: /lib/shrine/plugins/remote_url.rb
 [Down]: https://github.com/janko/down
+[Down::NetHttp]: https://github.com/janko/down#downnethttp
 [open-uri]: https://ruby-doc.org/stdlib/libdoc/open-uri/rdoc/OpenURI.html
 [http.rb]: https://github.com/httprb/http
 [shrine-url]: https://github.com/shrinerb/shrine-url

data/doc/plugins/remove_attachment.md

@@ -7,12 +7,31 @@ 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 add a form field for removing attachments:
+The plugin adds the `#remove_<name>` accessor to your model, which removes the
+attached file if it receives a truthy value:
 
 ```rb
-form.check_box :remove_avatar
+photo.image #=> #<Shrine::UploadedFile>
+photo.remove_image = 'true'
+photo.image #=> nil
+```
+
+This allows you to add a checkbox form field for removing attachments:
+
+```rb
+form_for photo do |f|
+  # ...
+  f.check_box :remove_image
+end
+```
+
+If you're using the `Shrine::Attacher` directly, you can use the
+`Attacher#remove` accessor:
+
+```rb
+attacher.file #=> #<Shrine::UploadedFile>
+attacher.remove = '1'
+attacher.file #=> nil
 ```
 
 [remove_attachment]: /lib/shrine/plugins/remove_attachment.rb

data/doc/plugins/remove_invalid.md

@@ -1,9 +1,8 @@
 # Remove Invalid
 
-The [`remove_invalid`][remove_invalid] plugin automatically deletes a new
-assigned file if it was invalid and deassigns it from the record. If there was
-a previous file attached, it will be assigned back, otherwise no attachment
-will be assigned.
+The [`remove_invalid`][remove_invalid] plugin automatically deletes and
+deassigns a new assigned file if it was invalid. If there was a previous file
+attached, it will be assigned back.
 
 ```rb
 plugin :remove_invalid

data/doc/plugins/restore_cached_data.md

@@ -11,6 +11,8 @@ extracted on the client side.
 plugin :restore_cached_data
 ```
 
-It uses the `refresh_metadata` plugin to re-extract metadata.
+It uses the [`refresh_metadata`][refresh_metadata] plugin to re-extract
+metadata.
 
 [restore_cached_data]: /lib/shrine/plugins/restore_cached_data.rb
+[refresh_metadata]: /doc/plugins/refresh_metadata.md#readme

data/doc/plugins/sequel.md

@@ -21,7 +21,7 @@ end
 
 ### Callbacks
 
-#### Save
+#### After Save
 
 After a record is saved and the transaction is committed, `Attacher#finalize`
 is called, which promotes cached file to permanent storage and deletes previous
@@ -37,7 +37,7 @@ photo.save
 photo.image.storage_key #=> :store
 ```
 
-#### Destroy
+#### After Destroy
 
 After a record is destroyed and the transaction is committed,
 `Attacher#destroy_attached` method is called, which deletes stored attached
@@ -52,7 +52,7 @@ photo.destroy
 photo.image.exists? #=> false
 ```
 
-#### Skipping
+#### Skipping Callbacks
 
 If you don't want the attachment module to add any callbacks to your Sequel
 model, you can set `:callbacks` to `false`:
@@ -82,7 +82,7 @@ photo.valid?
 photo.errors #=> { image: ["size must not be greater than 10.0 MB"] }
 ```
 
-#### Presence
+#### Attachment Presence
 
 If you want to validate presence of the attachment, you can use Sequel's
 presence validator:
@@ -100,7 +100,7 @@ class Photo < Sequel::Model
 end
 ```
 
-#### Skipping
+#### Skipping Validations
 
 If don't want the attachment module to merge file validations errors into
 model errors, you can set `:validations` to `false`:
@@ -114,111 +114,19 @@ plugin :sequel, validations: false
 This section will cover methods added to the `Shrine::Attacher` instance. If
 you're not familar with how to obtain it, see the [`model`][model] plugin docs.
 
-### Atomic promotion
+The following persistence methods are added to the attacher:
 
-If you're promoting cached file to permanent storage
-[asynchronously][backgrounding], you might want to handle the possibility of
-the attachment changing during promotion. You can do that with
-`Attacher#atomic_promote`:
+| Method                    | Description                                                            |
+| :-----                    | :----------                                                            |
+| `Attacher#atomic_promote` | calls `Attacher#promote` and persists if the attachment hasn't changed |
+| `Attacher#atomic_persist` | saves changes if the attachment hasn't changed                         |
+| `Attacher#persist`        | saves any changes to the underlying record                             |
 
-```rb
-# in your controller
-attacher.attach_cached(io)
-attacher.cached? #=> true
-```
-```rb
-# in a background job
-attacher.atomic_promote # promotes cached file and persists
-attacher.stored? #=> true
-```
-
-After cached file is uploaded to permanent storage, the record is reloaded in
-order to check whether the attachment hasn't changed, and if it hasn't the
-attachment is persisted. If the attachment has changed,
-`Shrine::AttachmentChanged` exception is raised.
-
-Additional options are passed to `Attacher#promote`.
-
-#### Reloader & persister
-
-You can change how the record is reloaded or persisted during atomic promotion:
-
-```rb
-# reloader
-attacher.atomic_promote(reload: :lock)    # uses database locking (default)
-attacher.atomic_promote(reload: :fetch)   # reloads with no locking
-attacher.atomic_promote(reload: ->(&b){}) # custom reloader (see atomic_helpers plugin docs)
-attacher.atomic_promote(reload: false)    # skips reloading
-
-# persister
-attacher.atomic_promote(persist: :save) # persists stored file (default)
-attacher.atomic_promote(persist: ->{})  # custom persister (see atomic_helpers plugin docs)
-attacher.atomic_promote(persist: false) # skips persistence
-```
-
-For more details, see the [`atomic_helpers`][atomic_helpers] plugin docs.
-
-### Atomic persistence
-
-If you're updating something based on the attached file
-[asynchronously][backgrounding], you might want to handle the possibility of
-the attachment changing in the meanwhile. You can do that with
-`Attacher#atomic_persist`:
-
-```rb
-# in a background job
-attacher.refresh_metadata! # refresh_metadata plugin
-attacher.atomic_persist # persists attachment data
-```
-
-The record is first reloaded in order to check whether the attachment hasn't
-changed, and if it hasn't the attachment is persisted. If the attachment has
-changed, `Shrine::AttachmentChanged` exception is raised.
-
-#### Reloader & persister
-
-You can change how the record is reloaded or persisted during atomic
-persistence:
-
-```rb
-# reloader
-attacher.atomic_persist(reload: :lock)       # uses database locking (default)
-attacher.atomic_persist(reload: :fetch)      # reloads with no locking
-attacher.atomic_persist(reload: ->(&b){...}) # custom reloader (see atomic_helpers plugin docs)
-attacher.atomic_persist(reload: false)       # skips reloading
-
-# persister
-attacher.atomic_persist(persist: :save)   # persists stored file (default)
-attacher.atomic_persist(persist: ->{...}) # custom persister (see atomic_helpers plugin docs)
-attacher.atomic_persist(persist: false)   # skips persistence
-```
-
-For more details, see the [`atomic_helpers`][atomic_helpers] plugin docs.
-
-### Persistence
-
-You can call `Attacher#persist` to save any changes to the underlying record:
-
-```rb
-attacher.attach(io)
-attacher.persist # saves the underlying record
-```
-
-### With other database plugins
-
-If you have another database plugin loaded together with the `sequel` plugin,
-you can prefix any method above with `sequel_*` to avoid naming clashes:
-
-```rb
-attacher.sequel_atomic_promote
-attacher.sequel_atomic_persist
-attacher.sequel_persist
-```
+See [persistence] docs for more details.
 
 [sequel]: /lib/shrine/plugins/sequel.rb
 [Sequel]: https://sequel.jeremyevans.net/
 [model]: /doc/plugins/model.md#readme
 [hooks]: http://sequel.jeremyevans.net/rdoc/files/doc/model_hooks_rdoc.html
 [validation]: /doc/plugins/validation.md#readme
-[atomic_helpers]: /doc/plugins/atomic_helpers.md#readme
-[backgrounding]: /doc/plugins/backgrounding.md#readme
+[persistence]: /doc/plugins/persistence.md#readme

data/doc/plugins/signature.md

@@ -39,7 +39,7 @@ calculated hash.
 ```rb
 plugin :add_metadata
 
-add_metadata :md5 do |io, context|
+add_metadata :md5 do |io|
   calculate_signature(io, :md5)
 end
 ```
@@ -48,8 +48,8 @@ This will generate a hash for each uploaded file, but if you want to generate
 one only for the original file, you can add a conditional:
 
 ```rb
-add_metadata :md5 do |io, context|
-  calculate_signature(io, :md5) if context[:action] == :cache
+add_metadata :md5 do |io, action: nil, **|
+  calculate_signature(io, :md5) if action == :cache
 end
 ```
 

data/lib/shrine/attachment.rb

@@ -29,6 +29,16 @@ class Shrine
         @options = options
       end
 
+      def included(klass)
+        super
+
+        attachment = self
+
+        klass.send(:define_singleton_method, :"#{@name}_attacher") do |**options|
+          attachment.shrine_class::Attacher.new(**attachment.options, **options)
+        end
+      end
+
       # Returns name of the attachment this module provides.
       def attachment_name
         @name
@@ -43,7 +53,7 @@ class Shrine
       #
       #     Shrine::Attachment.new(:image).to_s #=> "#<Shrine::Attachment(image)>"
       def inspect
-        "#<#{self.class.inspect}(#{attachment_name})>"
+        "#<#{self.class.inspect}(#{@name})>"
       end
       alias to_s inspect
 

data/lib/shrine/plugins/_persistence.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    # Helper plugin that defines persistence methods on the attacher according
+    # to convention.
+    #
+    #     plugin :_persistence, plugin: MyPlugin
+    module Persistence
+      def self.load_dependencies(uploader, *)
+        uploader.plugin :atomic_helpers
+      end
+
+      # Defines the following attacher methods for a persistence plugin:
+      #
+      # * #persist (calls #<name>_persist and #<name>?)
+      # * #atomic_persist (calls #<name>_reload, #<name>_persist and #<name>?)
+      # * #atomic_promote (calls #<name>_reload, #<name>_persist and #<name>?)
+      def self.configure(uploader, plugin:)
+        plugin_name = plugin.to_s.split("::").last.downcase
+
+        plugin::AttacherMethods.module_eval do
+          define_method :atomic_promote do |**options, &block|
+            return super(**options, &block) unless send(:"#{plugin_name}?")
+
+            abstract_atomic_promote(
+              reload:  method(:"#{plugin_name}_reload"),
+              persist: method(:"#{plugin_name}_persist"),
+              **options, &block
+            )
+          end
+
+          define_method :atomic_persist do |*args, **options, &block|
+            return super(*args, **options, &block) unless send(:"#{plugin_name}?")
+
+            abstract_atomic_persist(
+              *args,
+              reload:  method(:"#{plugin_name}_reload"),
+              persist: method(:"#{plugin_name}_persist"),
+              **options, &block
+            )
+          end
+
+          define_method :persist do
+            return super() unless send(:"#{plugin_name}?")
+
+            send(:"#{plugin_name}_persist")
+          end
+        end
+      end
+
+      module AttacherMethods
+        def atomic_promote(*)
+          raise NotImplementedError, "unhandled by a persistence plugin"
+        end
+
+        def atomic_persist(*)
+          raise NotImplementedError, "unhandled by a persistence plugin"
+        end
+
+        def persist(*)
+          raise NotImplementedError, "unhandled by a persistence plugin"
+        end
+      end
+    end
+
+    register_plugin(:_persistence, Persistence)
+  end
+end

data/lib/shrine/plugins/activerecord.rb

@@ -10,7 +10,7 @@ class Shrine
     module Activerecord
       def self.load_dependencies(uploader, **)
         uploader.plugin :model
-        uploader.plugin :atomic_helpers
+        uploader.plugin :_persistence, plugin: self
       end
 
       def self.configure(uploader, **opts)
@@ -24,15 +24,15 @@ class Shrine
 
           return unless model < ::ActiveRecord::Base
 
-          name = attachment_name
+          name = @name
 
           if shrine_class.opts[:activerecord][:validations]
+            # add validation plugin integration
             model.validate do
-              # validation plugin integration
-              if send(:"#{name}_attacher").respond_to?(:errors)
-                send(:"#{name}_attacher").errors.each do |message|
-                  errors.add(name, *message)
-                end
+              next unless send(:"#{name}_attacher").respond_to?(:errors)
+
+              send(:"#{name}_attacher").errors.each do |message|
+                errors.add(name, *message)
               end
             end
           end
@@ -48,7 +48,7 @@ class Shrine
               model.after_commit on: action do
                 if send(:"#{name}_attacher").changed?
                   send(:"#{name}_attacher").finalize
-                  send(:"#{name}_attacher").activerecord_persist
+                  send(:"#{name}_attacher").persist
                 end
               end
             end
@@ -68,81 +68,13 @@ class Shrine
       end
 
       module AttacherMethods
-        # Promotes cached file to permanent storage in an atomic way. It's
-        # intended to be called from a background job.
-        #
-        #     attacher.assign(file)
-        #     attacher.cached? #=> true
-        #
-        #     # ... in background job ...
-        #
-        #     attacher.atomic_promote
-        #     attacher.stored? #=> true
-        #
-        # It accepts `:reload` and `:persist` strategies:
-        #
-        #     attacher.atomic_promote(reload: :lock)    # uses database locking (default)
-        #     attacher.atomic_promote(reload: :fetch)   # reloads with no locking
-        #     attacher.atomic_promote(reload: ->(&b){}) # custom reloader
-        #     attacher.atomic_promote(reload: false)    # skips reloading
-        #
-        #     attacher.atomic_promote(persist: :save) # persists stored file (default)
-        #     attacher.atomic_promote(persist: ->{})  # custom persister
-        #     attacher.atomic_promote(persist: false) # skips persistence
-        def activerecord_atomic_promote(**options, &block)
-          abstract_atomic_promote(activerecord_strategies(**options), &block)
-        end
-        alias atomic_promote activerecord_atomic_promote
-
-        # Persist the the record only if the attachment hasn't changed.
-        # Optionally yields reloaded attacher to the block before persisting.
-        # It's intended to be called from a background job.
+        # The _persistence plugin defines the following methods:
         #
-        #     # ... in background job ...
-        #
-        #     attacher.file.metadata["foo"] = "bar"
-        #     attacher.write
-        #
-        #     attacher.atomic_persist
-        def activerecord_atomic_persist(*args, **options, &block)
-          abstract_atomic_persist(*args, activerecord_strategies(**options), &block)
-        end
-        alias atomic_persist activerecord_atomic_persist
-
-        # Called in the `after_commit` callback after finalization.
-        def activerecord_persist
-          activerecord_save
-        end
-        alias persist activerecord_persist
-
+        #   * #persist (calls #activerecord_persist and #activerecord?)
+        #   * #atomic_persist (calls #activerecord_lock, #activerecord_persist and #activerecord?)
+        #   * #atomic_promote (calls #activerecord_lock, #activerecord_persist and #activerecord?)
         private
 
-        # Resolves strategies for atomic promotion and persistence.
-        def activerecord_strategies(reload: :lock, persist: :save, **options)
-          reload  = method(:"activerecord_#{reload}")  if reload.is_a?(Symbol)
-          persist = method(:"activerecord_#{persist}") if persist.is_a?(Symbol)
-
-          { reload: reload, persist: persist, **options }
-        end
-
-        # Implements the "fetch" reload strategy for #atomic_promote and
-        # #atomic_persist.
-        def activerecord_fetch
-          yield record.clone.reload
-        end
-
-        # Implements the "lock" reload strategy for #atomic_promote and
-        # #atomic_persist.
-        def activerecord_lock
-          record.transaction { yield record.clone.reload(lock: true) }
-        end
-
-        # Implements the "save" persist strategy for #atomic_promote and
-        # #atomic_persist.
-        def activerecord_save
-          record.save(validate: false)
-        end
-
         # ActiveRecord JSON column attribute needs to be assigned with a Hash.
         def serialize_column(data)
           activerecord_json_column? ? data : super
@@ -150,11 +82,29 @@ class Shrine
 
         # Returns true if the data attribute represents a JSON or JSONB column.
         def activerecord_json_column?
-          return false unless record.is_a?(ActiveRecord::Base)
+          return false unless activerecord?
           return false unless column = record.class.columns_hash[attribute.to_s]
 
           [:json, :jsonb].include?(column.type)
         end
+
+        # Saves changes to the model instance, skipping validations. Used by
+        # the _persistence plugin.
+        def activerecord_persist
+          record.save(validate: false)
+        end
+
+        # Locks the database row and yields the reloaded record. Used by the
+        # _persistence plugin.
+        def activerecord_reload
+          record.transaction { yield record.clone.reload(lock: true) }
+        end
+
+        # Returns whether the record is an ActiveRecord model. Used by the
+        # _persistence plugin.
+        def activerecord?
+          record.is_a?(::ActiveRecord::Base)
+        end
       end
     end
 

data/lib/shrine/plugins/atomic_helpers.rb

@@ -14,9 +14,9 @@ class Shrine
         # the attachment hasn't changed. It raises `Shrine::AttachmentChanged`
         # exception if the attached file doesn't match.
         #
-        #     Shrine::Attacher.retrieve(model: photo, name: :image, data: data)
+        #     Shrine::Attacher.retrieve(model: photo, name: :image, file: file_data)
         #     #=> #<ImageUploader::Attacher>
-        def retrieve(model: nil, entity: nil, name:, data:, **options)
+        def retrieve(model: nil, entity: nil, name:, file:, **options)
           fail ArgumentError, "either :model or :entity is required" unless model || entity
 
           record = model || entity
@@ -25,7 +25,7 @@ class Shrine
           attacher ||= from_model(record, name, **options) if model
           attacher ||= from_entity(record, name, **options) if entity
 
-          if attacher.file != attacher.class.from_data(data).file
+          if attacher.file != attacher.uploaded_file(file)
             fail Shrine::AttachmentChanged, "attachment has changed"
           end
 
@@ -82,6 +82,16 @@ class Shrine
           end
         end
 
+        # Return only needed main file data, without the metadata. This allows
+        # you to avoid bloating your background job payload when you have
+        # derivatives or lots of metadata, by only sending data you need for
+        # atomic persitence.
+        #
+        #     attacher.file_data #=> { "id" => "abc123.jpg", "storage" => "store" }
+        def file_data
+          file!.data.reject { |key, value| key == "metadata" }
+        end
+
         protected
 
         # Calls the reload strategy and yields a reloaded attacher from the