shrine 3.9.0 → 3.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc3e1cb064bc4b1fc0132c5d97c244506b65014eac06b0e8181cf44b2319bf67
-  data.tar.gz: c289af323f41d3cd70dbe740439c9a08f595bba81150a396639cecd92b8b53af
+  metadata.gz: '078c4711b7bd211c577666899edb233967df970a48b96d3b6239189f9c516586'
+  data.tar.gz: a46ed9608642d54c84fd80cc106e56655b4bff7439ff3cf2627bd1c199b40a15
 SHA512:
-  metadata.gz: 128cb224b8199aba9b4a24a0b911c90bc88e404fc9746b440b3edafe19b28422506edf67f4c01474701a9d9a56d5bc4a874152741239a8ff05bc1fa6449a6fb4
-  data.tar.gz: 2582f06b0c087d56cea3e9056bd0763a8d50613dc86bc2707593a3322da0d4be018a507189ca96b63f70715309d8f469f3bc536fcf4c5b3ab859d54697e9910b
+  metadata.gz: 9526af08df019ad15b330e804d2136d0a2f876657b55018b3498ec5fd9c75b881ee1d7559fb4bd862512975d0a7439c4991d11dedf61b9c2bcc6d8c1c3ef38b6
+  data.tar.gz: af84847b2664f400250142bda5995b31d9303de422d5e73d75593ec2d9911f1cdc9e6dc27f10a3f97ab97aaefcb9ebf3f5754a35a6220501af2230dc7f7dcd6b

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 3.10.1 (2026-10-10)
+
+* `model` – Make `Attacher#write` a no-op when the attacher isn't backed by a model, fixing `remove_invalid` raising `NoMethodError` on attachers without a record (@janko)
+
+## 3.10.0 (2026-09-20)
+
+* Add `fallback_storage` plugin for reading files from a secondary storage when they're missing in the primary storage (@yegorov, @janko)
+
+* `data_uri` – Add `:max_size` option for limiting the size of the data URI content, checked before the content is decoded (@jalrax, @janko)
+
+* `data_uri` – Pass the error to the `:error_message` proc as an optional second argument (@jalrax, @janko)
+
 ## 3.9.0 (2026-07-13)
 
 * `Shrine.find_storage` now raises `Shrine::MissingStorage` (subclass of `Shrine::Error`) when the storage isn't registered, so it can be rescued separately (@janko)

data/doc/advantages.md

@@ -389,19 +389,19 @@ and Active Storage.
 
 Uppy supports direct uploads to [AWS S3][Uppy AwsS3] or to a [custom
 endpoint][Uppy XHRUpload]. It also supports **resumable** uploads, either
-[directly to S3][Uppy AwsS3Multipart] or via the [tus protocol][tus]. For the
+[directly to S3][Uppy AwsS3 multipart] or via the [tus protocol][tus]. For the
 UI you can choose from various components, ranging from a simple [status
 bar][Uppy StatusBar] to a full-featured [dashboard][Uppy Dashboard].
 
 Shrine provides server side components for each type of upload. They are built
 on top of Rack, so that they can be used with any Ruby web framework.
 
-| Uppy                                  | Shrine                                   |
-| :---                                  | :-----                                   |
-| [XHRUpload][Uppy XHRUpload]           | [`upload_endpoint`][upload_endpoint]     |
-| [AwsS3][Uppy AwsS3]                   | [`presign_endpoint`][presign_endpoint]   |
-| [AwsS3Multipart][Uppy AwsS3Multipart] | [`uppy-s3_multipart`][uppy-s3_multipart] |
-| [Tus][Uppy Tus]                       | [`tus-ruby-server`][tus-ruby-server]     |
+| Uppy                                      | Shrine                                   |
+| :---                                      | :-----                                   |
+| [XHRUpload][Uppy XHRUpload]               | [`upload_endpoint`][upload_endpoint]     |
+| [AwsS3][Uppy AwsS3]                       | [`presign_endpoint`][presign_endpoint]   |
+| [AwsS3 (multipart)][Uppy AwsS3 multipart] | [`uppy-s3_multipart`][uppy-s3_multipart] |
+| [Tus][Uppy Tus]                           | [`tus-ruby-server`][tus-ruby-server]     |
 
 [Rack]: https://rack.github.io
 [Sinatra]: http://sinatrarb.com
