shrine 3.0.0.beta2 → 3.0.0.beta3

data/doc/validation.md

@@ -1,20 +1,23 @@
 # File Validation
 
-Shrine allows validating assigned files based on their metadata. Validation
-code is defined inside a `Shrine::Attacher.validate` block:
+Shrine allows validating assigned files using the [`validation`][validation]
+plugin. Validation code is defined inside an `Attacher.validate` block:
 
+```rb
+Shrine.plugin :validation
+```
 ```rb
 class ImageUploader < Shrine
   Attacher.validate do
-    # validations
+    # ... perform validation ...
   end
 end
 ```
 
-The validation block is run when a file is assigned to an attachment attribute,
-afterwards the validation errors are stored in `Shrine::Attacher#errors`. ORM
-plugins like `sequel` and `activerecord` will automatically merge these
-validation errors into the `#errors` hash on the model instance.
+The validation block is run when a new file is assigned, and any validation
+errors are stored in `Shrine::Attacher#errors`. ORM plugins like `sequel` and
+`activerecord` will automatically merge these validation errors into the
+`#errors` hash on the model instance.
 
 ```rb
 photo = Photo.new
@@ -23,57 +26,20 @@ photo.valid? #=> false
 photo.errors[:image] #=> [...]
 ```
 
-By default the invalid file will remain assigned to the attachment attribute,
-but you can have it automatically removed and deleted by loading the
-`remove_invalid` plugin.
-
-```rb
-Shrine.plugin :remove_invalid # remove and delete files that failed validation
-```
-
-The validation block is evaluated in the context of a `Shrine::Attacher`
-instance, so you have access to the original file and the record:
-
-```rb
-class ImageUploader < Shrine
-  Attacher.validate do
-    self   #=> #<Shrine::Attacher>
-
-    get    #=> #<Shrine::UploadedFile>
-    record #=> #<Photo>
-    name   #=> :image
-  end
-end
-```
+## Validation helpers
 
-You can use the attacher context to pass additional parameters you want to use
-for validation:
+The [`validation_helpers`][validation_helpers] plugin provides convenient
+validators for built-in metadata:
 
 ```rb
-photo.image_attacher.context[:foo] = "bar"
+Shrine.plugin :validation_helpers
 ```
 ```rb
 class ImageUploader < Shrine
   Attacher.validate do
-    context[:foo] #=> "bar"
-  end
-end
-```
-
-## Validation helpers
-
-The `validation_helpers` plugin provides helper methods for validating common
-metadata values:
-
-```rb
-class ImageUploader < Shrine
-  plugin :validation_helpers
-
-  Attacher.validate do
-    validate_min_size 1, message: "must not be empty"
-    validate_max_size 5*1024*1024, message: "is too large (max is 5 MB)"
-    validate_mime_type_inclusion %w[image/jpeg image/png image/tiff]
-    validate_extension_inclusion %w[jpg jpeg png tiff tif]
+    validate_size      1..5*1024*1024
+    validate_mime_type %w[image/jpeg image/png image/webp image/tiff]
+    validate_extension %w[jpg jpeg png webp tiff tif]
   end
 end
 ```
@@ -81,47 +47,31 @@ end
 Note that for secure MIME type validation it's recommended to also load
 `determine_mime_type` and `restore_cached_data` plugins.
 
-It's also easy to do conditional validations with these helper methods:
-
-```rb
-class ImageUploader < Shrine
-  plugin :validation_helpers
-
-  Attacher.validate do
-    # validate dimensions only of the attached file is an image
-    if validate_extension_inclusion %w[jpg jpeg png tiff tif]
-      validate_max_width 5000
-      validate_max_height 5000
-    end
-  end
-end
-```
-
-See the `validation_helpers` plugin documentation for more details.
+See the [`validation_helpers`][validation_helpers] plugin documentation for
+more details.
 
 ## Custom validations
 
-You might sometimes want to validate custom metadata, or in general do custom
-validation that the `validation_helpers` plugin does not provide. The
-`Shrine::Attacher.validate` block is evaluated at instance level, so you're
-free to write there any code you like and add validation errors onto the
-`Shrine::Attacher#errors` array.
-
-For example, if you're uploading images, you might want to validate that the
-image is processable using the [ImageProcessing] gem:
+You can also do your own custom validations:
 
 ```rb
-require "image_processing/mini_magick"
+# Gemfile
+gem "streamio-ffmpeg"
+```
+```rb
+require "streamio-ffmpeg"
 
-class ImageUploader < Shrine
-  plugin :validation_helpers
+class VideoUploader < Shrine
+  plugin :add_metadata
+
+  add_metadata :duration do |io|
+    movie = Shrine.with_file(io) { |file| FFMPEG::Movie.new(file.path) }
+    movie.duration
+  end
 
   Attacher.validate do
-    # validate dimensions only of the attached file is an image
-    if validate_mime_type_inclusion %w[image/jpeg image/png image/tiff]
-      get.download do |tempfile|
-        errors << "is corrupted or invalid" unless ImageProcessing::MiniMagick.valid_image?(tempfile)
-      end
+    if file.duration > 5*60*60
+      errors << "duration must not be longer than 5 hours"
     end
   end
 end
@@ -134,15 +84,26 @@ when defining more validations:
 
 ```rb
 class ApplicationUploader < Shrine
