shrine 3.4.0 → 3.10.0

data/doc/plugins/keep_files.md

@@ -2,10 +2,11 @@
 title: Keep Files
 ---
 
-The [`keep_files`][keep_files] plugin prevents file deletion when the attacher
-is about to destroy currently attached or previously attached file. This
-functionality is useful when implementing soft deletes, versioning, or in
-general any scenario where you need to track history.
+The [`keep_files`][keep_files] plugin prevents the attached file (and any of
+its [derivatives]) from being deleted when the attachment would normally be
+destroyed, which happens when the attachment is removed/replaced, or when the
+record is deleted. This functionality is useful when implementing soft deletes,
+versioning, or in general any scenario where you need to keep history.
 
 ```rb
 plugin :keep_files
@@ -17,3 +18,4 @@ photo.image.exists? #=> true
 ```
 
 [keep_files]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/keep_files.rb
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives

data/doc/plugins/rack_response.md

@@ -95,6 +95,15 @@ headers["Content-Range"]  #=> "bytes 100-200/1000"
 body                      # partial content
 ```
 
+## ETag
+
+A custom ETag value can be provided via the `:etag` option:
+
+```rb
+response = uploaded_file.to_rack_response(etag: "my-custom-etag")
+response[1]["ETag"] #=> "my-custom-etag"
+```
+
 ## Download options
 
 The `#to_rack_response` method will automatically open the `UploadedFile` if it

data/doc/plugins/refresh_metadata.md

