shrine 2.18.1 → 2.19.0

data/doc/plugins/upload_endpoint.md

@@ -66,7 +66,7 @@ class UploadsController < ApplicationController
   def image
     # ... we can perform authentication here ...
 
-    set_rack_response ImageUploader.upload_response(:cache, env)
+    set_rack_response ImageUploader.upload_response(:cache, request.env)
   end
 
   private
@@ -161,7 +161,7 @@ You can override any of the options above when creating the endpoint/response:
 ```rb
 Shrine.upload_endpoint(:cache, max_size: 20*1024*1024)
 # or
-Shrine.upload_response(:cache, env, max_size: 20*1024*1024)
+Shrine.upload_response(:cache, request.env, max_size: 20*1024*1024)
 ```
 
 ## Checksum

data/doc/plugins/validation_helpers.md

@@ -17,84 +17,116 @@ end
 ### File size
 
 The `#validate_max_size`/`#validate_min_size` methods accept a number of bytes,
-and validate that the `size` metadata value is not larger or smaller than the
+and validate that the `size` metadata value is not greater/less than the
 specified size.
 
 ```rb
-validate_max_size 5*1024*1024 # file must be smaller than 5 MB
-validate_min_size 1024        # file must be larger than 1 KB
+validate_max_size 5*1024*1024 # file size must not be greater than 5 MB
+validate_min_size 1024        # file size must not be less than 1 KB
+```
+
+You can also use the `#validate_size` method, which combines these two:
+
+```rb
+validate_size 1024..5*1024*1024 # file size must not be greater than 5 MB nor less than 1 KB
 ```
 
 ### MIME type
 
 The `#validate_mime_type_inclusion`/`#validate_mime_type_exclusion` methods
 accept a list of MIME types, and validate that the `mime_type` metadata value
-is (not) a member of that list.
+is/is not a member of that list.
 
 ```rb
 validate_mime_type_inclusion %w[image/jpeg image/png image/gif] # file must be a JPEG, PNG or a GIF image
 validate_mime_type_exclusion %w[application/x-php]              # file must not be a PHP script
 ```
 
+Instead of `#validate_mime_type_inclusion` you can also use just
+`#validate_mime_type`.
+
 ### File extension
 
 The `#validate_extension_inclusion`/`#validation_extension_exclusion` methods
 accept a list of file extensions, and validate that the `filename` metadata
-value extension is (not) a member of that list.
+value extension is/is not a member of that list.
 
 ```rb
 validate_extension_inclusion %w[jpg jpeg png gif] # file must have .jpg, .jpeg, .png, or .gif extension
 validate_extension_exclusion %w[php]              # file must not have a .php extension
 ```
 
+Instead of `#validate_extension_inclusion` you can also use just
+`#validate_extension`.
+
 Since file extension doesn't have to match the type of the file, it's good
 practice to validate both the file extension and the MIME type.
 
 ### Image Dimensions
 
+These validations validate `width` and `height` metadata values, which are
+extracted by the `store_dimensions` plugin.
+
+```rb
+plugin :store_dimensions
+```
+
+It's good practice to validate dimensions in addition to filesize, as a guard
+against decompression attacks.
+
+#### Width
+
 The `#validate_max_width`/`#validate_min_width` methods accept a width in
-pixels, and validates that the `width` metadata value is not larger or smaller
+pixels, and validates that the `width` metadata value is not greater/less
 than the specified number:
 
 ```rb
-validate_max_width 5000 # image width must be smaller than 5000px
-validate_min_width 100  # image width must be larger than 100px
+validate_max_width 5000 # image width must not be greater than 5000px
+validate_min_width 100  # image width must not be less than 100px
 ```
 
+You can also use the `#validate_width` method, which combines these two:
+
+```rb
+validate_width 100..5000 # image width must not be greater than 5000px nor less than 100px
+```
+
+#### Height
+
 The `#validate_max_height`/`#validate_min_height` methods accept a height in
-pixels, and validates that the `height` metadata value is not larger or smaller
+pixels, and validates that the `height` metadata value is not greater/less
 than the specified number:
 
 ```rb
-validate_max_height 5000 # image height must be smaller than 5000px
-validate_min_height 100  # image height must be larger than 100px
+validate_max_height 5000 # image height must not be greater than 5000px
+validate_min_height 100  # image height must not be less than 100px
 ```
 
