shrine 3.4.0 → 3.10.0

data/doc/testing.md

@@ -2,6 +2,9 @@
 title: Testing with Shrine
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 The goal of this guide is to provide some useful tips for testing file
 attachments implemented with Shrine in your application.
 
@@ -137,19 +140,26 @@ module TestData
   end
 end
 ```
-<!--DOCUSAURUS_CODE_TABS-->
-<!--FactoryBot-->
+
+<Tabs>
+<TabItem value="factory_bot" label="FactoryBot">
+
 ```rb
 factory :photo do
   image_data { TestData.image_data }
 end
 ```
-<!--Rails YAML fixtures-->
+
+</TabItem>
+<TabItem value="fixtures" label="Rails YAML fixtures">
+
 ```erb
 photo:
   image_data: <%= TestData.image_data %>
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+
+</TabItem>
+</Tabs>
 
 ## Unit tests
 
@@ -182,24 +192,33 @@ end
 In acceptance tests you're testing your app end-to-end, and you likely want to
 also test file attachments here. Here are examples for some common use cases:
 
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Capybara-->
+<Tabs>
+<TabItem value="capybara" label="Capybara">
+
 ```rb
 attach_file("#image-field", "test/files/image.jpg")
 ```
-<!--Rack::Test-->
+
+</TabItem>
+<TabItem value="rack-test" label="rack-test">
+
 ```rb
 post "/photos", photo: {
   image: Rack::Test::UploadedFile.new("test/files/image.jpg", "image/jpeg")
 }
 ```
-<!--Rack::TestApp-->
+
+</TabItem>
+</Tabs>
+
+If you want to test requests with cached attachment data, you can do so as
+follows:
+
 ```rb
-app.post "/photos", multipart: {
-  "photo[image]" => File.open("test/files/image.jpg")
-}
+cached_file = Shrine.upload(file, :cache)
+
+post "/photos", photo: { image: cached_file.to_json }
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Background jobs
 
@@ -207,21 +226,30 @@ If you're using background jobs with Shrine, you probably want to make them
 synchronous in tests. See your backgrounding library docs for how to make jobs
 synchronous.
 
-<!--DOCUSAURUS_CODE_TABS-->
-<!--ActiveJob-->
+<Tabs>
+<TabItem value="activejob" label="Active Job">
+
 ```rb
 ActiveJob::Base.queue_adapter = :inline
 ```
-<!--Sidekiq-->
+
+</TabItem>
+<TabItem value="sidekiq" label="Sidekiq">
+
 ```rb
 require "sidekiq/testing"
 Sidekiq::Testing.inline!
 ```
-<!--SuckerPunch-->
+
+</TabItem>
+<TabItem value="sucker_punch" label="SuckerPunch">
+
 ```rb
 require "sucker_punch/testing/inline"
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+
+</TabItem>
+</Tabs>
 
 ## Processing
 

data/doc/upgrading_to_3.md

@@ -7,9 +7,6 @@ This guide provides instructions for upgrading Shrine in your apps to version
 3.x. If you're looking for a full list of changes, see the **[3.0 release
 notes]**.
 
-If you would like assistance with the upgrade, I'm available for consultation,
-you can email me at <janko.marohnic@gmail.com>.
-
 ## Attacher
 
 The `Shrine::Attacher` class has been rewritten in Shrine 3.0, though much of
@@ -447,7 +444,7 @@ class PromoteJob
     attacher.create_derivatives # call derivatives processor
     attacher.atomic_promote
   rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-    # attachment has changed or record has beeen deleted, nothing to do
+    # attachment has changed or record has been deleted, nothing to do
   end
 end
 ```
@@ -649,7 +646,8 @@ attacher.copy(other_attacher)
 with
 
 ```rb
-attacher.set attacher.upload(other_attacher.file)
+attacher.set nil # clear original attachment
+attacher.attach other_attacher.file, storage: other_attacher.file.storage_key
 attacher.add_derivatives other_attacher.derivatives # if using derivatives
 ```
 

data/lib/shrine/attacher.rb

@@ -20,10 +20,10 @@ class Shrine
 
       # Initializes the attacher from a data hash generated from `Attacher#data`.
       #
