shrine 3.0.1 → 3.3.0

data/doc/refile.md

@@ -1,12 +1,12 @@
 ---
-title: Shrine for Refile Users
+title: Upgrading from Refile
 ---
 
 This guide is aimed at helping Refile users transition to Shrine, and it consists
 of three parts:
 
 1. Explanation of the key differences in design between Refile and Shrine
-2. Instructions how to migrate and existing app that uses Refile to Shrine
+2. Instructions how to migrate an existing app that uses Refile to Shrine
 3. Extensive reference of Refile's interface with Shrine equivalents
 
 ## Overview
@@ -110,13 +110,6 @@ into separate columns.
 Shrine provides on-the-fly processing via the
 [`derivation_endpoint`][derivation_endpoint] plugin:
 
-```rb
-# config/routes.rb (Rails)
-Rails.application.routes.draw do
-  # ...
-  mount ImageUploader.derivation_endpoint => "/derivations/image"
-end
-```
 ```rb
 require "image_processing/mini_magick"
 
@@ -132,8 +125,15 @@ class ImageUploader < Shrine
   end
 end
 ```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
+end
+```
 
-Shrine also support processing up front using the [`derivatives`][derivatives]
+Shrine also support eager processing using the [`derivatives`][derivatives]
 plugin.
 
 ### Validation
@@ -199,13 +199,18 @@ explains this setup in more detail.
 ## Migrating from Refile
 
 You have an existing app using Refile and you want to transfer it to
-Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
-we need to create the `image_data` column for Shrine:
+Shrine. Let's assume we have a `Photo` model with the "image" attachment.
+
+### 1. Add Shrine column
+
+First we need to create the `image_data` column for Shrine:
 
 ```rb
 add_column :photos, :image_data, :text
 ```
 
+### 2. Dual write
+
 Afterwards we need to make new uploads write to the `image_data` column. This
 can be done by including the below module to all models that have Refile
 attachments:
@@ -219,8 +224,7 @@ Shrine.storages = {
 }
 
 Shrine.plugin :model
-```
-```rb
+
 module RefileShrineSynchronization
   def write_shrine_data(name)
     attacher = Shrine::Attacher.from_model(self, name)
@@ -257,8 +261,12 @@ end
 ```
 
 After you deploy this code, the `image_data` column should now be successfully
-synchronized with new attachments.  Next step is to run a script which writes
-all existing Refile attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing Refile attachments to
+`image_data`:
 
 ```rb
 Photo.find_each do |photo|
@@ -267,9 +275,22 @@ Photo.find_each do |photo|
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of Refile, using equivalent Shrine storages. For help with translating
-the code from Refile to Shrine, you can consult the reference below.
+instead of Refile (you can consult the reference in the next section). You can
+remove the `RefileShrineSynchronization` module as well.
+
+### 5. Remove Refile columns
+
+If everything is looking good, we can remove Refile columns:
+
+```rb
+remove_column :photos, :image_id
+remove_column :photos, :image_size
+remove_column :photos, :image_filename
+remove_column :photos, :image_content_type
+```
 
 ## Refile to Shrine direct mapping
 

data/doc/release_notes/2.19.0.md

@@ -16,7 +16,7 @@ title: Shrine 2.19.0
   uploaded_file.download
   uploaded_file.delete
   ```
-  ```plaintext
+  ```
   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}

data/doc/release_notes/2.8.0.md

@@ -1,5 +1,5 @@
 ---
-title: Shrine 2.9.0
+title: Shrine 2.8.0
 ---
 
 ## New Features

data/doc/release_notes/3.0.0.md

@@ -366,7 +366,7 @@ end
   ```
   ```rb
   attacher = photo.image_attacher
