shrine 3.2.2 → 3.3.0

data/doc/plugins/download_endpoint.md

@@ -87,6 +87,10 @@ class DownloadsController < ApplicationController
 end
 ```
 
+If you want to create an endpoint with a custom path, you can use the
+[`rack_response`][rack_response] plugin directly, which this plugin uses
+internally.
+
 ## Host
 
 You can specify download URL host via the `:host` plugin option:
@@ -155,11 +159,6 @@ You can override any of the options above when creating the endpoint:
 Shrine.download_endpoint(disposition: "attachment")
 ```
 
-## Custom endpoint
-
-If you want to have more control on download requests, you can use the
-`rack_response` plugin which this plugin uses internally.
-
 ## Plugin options
 
 | Name                | Description                                                                       | Default  |
@@ -171,3 +170,4 @@ If you want to have more control on download requests, you can use the
 | `:redirect`         | Whether to redirect to uploaded files on the storage                              | `false`  |
 
 [download_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/download_endpoint.rb
+[rack_response]: https://shrinerb.com/docs/plugins/rack_response

data/doc/plugins/dynamic_storage.md

@@ -12,7 +12,7 @@ Example:
 plugin :dynamic_storage
 
 storage /store_(\w+)/ do |match|
-  Shrine::Storages::S3.new(bucket: match[1])
+  Shrine::Storage::S3.new(bucket: match[1])
 end
 ```
 

data/doc/plugins/infer_extension.md

@@ -11,6 +11,15 @@ extension might not be known.
 plugin :infer_extension
 ```
 
+By default an extension will only be inferred if needed to supply an otherwise
+missing extension. But option `force: true` will normalize even an already
+present extension to the extension inferred from MIME type. This could be used
+to fix incorrect or malicious extensions on user-submitted files.
+
+```rb
+plugin :infer_extension, force: true
+```
+
 ## Inferrers
 
 By default, the [mini_mime] gem will be used for inferring the extension, but

data/doc/plugins/metadata_attributes.md

@@ -72,3 +72,4 @@ photo.original_filename #=> "nature.jpg"
 
 [metadata_attributes]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/metadata_attributes.rb
 [entity]: https://shrinerb.com/docs/plugins/entity
+[model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/mirroring.md

@@ -50,7 +50,7 @@ Shrine.plugin :mirroring, mirror: { ... }, delete: false
 You can have mirroring performed in a background job:
 
 ```rb
-Shrine.mirror_upload_block do |file|
+Shrine.mirror_upload_block do |file, **options|
   MirrorUploadJob.perform_async(file.shrine_class.name, file.data)
 end
 

data/doc/plugins/persistence.md

@@ -6,6 +6,10 @@ This is an internal plugin that provides uniform persistence interface across
 different persistence plugins (e.g. [`activerecord`][activerecord],
 [`sequel`][sequel]).
 
+For these activerecord and sequel, atomic persistence is implemented in terms
+of database locks, eg "SELECT... FOR UPDATE". For more discussion of concurrency
+challenges, see the [atomic_helpers] documentation.
+
 ## Atomic promotion
 
 If you're promoting cached file to permanent storage
@@ -65,11 +69,15 @@ changed, and if it hasn't the attachment is persisted. If the attachment has
 changed, `Shrine::AttachmentChanged` exception is raised.
 
 If you want to execute code after the attachment change check but before
-persistence, you can pass a block:
+persistence, you can pass a block. For instance, one way to allow concurrent
+changes to metadata, perhaps in different background workers,  without
+overwriting each other might be:
 
 ```rb
 attacher.atomic_persist do |reloaded_attacher|
   # run code after attachment change check but before persistence
+  attacher.file.metadata.merge!(reloaded_attacher.file.metadata)
+  attacher.file.metadata["some_key"] = "changed_value"
 end
 ```
 
@@ -89,4 +97,5 @@ attacher.persist # saves the underlying record
 
 [activerecord]: https://shrinerb.com/docs/plugins/activerecord
 [sequel]: https://shrinerb.com/docs/plugins/sequel
+[atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers
 [backgrounding]: https://shrinerb.com/docs/plugins/backgrounding

data/doc/plugins/store_dimensions.md

@@ -72,6 +72,16 @@ Shrine.dimensions(io) #=> [300, 400] (calls the defined analyzer)
 Shrine.dimensions_analyzers[:fastimage].call(io) #=> [300, 400] (calls a built-in analyzer)
 ```
 
+### Disabling auto-extraction
+
+If you want to use the dimensions extraction methods but not automatically
+extract dimensions on upload, you can setup this plugin with the
+`auto_extraction: false` option.
+
+```rb
+plugin :store_dimensions, auto_extraction: false
+```
+
 ## Errors
 
 By default, any exceptions that the analyzer raises while extracting dimensions

data/doc/plugins/url_options.md

@@ -4,10 +4,10 @@ title: URL Options
 
 The [`url_options`][url_options] plugin allows you to specify
 URL options that will be applied by default for uploaded files of specified
-storages.
+storages. `url_options` are parameters specific to the storage service.
 
 ```rb
-plugin :url_options, store: { expires_in: 24*60*60 }
+plugin :url_options, store: { expires_in: 24*60*60 } # `expires_in` is a URL option for AWS S3
 ```
 
 You can also generate the default URL options dynamically by using a block,

data/doc/processing.md

@@ -60,8 +60,11 @@ end
 ```
 ```rb
 photo = Photo.new(image: file)
-photo.image_derivatives! # calls derivatives processor
-photo.save
+
+if photo.valid?
+  photo.image_derivatives! if photo.image_changed? # creates derivatives
+  photo.save
+end
 ```
 
 After the processed files are uploaded, their data is saved into the
@@ -468,15 +471,11 @@ end
 ### Automatic derivatives
 
 If you would like derivatives to be automatically created with promotion, you
-can override `Attacher#promote` for call `Attacher#create_derivatives` before
-promotion:
+can use the `create_on_promote` option built-in to the derivatives plugin.
 
 ```rb
 class Shrine::Attacher
-  def promote(*)
-    create_derivatives
-    super
-  end
+  plugin :derivatives, create_on_promote: true
 end
 ```
 

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.2.1.md

@@ -20,10 +20,9 @@ title: Shrine 3.2.1
   gem "image_processing", ">= 1.10.3", "< 2"
   ```
 
-## Rack 2.1.0 compatibility
+## Rack 2.1 compatibility
 
-* The `derivation_endpoint` plugin now uses `Rack::Files` on Rack 2.1.0 or
-  newer.
+* The `derivation_endpoint` plugin now uses `Rack::Files` on Rack 2.1 or newer.
 
 ## Other improvements 
 

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

data/doc/storage/s3.md

@@ -267,9 +267,15 @@ s3.open("key", sse_customer_algorithm: "AES256",
                sse_customer_key_md5:   "secret_key_md5")
 ```
 
-If you want to use **client-side** encryption instead, note that it's still a
-work in progress, see issue [#348] for some discussion and
-[workarounds][client-side encryption workaround].
+**Client-side** encryption is supported as well:
+
+```rb
+encryption_client = Aws::S3::EncryptionV2::Client.new(...)
+s3 = Shrine::Storage::S3.new(client: encryption_client, **other_options)
+
+s3.upload(io, "key") # encrypts on upload
+s3.open("key")       # decrypts on download
+```
 
 ## Accelerate endpoint
 
@@ -317,5 +323,3 @@ s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 }
 [credentials]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html
 [`Aws::S3::Object#presigned_post`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
 [`Aws::S3::Object#presigned_url`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_url-instance_method
-[#348]: https://github.com/shrinerb/shrine/issues/348
-[client-side encryption workaround]: https://github.com/shrinerb/shrine/issues/348#issuecomment-486445382

data/doc/upgrading_to_3.md

@@ -323,15 +323,17 @@ else
 end
 ```
 
-With `derivatives`, the original file is automatically downloaded and retained,
-so the processing code is much simpler:
+With `derivatives`, the original file is automatically downloaded and retained
+during processing, so the setup is simpler:
 
 ```rb
-Shrine.plugin :derivatives, versions_compatibility: true # handle versions column format
+Shrine.plugin :derivatives,
+  create_on_promote:      true, # automatically create derivatives on promotion
+  versions_compatibility: true  # handle versions column format
 ```
 ```rb
 class ImageUploader < Shrine
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
     # the :original file should NOT be included anymore
@@ -343,35 +345,17 @@ class ImageUploader < Shrine
   end
 end
 ```
-
-However, you now need to trigger processing manually during attachment:
-
 ```rb
 photo = Photo.new(photo_params)
 
 if photo.valid?
-  photo.image_derivatives! if photo.image_changed? # create derivatives
-  photo.save
+  photo.save # creates derivatives on promotion
   # ...
 else
   # ...
 end
 ```
 
-### Automatic processing
-
-If you prefer processing to happen automatically with promotion (like it did
-with the `versions` plugin), you can put the following in your initializer:
-
-```rb
-class Shrine::Attacher
-  def promote(*)
-    create_derivatives
-    super
-  end
-end
-```
-
 ### Accessing derivatives
 
 The derivative URLs are accessed in the same way as versions:
@@ -475,11 +459,11 @@ creating another derivatives processor that you will trigger in the controller:
 
 ```rb
 class ImageUploader < Shrine
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     # this will be triggered in the background job
   end
 
-  Attacher.derivatives_processor :foreground do |original|
+  Attacher.derivatives :foreground do |original|
     # this will be triggered in the controller
   end
 end
@@ -586,7 +570,7 @@ you should now add the processed file as a derivative:
 class MyUploader < Shrine
   plugin :derivatives
 
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
     { normalized: magick.resize_to_limit!(1600, 1600) }
@@ -665,7 +649,7 @@ attacher.copy(other_attacher)
 with
 
 ```rb
-attacher.attach other_attacher.file
+attacher.set attacher.upload(other_attacher.file)
 attacher.add_derivatives other_attacher.derivatives # if using derivatives
 ```
 

data/lib/shrine/attacher.rb

@@ -217,7 +217,7 @@ class Shrine
       #     attacher.file #=> #<Shrine::UploadedFile>
       #     attacher.changed? #=> true
       def change(file)
-        @previous = dup unless @file == file
+        @previous = dup if change?(file)
         set(file)
       end
 
@@ -373,6 +373,11 @@ class Shrine
         attached? && !cached?
       end
 
+      # Whether assigning the given file is considered a change.
+      def change?(file)
+        @file != file
+      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

@@ -55,7 +55,7 @@ class Shrine
           # reload the attacher on record reload
           define_method :reload do |*args|
             result = super(*args)
-            instance_variable_set(:"@#{name}_attacher", nil)
+            send(:"#{name}_attacher").reload
             result
           end
         end

data/lib/shrine/plugins/add_metadata.rb

@@ -9,8 +9,8 @@ class Shrine
       end
 
       module ClassMethods
-        def add_metadata(name = nil, &block)
-          opts[:add_metadata][:definitions] << [name, block]
+        def add_metadata(name = nil, **options, &block)
+          opts[:add_metadata][:definitions] << [name, options, block]
 
           metadata_method(name) if name
         end
@@ -40,10 +40,12 @@ class Shrine
         private
 
         def extract_custom_metadata(io, **options)
-          opts[:add_metadata][:definitions].each do |name, block|
+          opts[:add_metadata][:definitions].each do |name, definition_options, block|
             result = instance_exec(io, **options, &block)
 
-            if name
+            if result.nil? && definition_options[:skip_nil]
+              # Do not store this metadata
+            elsif name
               options[:metadata].merge! name.to_s => result
             else
               options[:metadata].merge! result.transform_keys(&:to_s) if result