-      #     attacher = Attacher.from_data({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+      #     attacher = Attacher.from_data({ "id" => "...", "storage" => "...", "metadata" => {} })
       #     attacher.file #=> #<Shrine::UploadedFile>
-      def from_data(data, **options)
-        attacher = new(**options)
+      def from_data(data, **)
+        attacher = new(**)
         attacher.load_data(data)
         attacher
       end
@@ -47,34 +47,34 @@ class Shrine
       end
 
       # Returns the temporary storage identifier.
-      def cache_key; @cache.to_sym; end
+      def cache_key = @cache.to_sym
       # Returns the permanent storage identifier.
-      def store_key; @store.to_sym; end
+      def store_key = @store.to_sym
 
       # Returns the uploader that is used for the temporary storage.
-      def cache; shrine_class.new(cache_key); end
+      def cache = shrine_class.new(cache_key)
       # Returns the uploader that is used for the permanent storage.
-      def store; shrine_class.new(store_key); end
+      def store = shrine_class.new(store_key)
 
       # Calls #attach_cached, but skips if value is an empty string (this is
       # useful when the uploaded file comes from form fields). Forwards any
       # additional options to #attach_cached.
       #
-      #     attacher.assign(File.open(...))
-      #     attacher.assign(File.open(...), metadata: { "foo" => "bar" })
+      #     attacher.assign(File.open(path))
+      #     attacher.assign(File.open(path), metadata: { "foo" => "bar" })
       #     attacher.assign('{"id":"...","storage":"cache","metadata":{...}}')
       #     attacher.assign({ "id" => "...", "storage" => "cache", "metadata" => {} })
       #
       #     # ignores the assignment when a blank string is given
       #     attacher.assign("")
-      def assign(value, **options)
+      def assign(value, **)
         return if value == "" # skip empty hidden field
 
         if value.is_a?(Hash) || value.is_a?(String)
           return if uploaded_file(value) == file # skip assignment for current file
         end
 
-        attach_cached(value, **options)
+        attach_cached(value, **)
       end
 
       # Sets an existing cached file, or uploads an IO object to temporary
@@ -82,21 +82,21 @@ class Shrine
       # #attach.
       #
       #     # upload file to temporary storage and set the uploaded file.
-      #     attacher.attach_cached(File.open(...))
+      #     attacher.attach_cached(File.open(path))
       #
       #     # foward additional options to the uploader
-      #     attacher.attach_cached(File.open(...), metadata: { "foo" => "bar" })
+      #     attacher.attach_cached(File.open(path), metadata: { "foo" => "bar" })
       #
       #     # sets an existing cached file from JSON data
       #     attacher.attach_cached('{"id":"...","storage":"cache","metadata":{...}}')
       #
       #     # sets an existing cached file from Hash data
       #     attacher.attach_cached({ "id" => "...", "storage" => "cache", "metadata" => {} })
-      def attach_cached(value, **options)
+      def attach_cached(value, **)
         if value.is_a?(String) || value.is_a?(Hash)
-          change(cached(value, **options))
+          change(cached(value, **))
         else
-          attach(value, storage: cache_key, action: :cache, **options)
+          attach(value, storage: cache_key, action: :cache, **)
         end
       end
 
@@ -113,8 +113,8 @@ class Shrine
       #
       #     # removes the attachment
       #     attacher.attach(nil)
-      def attach(io, storage: store_key, **options)
-        file = upload(io, storage, **options) if io
+      def attach(io, storage: store_key, **)
+        file = upload(io, storage, **) if io
 
         change(file)
       end
@@ -158,8 +158,8 @@ class Shrine
       #     attacher.cached? #=> true
       #     attacher.promote_cached
       #     attacher.stored? #=> true