-  attacher.form_assign("image" => file, "title" => "...", "description" => "...")
+  attacher.form_assign({ "image" => file, "title" => "...", "description" => "..." })
   attacher.file #=> #<Shrine::UploadedFile id="..." storage=:cache ...>
   ```
 

data/doc/release_notes/3.0.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 3.0.1
+---
+
 ## Regressions
 
 * Fixed `metadata_attributes` plugin raising an exception when the attachment

data/doc/release_notes/3.1.0.md

@@ -0,0 +1,73 @@
+---
+title: Shrine 3.1.0
+---
+
+## New features
+
+* The `Attacher#create_derivatives` method now accepts a `:storage` option for
+  specifying the storage to which derivatives should be uploaded.
+
+  ```rb
+  # with attachment module
+  photo.image_derivatives!(storage: :other_store)
+
+  # with attacher
+  attacher.create_derivatives(storage: :other_store)
+  ```
+
+* The `Shrine.calculate_signature` now accepts a `:rewind` boolean option for
+  choosing whether the IO object should be rewinded after reading. This is
+  useful if you want to calculate signature from non-rewindable IO objects,
+  such as `IO.pipe`, `Socket`, non-rewindable `Down::ChunkedIO` etc.
+
+  ```rb
+  Shrine.signature(io, rewind: false)
+  ```
+
+## Improvements
+
+* The derivatives processor can now be registered with `Attacher.derivatives`,
+  which is just an alias for `Attacher.derivatives_processor`.
+
+  ```rb
+  class ImageUploader < Shrine
+    Attacher.derivatives_processor do |original|
+      # ...
+    end
+  end
+
+  # can now be written as
+
+  class ImageUploader < Shrine
+    Attacher.derivatives do |original|
+      # ...
+    end
+  end
+  ```
+
+* The `Attacher#cached?` and `Attacher#stored?` methods now work correctly if
+  temporary/permanent storage identifiers were specified as strings.
+
+* The `store_dimensions` plugin now properly propagates exceptions when loading
+  the `ruby-vips` gem in `:vips` analyzer.
+
+* The `add_metadata` plugin now respects inheritance again when defining
+  metadata methods on the `Shrine::UploadedFile` class. In 2.19.0, the
+  `add_metadata` plugin was changed to define metadata methods on the internal
+  `FileMethods` plugin module, which is shared across all uploaders. This
+  change has now been reverted.
+
+## Backwards compatibility
+
+* The `Attacher#cache_key` and `Attacher#store_key` methods now always return
+  symbol keys, even if the storage key that was specified was a string key.
+
+  ```rb
+  attacher = Shrine::Attacher.new(cache: "cache", store: "store")
+  attacher.cache_key #=> :cache (previously "cache")
+  attacher.store_key #=> :store (previously "store")
+  ```
+
+* The `add_metadata` plugin now defines metadata methods directly on the
+  `UploadedFile` class, which means that if you happen to have been overriding
+  these metadata methods and calling `super`, this won't work anymore.

data/doc/release_notes/3.2.0.md