-It's good practice to validate dimensions in addition to filesize, as a guard
-against decompression attacks. Note that these validations only make sense if
-the `store_dimensions` plugin is loaded, so that image dimensions are extracted.
+You can also use the `#validate_height` method, which combines these two:
 
 ```rb
-plugin :store_dimensions
+validate_height 100..5000 # image height must not be greater than 5000px nor less than 100px
 ```
 
-## Dynamic evaluation
+#### Width & Height
 
-The validation block is evaluated dynamically in the context of a
-`Shrine::Attacher` instance, so you can access the attachment name, record and
-context:
+The `#validate_max_dimensions`/`#validate_min_dimensions` methods accept an
+array of width and height in pixels, and validates that the `width` and
+`height` metadata values are not greater/less than the specified numbers:
 
 ```rb
-Attacher.validate do
-  self    #=> #<Shrine::Attacher>
-  name    #=> :image
-  record  #=> #<Photo>
-  context #=> { ... }
+validate_max_dimensions [5000, 5000] # image dimensions must not be greater than 5000x5000
+validate_min_dimensions [100, 100]   # image dimensions must not be less than 100x100
+```
 
-  # ...
-end
+You can also use the `#validate_dimensions` methods, which combines these two:
+
+```rb
+validate_dimensions [100..5000, 100..5000] # image dimensions must not be greater than 5000x5000 nor less than 100x100
 ```
 
+## Dynamic evaluation
+
 The validation methods return whether the validation succeeded, allowing you to
 easily do conditional validation:
 
@@ -114,8 +146,18 @@ the `:default_messages` option to the plugin:
 
 ```rb
 plugin :validation_helpers, default_messages: {
-  max_size: ->(max) { I18n.t("errors.file.max_size", max: max) },
-  mime_type_inclusion: ->(whitelist) { I18n.t("errors.file.mime_type_inclusion", whitelist: whitelist) },
+  max_size:            -> (max)  { I18n.t("errors.file.max_size", max: max) },
+  min_size:            -> (max)  { I18n.t("errors.file.min_size", min: min) },
+  max_width:           -> (max)  { I18n.t("errors.file.max_width", max: max) },
+  min_width:           -> (max)  { I18n.t("errors.file.min_width", min: min) },
+  max_height:          -> (max)  { I18n.t("errors.file.max_height", max: max) },
+  min_height:          -> (max)  { I18n.t("errors.file.min_height", min: min) },
+  max_dimensions:      -> (dims) { I18n.t("errors.file.max_dimensions", dims: dims) },
+  min_dimensions:      -> (dims) { I18n.t("errors.file.min_dimensions", dims: dims) },
+  mime_type_inclusion: -> (list) { I18n.t("errors.file.mime_type_inclusion", list: list) },
+  mime_type_exclusion: -> (list) { I18n.t("errors.file.mime_type_exclusion", list: list) },
+  extension_inclusion: -> (list) { I18n.t("errors.file.extension_inclusion", list: list) },
+  extension_exclusion: -> (list) { I18n.t("errors.file.extension_exclusion", list: list) },
 }
 ```
 
@@ -124,7 +166,7 @@ If you would like to change the error message inline, you can pass the
 
 ```rb
 Attacher.validate do
-  validate_mime_type_inclusion %w[image/jpeg image/png image/gif], message: "must be JPEG, PNG or GIF"
+  validate_mime_type %w[image/jpeg image/png image/gif], message: "must be JPEG, PNG or GIF"
 end
 ```
 

data/doc/refile.md

@@ -312,7 +312,7 @@ specify the storage that will be used.
 #### `.logger`
 
 ```rb
-Shrine.plugin :logging
+Shrine.logger
 ```
 
 #### `.processors`, `.processor`

data/doc/release_notes/2.18.0.md

@@ -17,7 +17,7 @@
     def image
       authenticate_user!
 
-      set_rack_response ImageUploader.upload_response(:cache, env)
+      set_rack_response ImageUploader.upload_response(:cache, request.env)
     end
 
     private
@@ -47,7 +47,7 @@
     def image
       authenticate_user!
 
-      set_rack_response ImageUploader.presign_response(:cache, env)
+      set_rack_response ImageUploader.presign_response(:cache, request.env)
     end
 
     private

data/doc/release_notes/2.19.0.md