-      def promote_cached(**options)
-        promote(**options) if promote?
+      def promote_cached(**)
+        promote(**) if promote?
       end
 
       # Uploads current file to permanent storage and sets the stored file.
@@ -167,8 +167,8 @@ class Shrine
       #     attacher.cached? #=> true
       #     attacher.promote
       #     attacher.stored? #=> true
-      def promote(storage: store_key, **options)
-        set upload(file, storage, action: :store, **options)
+      def promote(storage: store_key, **)
+        set upload(file, storage, action: :store, **)
       end
 
       # Delegates to `Shrine.upload`, passing the #context.
@@ -178,8 +178,8 @@ class Shrine
       #
       #     # pass additional options for the uploader
       #     attacher.upload(io, :store, metadata: { "foo" => "bar" })
-      def upload(io, storage = store_key, **options)
-        shrine_class.upload(io, storage, **context, **options)
+      def upload(io, storage = store_key, **)
+        shrine_class.upload(io, storage, **context, **)
       end
 
       # If a new file was attached, deletes previously attached file if any.
@@ -189,7 +189,7 @@ class Shrine
       #     attacher.destroy_previous
       #     previous_file.exists? #=> false
       def destroy_previous
-        @previous.destroy_attached if changed?
+        @previous.destroy_attached if changed? && destroy_previous?
       end
 
       # Destroys the attached file if it exists and is uploaded to permanent
@@ -249,8 +249,8 @@ class Shrine
       #
       #     attacher.file = nil
       #     attacher.url #=> nil
-      def url(**options)
-        file&.url(**options)
+      def url(**)
+        file&.url(**)
       end
 
       # Returns whether the attachment has changed.
@@ -299,7 +299,7 @@ class Shrine
       # Loads the uploaded file from data generated by `Attacher#data`.
       #
       #     attacher.file #=> nil
-      #     attacher.load_data({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+      #     attacher.load_data({ "id" => "...", "storage" => "...", "metadata" => {} })
       #     attacher.file #=> #<Shrine::UploadedFile>
       def load_data(data)
         @file = data && uploaded_file(data)
@@ -341,6 +341,13 @@ class Shrine
 
       private
 
+      # The copy constructor that's called on #dup and #clone
+      # We need to duplicate the context to prevent it from being shared
+      def initialize_copy(other)
+        super
+        @context = @context.dup
+      end
+
       # Converts a String or Hash value into an UploadedFile object and ensures
       # it's uploaded to temporary storage.
       #
@@ -349,7 +356,7 @@ class Shrine
       #     #=> #<Shrine::UploadedFile>
       #
       #     # from Hash data
-      #     attacher.cached({ "id" => "...", "storage" => "cache", "metadata" => { ... } })
+      #     attacher.cached({ "id" => "...", "storage" => "cache", "metadata" => {} })
       #     #=> #<Shrine::UploadedFile>
       def cached(value, **)
         uploaded_file = uploaded_file(value)
@@ -373,6 +380,11 @@ class Shrine
         attached? && !cached?
       end
 
+      # Whether the previous attached file should be deleted.
+      def destroy_previous?
+        true
+      end
+
       # Whether assigning the given file is considered a change.
       def change?(file)
         @file != file

data/lib/shrine/attachment.rb

@@ -22,8 +22,8 @@ class Shrine
       # Shorthand for `Attachment.new`.
       #
       #   Shrine::Attachment[:image]
-      def [](*args, **options)
-        new(*args, **options)
+      def [](*, **)
+        new(*, **)
       end
     end
 

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

@@ -23,8 +23,8 @@ class Shrine
       end
 
       module FileMethods
-        def urlsafe_dump(**options)
-          self.class.urlsafe_dump(self, **options)
+        def urlsafe_dump(**)
+          self.class.urlsafe_dump(self, **)
         end
 
         def urlsafe_data(metadata: [])
@@ -45,8 +45,8 @@ class Shrine
       end
 
       module FileClassMethods