@@ -0,0 +1,96 @@
+---
+title: Shrine 3.2.0
+---
+
+## New features
+
+* The `type_predicates` plugin has been added, which adds convenient predicate
+  methods to `Shrine::UploadedFile` based on the MIME type.
+
+  ```rb
+  # Gemfile
+  gem "mini_mime" # default dependency of type_predicates
+  ```
+  ```rb
+  Shrine.plugin :type_predicates
+  ```
+
+  The plugin adds four predicate methods based on the general type of the file:
+
+  ```rb
+  file.image? # returns true for any "image/*" MIME type
+  file.video? # returns true for any "video/*" MIME type
+  file.audio? # returns true for any "audio/*" MIME type
+  file.text?  # returns true for any "text/*" MIME type
+  ```
+
+  You can also check for specific MIME type using the extension name:
+
+  ```rb
+  file.type?(:jpg) # returns true if MIME type is "image/jpeg"
+  file.type?(:svg) # returns true if MIME type is "image/svg+xml"
+  file.type?(:mov) # returns true if MIME type is "video/quicktime"
+  file.type?(:ppt) # returns true if MIME type is "application/vnd.ms-powerpoint"
+  ...
+  ```
+
+  For convenience, you can create predicate methods for specific file types:
+
+  ```rb
+  Shrine.plugin :type_predicates, methods: %i[jpg svg mov ppt]
+  ```
+  ```rb
+  file.jpg? # returns true if MIME type is "image/jpeg"
+  file.svg? # returns true if MIME type is "image/svg+xml"
+  file.mov? # returns true if MIME type is "video/quicktime"
+  file.ppt? # returns true if MIME type is "application/vnd.ms-powerpoint"
+  ```
+
+* The `#add_metadata` method has been added to the `add_metadata` plugin for
+  adding new metadata to an existing file/attachment.
+
+  ```rb
+  attacher.file.metadata #=> { ... }
+  attacher.add_metadata("foo" => "bar")
+  attacher.file.metadata #=> { ..., "foo" => "bar" }
+  ```
+
+## Other improvements
+
+* The `remove_invalid` plugin now works correctly with `derivatives` plugin.
+
+* The `remove_invalid` plugin is now also activated when `Attacher#validate`
+  is called manually.
+
+* The current attached file data can now be assigned back to the attachment
+  attribute, and this operation will be a no-op.
+
+  ```rb
+  photo.image #=> #<Shrine::UploadedFile id="foo" storage=:store metadata={...}>
+  photo.image = { "id" => "foo", "storage" => "store", "metadata" => { ... } } # no-op
+  ```
+
+  This allows treating the attachment attribute as a persistent attribute,
+  where the current value can be assigned back on record updates.
+
+* When promoting derivatives, the `:derivative` parameter value was being
+  passed to the uploader as an array. This has been fixed, and the value is now
+  the same as when uploading derivatives directly to permanent storage.
+
+* The `derivatives` plugin now includes additional `:io` and `:attacher` values
+  in the instrumentation event payload.
+
+## Backwards compatibility
+
+* The `validation` plugin now runs validations on `Attacher#attach` and
+  `Attacher#attach_cached`. If you were using `Attacher#change` directly and
+  expecting the validations to be run automatically, you will need to update
+  your code.
+
+* If you were updating the cached file metadata via file data assignment, this
+  will no longer work.
+
+  ```rb
+  photo.image #=> #<Shrine::UploadedFile id="foo" storage=:cache metadata={...}>
+  photo.image = { "id" => "foo", "storage" => "cache", "metadata" => { ... } } # no-op
+  ```

data/doc/release_notes/3.2.1.md

@@ -0,0 +1,31 @@
+---
+title: Shrine 3.2.1
+---
+
+## Ruby 2.7 compatibility
+
+* Shrine doesn't trigger [Ruby 2.7 warnings for separation of positional and
+  keyword arguments][kwargs] anymore.
+
+* Down 5.1.0 has been released, which resolves warnings and a `FrozenError`
+  exception on Ruby 2.7. Shrine now requires at least this version of Down.
+
+  If you're using `Down::Http`, make sure you're using http.rb 4.3.0 or newer.
+
+* ImageProcessing 1.10.3 gem has been released which resolves Ruby 2.7 warnings
+  as well. If you're using it for image processing, make sure to upgrade to
+  this version:
+
+  ```rb
+  gem "image_processing", ">= 1.10.3", "< 2"
+  ```
+
+## Rack 2.1 compatibility
+
+* The `derivation_endpoint` plugin now uses `Rack::Files` on Rack 2.1 or newer.
+
+## Other improvements 
+
+* The `S3#open` method now handles empty S3 objects.
+
+[kwargs]: https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/

data/doc/release_notes/3.2.2.md