@@ -412,7 +412,7 @@ on top of Rack, so that they can be used with any Ruby web framework.
 [Sequel]: http://sequel.jeremyevans.net
 [ROM]: http://rom-rb.org
 [Hanami::Model]: https://github.com/hanami/model
-[plugin system]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+[plugin system]: https://janko.io/the-plugin-system-of-sequel-and-roda/
 [Down]: https://github.com/janko/down
 [ContentDisposition]: https://github.com/shrinerb/content_disposition
 [`file`]: http://linux.die.net/man/1/file
@@ -440,10 +440,10 @@ on top of Rack, so that they can be used with any Ruby web framework.
 [Uppy XHRUpload]: https://uppy.io/docs/xhr-upload/
 [Uppy AwsS3]: https://uppy.io/docs/aws-s3/
 [Uppy Tus]: https://uppy.io/docs/tus/
-[Uppy AwsS3Multipart]: https://uppy.io/docs/aws-s3-multipart/
+[Uppy AwsS3 multipart]: https://uppy.io/docs/aws-s3/#shouldusemultipartfile
 [tus]: https://tus.io
-[Uppy StatusBar]: https://uppy.io/examples/statusbar/
-[Uppy Dashboard]: https://uppy.io/examples/dashboard/
+[Uppy StatusBar]: https://uppy.io/docs/status-bar/
+[Uppy Dashboard]: https://uppy.io/docs/dashboard/
 [tus-ruby-server]: https://github.com/janko/tus-ruby-server
 [uppy-s3_multipart]: https://github.com/janko/uppy-s3_multipart
 [backgrounding]: https://shrinerb.com/docs/plugins/backgrounding

data/doc/design.md

