shrine 3.9.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc3e1cb064bc4b1fc0132c5d97c244506b65014eac06b0e8181cf44b2319bf67
-  data.tar.gz: c289af323f41d3cd70dbe740439c9a08f595bba81150a396639cecd92b8b53af
+  metadata.gz: 5601661d53737bf3290ec5897dc9d33cfe5edac60a7468e67de7191649671a14
+  data.tar.gz: bf2a26e2162a0c1805f2e8d174128e8ee5008060fdbbb9b8e358d41bfdf680a2
 SHA512:
-  metadata.gz: 128cb224b8199aba9b4a24a0b911c90bc88e404fc9746b440b3edafe19b28422506edf67f4c01474701a9d9a56d5bc4a874152741239a8ff05bc1fa6449a6fb4
-  data.tar.gz: 2582f06b0c087d56cea3e9056bd0763a8d50613dc86bc2707593a3322da0d4be018a507189ca96b63f70715309d8f469f3bc536fcf4c5b3ab859d54697e9910b
+  metadata.gz: 7eb43ca8a78d4dedec0d24422ca4bc9f62eb6e454aa61ac7871760c4c398973a9787591295c39799f6b3250d4b3af9e80f7082c659fb6ed67435d775846ca5e2
+  data.tar.gz: 636a7343486f6baaa3fa841abcef8439eb0df5d7183d6ac39a756a508de544dd356bca2562a9e01ac76b871a29455d2a40601f8086e8050dcc793bd57fc568e0

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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

@@ -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

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/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/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/version.rb

@@ -7,7 +7,7 @@ class Shrine
 
   module VERSION
     MAJOR = 3
-    MINOR = 9
+    MINOR = 10
     TINY  = 0
     PRE   = nil
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.10.0
 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,7 @@ 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.2.0.md
 - doc/release_notes/3.2.1.md
 - doc/release_notes/3.2.2.md
@@ -530,6 +532,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