-        def urlsafe_dump(file, **options)
-          data = file.urlsafe_data(**options)
+        def urlsafe_dump(file, **)
+          data = file.urlsafe_data(**)
 
           shrine_class.urlsafe_serialize(data)
         end

data/lib/shrine/plugins/activerecord.rb

@@ -12,7 +12,7 @@ class Shrine
       end
 
       def self.configure(uploader, **opts)
-        uploader.opts[:activerecord] ||= { callbacks: true, validations: true }
+        uploader.opts[:activerecord] ||= { callbacks: true, validations: true, attribute_types: false }
         uploader.opts[:activerecord].merge!(opts)
       end
 
@@ -108,12 +108,22 @@ class Shrine
           record.transaction { yield record.clone.reload(lock: true) }
         end
 
-        # Returns true if the data attribute represents a JSON or JSONB column.
+        # Returns true if the data attribute represents a JSON or JSONB type.
         # Used by the _persistence plugin to determine whether serialization
         # should be skipped.
+        #
+        # By default only real database columns are checked. When the
+        # `:attribute_types` plugin option is enabled, the check uses
+        # `type_for_attribute`, so attributes declared via the Attributes API
+        # are recognized as well.
         def activerecord_hash_attribute?
-          column = record.class.columns_hash[attribute.to_s]
-          column && [:json, :jsonb].include?(column.type)
+          if shrine_class.opts[:activerecord][:attribute_types]
+            attribute_type = record.class.type_for_attribute(attribute.to_s)
+            attribute_type && [:json, :jsonb].include?(attribute_type.type)
+          else
+            column = record.class.columns_hash[attribute.to_s]
+            column && [:json, :jsonb].include?(column.type)
+          end
         end
 
         # Returns whether the record is an ActiveRecord model. Used by the
@@ -121,6 +131,17 @@ class Shrine
         def activerecord?
           record.is_a?(::ActiveRecord::Base)
         end
+
+        # Prevents the previous file from being destroyed when this save
+        # created the record (as opposed to updating an existing one), since
+        # a record being created can't yet have its own confirmed attachment
+        # to safely replace (e.g. when it was duplicated via `#dup` from
+        # another, still-persisted record).
+        def destroy_previous?
+          return super unless activerecord?
+
+          super && !record.previously_new_record?
+        end
       end
     end
 

data/lib/shrine/plugins/add_metadata.rb

@@ -29,11 +29,9 @@ class Shrine
       end
 
       module InstanceMethods
-        def extract_metadata(io, **options)
+        def extract_metadata(io, **)
           metadata = super
-
-          extract_custom_metadata(io, **options, metadata: metadata)
-
+          extract_custom_metadata(io, **, metadata:)
           metadata
         end
 

data/lib/shrine/plugins/atomic_helpers.rb

@@ -14,14 +14,14 @@ class Shrine
         #
         #     Shrine::Attacher.retrieve(model: photo, name: :image, file: file_data)
         #     #=> #<ImageUploader::Attacher>
-        def retrieve(model: nil, entity: nil, name:, file:, **options)
+        def retrieve(model: nil, entity: nil, name:, file:, **)
           fail ArgumentError, "either :model or :entity is required" unless model || entity
 
           record = model || entity
 
-          attacher   = record.send(:"#{name}_attacher", **options) if record.respond_to?(:"#{name}_attacher")
-          attacher ||= from_model(record, name, **options) if model
-          attacher ||= from_entity(record, name, **options) if entity
+          attacher   = record.send(:"#{name}_attacher", **) if record.respond_to?(:"#{name}_attacher")
+          attacher ||= from_model(record, name, **) if model
+          attacher ||= from_entity(record, name, **) if entity
 
           if attacher.file != attacher.uploaded_file(file)
             fail Shrine::AttachmentChanged, "attachment has changed"
@@ -43,13 +43,13 @@ class Shrine
         #
         # This more convenient to use with concrete persistence plugins, which
         # provide defaults for reloading and persistence.
