shrine 2.10.1 → 2.11.0

data/doc/refile.md

@@ -427,10 +427,10 @@ No equivalent in Shrine, but take a look at the "[Multiple Files]" guide.
 
 The following Refile code
 
-```erb
-<%= form_for @user do |form| %>
-  <%= form.attachment_field :profile_image %>
-<% end %>
+```rb
+form_for @user do |form|
+  form.attachment_field :profile_image
+end
 ```
 
 is equivalent to the following Shrine code
@@ -438,11 +438,11 @@ is equivalent to the following Shrine code
 ```rb
 Shrine.plugin :cached_attachment_data
 ```
-```erb
-<%= form_for @user do |form| %>
-  <%= form.hidden_field :profile_image, value: @user.cached_profile_image_data %>
-  <%= form.file_field :profile_image %>
-<% end %>
+```rb
+form_for @user do |form|
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.file_field :profile_image
+end
 ```
 
 ### Model methods
@@ -455,12 +455,12 @@ Shrine comes with a `remove_attachment` plugin which adds the same
 ```rb
 Shrine.plugin :remove_attachment
 ```
-```erb
-<%= form_for @user do |form| %>
-  <%= form.hidden_field :profile_image, value: @user.cached_profile_image_data %>
-  <%= form.file_field :profile_image %>
-  <%= form.check_box :remove_profile_image %>
-<% end %>
+```rb
+form_for @user do |form|
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.file_field :profile_image
+  form.check_box :remove_profile_image
+end
 ```
 
 #### `remote_<attachment>_url`
@@ -471,12 +471,12 @@ Shrine comes with a `remote_url` plugin which adds the same
 ```rb
 Shrine.plugin :remote_url
 ```
-```erb
-<%= form_for @user do |form| %>
-  <%= form.hidden_field :profile_image, value: @user.cached_profile_image_data %>
-  <%= form.file_field :profile_image %>
-  <%= form.text_field :profile_image_remote_url %>
-<% end %>
+```rb
+form_for @user do |form|
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.file_field :profile_image
+  form.text_field :profile_image_remote_url
+end
 ```
 
 [shrine-cloudinary]: https://github.com/shrinerb/shrine-cloudinary
@@ -485,6 +485,6 @@ Shrine.plugin :remote_url
 [Attache]: https://github.com/choonkeat/attache
 [image_processing]: https://github.com/janko-m/image_processing
 [Uppy]: https://uppy.io
-[Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[Direct Uploads to S3]: https://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [demo app]: https://github.com/shrinerb/shrine/tree/master/demo
-[Multiple Files]: http://shrinerb.com/rdoc/files/doc/multiple_files_md.html
+[Multiple Files]: https://shrinerb.com/rdoc/files/doc/multiple_files_md.html

data/doc/testing.md

@@ -36,16 +36,12 @@ end
 
 ## Storage
 
-If you're using an external storage in development, it is common in tests to
-switch to a filesystem storage. However, that means that you'll also have to
-clean up the test directory between tests, and writing to filesystem can affect
-the performance of your tests.
-
-If your tests are run in a single process, instead of filesystem you can use
-[memory storage][shrine-memory], which is both faster and doesn't require you
-to clean up anything between tests.
+If you're using FileSystem storage and your tests run in a single process,
+you can switch to [memory storage][shrine-memory], which is both faster and
+doesn't require you to clean up anything between tests.
 
 ```rb
+# Gemfile
 gem "shrine-memory"
 ```
 ```rb
@@ -58,8 +54,49 @@ Shrine.storages = {
 }
 ```
 
-Alternatively, if you're using Amazon S3 storage, in tests you can use
-[aws-sdk-ruby stubs].
+If you're using AWS S3 storage, in you can switch to using [Minio] (explained
+below), both in test and development environment. Alternatively, you can [stub
+aws-sdk-s3 requests][aws-sdk-ruby stubs] in tests.
+
+### Minio
+
+[Minio] is an open source object storage server with AWS S3 compatible API which
+you can run locally. The advantage of using Minio for your development and test
+environments is that all AWS S3 functionality should still continue to work,
+including direct uploads, so you don't need to update your code.
+
+If you're on a Mac you can install it with Homebrew:
+
+```
+$ brew install minio/stable/minio
+```
+
+Afterwards you can start the Minio server and give it a directory where it will
+store the data:
+
+```
+$ minio server data/
+```
+
+This command will print out the credentials for the running Minio server, as
+well as a link to the Minio web interface. Follow that link and create a new
+bucket. Once you've done that, you can configure `Shrine::Storage::S3` to use
+your Minio server:
+
+```rb
+Shrine::Storage::S3.new(
+  access_key_id:     "<MINIO_ACCESS_KEY>", # "AccessKey" value
+  secret_access_key: "<MINIO_SECRET_KEY>", # "SecretKey" value
+  endpoint:          "<MINIO_ENDPOINT>",   # "Endpoint"  value
+  bucket:            "<MINIO_BUCKET>",     # name of the bucket you created
+  region:            "us-east-1",
+  force_path_style:  true,
+)
+```
+
+The `:endpoint` option will make aws-sdk-s3 point all URLs to your Minio server
+(instead of `s3.amazonaws.com`), and `:force_path_style` tells it not to use
+subdomains when generating URLs.
 
 ## Test data
 