-  Attacher.validate { validate_max_size 5.megabytes }
+  Attacher.validate { validate_max_size 5*1024*1024 }
 end
 
 class ImageUploader < ApplicationUploader
   Attacher.validate do
     super() # empty braces are required
-    validate_mime_type_inclusion %w[image/jpeg image/jpg image/png]
+    validate_mime_type %w[image/jpeg image/png image/webp]
   end
 end
 ```
 
-[ImageProcessing]: https://github.com/janko/image_processing
+## Removing invalid files
+
+By default, an invalid file will remain assigned after validation failed, but
+you can have it automatically removed and deleted by loading the
+`remove_invalid` plugin.
+
+```rb
+Shrine.plugin :remove_invalid # remove and delete files that failed validation
+```
+
+[validation]: /doc/plugins/validation.md#readme
+[validation_helpers]: /doc/plugins/validation_helpers.md#readme

data/lib/shrine.rb

@@ -178,15 +178,18 @@ class Shrine
     # The symbol identifier for the storage used by the uploader.
     attr_reader :storage_key
 
-    # The storage object used by the uploader.
-    attr_reader :storage
-
     # Accepts a storage symbol registered in `Shrine.storages`.
     #
     #     Shrine.new(:store)
     def initialize(storage_key)
-      @storage     = self.class.find_storage(storage_key)
       @storage_key = storage_key.to_sym
+
+      storage # ensure storage is registered
+    end
+
+    # Returns the storage object referenced by the identifier.
+    def storage
+      self.class.find_storage(storage_key)
     end
 
     # The main method for uploading files. Takes an IO-like object and an

data/lib/shrine/attacher.rb

@@ -154,7 +154,7 @@ class Shrine
       #     attacher.promote_cached
       #     attacher.stored? #=> true
       def promote_cached(**options)
-        promote(action: :store, **options) if changed? && cached?
+        promote(action: :store, **options) if promote?
       end
 
       # Uploads current file to permanent storage and sets the stored file.
@@ -183,8 +183,8 @@ class Shrine
       #     attacher.attach(file)
       #     attacher.destroy_previous
       #     previous_file.exists? #=> false
-      def destroy_previous(**options)
-        @previous.destroy_attached(**options) if changed?
+      def destroy_previous
+        @previous.destroy_attached if changed?
       end
 
       # Destroys the attached file if it exists and is uploaded to permanent
@@ -193,8 +193,8 @@ class Shrine
       #     attacher.file.exists? #=> true
       #     attacher.destroy_attached
       #     attacher.file.exists? #=> false
-      def destroy_attached(**options)
-        destroy(**options) if attached? && !cached?
+      def destroy_attached
+        destroy if destroy?
       end
 
       # Destroys the attachment.
@@ -202,7 +202,7 @@ class Shrine
       #     attacher.file.exists? #=> true
       #     attacher.destroy
       #     attacher.file.exists? #=> false
-      def destroy(**options)
+      def destroy
         file&.delete
       end
 
@@ -358,6 +358,16 @@ class Shrine
         uploaded_file
       end
 
+      # Whether attached file should be uploaded to permanent storage.
+      def promote?
+        changed? && cached?
+      end
+
+      # Whether attached file should be deleted.
+      def destroy?
+        attached? && !cached?
+      end
+
       # Returns whether the file is uploaded to specified storage.
       def uploaded?(file, storage_key)
         file&.storage_key == storage_key

data/lib/shrine/plugins/activerecord.rb

@@ -27,34 +27,24 @@ class Shrine
           name = @name
 
           if shrine_class.opts[:activerecord][:validations]
-            # add validation plugin integration
             model.validate do
-              next unless send(:"#{name}_attacher").respond_to?(:errors)
-
-              send(:"#{name}_attacher").errors.each do |message|
-                errors.add(name, *message)
-              end
+              send(:"#{name}_attacher").send(:activerecord_validate)
             end
           end
 
           if shrine_class.opts[:activerecord][:callbacks]
             model.before_save do
-              if send(:"#{name}_attacher").changed?
-                send(:"#{name}_attacher").save
-              end
+              send(:"#{name}_attacher").send(:activerecord_before_save)
             end
 
             [:create, :update].each do |action|
               model.after_commit on: action do
-                if send(:"#{name}_attacher").changed?
-                  send(:"#{name}_attacher").finalize
-                  send(:"#{name}_attacher").persist
-                end
+                send(:"#{name}_attacher").send(:activerecord_after_save)
               end
             end
 
             model.after_commit on: :destroy do
-              send(:"#{name}_attacher").destroy_attached
+              send(:"#{name}_attacher").send(:activerecord_after_destroy)
             end
           end
 
@@ -77,6 +67,35 @@ class Shrine
       module AttacherMethods
         private
 
+        # Adds file validation errors to the model. Called on model validation.
+        def activerecord_validate
+          return unless respond_to?(:errors)
+
+          errors.each do |message|
+            record.errors.add(name, *message)
+          end
+        end
+
+        # Calls Attacher#save. Called before model save.
+        def activerecord_before_save
+          return unless changed?
+
+          save
+        end
+
+        # Finalizes attachment and persists changes. Called after model save.
+        def activerecord_after_save
+          return unless changed?
+
+          finalize
+          persist
+        end
+
+        # Deletes attached files. Called after model destroy.
+        def activerecord_after_destroy
+          destroy_attached
+        end
+
         # Saves changes to the model instance, skipping validations. Used by
         # the _persistence plugin.
         def activerecord_persist

data/lib/shrine/plugins/atomic_helpers.rb

@@ -54,7 +54,7 @@ class Shrine
             abstract_atomic_persist(original_file, reload: reload, persist: persist, &block)
             result
           rescue Shrine::AttachmentChanged
-            destroy(background: true)
+            destroy_attached
             raise
           end
         end

data/lib/shrine/plugins/backgrounding.rb

@@ -2,75 +2,9 @@
 
 class Shrine
   module Plugins
-    # The backgrounding plugin allows delaying promotion and deletion into a
-    # background job.
+    # Documentation lives in [doc/plugins/backgrounding.md] on GitHub.
     #
-    # You can register promotion and deletion blocks on an instance of the
-    # attacher, and they will be called as needed.
-    #
-    # ## Promotion
-    #
-    #     attacher.promote_block do
-    #       Attachment::PromoteJob.perform_async(record, name, file_data)
-    #     end
-    #
-    #     attacher.assign(io)
-    #     attacher.finalize # promote block called
-    #
-    #     attacher.file # cached file
-    #     # ... background job finishes ...
-    #     attacher.file # stored file
-    #
-    # The promote worker can be implemented like this:
-    #
-    #     class Attachment::PromoteJob
-    #       def perform(record, name, file_data)
-    #         attacher = Shrine::Attacher.retrieve(model: record, name: name, file: file_data)
-    #         attacher.atomic_promote
-    #       end
-    #     end
-    #
-    # ## Deletion
-    #
-    #     attacher.destroy_block do
-    #       Attachment::DestroyJob.perform_async(data)
-    #     end
-    #
-    #     previous_file = attacher.file
-    #
-    #     attacher.attach(io)
-    #     attacher.finalize # delete hook called
-    #
-    #     previous_file.exists? #=> true
-    #     # ... background job finishes ...
-    #     previous_file.exists? #=> false
-    #
-    #     attacher.destroy_attached
-    #
-    #     attacher.file.exists? #=> true
-    #     # ... background job finishes ...
-    #     attacher.file.exists? #=> false
-    #
-    # The delete worker can be implemented like this:
-    #
-    #     class Attachment::DestroyJob
-    #       def perform(data)
-    #         attacher = Shrine::Attacher.from_data(data)
-    #         attacher.destroy
-    #       end
-    #     end
-    #
-    # ## Global hooks
-    #
-    # You can also register promotion and deletion hooks globally:
-    #
-    #     Shrine::Attacher.promote_block do
-    #       Attachment::PromoteJob.perform_async(record, name, file_data)
-    #     end
-    #
-    #     Shrine::Attacher.destroy_block do
-    #       Attachment::DestroyJob.perform_async(data)
-    #     end
+    # [doc/plugins/backgrounding.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/backgrounding.md
     module Backgrounding
       def self.configure(uploader)
         uploader.opts[:backgrounding] ||= {}
@@ -134,38 +68,38 @@ class Shrine
           @destroy_block
         end
 
-        # Signals the #promote method that it should use backgrounding if
-        # registered.
+        # Does a background promote if promote block was registered.
         def promote_cached(**options)
-          super(background: true, **options)
-        end
-
-        # Calls the promotion hook if registered and called via #promote_cached,
-        # otherwise promotes synchronously.
-        def promote(background: false, **options)
-          if promote_block && background
-            background_block(promote_block, **options)
+          if promote? && promote_block
+            promote_background(**options)
           else
-            super(**options)
+            super
           end
         end
 
-        # Signals the #destroy method that it should use backgrounding if
-        # registered.
-        def destroy_attached(**options)
-          super(background: true, **options)
+        # Calls the registered promote block.
+        def promote_background(**options)
+          fail Error, "promote block is not registered" unless promote_block
+
+          background_block(promote_block, **options)
         end
 
-        # Calls the destroy hook if registered and called via #destroy_attached,
-        # otherwise destroys synchronously.
-        def destroy(background: false, **options)
-          if destroy_block && background
-            background_block(destroy_block, **options)
+        # Does a background destroy if destroy block was registered.
+        def destroy_attached
+          if destroy? && destroy_block
+            destroy_background
           else
-            super(**options)
+            super
           end
         end
 
+        # Calls the registered destroy block.
+        def destroy_background
+          fail Error, "destroy block is not registered" unless destroy_block
+
+          background_block(destroy_block)
+        end
+
         private
 
         def background_block(block, **options)