shrine 3.0.0 → 3.2.2

data/doc/testing.md

@@ -119,7 +119,7 @@ module TestData
       small:  uploaded_image,
     )
 
-    attacher.column_data
+    attacher.column_data # or attacher.data in case of postgres jsonb column
   end
 
   def uploaded_image
@@ -128,7 +128,7 @@ module TestData
     # for performance we skip metadata extraction and assign test metadata
     uploaded_file = Shrine.upload(file, :store, metadata: false)
     uploaded_file.metadata.merge!(
-      "size"      => file.size,
+      "size"      => File.size(file.path),
       "mime_type" => "image/jpeg",
       "filename"  => "test.jpg",
     )

data/doc/upgrading_to_3.md

@@ -4,7 +4,11 @@ title: Upgrading to Shrine 3.x
 ---
 
 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].
+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
 
@@ -72,6 +76,20 @@ attacher.reload
 attacher.file #=> #<Shrine::UploadedFile ...>
 ```
 
+### Assigning
+
+The `Attacher#assign` method now raises an exception when non-cached uploaded
+file data is assigned:
+
+```rb
+# Shrine 2.x
+attacher.assign('{"id": "...", "storage": "store", "metadata": {...}}') # ignored
+
+# Shrine 3.0
+attacher.assign('{"id": "...", "storage": "store", "metadata": {...}}')
+#~> Shrine::Error: expected cached file, got #<Shrine::UploadedFile storage=:store ...>
+```
+
 ### Validation
 
 The validation functionality has been extracted into the `validation` plugin.
@@ -265,8 +283,9 @@ attacher.destroy_background # calls destroy block
 ## Versions
 
 The `versions`, `processing`, `recache`, and `delete_raw` plugins have been
-deprecated in favour of the new [`derivatives`][derivatives] plugin. Let's
-assume you have the following `versions` code:
+deprecated in favour of the new **[`derivatives`][derivatives]** plugin.
+
+Let's assume you have the following `versions` configuration:
 
 ```rb
 class ImageUploader < Shrine
@@ -289,18 +308,23 @@ class ImageUploader < Shrine
   end
 end
 ```
+
+When an attached file is promoted to permanent storage, the versions would
+automatically get generated:
+
 ```rb
 photo = Photo.new(photo_params)
 
 if photo.valid?
-  photo.save # automatically calls processing block
+  photo.save # generates versions on promotion
   # ...
 else
   # ...
 end
 ```
 
-With `derivatives` it becomes this:
+With `derivatives`, the original file is automatically downloaded and retained,
+so the processing code is much simpler:
 
 ```rb
 Shrine.plugin :derivatives, versions_compatibility: true # handle versions column format
@@ -310,6 +334,7 @@ class ImageUploader < Shrine
   Attacher.derivatives_processor do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
+    # the :original file should NOT be included anymore
     {
       large:  magick.resize_to_limit!(800, 800),
       medium: magick.resize_to_limit!(500, 500),
@@ -318,22 +343,25 @@ class ImageUploader < Shrine
   end
 end
 ```
+
+However, you now need to trigger processing manually during attachment:
+
 ```rb
 photo = Photo.new(photo_params)
 
 if photo.valid?
   photo.image_derivatives! if photo.image_changed? # create derivatives
-  photo.save # automatically calls processing block
+  photo.save
   # ...
 else
   # ...
 end
 ```
 
-If you have multiple places where you need to generate derivatives, and want it
-to happen automatically like it did with the `versions` plugin, you can
-override `Attacher#promote` to call `Attacher#create_derivatives` before
-promotion:
+### Automatic processing
+
+If you prefer processing to happen automatically with promotion (like it did
+with the `versions` plugin), you can put the following in your initializer:
 
 ```rb
 class Shrine::Attacher
@@ -352,7 +380,7 @@ The derivative URLs are accessed in the same way as versions:
 photo.image_url(:small)
 ```
 
-But the derivatives themselves are accessed differently:
+But the files themselves are accessed differently:
 
 ```rb
 # versions
@@ -406,8 +434,8 @@ database column in different formats:
 
 The `:versions_compatibility` flag to the `derivatives` plugin enables it to
 read the `versions` format, which aids in transition. Once the `derivatives`
-plugin has been deployed to production, you can switch existing records to the
-new column format:
+plugin has been deployed to production, you can update existing records with
+the new column format:
 
 ```rb
 Photo.find_each do |photo|
@@ -468,48 +496,77 @@ else
 end
 ```
 
-#### Parallelize
+### Default URL
 
-The `parallelize` plugin has been removed. The `derivatives` plugin is
-thread-safe, so you can parallelize uploading processed files manually:
+If you were using the `default_url` plugin, the `Attacher.default_url` now
+receives a `:derivative` option:
 
 ```rb
-# Gemfile
-gem "concurrent-ruby"
+Attacher.default_url do |derivative: nil, **|
+  "https://my-app.com/fallbacks/#{derivative}.jpg" if derivative
+end
 ```
-```rb
-require "concurrent"
 