@@ -240,47 +277,6 @@ end
 This also has the benefit of allowing you to test `ImageThumbnailsGenerator` in
 isolation.
 
-## Direct S3 uploads
-
-If you want to do direct uploads to Amazon S3 in production, in development and
-tests you'll probably want to keep using filesystem storage to avoid making
-network requests.
-
-The simplest way to do that is to use [Minio]. Minio is an open source object
-storage server with Amazon S3 compatible API. If you're on a Mac you can
-install it with Homebrew:
-
-```
-$ brew install minio/stable/minio
-```
-
-Now you can start the Minio server and give it a directory where it will store
-the data:
-
-```
-$ minio server data/
-```
-
-This command will print out the credentials for the running Minio server, as
-well as a link to the Minio web interface. Follow that link and create a new
-bucket. Once you've done that, all that's lef to do is configure
-`Shrine::Storage::S3` with the credentials of your Minio server:
-
-```rb
-Shrine::Storage::S3.new(
-  access_key_id:     "MINIO_ACCESS_KEY", # "AccessKey" value
-  secret_access_key: "MINIO_SECRET_KEY", # "SecretKey" value
-  endpoint:          "MINIO_ENDPOINT",   # "Endpoint"  value
-  bucket:            "MINIO_BUCKET",     # name of the bucket you created
-  region:            "us-east-1",
-  force_path_style:  true,
-)
-```
-
-The `:endpoint` option will make `aws-sdk-s3` point all URLs to your Minio
-server (instead of `s3.amazonaws.com`), and `:force_path_style` tells it not
-to use subdomains when generating URLs.
-
 [DatabaseCleaner]: https://github.com/DatabaseCleaner/database_cleaner
 [shrine-memory]: https://github.com/shrinerb/shrine-memory
 [factory_bot]: https://github.com/thoughtbot/factory_bot

data/doc/validation.md

@@ -0,0 +1,148 @@
+# File Validation
+
+Shrine allows validating assigned files based on their metadata. Validation
+code is defined inside a `Shrine::Attacher.validate` block:
+
+```rb
+class ImageUploader < Shrine
+  Attacher.validate do
+    # validations
+  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.
+
+```rb
+photo = Photo.new
+photo.image = image_file
+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
+```
+
+You can use the attacher context to pass additional parameters you want to use
+for validation:
+
+```rb
+photo.image_attacher.context[:foo] = "bar"
+```
+```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]
+  end
+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.
+
+## 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:
+
+```rb
+require "image_processing/mini_magick"
+
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  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
+    end
+  end
+end
+```
+
+## Inheritance
+
+Validations are inherited from superclasses, but you need to call them manually
+when defining more validations:
+
+```rb
+class ApplicationUploader < Shrine
+  Attacher.validate { validate_max_size 5.megabytes }
+end
+
+class ImageUploader < ApplicationUploader
+  Attacher.validate do
+    super() # empty braces are required
+    validate_mime_type_inclusion %w[image/jpeg image/jpg image/png]
+  end
+end
+```
+
+[ImageProcessing]: https://github.com/janko-m/image_processing

data/lib/shrine.rb

@@ -170,6 +170,27 @@ class Shrine
           end
         end
 
+        # Temporarily converts an IO-like object into a file. If the input IO
+        # object is already a file, it simply yields it to the block, otherwise
+        # it copies IO content into a Tempfile object which is then yielded and
+        # afterwards deleted.
+        #
+        #     Shrine.with_file(io) { |file| file.path }
+        def with_file(io)
+          if io.respond_to?(:path)
+            yield io
+          elsif io.is_a?(UploadedFile)
+            io.download { |tempfile| yield tempfile }
+          else
+            Tempfile.create("shrine-file", binmode: true) do |file|
+              IO.copy_stream(io, file.path)
+              io.rewind
+
+              yield file
+            end
+          end
+        end
+
         # Prints a deprecation warning to standard error.
         def deprecation(message)
           warn "SHRINE DEPRECATION WARNING: #{message}"
