shrine 2.14.0 → 2.15.0

data/doc/validation.md

@@ -145,4 +145,4 @@ class ImageUploader < ApplicationUploader
 end
 ```
 
-[ImageProcessing]: https://github.com/janko-m/image_processing
+[ImageProcessing]: https://github.com/janko/image_processing

data/lib/shrine/plugins/_urlsafe_serialization.rb

@@ -2,116 +2,66 @@
 
 require "base64"
 require "json"
-require "openssl"
 
 class Shrine
   module Plugins
-    # The `urlsafe_serialization` plugin provides the ability to serialize and
-    # deserialize a `Shrine::UploadedFile` in a way that's suitable for
-    # including in a URL.
-    #
-    #     plugin :urlsafe_serialization
-    #
-    # The plugin defines `urlsafe_dump` and `urlsafe_load` methods on
-    # `Shrine::UploadedFile`. The file is first serialized to JSON, then
-    # encoded with base64.
-    #
-    #     serialized = uploaded_file.urlsafe_dump
-    #     # or
-    #     serialized = MyUploader::UploadedFile.urlsafe_dump(uploaded_file)
-    #     serialized #=> "eyJpZCI6IjlhZGM0NmIzZjI..."
-    #
-    #     # ...
-    #
-    #     uploaded_file = MyUploader::UploadedFile.urlsafe_load(serialized)
-    #     uploaded_file #=> #<MyUploader::UploadedFile>
-    #
-    # ## Metadata
-    #
-    # By default no metadata is included in the serialization:
-    #
-    #     uploaded_file.metadata #=> { ... metadata ... }
-    #
-    #     serialized    = MyUploader::UploadedFile.urlsafe_dump(uploaded_file)
-    #     uploaded_file = MyUploader::UploadedFile.urlsafe_load(serialized)
-    #
-    #     uploaded_file.metadata #=> {}
-    #
-    # The `:metadata` option can be used to specify metadata you want to
-    # serialize:
-    #
-    #     serialized    = MyUploader::UploadedFile.urlsafe_dump(uploaded_file, metadata: %w[size mime_type])
-    #     uploaded_file = MyUploader::UploadedFile.urlsafe_load(serialized)
-    #
-    #     uploaded_file.metadata #=> { "size" => 4394, "mime_type" => "image/jpeg" }
-    #
-    # ## Signing
-    #
-    # By default the seralization is done with simple JSON + base64 encoding.
-    # If you want to ensure the serialized data hasn't been tampred with, you
-    # can have it signed with a secret key.
-    #
-    #     plugin :urlsafe_serialization, secret_key: "my secret key"
-    #
-    # Now the `urlsafe_dump` will automatically sign serialized data with your
-    # secret key, and `urlsafe_load` will automatically verify it.
-    #
-    #     serialized = MyUploader::UploadedFile.urlsafe_dump(uploaded_file)
-    #     serialized #=> "<signature>--<json-base64-encoded-data>"
-    #
-    #     uploaded_file = MyUploader::UploadedFile.urlsafe_load(serialized) # verifies the signature
-    #     uploaded_file #=> #<MyUploader::UploadedFile>
-    #
-    # If the signature is missing or invalid,
-    # `Shrine::Plugins::UrlsafeSerialization::InvalidSignature` exception is
-    # raised.
     module UrlsafeSerialization
-      class InvalidSignature < Error; end
+      module ClassMethods
+        def urlsafe_serialize(hash)
+          urlsafe_serializer.encode(hash)
+        end
+
+        def urlsafe_deserialize(string)
+          urlsafe_serializer.decode(string)
+        end
 
-      def self.configure(uploader, opts = {})
-        uploader.opts[:urlsafe_serialization] ||= {}
-        uploader.opts[:urlsafe_serialization].merge!(opts)
+        def urlsafe_serializer
+          Serializer.new
+        end
       end
 
       module FileMethods
         def urlsafe_dump(**options)
           self.class.urlsafe_dump(self, **options)
         end
+
+        def urlsafe_data(metadata: [])
+          data = self.data.dup
+
+          if metadata.any?
+            # order metadata in the specified order
+            data["metadata"] = metadata
+              .map { |name| [name, self.metadata[name]] }
+              .to_h
+          else
+            # save precious characters
+            data.delete("metadata")
+          end
+
+          data
+        end
       end
 
       module FileClassMethods
-        def urlsafe_dump(file, metadata: [])
-          data = file.data.dup
-          data["metadata"] = metadata
-            .map { |name| [name, file.metadata[name]] }
-            .to_h
+        def urlsafe_dump(file, **options)
+          data = file.urlsafe_data(**options)
 
-          urlsafe_serializer.dump(data)
+          shrine_class.urlsafe_serialize(data)
         end
 
         def urlsafe_load(string)
-          data = urlsafe_serializer.load(string)
+          data = shrine_class.urlsafe_deserialize(string)
 
           new(data)
         end
-
-        def urlsafe_serializer
-          secret_key = shrine_class.opts[:urlsafe_serialization][:secret_key]
-
-          if secret_key
-            SecureSerializer.new(secret_key: secret_key)
-          else
-            Serializer.new
-          end
-        end
       end
 
       class Serializer
-        def dump(data)
+        def encode(data)
           base64_encode(json_encode(data))
         end
 
-        def load(data)
+        def decode(data)
           json_decode(base64_decode(data))
         end
 
@@ -133,48 +83,6 @@ class Shrine
           JSON.parse(data)
         end
       end
-
-      class SecureSerializer < Serializer
-        attr_reader :secret_key
-
-        def initialize(secret_key:)
-          @secret_key = secret_key
-        end
-
-        def dump(data)
-          hmac_encode(super)
-        end
-
-        def load(data)
-          super(hmac_decode(data))
-        end
-
-        def hmac_encode(data)
-          "#{generate_hmac(data)}--#{data}"
-        end
-
-        def hmac_decode(data)
-          data, hmac = data.split("--", 2).reverse
-          verify_hmac(hmac, data)
-          data
-        end
-
-        def verify_hmac(provided_hmac, data)
-          if provided_hmac.nil?
-            raise InvalidSignature, "signature is missing"
-          end
-
-          expected_hmac = generate_hmac(data)
-
-          if provided_hmac != expected_hmac
-            raise InvalidSignature, "provided signature doesn't match the expected"
-          end
-        end
-
-        def generate_hmac(data)
-          OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, secret_key, data)
-        end
-      end
     end
 
     register_plugin(:_urlsafe_serialization, UrlsafeSerialization)

data/lib/shrine/plugins/activerecord.rb

@@ -4,84 +4,6 @@ require "active_record"
 
 class Shrine
   module Plugins
-    # The `activerecord` plugin extends the "attachment" interface with support
-    # for ActiveRecord.
-    #
-    #     plugin :activerecord
-    #
-    # ## Callbacks
-    #
-    # Now the attachment module will add additional callbacks to the model:
-    #
-    # * "before save" -- Used by the `recache` plugin.
-    # * "after commit" (save) -- Promotes the attachment, deletes replaced ones.
-    # * "after commit" (destroy) -- Deletes the attachment.
-    #
-    # Note that ActiveRecord versions 3.x and 4.x have errors automatically
-    # silenced in hooks, which can make debugging more difficult, so it's
-    # recommended that you enable errors:
-    #
-    #     # This is the default in ActiveRecord 5
-    #     ActiveRecord::Base.raise_in_transactional_callbacks = true
-    #
-    # If you want to put promoting/deleting into a background job, see the
-    # `backgrounding` plugin.
-    #
-    # Since attaching first saves the record with a cached attachment, then
-    # saves again with a stored attachment, you can detect this in callbacks:
-    #
-    #     class User < ActiveRecord::Base
-    #       include ImageUploader::Attachment.new(:avatar)
-    #
-    #       before_save do
-    #         if avatar_data_changed? && avatar_attacher.cached?
-    #           # cached
-    #         elsif avatar_data_changed? && avatar_attacher.stored?
-    #           # promoted
-    #         end
-    #       end
-    #     end
-    #
-    # Note that ActiveRecord currently has a [bug with transaction callbacks],
-    # so if you have any "after commit" callbacks, make sure to include Shrine's
-    # attachment module *after* they have all been defined.
-    #
-    # If you don't want the attachment module to add any callbacks to the
-    # model, and would instead prefer to call these actions manually, you can
-    # disable callbacks:
-    #
-    #     plugin :activerecord, callbacks: false
-    #
-    # ## Validations
-    #
-    # Additionally, any Shrine validation errors will be added to
-    # ActiveRecord's errors upon validation. Note that Shrine validation
-    # messages don't have to be strings, they can also be symbols or symbols
-    # and options, which allows them to be internationalized together with
-    # other ActiveRecord validation messages.
-    #
-    #     class MyUploader < Shrine
-    #       plugin :validation_helpers
-    #
-    #       Attacher.validate do
-    #         validate_max_size 256 * 1024**2, message: ->(max) { [:max_size, max: max] }
-    #       end
-    #     end
-    #
-    # If you want to validate presence of the attachment, you can do it
-    # directly on the model.
-    #
-    #     class User < ActiveRecord::Base
-    #       include ImageUploader::Attachment.new(:avatar)
-    #       validates_presence_of :avatar
-    #     end
-    #
-    # If don't want the attachment module to merge file validations errors into
-    # model errors, you can disable it:
-    #
-    #     plugin :activerecord, validations: false
-    #
-    # [bug with transaction callbacks]: https://github.com/rails/rails/issues/14493
     module Activerecord
       def self.configure(uploader, opts = {})
         uploader.opts[:activerecord_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:activerecord_callbacks, true))

data/lib/shrine/plugins/add_metadata.rb

@@ -2,86 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `add_metadata` plugin provides a convenient method for extracting and
-    # adding custom metadata values.
-    #
-    #     plugin :add_metadata
-    #
-    #     add_metadata :exif do |io, context|
-    #       begin
-    #         Exif::Data.new(io).to_h
-    #       rescue Exif::NotReadable # not a valid image
-    #         {}
-    #       end
-    #     end
-    #
-    # The above will add "exif" to the metadata hash, and also create the
-    # `#exif` reader method on Shrine::UploadedFile.
-    #
-    #     image.metadata["exif"]
-    #     # or
-    #     image.exif
-    #
-    # You can also extract multiple metadata values at once, by using
-    # `add_metadata` without an argument and returning a hash of metadata.
-    #
-    #     add_metadata do |io, context|
-    #       begin
-    #         data = Exif::Data.new(io)
-    #       rescue Exif::NotReadable # not a valid image
-    #         next {}
-    #       end
-    #
-    #       { date_time:     data.date_time,
-    #         flash:         data.flash,
-    #         focal_length:  data.focal_length,
-    #         exposure_time: data.exposure_time }
-    #     end
-    #
-    # In this case Shrine won't automatically create reader methods for the
-    # extracted metadata on Shrine::UploadedFile, but you can create them via
-    # `#metadata_method`.
-    #
-    #     metadata_method :date_time, :flash
-    #
-    # The `io` might not always be a file object, so if you're using an
-    # analyzer which requires the source file to be on disk, you can use
-    # `Shrine.with_file` to ensure you have a file object.
-    #
-    #     add_metadata do |io, context|
-    #       movie = Shrine.with_file(io) { |file| FFMPEG::Movie.new(file.path) }
-    #
-    #       { "duration"   => movie.duration,
-    #         "bitrate"    => movie.bitrate,
-    #         "resolution" => movie.resolution,
-    #         "frame_rate" => movie.frame_rate }
-    #     end
-    #
-    # Any previously extracted metadata can be accessed via
-    # `context[:metadata]`:
-    #
-    #     add_metadata :foo do |io, context|
-    #       context[:metadata] #=>
-    #       # {
-    #       #   "size"      => 239823,
-    #       #   "filename"  => "nature.jpg",
-    #       #   "mime_type" => "image/jpeg"
-    #       # }
-    #
-    #       "foo"
-    #     end
-    #
-    #     add_metadata :bar do |io, context|
-    #       context[:metadata] #=>
-    #       # {
-    #       #   "size"      => 239823,
-    #       #   "filename"  => "nature.jpg",
-    #       #   "mime_type" => "image/jpeg",
-    #       #   "foo"       => "foo"
-    #       # }
-    #
-    #       "bar"
-    #     end
     module AddMetadata
       def self.configure(uploader)
         uploader.opts[:metadata] ||= []