@@ -0,0 +1,263 @@
+## New features
+
+* A new `instrumentation` plugin has been added. It sends and logs events for
+  various Shrine operations, and provides an API for other plugins to send and
+  log their own events.
+
+  ```rb
+  Shrine.plugin :instrumentation
+
+  uploaded_file = Shrine.upload(io, :store)
+  uploaded_file.exists?
+  uploaded_file.download
+  uploaded_file.delete
+  ```
+  ```
+  Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
+  Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
+  Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+  Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :download_options=>{}, :uploader=>Shrine}
+  Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+  ```
+
+  It supports [ActiveSupport::Notifications] (default) and [dry-monitor]
+  notification backends out of the box.
+
+  ```rb
+  require "dry-monitor"
+
+  Shrine.plugin :instrumentation, notifications: Dry::Monitor::Notifications.new(:test)
+  ```
+
+* Metadata extraction can now be skipped during the upload by passing
+  `metadata: false` to the uploader. This is useful in tests, where you might
+  want to skip any potentially expensive metadata extraction while creating
+  test data.
+
+  ```rb
+  uploaded_file = uploader.upload(io, metadata: false) # skips metadata extraction
+  uploaded_file.metadata #=> {}
+  ```
+
+* Metadata extraction can now be forced during the upload of a
+  `Shrine::UploadedFile` object by passing `metadata: true` to the uploader.
+
+  ```rb
+  uploaded_file = uploader.upload(another_uploaded_file, metadata: true) # forces metadata extraction
+  uploaded_file.metadata #=> re-extracted metadata
+  ```
+
+* The `pretty_location` plugin now supports specifying a different identifier.
+
+  ```rb
+  plugin :pretty_location, identifier: "uuid"
+  # "user/aa357797-5845-451b-8662-08eecdc9f762/profile_picture/493g82jf23.jpg"
+
+  plugin :pretty_location, identifier: :email
+  # "user/foo@bar.com/profile_picture/493g82jf23.jpg"
+  ```
+
+* The `store_dimensions` plugin has gained an `:on_error` option for specifying
+  how to react when an error occurrs while extracting dimensions.
+
+  ```rb
+  plugin :store_dimensions, on_error: :warn        # prints a warning message (default)
+  plugin :store_dimensions, on_error: :fail        # raises the exception
+  plugin :store_dimensions, on_error: :ignore      # ignores the exception
+  plugin :store_dimensions, on_error: -> (error) { # custom handler
+    # report the exception to your exception handler
+  }
+  ```
+
+* The `FileSystem#upload` method now accepts a `:move` option for moving the
+  file instead of copying it. This is now preferred over the `moving` plugin.
+
+  ```rb
+  uploader.upload(file, move: true)
+  File.exist?(file.path) #=> false
+  ```
+
+* The `FileSystem#clear!` method can now take a block for more control over
+  which files should be deleted.
+
+  ```rb
+  file_system.clear! { |path| path.mtime < Time.now - 7*24*60*60 } # delete files older than 1 week
+  ```
+
+## Other improvements
+
+* Registering storage objects under string keys now works again (this got
+  broken in version 2.18.0).
+
+* Several plugins now add their own instrumentation when the `instrumentation`
+  plugin has been loaded:
+
+  | Plugin                | Instrumentation                         |
+  | :-----                | :--------------                         |
+  | `derivation_endpoint` | instruments file processing             |
+  | `determine_mime_type` | instruments analyzing MIME type         |
+  | `store_dimensions`    | instruments extracting image dimensions |
+  | `signature`           | instruments calculating signature       |
+  | `infer_extension`     | instruments inferring extension         |
+  | `remote_url`          | instruments remote URL downloading      |
+  | `data_uri`            | instruments data URI parsing            |
+
+* `Shrine.logger` has been added, and any warnings or other messages (such as
+  from the `instrumentation` plugin) now go through it. This way you can change
+  the logging destination:
+
+  ```rb
+  # log messages into the Rails logger
+  Shrine.logger = Rails.logger
+  ```
+
+* The `store_dimensions` plugin now prints warnings by default when extracting
+  dimensions failed.
+
+* The `pretty_location` plugin now comes with a `#pretty_location` method which
+  you can call for customization.
+
+  ```rb
+  def generate_location(io, record: nil, **context)
+    identifier = record.email if record.is_a?(User)
+    pretty_location(io, record: record, identifier: identifier, **context)
+  end
+  ```
+
+* The `Shrine::UploadedFile#[]` operator has been added for easier metadata
+  retrieving.
+
+  ```rb
+  uploaded_file.metadata["duration"]
+  # can now be just
+  uploaded_file["duration"]
+  ```
+
+* The `Shrine.mime_type`, `Shrine.dimensions`, and `Shrine.signature` aliases
+  have been added to `determine_mime_type`, `store_dimensions`, and `signature`
+  plugins.
+
+  ```rb
+  Shrine.determine_mime_type(io)
+  # can now be just
+  Shrine.mime_type(io)
+  ```
+  ```rb
+  Shrine.extract_dimensions(io)
+  # can now be just
+  Shrine.dimensions(io)
+  ```
+  ```rb
+  Shrine.calculate_signature(io)
+  # can now be just
+  Shrine.signature(io)
+  ```
+
+* The `#validate_{max,min}_dimensions` validators have been added to the
+  `validation_helpers` plugin.
+
+  ```rb
+  validate_min_width  10
+  validate_min_height 10
+  validate_max_width  5000
+  validate_max_height 5000
+
+  # can now be written as
+
+  validate_min_dimensions [10, 10]
+  validate_max_dimensions [5000, 5000]
+
+  # which can be additionally shortened to
+
+  validate_dimensions [10..5000, 10..5000]
+  ```
+
+* The `#validate_size`, `#validate_width`, and `#validate_height` shorthands
+  have been added to the `validation_helpers` plugin.
+
+  ```rb
+  validate_min_size 1024
+  validate_max_size 10*1024*1024
+
+  # can now be shortned to
+
+  validate_size 1024..10*1024*1024
+  ```
+  ```rb
+  validate_min_width 10
+  validate_max_width 5000
+
+  # can now be shortened to
+
+  validate_width 10..5000
+  ```
+  ```rb
+  validate_min_height 10
+  validate_max_height 5000
+
+  # can now be shortened to
+
+  validate_height 10..5000
+  ```
+
+* The `#validate_mime_type` and `#validate_extension` shorthands have been
+  added to the `validation_helpers` plugin.
+
+  ```rb
+  validate_mime_type_inclusion %w[image/jpeg image/png image/webp]
+  # can now be just
+  validate_mime_type %w[image/jpeg image/png image/webp]
+  ```
+  ```rb
+  validate_extension_inclusion %w[jpeg png webp]
+  # can now be just
+  validate_extension %w[jpeg png webp]
+  ```
+
+* Default error messages in `validation_helpers` plugin have been simplified.
+
+* You can now call `super` when overriding `Shrine::UploadedFile` methods
+  defined by the `add_metadata` plugin.
+
+## Backwards compatibility
+
+* The `logging` plugin has been deprecated in favour of the `instrumentation`
+  plugin.
+
+* The `moving` pluing has been deprecated in favour of the `:move` option to
+  `FileSystem#upload`. This means that the `#move` && `#movable?` methods are
+  not part of the storage abstraction anymore.
+
+* The `backup` plugin has been deprecated over [mirroring uploads] via the
+  `instrumentation` plugin.
+
+* The `copy` plugin has been deprecated.
+
+* The `Shrine::Plugins::DataUri::DataFile` constant from the `data_uri` plugin
+  has been renamed to `Shrine::DataFile`.
+
+* The `Shrine::Plugins::RackFile::UploadedFile` constant from the `data_uri` plugin
+  has been renamed to `Shrine::RackFile`.
+
+* The `:older_than` option for `FileSystem#clear!` has been deprecated in
+  favour of passing a block.
+
+  ```rb
+  file_system.clear!(older_than: Time.now - 7*24*60*60)
+  # should now be replaced with
+  file_system.clear! { |path| path.mtime < Time.now - 7*24*60*60 }
+  ```
+
+* The `FileSystem#upload` method deprecates ignoring unrecognized upload
+  options.
+
+* The `FileSystem#upload` method doesn't backfill `size` metadata anymore if an
+  IO with unknown size is being uploaded via `Shrine#upload`.
+
+* Several plugins have changed how they store configuration options internally.
+  If you were accessing these options directly, you will need to update your
+  code.
+
+[ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
+[dry-monitor]: https://github.com/dry-rb/dry-monitor
+[mirroring uploads]: https://github.com/shrinerb/shrine/wiki/Mirroring-Uploads