-derivatives = attacher.process_derivatives
+#### Fallback to original
 
-tasks = derivatives.map do |name, file|
-  Concurrent::Promises.future(name, file) do |name, file|
-    attacher.add_derivative(name, file)
-  end
-end
+With the `versions` plugin, a missing version URL would automatically fall back
+to the original file. The `derivatives` plugin has no such fallback, but you
+can configure it manually:
 
-Concurrent::Promises.zip(*tasks).wait!
+```rb
+Attacher.default_url do |derivative: nil, **|
+  file&.url if derivative
+end
 ```
 
-#### Default URL
+#### Fallback to version
 
-The `derivatives` plugin integrates with the `default_url` plugin:
+The `versions` plugin had the ability to fall back missing version URL to
+another version that already exists. The `derivatives` plugin doesn't have this
+built in, but you can implement it as follows:
 
 ```rb
+DERIVATIVE_FALLBACKS = { foo: :bar, ... }
+
 Attacher.default_url do |derivative: nil, **|
-  "https://my-app.com/fallbacks/#{derivative}.jpg" if derivative
+  derivatives[DERIVATIVE_FALLBACKS[derivative]]&.url if derivative
 end
 ```
 
-However, it doesn't implement any other URL fallbacks that the `versions`
-plugin has for missing derivatives.
+### Location
+
+The `Shrine#generate_location` method will now receive a `:derivative`
+parameter instead of `:version`:
+
+```rb
+class MyUploader < Shrine
+  def generate_location(io, derivative: nil, **)
+    derivative #=> :large, :medium, :small, ...
+    # ...
+  end
+end
+```
+
+### Overwriting original
+
+With the `derivatives` plugin, saving processed files separately from the
+original file, so the original file is automatically kept. This means it's not
+possible anymore to overwrite the original file as part of processing.
+
+However, **it's highly recommended to always keep the original file**, even if
+you don't plan to use it. That way, if there is ever a need to reprocess
+derivatives, you have the original file to use as a base.
+
+That being said, if you still want to overwrite the original file, [this
+thread][overwriting original] has some tips.
 
 ## Other
 
 ### Processing
 
 The `processing` plugin has been deprecated over the new
-[`derivatives`][derivatives] plugin. If you were modifying the original file:
+[`derivatives`][derivatives] plugin. If you were previously replacing the
+original file:
 
 ```rb
 class MyUploader < Shrine
@@ -537,6 +594,30 @@ class MyUploader < Shrine
 end
 ```
 
+### Parallelize
+
+The `parallelize` plugin has been removed. With `derivatives` plugin you can
+parallelize uploading processed files manually:
+
+```rb
+# Gemfile
+gem "concurrent-ruby"
+```
+```rb
+require "concurrent"
+
+attacher    = photo.image_attacher
+derivatives = attacher.process_derivatives
+
+tasks = derivatives.map do |name, file|
+  Concurrent::Promises.future(name, file) do |name, file|
+    attacher.add_derivative(name, file)
+  end
+end
+
+Concurrent::Promises.zip(*tasks).wait!
+```
+
 ### Logging
 
 The `logging` plugin has been removed in favour of the
@@ -642,3 +723,4 @@ end
 [derivatives]: https://shrinerb.com/docs/plugins/derivatives
 [instrumentation]: https://shrinerb.com/docs/plugins/instrumentation
 [mirroring]: https://shrinerb.com/docs/plugins/mirroring
+[overwriting original]: https://discourse.shrinerb.com/t/keep-original-file-after-processing/50/4

data/doc/validation.md

@@ -88,10 +88,11 @@ when defining more validations:
 class ApplicationUploader < Shrine
   Attacher.validate { validate_max_size 5*1024*1024 }
 end
-
+```
+```rb
 class ImageUploader < ApplicationUploader
   Attacher.validate do
-    super() # empty braces are required
+    super() # empty parentheses are required
     validate_mime_type %w[image/jpeg image/png image/webp]
   end
 end

data/lib/shrine.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require "shrine/version"
 require "shrine/uploaded_file"
 require "shrine/attacher"
 require "shrine/attachment"
 require "shrine/plugins"
+require "shrine/version"
 
 require "securerandom"
 require "json"
 require "tempfile"
 require "logger"
 
-# Core class that represents uploader.
-# Base implementation is defined in InstanceMethods and ClassMethods.
+# Core class that handles uploading files to specified storage.
 class Shrine
   # A generic exception used by Shrine.
-  class Error < StandardError; end
+  class Error < StandardError
+  end
 
   # Raised when a file is not a valid IO.
   class InvalidFile < Error
@@ -68,9 +68,9 @@ class Shrine
     #
     #     Shrine.plugin MyPlugin
     #     Shrine.plugin :my_plugin
-    def plugin(plugin, *args, &block)
+    def plugin(plugin, *args, **kwargs, &block)
       plugin = Plugins.load_plugin(plugin) if plugin.is_a?(Symbol)