@@ -751,8 +772,8 @@ class Shrine
           metadata["filename"]
         end
 
-        # The extension derived from #id if present, otherwise from
-        # #original_filename.
+        # The extension derived from #id if present, otherwise it's derived
+        # from #original_filename.
         def extension
           result = File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
           result.downcase if result
@@ -800,7 +821,7 @@ class Shrine
         end
 
         # Calls `#download` on the storage if the storage implements it,
-        # otherwise uses #open to stream the underlying IO to a Tempfile.
+        # otherwise streams content into a newly created Tempfile.
         #
         # If a block is given, the opened Tempfile object is yielded to the
         # block, and at the end of the block it's automatically closed and
@@ -821,7 +842,7 @@ class Shrine
             tempfile = storage.download(id, *args)
           else
             tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
-            open(*args) { |io| IO.copy_stream(io, tempfile) }
+            stream(tempfile, *args)
             tempfile.open
           end
 
@@ -830,6 +851,26 @@ class Shrine
           tempfile.close! if ($! || block_given?) && tempfile
         end
 
+        # Streams uploaded file content into the specified destination. The
+        # destination object is given directly to `IO.copy_stream`, so it can
+        # be either a path on disk or an object that responds to `#write`.
+        #
+        # If the uploaded file is already opened, it will be simply rewinded
+        # after streaming finishes. Otherwise the uploaded file is opened and
+        # then closed after streaming.
+        #
+        #     uploaded_file.stream(StringIO.new)
+        #     # or
+        #     uploaded_file.stream("/path/to/destination")
+        def stream(destination, *args)
+          if @io
+            IO.copy_stream(io, destination)
+            io.rewind
+          else
+            open(*args) { |io| IO.copy_stream(io, destination) }
+          end
+        end
+
         # Part of complying to the IO interface. It delegates to the internally
         # opened IO object.
         def read(*args)

data/lib/shrine/plugins/add_metadata.rb

@@ -7,34 +7,55 @@ class Shrine
     #
     #     plugin :add_metadata
     #
-    #     add_metadata :pages do |io, context|
-    #       PDF::Reader.new(io.path).page_count
+    #     add_metadata :exif do |io, context|
+    #       begin
+    #         Exif::Data.new(io).to_h
+    #       rescue Exif::NotReadable # not a valid image
+    #         {}
+    #       end
     #     end
     #
-    # The above will add "pages" to the metadata hash, and also create the
-    # `#pages` reader method on Shrine::UploadedFile.
+    # The above will add "exif" to the metadata hash, and also create the
+    # `#exif` reader method on Shrine::UploadedFile.
     #
-    #     document.metadata["pages"]
+    #     image.metadata["exif"]
     #     # or
-    #     document.pages
+    #     image.exif
     #
     # You can also extract multiple metadata values at once, by using
-    # `add_metadata` without an argument, and returning a hash of metadata.
+    # `add_metadata` without an argument and returning a hash of metadata.
     #
     #     add_metadata do |io, context|
-    #       movie = FFMPEG::Movie.new(io.path)
+    #       begin
+    #         data = Exif::Data.new(io)
+    #       rescue Exif::NotReadable # not a valid image
+    #         next {}
+    #       end
     #
-    #       { "duration"   => movie.duration,
-    #         "bitrate"    => movie.bitrate,
-    #         "resolution" => movie.resolution,
-    #         "frame_rate" => movie.frame_rate }
+    #       { date_time:     data.date_time,
+    #         flash:         data.flash,
+    #         focal_length:  data.focal_length,
+    #         exposure_time: data.exposure_time }
     #     end
     #
     # In this case Shrine won't automatically create reader methods for the
     # extracted metadata on Shrine::UploadedFile, but you can create them via
-    # `metadata_method`.
+    # `#metadata_method`.
     #
-    #     metadata_method :duration, :bitrate, :resolution, :frame_rate
+    #     metadata_method :date_time, :flash
+    #
+    # The `io` might not always be a file object, so if you're using an
+    # analyzer which requires the source file to be on disk, you can use
+    # `Shrine.with_file` to ensure you have a file object.
+    #
+    #     add_metadata do |io, context|
+    #       movie = Shrine.with_file(io) { |file| FFMPEG::Movie.new(file.path) }
+    #
+    #       { "duration"   => movie.duration,
+    #         "bitrate"    => movie.bitrate,
+    #         "resolution" => movie.resolution,
+    #         "frame_rate" => movie.frame_rate }
+    #     end
     module AddMetadata
       def self.configure(uploader)
         uploader.opts[:metadata] = []