shrine 3.7.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01c1404cab9882d16a6795c41467591b4083cbef76b5d42b91626a4306b33584
-  data.tar.gz: bec484b8594573db2056eabeda97ae5c22fb170a35f984802cd200085611e556
+  metadata.gz: 55c3fc9bf7eb40700d2be0ee82900986c601b1b3449d5d5ee7b246546bfe5eb3
+  data.tar.gz: 11ffe3b196b79946c931f5a0e9538bda74cc4abd74711124509c76a13a5eaddc
 SHA512:
-  metadata.gz: 298e5065ba40638cee54dc4b74be98e466974502f56b5bff956fb2d7cc4d73028ec8a9d79dae7c073306c4512145cfef082ec4beeeb60a0eddef5497bbcf8174
-  data.tar.gz: 3413b070afe6315133342ab3faf7c41d97bb9767a3aa13f62bf4ba339246fb4f1b3d1ebc91036b37942b8893c20b652edf4603f2b710bd66647caed6b9cddc48
+  metadata.gz: 19585a7a2c486d43fb9be2abc84123adced4d18beebf50919938a9c631d16c0c2ecb15e777397b5b8a1642911171d328c55bf86769b9a31a4a3957cf3d8256d9
+  data.tar.gz: 1dfbb667941b5f2bfa1b035230f0b1fb809c59855fc253f8365394624cffd4e3078a0aa41188eb27c8e57be8d4243e45d5dcf56a83b4d9ea1900bf02fa340dc6

data/CHANGELOG.md

@@ -1,5 +1,23 @@
+## 3.8.0 (2026-06-24)
+
+* `s3` – Use single-request uploads for smaller files again instead of always using multipart uploads (@janko)
+
+* `derivatives` – Forward `Attacher#promote` options to `Attacher#upload_derivatives` (@milkcocoa)
+
+* `file_system` – Prevent path traversal outside of the storage directory (@janko)
+
+## 3.7.1 (2026-06-03)
+
+* Update method signatures of some plugins to work around a Bootsnap bug causing a `wrong number of arguments` error (@janko)
+
+* `derivation_endpoint` – Add `:format` argument to `UploadedFile#derivation_url` for path extension (@janko)
+
+* `rack_response` – Add `:etag` argument for setting a custom `ETag` (@camilohollanda)
+
 ## 3.7.0 (2026-05-27)
 
+* `rack_response` - Add `:etag` option for setting a custom `ETag` header (@janko)
+
 * `download_endpoint` - Add support for expiring URLs (@davidwessman)
 
 * `s3` - Use `TransferManager` where available instead of deprecated `upload_steam` (@danieldevlewis)

data/doc/plugins/derivation_endpoint.md

@@ -309,6 +309,19 @@ uploaded_file.derivation_url(:thumbnail, prefix: "transformations/image")
 #=> ".../transformations/image/thumbnail/eyJpZCI6ImZvbyIsInN?signature=..."
 ```
 
+## Format
+
+Some HTTP clients and CDNs use the URL path extension to determine the content
+type of the response. You can append a file extension to the derivation URL
+path with the `:format` option:
+
+```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.
+
 ## Expiration
 
 By default derivation URLs are valid indefinitely. If you want URLs to expire

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/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/lib/shrine/plugins/_persistence.rb

@@ -7,7 +7,7 @@ class Shrine
     #
     #     plugin :_persistence, plugin: MyPlugin
     module Persistence
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :atomic_helpers
         uploader.plugin :entity
       end

data/lib/shrine/plugins/data_uri.rb

@@ -24,7 +24,7 @@ class Shrine
         }.inspect}"
       end
 
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :validation
       end
 

data/lib/shrine/plugins/derivation_endpoint.rb

@@ -303,9 +303,9 @@ class Shrine
   class Derivation::Url < Derivation::Command
     delegate :name, :args, :source, :secret_key, :signer
 
-    def call(host: nil, prefix: nil, metadata: [], **)
+    def call(host: nil, prefix: nil, metadata: [], format: nil, **)
       base_url = [host, *prefix].join("/")
-      path = path_identifier(metadata:)
+      path = path_identifier(metadata:, format:)
 
       if signer
         url = [base_url, path].join("/")
@@ -318,12 +318,13 @@ class Shrine
 
     private
 