-      plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
+      Plugins.load_dependencies(plugin, self, *args, **kwargs, &block)
       self.include(plugin::InstanceMethods) if defined?(plugin::InstanceMethods)
       self.extend(plugin::ClassMethods) if defined?(plugin::ClassMethods)
       self::UploadedFile.include(plugin::FileMethods) if defined?(plugin::FileMethods)
@@ -79,7 +79,7 @@ class Shrine
       self::Attachment.extend(plugin::AttachmentClassMethods) if defined?(plugin::AttachmentClassMethods)
       self::Attacher.include(plugin::AttacherMethods) if defined?(plugin::AttacherMethods)
       self::Attacher.extend(plugin::AttacherClassMethods) if defined?(plugin::AttacherClassMethods)
-      plugin.configure(self, *args, &block) if plugin.respond_to?(:configure)
+      Plugins.configure(plugin, self, *args, **kwargs, &block)
       plugin
     end
 
@@ -297,7 +297,7 @@ class Shrine
     # Retrieves the location for the given IO and context. First it looks
     # for the `:location` option, otherwise it calls #generate_location.
     def get_location(io, location: nil, **options)
-      location ||= generate_location(io, options)
+      location ||= generate_location(io, **options)
       location or fail Error, "location generated for #{io.inspect} was nil"
     end
 

data/lib/shrine/attacher.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 class Shrine
-  # Core class which handles attaching files to model instances.
-  # Base implementation is defined in InstanceMethods and ClassMethods.
+  # Core class that handles attaching files. It uses Shrine and
+  # Shrine::UploadedFile objects internally.
   class Attacher
     @shrine_class = ::Shrine
 
@@ -39,16 +39,17 @@ class Shrine
 
       # Initializes the attached file, temporary and permanent storage.
       def initialize(file: nil, cache: :cache, store: :store)
-        @file    = file
-        @cache   = cache
-        @store   = store
-        @context = {}
+        @file     = file
+        @cache    = cache
+        @store    = store
+        @context  = {}
+        @previous = nil
       end
 
       # Returns the temporary storage identifier.
-      def cache_key; @cache; end
+      def cache_key; @cache.to_sym; end
       # Returns the permanent storage identifier.
-      def store_key; @store; end
+      def store_key; @store.to_sym; end
 
       # Returns the uploader that is used for the temporary storage.
       def cache; shrine_class.new(cache_key); end
@@ -69,6 +70,10 @@ class Shrine
       def assign(value, **options)
         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)
       end
 
@@ -89,7 +94,7 @@ class Shrine
       #     attacher.attach_cached({ "id" => "...", "storage" => "cache", "metadata" => {} })
       def attach_cached(value, **options)
         if value.is_a?(String) || value.is_a?(Hash)
-          change(cached(value, **options), **options)
+          change(cached(value, **options))
         else
           attach(value, storage: cache_key, action: :cache, **options)
         end
@@ -111,7 +116,7 @@ class Shrine
       def attach(io, storage: store_key, **options)
         file = upload(io, storage, **options) if io
 
-        change(file, **options)
+        change(file)
       end
 
       # Deletes any previous file and promotes newly attached cached file.
@@ -138,7 +143,7 @@ class Shrine
       def finalize
         destroy_previous
         promote_cached
-        remove_instance_variable(:@previous) if changed?
+        @previous = nil
       end
 
       # Plugins can override this if they want something to be done in a
@@ -211,7 +216,7 @@ class Shrine
       #     attacher.change(uploaded_file)
       #     attacher.file #=> #<Shrine::UploadedFile>
       #     attacher.changed? #=> true
-      def change(file, **)
+      def change(file)
         @previous = dup unless @file == file
         set(file)
       end
@@ -254,7 +259,7 @@ class Shrine
       #     attacher.attach(file)
       #     attacher.changed? #=> true
       def changed?
-        instance_variable_defined?(:@previous)
+        !!@previous
       end
 
       # Returns whether a file is attached.
@@ -352,7 +357,7 @@ class Shrine
         # reject files not uploaded to temporary storage, because otherwise
         # attackers could hijack other users' attachments
         unless cached?(uploaded_file)
-          fail Shrine::Error, "expected cached file, got #{value.inspect}"
+          fail Shrine::Error, "expected cached file, got #{uploaded_file.inspect}"
         end
 
         uploaded_file

data/lib/shrine/attachment.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 class Shrine
-  # Core class which creates attachment modules for specified attribute names
-  # that are included into model classes.
-  # Base implementation is defined in InstanceMethods and ClassMethods.
+  # Core class that provides an attachment interface for a specified attribute
+  # name, which can be added to model/entity classes. The model/entity plugins
+  # define the main interface, which delegates to a Shrine::Attacher object.
   class Attachment < Module
     @shrine_class = ::Shrine
 
@@ -22,8 +22,8 @@ class Shrine
       # Shorthand for `Attachment.new`.
       #
       #   Shrine::Attachment[:image]
-      def [](*args)
-        new(*args)
+      def [](*args, **options)
+        new(*args, **options)
       end
     end