@@ -264,7 +264,7 @@ When a persistence plugin is loaded ([`activerecord`][activerecord],
 [Using Attacher]: https://shrinerb.com/docs/attacher
 [Notes on study of shrine implementation]: https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/
 [Creating a New Plugin]: https://shrinerb.com/docs/creating-plugins
-[Plugin system of Sequel and Roda]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+[Plugin system of Sequel and Roda]: https://janko.io/the-plugin-system-of-sequel-and-roda/
 [entity]: https://shrinerb.com/docs/plugins/entity
 [model]: https://shrinerb.com/docs/plugins/model
 [activerecord]: https://shrinerb.com/docs/plugins/activerecord

data/doc/direct_s3.md

@@ -174,11 +174,21 @@ and request headers.
 }
 ```
 
-Uppy's [AWS S3][uppy aws-s3] plugin would then make a request to this endpoint
-and use these parameters to upload the file directly to S3. Once the file has
-been uploaded, you can generate a JSON representation of the uploaded file on
-the client side, and write it to the hidden attachment field (or send it
-directly in an AJAX request).
+Uppy's [AWS S3][uppy aws-s3] plugin in Companion mode will then fetch these
+parameters from `<companionEndpoint>/s3/params` and use them to upload the file
+directly to S3:
+
+```js
+uppy.use(AwsS3, {
+  companionEndpoint: '', // relative to the current host
+  shouldUseMultipart: false, // Shrine's presign endpoint only signs single-request uploads
+})
+```
+
+Once the file has been uploaded, you can generate a JSON representation of the
+uploaded file on the client side (the S3 object key is available as
+`response.body.key` in the `upload-success` event), and write it to the hidden
+attachment field (or send it directly in an AJAX request).
 
 ```rb
 {
@@ -203,8 +213,8 @@ as the [Roda][roda demo] / [Rails][rails demo] demo app for a complete example
 of multiple direct S3 uploads.
 
 Also, if you're dealing with larger files, you may want to make the uploads
-resumable by using the [AWS S3 Multipart][uppy aws-s3-multipart] Uppy plugin
-instead, with the [uppy-s3_multipart] gem on the backend. Your back-end
+resumable by using Uppy's [AWS S3][uppy aws-s3-multipart] plugin in multipart
+mode instead, with the [uppy-s3_multipart] gem on the backend. Your back-end
 implementation is similar, just using `Shrine.uppy_s3_multipart` in place of
 `Shrine.presign_endpoint`. Instructions can be found in the [gem
 docs][uppy-s3_multipart shrine].
@@ -396,8 +406,8 @@ setup] guide.
 [rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
 [Uppy]: https://uppy.io
 [uppy aws-s3]: https://uppy.io/docs/aws-s3/
-[uppy aws-s3 cors]: https://uppy.io/docs/aws-s3/#S3-Bucket-configuration
-[uppy aws-s3-multipart]: https://uppy.io/docs/aws-s3/
+[uppy aws-s3 cors]: https://uppy.io/docs/aws-s3/#bucket-and-cors-setup
+[uppy aws-s3-multipart]: https://uppy.io/docs/aws-s3/#shouldusemultipartfile
 [uppy-s3_multipart]: https://github.com/janko/uppy-s3_multipart
 [uppy-s3_multipart shrine]: https://github.com/janko/uppy-s3_multipart#shrine
 [Amazon S3 Data Consistency Model]: http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#ConsistencyMode

data/doc/external/extensions.md

@@ -50,4 +50,4 @@ title: Extensions
 | [faster_s3_url](https://github.com/jrochkind/faster_s3_url)     | Optimized generation of public and presigned AWS S3 GET URLs                    |
 | [imgproxy](https://github.com/imgproxy/imgproxy.rb)             | Integration for [imgproxy](https://github.com/imgproxy/imgproxy)                |
 | [rails_admin](https://github.com/sferik/rails_admin)            | Integration for [RailsAdmin](https://github.com/sferik/rails_admin)             |
-| [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart) | Integration for [Uppy AWS S3 Multipart](https://uppy.io/docs/aws-s3-multipart/) |
+| [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart) | Integration for [Uppy AWS S3](https://uppy.io/docs/aws-s3/) multipart uploads |

data/doc/getting_started.md

@@ -896,13 +896,13 @@ on slow and flaky internet connections.
 
 #### Uppy S3 Multipart
 
-You can achieve resumable uploads directly to S3 with the [AWS S3
-Multipart][uppy aws-s3-multipart] Uppy plugin, accompanied with
+You can achieve resumable uploads directly to S3 with Uppy's [AWS S3][uppy
+aws-s3-multipart] plugin in multipart mode, accompanied with the
 `uppy_s3_multipart` Shrine plugin provided by the [uppy-s3_multipart] gem.
 
 ```rb
 # Gemfile
-gem "uppy-s3_multipart", "~> 0.3"
+gem "uppy-s3_multipart", "~> 1.3"
 ```
 ```rb
 Shrine.plugin :uppy_s3_multipart
@@ -1108,7 +1108,7 @@ Shrine.logger.level = Logger::WARN
 [Uppy]: https://uppy.io
 [shrine-tus]: https://github.com/shrinerb/shrine-tus
 [tus]: https://tus.io
-[uppy aws-s3-multipart]: https://uppy.io/docs/aws-s3-multipart/
+[uppy aws-s3-multipart]: https://uppy.io/docs/aws-s3/#shouldusemultipartfile
 [uppy aws-s3]: https://uppy.io/docs/aws-s3/
 [uppy tus]: https://uppy.io/docs/tus/
 [uppy xhr-upload]: https://uppy.io/docs/xhr-upload/

data/doc/plugins/data_uri.md

@@ -37,8 +37,23 @@ attachment column. You can change the default error message:
 ```rb
 plugin :data_uri, error_message: "data URI was invalid"
 plugin :data_uri, error_message: ->(uri) { I18n.t("errors.data_uri_invalid") }
+plugin :data_uri, error_message: ->(uri, error) { I18n.t("errors.data_uri.#{error.message}") }
 ```
 
+## Maximum size
+
+It's a good practice to limit the maximum size of the data URI content:
+
+```rb
+plugin :data_uri, max_size: 10*1024*1024 # 10 MB
+```
+
+Now if content bigger than 10MB is assigned, parsing will fail the same way as
+for an invalid data URI. 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.
+
 ## Uploader options
 
 Any options passed to `Attacher#assign_data_uri` will be forwarded to

data/doc/plugins/fallback_storage.md

@@ -0,0 +1,90 @@
+---
+title: Fallback Storage
+---
+
+The [`fallback_storage`][fallback_storage] plugin allows you to specify a secondary (fallback) storage that
+Shrine will read from if a file is not found in the primary storage.
+
+This is especially useful when setting up a staging or development environment where you want to read files
+from production storage without replicating or copying large amounts of data locally.
+
+```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
+```
+
+By default, the plugin looks for a storage named `:fallback`. You can override the fallback storage
+name by passing the `:store` option:
+
+```rb
+Shrine.plugin :fallback_storage, store: :production_store
+```
+
+## How It Works
+
+The plugin intercepts file existence checks, URL generation, and file reading methods on
+`Shrine::UploadedFile`.
+
+When performing read or check operations, Shrine will first attempt to query the main storage.
+If the file is missing in the primary storage, it seamlessly falls back to the configured fallback storage:
+
+* `UploadedFile#exists?` — Returns true if the file exists in the primary storage OR in the fallback storage.
+* `UploadedFile#url` — Returns the URL from the primary storage if the file exists there,
+otherwise generates the URL using the fallback storage.
+* `UploadedFile#open` (and methods relying on it like `read`, `download`, etc.) — Opens the file from the
+primary storage if present, otherwise opens it from the fallback storage.
+
+## Write and Delete Operations
+
+The plugin only affects read operations. Uploads, replacements, and deletions interact strictly with
+the primary storage:
+
+* Uploads: `Shrine.upload` writes files only to the main storage.
+* Deletes: `UploadedFile#delete` removes the file only from the primary storage. The fallback storage remains
+untouched.
+
+```ruby
+# File exists only in fallback storage
+file = Shrine.uploaded_file({ "id" => "some-id", "storage" => "store" })
+file.exists? # => true (found in fallback)
+
+# Deleting removes it from primary storage, but fallback remains intact
+file.delete
+file.exists? # => true (still found in fallback)
+```
+
+For additional security and reliability when pointing to a production environment, it is recommended
+to configure the credentials for the fallback storage (e.g., S3 access keys) with read-only permissions.
+
+## Rails example
+
+A common use case is a staging environment that should have access to production files without storing
+its own copies. You can configure Shrine differently per environment:
+
+```rb
+# config/initializers/shrine.rb
+if Rails.env.production?
+  Shrine.storages = {
+    cache: Shrine::Storage::S3.new(endpoint: "https://production.example.com", prefix: "cache"),
+    store: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+  }
+else
+  Shrine.storages = {
+    cache: Shrine::Storage::S3.new(endpoint: "https://stage.example.com", prefix: "cache"),
+    store: Shrine::Storage::S3.new(endpoint: "https://stage.example.com"),
+    production: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+  }
+
+  Shrine.plugin :fallback_storage, store: :production
+end
+```
+
+With this setup, staging uploads go to the staging endpoint, but any read for a missing file
+will automatically look in the production endpoint.
+
+[fallback_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/fallback_storage.rb

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

@@ -0,0 +1,15 @@
+---
+title: Shrine 3.10.1
+---
+
+## Bug fixes
+
+* Since Shrine 3.9.0, the `remove_invalid` plugin would raise `NoMethodError` when validation failed on an attacher without a record and the `model` plugin was loaded (directly or through the `activerecord`/`sequel` plugins).
+
+  ```rb
+  attacher = Shrine::Attacher.new
+  attacher.assign(invalid_file)
+  # NoMethodError: undefined method '=' for nil
+  ```
+
+  `Attacher#write` from the `model` plugin is now a no-op when the attacher isn't backed by a model, so the invalid file is removed and validation errors are kept as before.

data/lib/shrine/plugins/data_uri.rb

@@ -17,6 +17,7 @@ class Shrine
       BASE64_REGEXP        = /;base64/
       CONTENT_SEPARATOR    = /,/
       DEFAULT_CONTENT_TYPE = "text/plain"
+      BASE64_ALPHABET      = "A-Za-z0-9+/"
 
       LOG_SUBSCRIBER = -> (event) do
         Shrine.logger.info "Data URI (#{event.duration}ms) – #{{
@@ -78,13 +79,37 @@ class Shrine
           data_file
         end
 
-        # Parses the data URI string and returns parts.
+        # Raises `ParseError` if the content exceeds the `:max_size` option.
+        def verify_data_size!(uri, offset, base64)
+          max_size = opts[:data_uri][:max_size]
+          return unless max_size
+
+          size = data_size(uri, offset, base64)
+
+          raise ParseError, "data URI is too large" if size > max_size
+        end
+
+        # Returns the size the content will have once decoded. It's exact for
+        # base64 and an upper bound for percent-encoded content.
+        def data_size(uri, offset, base64)
+          return uri.bytesize - offset unless base64
+
+          header_characters  = uri.byteslice(0, offset).count(BASE64_ALPHABET)
+          content_characters = uri.count(BASE64_ALPHABET) - header_characters
+
+          content_characters * 3 / 4 # 4 characters decode into 3 bytes
+        end
+
+        # Parses the data URI string, verifies content size, and returns parts.
         def parse_data_uri(uri)
           scanner = StringScanner.new(uri)
           scanner.scan(DATA_REGEXP) or raise ParseError, "data URI has invalid format"
           media_type = scanner.scan(MEDIA_TYPE_REGEXP)
           base64 = scanner.scan(BASE64_REGEXP)
           scanner.scan(CONTENT_SEPARATOR) or raise ParseError, "data URI has invalid format"
+
+          verify_data_size!(scanner.string, scanner.pos, base64)
+
           content = scanner.post_match
 
           { content_type: media_type, base64: !!base64, data: content }
@@ -129,7 +154,7 @@ class Shrine
         # Generates an error message for failed data URI parse.
         def data_uri_error_messsage(uri, error)
           message = shrine_class.opts[:data_uri][:error_message]
-          message = message.call(uri) if message.respond_to?(:call)
+          message = message.call(*[uri, error].take(message.arity.abs)) if message.respond_to?(:call)
           message || error.message
         end
       end

data/lib/shrine/plugins/fallback_storage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    # Documentation can be found on https://shrinerb.com/docs/plugins/fallback_storage
+    module FallbackStorage
+      def self.configure(uploader, **opts)
+        uploader.opts[:fallback_storage] ||= { store: :fallback }
+        uploader.opts[:fallback_storage].merge!(opts)
+
+        uploader.find_storage(uploader.opts.dig(:fallback_storage, :store))
+      end
+
+      module FileMethods
+        def self.included(base)
+          base.class_eval do
+            alias_method :storage_exists?, :exists?
+
+            def exists?
+              super || fallback_storage.exists?(id)
+            end
+          end
+        end
+
+        def url(**)
+          if storage_exists?
+            super
+          else
+            fallback_storage.url(id, **)
+          end
+        end
+
+        private
+
+        def _open(**)
+          if storage_exists?
+            super
+          else
+            fallback_storage.open(id, **)
+          end
+        end
+
+        def fallback_storage
+          shrine_class.find_storage(shrine_class.opts.dig(:fallback_storage, :store))
+        end
+      end
+    end
+
+    register_plugin(:fallback_storage, FallbackStorage)
+  end
+end

data/lib/shrine/plugins/model.rb

@@ -122,12 +122,15 @@ class Shrine
         # Writes uploaded file data into the model.
         def set(*)
           result = super
-          write if model?
+          write
           result
         end
 
-        # Writes the attachment data into the model attribute.
+        # Writes the attachment data into the model attribute. Does nothing
+        # when the attacher isn't backed by a model instance.
         def write
+          return unless model?
+
           column_values.each do |name, value|
             write_attribute(name, value)
           end

data/lib/shrine/version.rb

@@ -7,8 +7,8 @@ class Shrine
 
   module VERSION
     MAJOR = 3
-    MINOR = 9
-    TINY  = 0
+    MINOR = 10
+    TINY  = 1
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.10.1
 platform: ruby
 authors:
 - Janko Marohnić
@@ -417,6 +417,7 @@ files:
 - doc/plugins/download_endpoint.md
 - doc/plugins/dynamic_storage.md
 - doc/plugins/entity.md
+- doc/plugins/fallback_storage.md
 - doc/plugins/form_assign.md
 - doc/plugins/included.md
 - doc/plugins/infer_extension.md
@@ -488,6 +489,8 @@ files:
 - doc/release_notes/3.0.0.md
 - doc/release_notes/3.0.1.md
 - doc/release_notes/3.1.0.md
+- doc/release_notes/3.10.0.md
+- doc/release_notes/3.10.1.md
 - doc/release_notes/3.2.0.md
 - doc/release_notes/3.2.1.md
 - doc/release_notes/3.2.2.md
@@ -530,6 +533,7 @@ files:
 - lib/shrine/plugins/download_endpoint.rb
 - lib/shrine/plugins/dynamic_storage.rb
 - lib/shrine/plugins/entity.rb
+- lib/shrine/plugins/fallback_storage.rb
 - lib/shrine/plugins/form_assign.rb
 - lib/shrine/plugins/included.rb
 - lib/shrine/plugins/infer_extension.rb