@@ -0,0 +1,14 @@
+---
+title: Shrine 3.2.2
+---
+
+## Bug fixes
+
+* aws-sdk-core 3.104.0 introduced a backwards incompatible changes that caused
+  `Shrine::Storage::S3#open` to start raising an exception.
+
+  ```
+  NoMethodError: undefined method `bytesize' for #<Array:0x000000000a721be0>
+  ```
+
+  This has now been fixed.

data/doc/release_notes/3.3.0.md

@@ -0,0 +1,105 @@
+---
+title: Shrine 3.3.0
+---
+
+## New features
+
+* The `:create_on_promote` option has been added to the `derivatives` plugin
+  for automatically creating derivatives after the attached cached file is
+  promoted to permanent storage.
+
+  ```rb
+  Shrine.plugin :derivatives, create_on_promote: true
+  ```
+
+* The `:auto_extraction` option has been added to the `store_dimensions` plugin
+  for skipping automatically extracting dimensions on upload.
+
+  ```rb
+  Shrine.plugin :store_dimensions, auto_extraction: false
+  ```
+
+* The `:skip_nil` option has been added to the `add_metadata` plugin for
+  excluding metadata keys whose values are nil.
+
+  ```rb
+  class PdfUploader < Shrine
+    add_metadata :pages, skip_nil: true do |io|
+      if is_pdf?(io)
+        reader = PDF::Reader.new(io)
+        reader.page_count
+      else
+        # If this is not a PDF, then the pages metadata will not be stored
+        nil
+      end
+    end
+  end
+  ```
+
+* The `:download` option has been added to derivatives processors in
+  `derivatives` plugin for skipping converting the source IO object into a
+  file. This can be used to avoid a potentially expensive download/copy when
+  the derivatives processor doesn't need the file.
+
+  ```rb
+  Attacher.derivatives :my_processor, download: false do |source|
+    source #=> Could be File, Shrine::UploadedFile, or other IO-like object
+    shrine_class.with_file(source) do |file|
+      # can force download/copy if necessary with `with_file`,
+    end
+  end
+  ```
+
+## Bug fixes
+
+* The `upload_endpoint` now handles calling `Shrine.upload_response` method
+  from a Rails controller.
+
+* The `derivation_endpoint` plugin now applies the `version` query parameter
+  to the derivation when creating the response.
+
+## Other improvements
+
+* The new `Aws:S3::EncryptionV2::Client` is now supported by the S3 storage for
+  client-side encryption.
+
+* The `derivation_endpoint` now reduces the possibility of timing attacks by
+  comparing URL signatures in constant time using `Rack::Utils.secure_compare`.
+
+* The `derivatives` plugin now copies non-file source IO objects to disk before
+  passing them to the processor. This is consistent with how a
+  `Shrine::UploadedFile` object is downloaded to disk.
+
+* The `sequel` and `activerecord` plugins now call `Attacher#reload` when
+  reloading the model, which reloads the attached files but keeps other
+  attacher state.
+
+* The `derivatives` plugin doesn't download the attached file anymore if
+  attempting to process derivatives when no derivatives processor was defined.
+
+* The `mirroring` plugin now forwards attacher options when uploading to mirror
+  storages.
+
+* The `presign_endpoint` plugin now handles the `OPTIONS` HTTP verb, which
+  newer versions of Uppy are requesting.
+
+* `Shrine::Storage::Memory#open` now always returns a `StringIO` in the file
+  content's original encoding, instead of the encoding set by
+  `Encoding.default_internal`. This works around a [bug][ruby-lang #16497]
+  in `StringIO` introduced in Ruby 2.7.0.
+
+* The `remove_attachment` plugin now deletes the removed file if a new file was
+  attached right after removal.
+
+## Backwards compatibility
+
+* If you were passing a non-file IO object to the derivatives processor, Shrine
+  will now convert it into a file beforehand. If you're currently doing this
+  and are converting the IO object into a file inside the processor, you can
+  now remove the conversion code to avoid doubling the amount of disk writes.
+
+* When reloading a Sequel/ActiveRecord model, any attacher state other than
+  uploaded files will now be retained after the reload. If you were relying on
+  all the attacher state being re-initialized, you'll need to update your code.
+
+[ruby-lang #16497]: https://bugs.ruby-lang.org/issues/16497