-        def abstract_atomic_promote(reload:, persist:, **options, &block)
+        def abstract_atomic_promote(reload:, persist:, **, &block)
           original_file = file
 
-          result = promote(**options)
+          result = promote(**)
 
           begin
-            abstract_atomic_persist(original_file, reload: reload, persist: persist, &block)
+            abstract_atomic_persist(original_file, reload:, persist:, &block)
             result
           rescue Shrine::AttachmentChanged
             destroy_attached

data/lib/shrine/plugins/backgrounding.rb

@@ -47,7 +47,7 @@ class Shrine
         #     attacher.promote_block do |attacher|
         #       Attachment::PromoteJob.perform_async(
         #         attacher.record,
-        #         attacher.name
+        #         attacher.name,
         #         attacher.file_data,
         #       )
         #     end
@@ -67,19 +67,19 @@ class Shrine
         end
 
         # Does a background promote if promote block was registered.
-        def promote_cached(**options)
+        def promote_cached(**)
           if promote? && promote_block
-            promote_background
+            promote_background(**)
           else
             super
           end
         end
 
         # Calls the registered promote block.
-        def promote_background(**options)
+        def promote_background(**)
           fail Error, "promote block is not registered" unless promote_block
 
-          background_block(promote_block, **options)
+          background_block(promote_block, **)
         end
 
         # Does a background destroy if destroy block was registered.
@@ -92,19 +92,19 @@ class Shrine
         end
 
         # Calls the registered destroy block.
-        def destroy_background(**options)
+        def destroy_background(**)
           fail Error, "destroy block is not registered" unless destroy_block
 
-          background_block(destroy_block, **options)
+          background_block(destroy_block, **)
         end
 
         private
 
-        def background_block(block, **options)
+        def background_block(block, **)
           if block.arity == 1
-            block.call(self, **options)
+            block.call(self, **)
           else
-            instance_exec(**options, &block)
+            instance_exec(**, &block)
           end
         end
       end

data/lib/shrine/plugins/column.rb

@@ -16,8 +16,8 @@ class Shrine
         # from a database record column.
         #
         #     Attacher.from_column('{"id":"...","storage":"...","metadata":{...}}')
-        def from_column(data, **options)
-          attacher = new(**options)
+        def from_column(data, **)
+          attacher = new(**)
           attacher.load_column(data)
           attacher
         end
@@ -28,8 +28,8 @@ class Shrine
         attr_reader :column_serializer
 
         # Allows overriding the default column serializer.
-        def initialize(column_serializer: shrine_class.opts[:column][:serializer], **options)
-          super(**options)
+        def initialize(column_serializer: shrine_class.opts[:column][:serializer], **)
+          super(**)
           @column_serializer = column_serializer
         end
 
@@ -54,7 +54,7 @@ class Shrine
         # Converts the column data hash into a string (generates JSON by
         # default).
         #
-        #     Attacher.serialize_column({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+        #     Attacher.serialize_column({ "id" => "...", "storage" => "...", "metadata" => {} })
         #     #=> '{"id":"...","storage":"...","metadata":{...}}'
         #
         #     Attacher.serialize_column(nil)
@@ -75,6 +75,8 @@ class Shrine
         #     Attacher.deserialize_column(nil)
         #     #=> nil
         def deserialize_column(data)
+          return nil if data == ""
+
           if column_serializer && data && !data.is_a?(Hash)
             column_serializer.load(data)
           else

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) – #{{
@@ -24,7 +25,7 @@ class Shrine
         }.inspect}"
       end
 
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :validation
       end
 
@@ -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/default_url.rb

@@ -16,16 +16,16 @@ class Shrine
       end
 
       module AttacherMethods
-        def url(**options)
-          super || default_url(**options)
+        def url(**)
+          super || default_url(**)
         end
 
         private
 
-        def default_url(**options)
+        def default_url(**)
           return unless default_url_block
 
-          url = instance_exec(**options, &default_url_block)
+          url = instance_exec(**, &default_url_block)
 
           [*default_url_host, url].join
         end