data/lib/shrine/plugins/backgrounding.rb

@@ -2,140 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `backgrounding` plugin enables you to move promoting and deleting of
-    # files from record's lifecycle into background jobs. This is especially
-    # useful if you're doing processing and/or you're storing files on an
-    # external storage service.
-    #
-    # The plugin provides `Attacher.promote` and `Attacher.delete` methods,
-    # which allow you to hook up to promoting and deleting and spawn background
-    # jobs, by passing a block.
-    #
-    #     Shrine.plugin :backgrounding
-    #
-    #     # makes all uploaders use background jobs
-    #     Shrine::Attacher.promote { |data| PromoteJob.perform_async(data) }
-    #     Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
-    #
-    # If you don't want to apply backgrounding for all uploaders, you can
-    # declare the hooks only for specific uploaders (in this case it's still
-    # recommended to keep the plugin loaded globally).
-    #
-    #     class MyUploader < Shrine
-    #       # makes this uploader use background jobs
-    #       Attacher.promote { |data| PromoteJob.perform_async(data) }
-    #       Attacher.delete { |data| DeleteJob.perform_async(data) }
-    #     end
-    #
-    # The yielded `data` variable is a serializable hash containing all context
-    # needed for promotion/deletion. Now you just need to declare the job
-    # classes, and inside them call `Attacher.promote` or `Attacher.delete`,
-    # this time with the received data.
-    #
-    #     class PromoteJob
-    #       include Sidekiq::Worker
-    #       def perform(data)
-    #         Shrine::Attacher.promote(data)
-    #       end
-    #     end
-    #
-    #     class DeleteJob
-    #       include Sidekiq::Worker
-    #       def perform(data)
-    #         Shrine::Attacher.delete(data)
-    #       end
-    #     end
-    #
-    # This example used Sidekiq, but obviously you could just as well use
-    # any other backgrounding library. This setup will be applied globally for
-    # all uploaders.
-    #
-    # If you're generating versions, and you want to process some versions in
-    # the foreground before kicking off a background job, you can use the
-    # `recache` plugin.
-    #
-    # In your application you can use `Attacher#cached?` and `Attacher#stored?`
-    # to differentiate between your background job being in progress and
-    # having completed.
-    #
-    #     if user.avatar_attacher.cached? # background job is still in progress
-    #       # ...
-    #     elsif user.avatar_attacher.stored? # background job has finished
-    #       # ...
-    #     end
-    #
-    # ## `Attacher.promote` and `Attacher.delete`
-    #
-    # In background jobs, `Attacher.promote` and `Attacher.delete` will resolve
-    # all necessary objects, and do the promotion/deletion. If
-    # `Attacher.find_record` is defined (which comes with ORM plugins), model
-    # instances will be treated as database records, with the `#id` attribute
-    # assumed to represent the primary key. Then promotion will have the
-    # following behaviour:
-    #
-    # 1. retrieves the database record
-    #     * if record is not found, it finishes
-    #     * if record is found but attachment has changed, it finishes
-    # 2. uploads cached file to permanent storage
-    # 3. reloads the database record
-    #     * if record is not found, it deletes the promoted files and finishes
-    #     * if record is found but attachment has changed, it deletes the promoted files and finishes
-    # 4. updates the record with the promoted files
-    #
-    # Both `Attacher.promote` and `Attacher.delete` return a `Shrine::Attacher`
-    # instance (if the action hasn't aborted), so you can use it to perform
-    # additional tasks:
-    #
-    #     def perform(data)
-    #       attacher = Shrine::Attacher.promote(data)
-    #       attacher.record.update(published: true) if attacher && attacher.record.is_a?(Post)
-    #     end
-    #
-    # ### Plain models
-    #
-    # You can also do backgrounding with plain models which don't represent
-    # database records; the plugin will use that mode if `Attacher.find_record`
-    # is not defined. In that case promotion will have the following behaviour:
-    #
-    # 1. instantiates the model
-    # 2. uploads cached file to permanent storage
-    # 3. writes promoted files to the model instance
-    #
-    # You can then retrieve the promoted files via the attacher object that
-    # `Attacher.promote` returns, and do any additional tasks if you need to.
-    #
-    # ## `Attacher#_promote` and `Attacher#_delete`
-    #
-    # The plugin modifies `Attacher#_promote` and `Attacher#_delete` to call
-    # the registered blocks with serializable attacher data, and these methods
-    # are internally called by the attacher. `Attacher#promote` and
-    # `Attacher#delete!` remain synchronous.
-    #
-    #     # asynchronous (spawn background jobs)
-    #     attacher._promote
-    #     attacher._delete(attachment)
-    #
-    #     # synchronous
-    #     attacher.promote
-    #     attacher.delete!(attachment)
-    #
-    # ## `Attacher.dump` and `Attacher.load`
-    #
-    # The plugin adds `Attacher.dump` and `Attacher.load` methods for
-    # serializing attacher object and loading it back up. You can use them to
-    # spawn background jobs for custom tasks.
-    #
-    #     data = Shrine::Attacher.dump(attacher)
-    #     SomethingJob.perform_async(data)
-    #
-    #     # ...
-    #
-    #     class SomethingJob
-    #       def perform(data)
-    #         attacher = Shrine::Attacher.load(data)
-    #         # ...
-    #       end
-    #     end
     module Backgrounding
       module AttacherClassMethods
         # If block is passed in, stores it to be called on promotion. Otherwise