@@ -69,5 +69,25 @@ Any options passed in will be forwarded to metadata extraction:
 uploaded_file.refresh_metadata!(foo: "bar") # passes `{ foo: "bar" }` options to metadata extraction
 ```
 
+## Replacing Metadata
+
+By default the `#refresh_metadata!` method will merge the results into any existing metadata.
+
+```rb
+  uploaded_file.metadata["custom"] = "custom value"
+  uploaded_file.refresh_metadata!
+  uploaded_file.metadata
+  # returns {"filename"=>"example.jpg", "size"=>1024, "mime_type"=>"image/jpeg", "custom"=>"custom value"}
+```
+
+Passing `replace: true` will instead fully overwrite the existing metadata with the new metadata.
+
+```rb
+  uploaded_file.metadata["custom"] = "custom value"
+  uploaded_file.refresh_metadata!(replace: true)
+  uploaded_file.metadata
+  # returns {"filename"=>"example.jpg", "size"=>1024, "mime_type"=>"image/jpeg"}
+```
+
 [refresh_metadata]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/refresh_metadata.rb
 [model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/sequel.md

@@ -100,6 +100,63 @@ set `:hooks` to `false`:
 plugin :sequel, hooks: false
 ```
 
+#### Duplicating records
+
+Since a record being created can't yet have a confirmed attachment of its own
+to safely replace, Shrine never deletes the previous file when the attachment
+changes as part of *creating* a record, only when *updating* one.
+
+Note that Sequel's `#dup`/`#clone`, unlike Active Record's, don't reset the
+primary key or persistence state — a duplicated record still refers to the
+*same* row, so saving it just updates that row rather than inserting a new
+one. There's only ever one row here, so there's nothing to protect:
+
+```rb
+photo  = Photo.create(image: file)
+photo2 = photo.dup # `photo2` refers to the same row as `photo`
+
+photo2.update(image: new_file)
+photo.image.exists? #=> false (the row now has `new_file`, so this is expected)
+```
+
+The common way to duplicate a record in Sequel is instead to construct a new
+one from the original's values, which *does* produce a genuinely new,
+unpersisted row, and so *is* protected:
+
+```rb
+photo2 = Photo.new(photo.values.except(:id))
+
+photo2.update(image: new_file)
+photo.image.exists? #=> true (not affected)
+```
+
+Keep in mind this only protects against *replacing* the attachment on create.
+As long as `photo` and `photo2` continue to reference the same underlying
+file (i.e. `photo2` is saved without ever changing its attachment),
+destroying either record will still delete the file the other one
+references, since Shrine has no way of knowing the file is shared:
+
+```rb
+photo2.save # still references the same file as `photo`
+
+photo2.destroy
+photo.image.exists? #=> false
+```
+
+If you want `photo2` to have its own independent copy of the file from the
+start, so that destroying either record is also safe, upload a new copy
+explicitly:
+
+```rb
+photo2 = Photo.new(photo.values.reject { |k, _| k == :id })
+photo2.image_attacher.set(nil)
+photo2.image_attacher.attach(photo.image, storage: photo.image.storage_key)
+photo2.save
+
+photo2.destroy # no longer affects `photo`
+photo.image.exists? #=> true
+```
+
 ### Validations
 
 If you're using the [`validation`][validation] plugin, the attachment module

data/doc/plugins/signature.md

@@ -78,15 +78,17 @@ plugin :signature
 Calculating signature will trigger a `signature.shrine` event with the
 following payload:
 
-| Key         | Description                            |
-| :--         | :----                                  |
-| `:io`       | The IO object                          |
-| `:uploader` | The uploader class that sent the event |
+| Key          | Description                            |
+| :--          | :----                                  |
+| `:algorithm` | The hashing algorithm used             |
+| `:format`    | The encoding format                    |
+| `:io`        | The IO object                          |
+| `:uploader`  | The uploader class that sent the event |
 
 A default log subscriber is added as well which logs these events:
 
 ```
-MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
+Signature (1ms) – {io: StringIO, algorithm: :md5, format: :hex, uploader: Shrine}
 ```
 
 You can also use your own log subscriber:
@@ -97,7 +99,7 @@ plugin :signature, log_subscriber: -> (event) {
 }
 ```
 ```
-{"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
+{"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","algorithm":"sha512","format":"hex","uploader":"Shrine"}
 ```
 
 Or disable logging altogether:

data/doc/plugins/tempfile.md

@@ -9,14 +9,22 @@ uploaded file on disk.
 Shrine.plugin :tempfile
 ```
 
-The plugin provides the `UploadedFile#tempfile` method, which when called on an
-open uploaded file will return a copy of its content on disk. The first time
-the method is called the file content will cached into a temporary file and
-returned. On any subsequent method calls the cached temporary file will be
-returned directly. The temporary file is deleted when the uploaded file is
-closed.
+The plugin provides the `UploadedFile#tempfile` method, which returns a copy
+of the uploaded file's content on disk. The first time the method is called
+the file content will be downloaded into a temporary file and returned. On
+any subsequent method calls the cached temporary file will be returned
+directly. If the uploaded file is currently open, its tempfile is deleted
+when the uploaded file is closed; otherwise it's deleted whenever it becomes
+unreachable and is garbage collected (so it's still recommended to close the
+uploaded file when you're done with it, to have the tempfile cleaned up
+deterministically).
 
 ```rb
+uploaded_file.tempfile #=> #<Tempfile:...> (file is downloaded and cached)
+uploaded_file.tempfile #=> #<Tempfile:...> (cache is returned)
+
+# OR
+
 uploaded_file.open do
   # ...
   uploaded_file.tempfile #=> #<Tempfile:...> (file is cached)

data/doc/plugins/upload_options.md

@@ -29,4 +29,16 @@ the uploader.
 uploader.upload(file, upload_options: { acl: "public-read" })
 ```
 
+If storage keys are generated dynamically (e.g. via the
+[`dynamic_storage`][dynamic_storage] plugin), it's not possible to list every
+storage key upfront. In that case you can use a `Regexp` instead, which will
+be matched against the storage key:
+
+```rb
+plugin :upload_options, /_store\z/ => { acl: "private" }
+```
+
+An exact storage key match always takes precedence over a `Regexp` match.
+
 [upload_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/upload_options.rb
+[dynamic_storage]: https://shrinerb.com/docs/plugins/dynamic_storage

data/doc/plugins/url_options.md

@@ -24,4 +24,16 @@ In both cases the default options are merged with options passed to
 `UploadedFile#url`, and the latter will always have precedence over default
 options.
 
+If storage keys are generated dynamically (e.g. via the
+[`dynamic_storage`][dynamic_storage] plugin), it's not possible to list every
+storage key upfront. In that case you can use a `Regexp` instead, which will
+be matched against the storage key:
+
+```rb
+plugin :url_options, /_store\z/ => { expires_in: 24*60*60 }
+```
+
+An exact storage key match always takes precedence over a `Regexp` match.
+
 [url_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/url_options.rb
+[dynamic_storage]: https://shrinerb.com/docs/plugins/dynamic_storage

data/doc/plugins/validation_helpers.md

@@ -10,7 +10,7 @@ plugin :validation_helpers
 
 Attacher.validate do
   validate_mime_type %w[image/jpeg image/png image/webp]
-  validate_max_size 5*1024*1024
+  validate_max_size 5*1024*1024 # bytes
   # ...
 end
 ```

data/doc/processing.md

@@ -18,7 +18,8 @@ $ brew install imagemagick
 ```
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 require "image_processing/mini_magick"
@@ -405,7 +406,7 @@ Shrine integration, the ImageProcessing gem that we saw earlier is a completely
 generic gem.
 
 To demonstrate, here is an example of transcoding videos using
-[streamio-ffmpeg]:
+[streamio-ffmpeg][streamio-ffmpeg]:
 
 ```rb
 # Gemfile
@@ -502,7 +503,8 @@ $ brew install vips
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "ruby-vips", "~> 2.3"
 ```
 
 ```rb

data/doc/refile.md

@@ -458,7 +458,7 @@ Shrine.plugin :cached_attachment_data
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
 end
 ```
@@ -475,7 +475,7 @@ Shrine.plugin :remove_attachment
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
   form.check_box :remove_profile_image
 end
@@ -491,7 +491,7 @@ Shrine.plugin :remote_url
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
   form.text_field :profile_image_remote_url
 end

data/doc/release_notes/2.1.0.md

@@ -51,7 +51,7 @@ end
 
 ```rb
 form_for @photo do |f|
-  f.hidden_field :image, value: @photo.cached_image_data
+  f.hidden_field :image, value: @photo.cached_image_data, id: nil
   f.file_filed :image
 end
 ```

data/doc/release_notes/3.10.0.md

@@ -0,0 +1,30 @@
+---
+title: Shrine 3.10.0
+---
+
+## New features
+
+* The new `fallback_storage` plugin makes Shrine read from a secondary (fallback) storage when a file is missing in the primary storage. This is useful for staging or development environments that should read files from production without copying them. `UploadedFile#exists?`, `#url` and `#open` (and methods relying on it) fall back to the secondary storage, while uploads and deletes only affect the primary storage.
+
+  ```rb
+  Shrine.storages = {
+    cache:    Shrine::Storage::S3.new(endpoint: "https://stage.example.com", prefix: "cache"),
+    store:    Shrine::Storage::S3.new(endpoint: "https://stage.example.com"),
+    fallback: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+  }
+
+  Shrine.plugin :fallback_storage # looks for the `:fallback` storage by default
+  Shrine.plugin :fallback_storage, store: :production_store # custom storage name
+  ```
+
+* The `data_uri` plugin now accepts a `:max_size` option for limiting the size of the data URI content. The size is calculated from the data URI before the content is decoded, so oversized content never gets loaded into memory. It's exact for base64 content, while for percent-encoded content the encoded length is used, which can overestimate. Content over the limit fails parsing the same way as an invalid data URI.
+
+  ```rb
+  plugin :data_uri, max_size: 10*1024*1024 # 10 MB
+  ```
+
+* The `data_uri` plugin's `:error_message` proc can now optionally accept the error as a second argument, so the size limit can have its own message.
+
+  ```rb
+  plugin :data_uri, error_message: ->(uri, error) { I18n.t("errors.data_uri.#{error.message}") }
+  ```

data/doc/release_notes/3.5.0.md

@@ -0,0 +1,63 @@
+---
+title: Shrine 3.5.0
+---
+
+## New features
+
+* The website has been migrated to Docusaurus v2. :sparkles:
+
+* The `:signer` option has been added to the `derivation_endpoint` plugin, for when you want to use custom URL signing. This is useful when using `:expires_in`, and wanting to have expiring URLs work with CDN caching.
+
+  ```rb
+  require "aws-sdk-cloudfront"
+  signer = Aws::CloudFront::UrlSigner.new(key_pair_id: "...", private_key: "...")
+
+  plugin :derivation_endpoint,
+    expires_in: 90,
+    signer: -> (url, expires_in:) do
+      signer.signed_url(url, expires: Time.now.to_i + expires_in)
+    end
+  ```
+
+* The S3 storage now supports `:max_multipart_parts` option for specifying the maximum number of concurrent parts in which a large file will get uploaded. This number defaults to `10_000`.
+
+  ```rb
+  Shrine::Storage::S3.new(max_multipart_parts: 1000, ...)
+  ```
+
+* The `:encoding` option can now be passed to `S3#open`, which is applied to downloaded chunks.
+
+  ```rb
+  io = uploaded_file.open(encoding: Encoding::UTF_8)
+  csv = CSV.new(io)
+  # ...
+  ```
+
+## Other improvements
+
+* Passing a boolean value to the `#remove_attachment=` setter now works on Ruby 3.2. Previously this would raise an error, because Shrine would try to call `=~` on it, but `Object#=~` method has been removed in Ruby 3.2.
+
+* When duplicating a model instance, the duplicated attacher now references the duplicated model instance instead of the original one.
+
+* The download endpoint now returns a `400 Bad Request` response when the serialized file component is invalid.
+
+* The `derivatives` plugin now supports passing `mutex: false` option to disable usage of a mutex. This makes the `Shrine::Attacher` object marshallable, which should enable using `Marshal.dump` and `Marshal.load` on model instances with attachments. This should be safe unless you're adding derivatives on the same attacher object concurrently.
+
+* When loading the `derivatives` plugin with `versions_compatibility: true`, this setting doesn't leak to other uploaders anymore. Previously if other uploaders would load `derivatives` plugin without this option, versions compatibility would still get enabled for them. This change also fixes behavior on JRuby.
+
+* When S3 storage copies files, the AWS tag are not inherited anymore. This allows passing the `:tagging` upload option when promoting from temporary to permanent storage, and have it take effect.
+
+* The `UploadedFile#url` method doesn't call the obsolete `URI.regexp` method anymore, which should avoid warnings.
+
+* The `infer_extension` plugin now defines `infer_extension` instance method (in addition to class method) on the uploader for convenience, so that it can be easily called at the uploader instance level.
+
+  ```rb
+  class MyUploader < Shrine
+    plugin :infer_extension
+
+    def generate_location(io, metadata:, **)
+      extension = infer_extension(metadata["mime_type"])
+      # ...
+    end
+  end
+  ```

data/doc/release_notes/3.6.0.md

@@ -0,0 +1,23 @@
+---
+title: Shrine 3.6.0
+---
+
+## New features
+
+* The S3 storage now accepts `:copy_options` when initializing. This can be used for supporting Cloudflare R2 by removing `:tagging_directive` when copying file from temporary to permanent storage.
+
+  ```rb
+  Shrine::Storage::S3.new(bucket: BUCKET, copy_options: {}, **s3_options)
+  ```
+
+## Other improvements
+
+* Rack 3 is now supported.
+
+* When duplicating the attacher, the `Attacher#context` hash is now copied as well, instead of being kept the same between the two attachers.
+
+* After `UploadedFile#close` was called, `UploadedFile#opened?` will return `false` and the uploaded file can be implicitly re-opened again.
+
+## Backwards compatibility
+
+* Shrine API that is returning a rack response triple will now return headers as an instance of `Rack::Headers` on Rack 3, which is a subclass of `Hash`. This should keep user code that references header names in mixed case working (in addition to lowercase), but could theoretically cause issues for code explicitly requiring headers to be an instance of `Hash`.

data/doc/release_notes/3.7.0.md

@@ -0,0 +1,75 @@
+---
+title: Shrine 3.7.0
+---
+
+## New features
+
+* The `download_endpoint` plugin now supports expiring URLs. Configure a `secret_key` and optionally a default `expires_in` on the plugin, then pass `expires_in:` when generating a URL. The URL is signed with HMAC-SHA256, and the endpoint will reject requests with an expired or tampered signature.
+
+  ```rb
+  plugin :download_endpoint,
+    prefix: "downloads",
+    secret_key: "<your-secret-key>",
+    expires_in: 5 * 60 # optional default; can be overridden per URL
+  ```
+
+  ```rb
+  uploaded_file.download_url                      # uses the default expires_in
+  uploaded_file.download_url(expires_in: 10 * 60) # override per URL
+  # => "https://example.com/downloads/<token>?signature=...&expires_at=..."
+  ```
+
+* The `derivatives` plugin now accepts a `:keep_derivatives` option. When set to `true`, existing derivatives are kept when a new file is attached via `Attacher#change`, instead of being cleared.
+
+  ```rb
+  plugin :derivatives, keep_derivatives: true
+  ```
+
+  ```rb
+  attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> }
+  attacher.change(new_file)
+  attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> } # preserved
+  ```
+
+* The `refresh_metadata` plugin now accepts a `replace:` keyword argument on `refresh_metadata!`. Passing `replace: true` replaces the file's metadata entirely with the freshly extracted values, instead of merging them. This is useful when you want to remove stale custom metadata keys.
+
+  ```rb
+  uploaded_file.metadata["custom"] = "stale value"
+
+  uploaded_file.refresh_metadata!              # merge (default)
+  uploaded_file.metadata["custom"]             #=> "stale value" (preserved)
+
+  uploaded_file.refresh_metadata!(replace: true)  # replace
+  uploaded_file.metadata["custom"]             #=> nil (removed)
+  ```
+
+## Other improvements
+
+* The `s3` storage now prefers using `TransferManager#upload_stream` over the deprecated `#upload_stream` method on the S3 object, when `TransferManager` is available. This avoids deprecation warnings from newer versions of the AWS SDK.
+
+* The `column` plugin no longer attempts to deserialize an empty string as JSON. Previously this would raise a parse error; now the attachment is treated as blank.
+
+* The `backgrounding` plugin now correctly forwards keyword arguments passed to `Attacher#promote_cached` into the `promote_block` callback.
+
+  ```rb
+  Shrine::Attacher.promote_block do |attacher:, my_option:, **|
+    # my_option was previously not forwarded here
+    SomePromoteJob.perform_async(attacher.dump, my_option: my_option)
+  end
+
+  attacher.promote_cached(my_option: "value") # now forwarded correctly
+  ```
+
+* `UploadedFile` no longer produces URI default parser warnings (`URI::RFC3986_PARSER.make_regexp is obsolete`) when verbose warnings are enabled.
+
+## Backwards compatibility
+
+* Support for Ruby versions below 3.2 has been dropped. Ruby >= 3.2 is now required.
+
+* ImageProcessing 2.0 made `mini_magick` and `ruby-vips` soft dependencies that are no longer loaded automatically. If you use either gem for image processing, you will need to add it explicitly to your `Gemfile`:
+
+  ```rb
+  gem "mini_magick"
+  # or
+  gem "ruby-vips"
+  ```

data/doc/release_notes/3.7.1.md

@@ -0,0 +1,31 @@
+---
+title: Shrine 3.7.1
+---
+
+## New features
+
+* The `derivation_endpoint` plugin now supports adding a file extension to the derivation URL path via the `:format` option on `UploadedFile#derivation_url`. Some HTTP clients and CDNs use the URL path extension to determine the content type of the response.
+
+  ```rb
+  uploaded_file.derivation_url(:thumbnail, format: "jpg")
+  #=> ".../thumbnail/eyJpZCI6ImZvbyIsInN.jpg?signature=..."
+  ```
+
+  The extension is included in the URL signature, so it cannot be tampered with.
+
+* The `rack_response` plugin now accepts an `:etag` option for setting a custom `ETag` header, overriding the default one Shrine generates.
+
+  ```rb
+  response = uploaded_file.to_rack_response(etag: "my-custom-etag")
+  response[1]["ETag"] #=> "my-custom-etag"
+  ```
+
+## Bug fixes
+
+* When initializing Shrine with the `activerecord` plugin, under Bootsnap 1.24.5 and Ruby 3.4.5 this would raise an error:
+
+  ```
+  ArgumentError: wrong number of arguments (given 2, expected 1; required keyword: plugin)
+  ```
+
+  The seems to be triggered by a special combination of method signatures, where keyword arguments get converted into positional arguments under Bootsnap. To work around this issue, method signatures of some plugin methods have been updated.

data/doc/release_notes/3.8.0.md

@@ -0,0 +1,37 @@
+---
+title: Shrine 3.8.0
+---
+
+## Security
+
+* The `file_system` storage now prevents path traversal outside of the storage
+  directory. Previously, an id containing `../` sequences (e.g. coming from
+  attacker-controlled data) could resolve to a location outside of the
+  configured storage directory. Now `Shrine::Error` is raised whenever an id
+  would resolve outside of the storage directory:
+
+  ```rb
+  storage = Shrine::Storage::FileSystem.new("uploads")
+  storage.open("../../etc/passwd") #~> Shrine::Error
+  ```
+
+## New features
+
+* The `derivatives` plugin now forwards options passed to `Attacher#promote`
+  into `Attacher#upload_derivatives`. This means options such as upload options
+  reach the derivatives upload as well, not just the main file.
+
+  ```rb
+  attacher.promote(upload_options: { acl: "public-read" })
+  # the same options are now forwarded when uploading derivatives
+  ```
+
+## Other improvements
+
+* The `s3` storage again uses single-request uploads for smaller files, instead
+  of always using multipart uploads. In Shrine 3.7.0, when a `TransferManager`
+  was available, it was used for uploads of any size, but `TransferManager`
+  uploads via multipart unconditionally, which is inefficient for smaller files.
+  Now files at or below the multipart threshold (`:upload`, 15MB by default) are
+  uploaded in a single request, and only larger files use multipart upload via
+  the `TransferManager` (falling back to the older API when it's not available).

data/doc/release_notes/3.9.0.md

@@ -0,0 +1,42 @@
+---
+title: Shrine 3.9.0
+---
+
+## New features
+
+* `Shrine.find_storage` now raises `Shrine::MissingStorage` (a subclass of `Shrine::Error`) when the storage isn't registered, instead of a generic `Shrine::Error`. This is useful with the `dynamic_storage` plugin, where the resolver might fail to find its dependencies (e.g. a deleted DB record), and lets you rescue that case separately from other errors.
+
+  ```rb
+  begin
+    Shrine.find_storage(:store)
+  rescue Shrine::MissingStorage
+    # handle missing storage specifically
+  end
+  ```
+
+* The `url_options` and `upload_options` plugins now accept a `Regexp` in place of a storage key. This is useful when storage keys are generated dynamically (e.g. via the `dynamic_storage` plugin), since it's not possible to list every storage key upfront. An exact storage key match always takes precedence over a `Regexp` match.
+
+  ```rb
+  plugin :url_options, /_store\z/ => { expires_in: 24*60*60 }
+  plugin :upload_options, /_store\z/ => { acl: "private" }
+  ```
+
+* The `activerecord` plugin now accepts an `:attribute_types` option. When enabled, it uses `type_for_attribute` (instead of just `columns_hash`) to detect whether the data attribute is JSON/JSONB, so Shrine also skips its own serialization for attributes declared via the Active Record Attributes API (not just real database columns). It defaults to `false` for backwards compatibility with apps that might be relying on the previous double-serialization behavior.
+
+  ```rb
+  class Photo < ActiveRecord::Base # `image_data` is a text column
+    include ImageUploader::Attachment(:image)
+
+    attribute :image_data, :json
+  end
+
+  plugin :activerecord, attribute_types: true
+  ```
+
+## Bug fixes
+
+* The `activerecord` and `sequel` plugins no longer delete the previous attachment when the record being saved was just created. Previously, duplicating a persisted record (e.g. via `#dup`) and immediately assigning a new attachment before saving the duplicate could end up deleting the *original* record's attachment, since both records shared the same underlying file.
+
+* The `remove_invalid` plugin now correctly clears/reverts the model attribute after an invalid file is deassigned. Previously the record's raw attribute could be left out of sync with the attacher after validation failed.
+
+* `UploadedFile#tempfile` (from the `tempfile` plugin) can now be called without opening the uploaded file first. Previously it raised `Shrine::Error` unless the file was already open; now it downloads and caches the file on demand. If the uploaded file is open, its tempfile is still cleaned up when the file is closed; otherwise it's cleaned up whenever it becomes unreachable and is garbage collected, so it's still recommended to close the uploaded file when you're done with it for deterministic cleanup.

data/doc/retrieving_uploads.md

@@ -124,7 +124,7 @@ end # underlying IO object is closed
 ```
 
 `Shrine::UploadedFile#open` will return the result of a given block.
-block. We can use that to safely retrieve the whole content of a file, without
+We can use that to safely retrieve the whole content of a file, without
 leaving any temporary files lying around.
 
 ```rb

data/doc/storage/s3.md

@@ -124,6 +124,16 @@ uploader.upload(file, upload_options: { acl: "private" })
   the uploader level won't be forwarded for generating presigns, since presigns
   are generated using the storage directly.
 
+## Copy options
+
+If you wish to override options that are passed when copying objects from
+temporary to permanent storage, you can pass `:copy_options`:
+
+```rb
+# Removes default :tagging_directive, which isn't supported by Cloudflare R2
+Shrine::Storage::S3.new(copy_options: {}, **s3_options)
+```
+
 ## URL Host
 
 If you want your S3 object URLs to be generated with a different URL host (e.g.