-    def path_identifier(metadata: [])
-      [
+    def path_identifier(metadata: [], format: nil)
+      path = [
         name,
         *args,
         source.urlsafe_dump(metadata:)
       ].map{|component| Rack::Utils.escape_path(component.to_s)}.join('/')
+      format ? "#{path}.#{format}" : path
     end
 
     def query(expires_in: nil,
@@ -386,6 +387,7 @@ class Shrine
       check_expiry!(request)
 
       name, *args, serialized_file = request.path_info.split("/")[1..-1]
+      serialized_file = serialized_file.sub(/\.\w+$/, "")
 
       name          = name.to_sym
       uploaded_file = shrine_class::UploadedFile.urlsafe_load(serialized_file)

data/lib/shrine/plugins/derivatives.rb

@@ -161,7 +161,7 @@ class Shrine
         #     attacher.stored?(attacher.derivatives[:thumb]) #=> true
         def promote(**options)
           super
-          promote_derivatives
+          promote_derivatives(**options)
           create_derivatives if create_derivatives_on_promote?
         end
 

data/lib/shrine/plugins/metadata_attributes.rb

@@ -4,7 +4,7 @@ class Shrine
   module Plugins
     # Documentation can be found on https://shrinerb.com/docs/plugins/metadata_attributes
     module MetadataAttributes
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :entity
       end
 

data/lib/shrine/plugins/rack_response.rb

@@ -49,14 +49,14 @@ class Shrine
         # "Content-Disposition" headers, whose values are extracted from
         # metadata. Also returns the correct "Content-Range" header on ranged
         # requests.
-        def rack_headers(filename: nil, type: nil, disposition: "inline", range: false)
+        def rack_headers(filename: nil, type: nil, disposition: "inline", range: false, etag: nil)
           {
             "Content-Length"      => content_length(range),
             "Content-Type"        => content_type(type),
             "Content-Disposition" => content_disposition(disposition, filename),
             "Content-Range"       => content_range(range),
             "Accept-Ranges"       => accept_ranges(range),
-            "ETag"                => etag,
+            "ETag"                => etag || self.etag,
           }.compact
         end
 

data/lib/shrine/plugins/remote_url.rb

@@ -18,7 +18,7 @@ class Shrine
 
       DOWNLOADER = -> (url, **options) { Down.download(url, **options) }
 
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :validation
       end
 

data/lib/shrine/plugins/validation_helpers.rb

@@ -32,7 +32,7 @@ class Shrine
         "%.1f %s" % [bytes.to_f / 1024 ** exp, FILESIZE_UNITS[exp]]
       end
 
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :validation
       end
 

data/lib/shrine/storage/file_system.rb

@@ -113,9 +113,18 @@ class Shrine
         end
       end
 
-      # Returns the full path to the file.
+      # Returns the full path to the file. Raises Shrine::Error if the id would
+      # resolve to a location outside of the storage #directory (e.g. an id
+      # containing `../` path traversal sequences in attacker-controlled data).
       def path(id)
-        directory.join(id.gsub("/", File::SEPARATOR))
+        path = directory.join(id.gsub("/", File::SEPARATOR))
+        expanded = path.expand_path
+
+        unless expanded == directory || expanded.to_s.start_with?("#{directory}#{File::SEPARATOR}")
+          raise Shrine::Error, "path #{id.inspect} resolves outside of the storage directory"
+        end
+
+        path
       end
 
       protected

data/lib/shrine/storage/s3.rb

@@ -230,20 +230,15 @@ class Shrine
 
       private
 
-      # Upload the file to S3.
-      # Uses @transfer_manager, if defined, for any size upload.
-      # Falls back to the original code using the older, now depricated
-      # AWS APIs for users of older version of the AWS Gem.
-      # for multipart uploads of large files.
+      # Uploads the file to S3. Uses multipart upload for large files.
       def put(io, id, **)
-        if @transfer_manager
+        if io.respond_to?(:size) && io.size && io.size <= @multipart_threshold[:upload]
+          object(id).put(body: io, **)
+        elsif @transfer_manager # multipart upload - transfer manager
           @transfer_manager.upload_stream(bucket: bucket.name, key: object_key(id), part_size: part_size(io), **) do |write_stream|
             IO.copy_stream(io, write_stream)
           end
-        elsif io.respond_to?(:size) && io.size && io.size <= @multipart_threshold[:upload]
-          object(id).put(body: io, **)
-        else
-          # multipart upload old API
+        else # multipart upload - before transfer manager
           object(id).upload_stream(part_size: part_size(io), **) do |write_stream|
             IO.copy_stream(io, write_stream)
           end

data/lib/shrine/version.rb

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

data/shrine.gemspec

@@ -67,10 +67,10 @@ direct uploads for fully asynchronous user experience.
 
   # for instrumentation plugin
   gem.add_development_dependency "dry-monitor"
-  gem.add_development_dependency "activesupport", RUBY_ENGINE == "jruby" ? "~> 7.0.0" : "~> 8.1"
+  gem.add_development_dependency "activesupport", RUBY_ENGINE == "jruby" ? "~> 8.0.0" : "~> 8.1"
 
   # for ORM plugins
   gem.add_development_dependency "sequel"
-  gem.add_development_dependency "activerecord", RUBY_ENGINE == "jruby" ? "~> 7.0.0" : "~> 8.1"
+  gem.add_development_dependency "activerecord", RUBY_ENGINE == "jruby" ? "~> 8.0.0" : "~> 8.1"
   gem.add_development_dependency "sqlite3", "~> 2.1" unless RUBY_ENGINE == "jruby"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 3.8.0
 platform: ruby
 authors:
 - Janko Marohnić
@@ -155,20 +155,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: ruby-filemagic
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: mime-types
   requirement: !ruby/object:Gem::Requirement
@@ -301,14 +287,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: 8.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.1'
+        version: 8.0.0
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
@@ -329,28 +315,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.1'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 8.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 8.0.0
 description: |
   Shrine is a toolkit for file attachments in Ruby applications. It supports
   uploading, downloading, processing and deleting IO objects, backed by various
@@ -482,6 +454,8 @@ files:
 - doc/release_notes/3.5.0.md
 - doc/release_notes/3.6.0.md
 - doc/release_notes/3.7.0.md
+- doc/release_notes/3.7.1.md
+- doc/release_notes/3.8.0.md
 - doc/retrieving_uploads.md
 - doc/securing_uploads.md
 - doc/storage/file_system.md