shrine 2.13.0 → 2.14.0

data/lib/shrine/attacher.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+class Shrine
+  # Core class which handles attaching files to model instances.
+  # Base implementation is defined in InstanceMethods and ClassMethods.
+  class Attacher
+    @shrine_class = ::Shrine
+
+    module ClassMethods
+      # Returns the Shrine class that this attacher class is namespaced
+      # under.
+      attr_accessor :shrine_class
+
+      # Since Attacher is anonymously subclassed when Shrine is subclassed,
+      # and then assigned to a constant of the Shrine subclass, make inspect
+      # reflect the likely name for the class.
+      def inspect
+        "#{shrine_class.inspect}::Attacher"
+      end
+
+      # Block that is executed in context of Shrine::Attacher during
+      # validation. Example:
+      #
+      #     Shrine::Attacher.validate do
+      #       if get.size > 5*1024*1024
+      #         errors << "is too big (max is 5 MB)"
+      #       end
+      #     end
+      def validate(&block)
+        define_method(:validate_block, &block)
+        private :validate_block
+      end
+    end
+
+    module InstanceMethods
+      # Returns the uploader that is used for the temporary storage.
+      attr_reader :cache
+
+      # Returns the uploader that is used for the permanent storage.
+      attr_reader :store
+
+      # Returns the context that will be sent to the uploader when uploading
+      # and deleting. Can be modified with additional data to be sent to the
+      # uploader.
+      attr_reader :context
+
+      # Returns an array of validation errors created on file assignment in
+      # the `Attacher.validate` block.
+      attr_reader :errors
+
+      # Initializes the necessary attributes.
+      def initialize(record, name, cache: :cache, store: :store)
+        @cache   = shrine_class.new(cache)
+        @store   = shrine_class.new(store)
+        @context = {record: record, name: name}
+        @errors  = []
+      end
+
+      # Returns the model instance associated with the attacher.
+      def record; context[:record]; end
+
+      # Returns the attachment name associated with the attacher.
+      def name;   context[:name];   end
+
+      # Receives the attachment value from the form. It can receive an
+      # already cached file as a JSON string, otherwise it assumes that it's
+      # an IO object and uploads it to the temporary storage. The cached file
+      # is then written to the attachment attribute in the JSON format.
+      def assign(value, **options)
+        if value.is_a?(String)
+          return if value == "" || !cached?(uploaded_file(value))
+          assign_cached(uploaded_file(value))
+        else
+          uploaded_file = cache!(value, action: :cache, **options) if value
+          set(uploaded_file)
+        end
+      end
+
+      # Accepts a Shrine::UploadedFile object and writes it to the attachment
+      # attribute. It then runs file validations, and records that the
+      # attachment has changed.
+      def set(uploaded_file)
+        file = get
+        @old = file unless uploaded_file == file
+        _set(uploaded_file)
+        validate
+      end
+
+      # Runs the validations defined by `Attacher.validate`.
+      def validate
+        errors.clear
+        validate_block if get
+      end
+
+      # Returns true if a new file has been attached.
+      def changed?
+        instance_variable_defined?(:@old)
+      end
+      alias attached? changed?
+
+      # Plugins can override this if they want something to be done before
+      # save.
+      def save
+      end
+
+      # Deletes the old file and promotes the new one. Typically this should
+      # be called after saving the model instance.
+      def finalize
+        return if !instance_variable_defined?(:@old)
+        replace
+        remove_instance_variable(:@old)
+        _promote(action: :store) if cached?
+      end
+
+      # Delegates to #promote, overriden for backgrounding.
+      def _promote(uploaded_file = get, **options)
+        promote(uploaded_file, **options)
+      end
+
+      # Uploads the cached file to store, and writes the stored file to the
+      # attachment attribute.
+      def promote(uploaded_file = get, **options)
+        stored_file = store!(uploaded_file, **options)
+        result = swap(stored_file) or _delete(stored_file, action: :abort)
+        result
+      end
+
+      # Calls #update, overriden in ORM plugins, and returns true if the
+      # attachment was successfully updated.
+      def swap(uploaded_file)
+        update(uploaded_file)
+        uploaded_file if uploaded_file == get
+      end
+
+      # Deletes the previous attachment that was replaced, typically called
+      # after the model instance is saved with the new attachment.
+      def replace
+        _delete(@old, action: :replace) if @old && !cached?(@old)
+      end
+
+      # Deletes the current attachment, typically called after destroying the
+      # record.
+      def destroy
+        file = get
+        _delete(file, action: :destroy) if file && !cached?(file)
+      end
+
+      # Delegates to #delete!, overriden for backgrounding.
+      def _delete(uploaded_file, **options)
+        delete!(uploaded_file, **options)
+      end
+
+      # Returns the URL to the attached file if it's present. It forwards any
+      # given URL options to the storage.
+      def url(**options)
+        get.url(**options) if read
+      end
+
+      # Returns true if attachment is present and cached.
+      def cached?(file = get)
+        file && cache.uploaded?(file)
+      end
+
+      # Returns true if attachment is present and stored.
+      def stored?(file = get)
+        file && store.uploaded?(file)
+      end
+
+      # Returns a Shrine::UploadedFile instantiated from the data written to
+      # the attachment attribute.
+      def get
+        uploaded_file(read) if read
+      end
+
+      # Reads from the `<attachment>_data` attribute on the model instance.
+      # It returns nil if the value is blank.
+      def read
+        value = record.send(data_attribute)
+        convert_after_read(value) unless value.nil? || value.empty?
+      end
+
+      # Uploads the file using the #cache uploader, passing the #context.
+      def cache!(io, **options)
+        Shrine.deprecation("Sending :phase to Attacher#cache! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
+        cache.upload(io, context.merge(_equalize_phase_and_action(options)))
+      end
+
+      # Uploads the file using the #store uploader, passing the #context.
+      def store!(io, **options)
+        Shrine.deprecation("Sending :phase to Attacher#store! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
+        store.upload(io, context.merge(_equalize_phase_and_action(options)))
+      end
+
+      # Deletes the file using the uploader, passing the #context.
+      def delete!(uploaded_file, **options)
+        Shrine.deprecation("Sending :phase to Attacher#delete! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
+        store.delete(uploaded_file, context.merge(_equalize_phase_and_action(options)))
+      end
+
+      # Enhances `Shrine.uploaded_file` with the ability to recognize uploaded
+      # files as JSON strings.
+      def uploaded_file(object, &block)
+        shrine_class.uploaded_file(object, &block)
+      end
+
+      # The name of the attribute on the model instance that is used to store
+      # the attachment data. Defaults to `<attachment>_data`.
+      def data_attribute
+        :"#{name}_data"
+      end
+
+      # Returns the Shrine class that this attacher's class is namespaced
+      # under.
+      def shrine_class
+        self.class.shrine_class
+      end
+
+      private
+
+      # Assigns a cached file.
+      def assign_cached(cached_file)
+        set(cached_file)
+      end
+
+      # Writes the uploaded file to the attachment attribute. Overriden in ORM
+      # plugins to additionally save the model instance.
+      def update(uploaded_file)
+        _set(uploaded_file)
+      end
+
+      # Performs validation actually.
+      # This method is redefined with `Attacher.validate`.
+      def validate_block
+      end
+
+      # Converts the UploadedFile to a data hash and writes it to the
+      # attribute.
+      def _set(uploaded_file)
+        data = convert_to_data(uploaded_file) if uploaded_file
+        write(data ? convert_before_write(data) : nil)
+      end
+
+      # Writes to the `<attachment>_data` attribute on the model instance.
+      def write(value)
+        record.send(:"#{data_attribute}=", value)
+      end
+
+      # Returns the data hash of the given UploadedFile.
+      def convert_to_data(uploaded_file)
+        uploaded_file.data
+      end
+
+      # Returns the hash value dumped to JSON.
+      def convert_before_write(value)
+        value.to_json
+      end
+
+      # Returns the read value unchanged.
+      def convert_after_read(value)
+        value
+      end
+
+      # Temporary method used for transitioning from :phase to :action.
+      def _equalize_phase_and_action(options)
+        options[:phase]  = options[:action] if options.key?(:action)
+        options[:action] = options[:phase] if options.key?(:phase)
+        options
+      end
+    end
+  end
+end

data/lib/shrine/attachment.rb

@@ -0,0 +1,97 @@
+# 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.
+  class Attachment < Module
+    @shrine_class = ::Shrine
+
+    module ClassMethods
+      # Returns the Shrine class that this attachment class is
+      # namespaced under.
+      attr_accessor :shrine_class
+
+      # Since Attachment is anonymously subclassed when Shrine is subclassed,
+      # and then assigned to a constant of the Shrine subclass, make inspect
+      # reflect the likely name for the class.
+      def inspect
+        "#{shrine_class.inspect}::Attachment"
+      end
+    end
+
+    module InstanceMethods
+      # Instantiates an attachment module for a given attribute name, which
+      # can then be included to a model class. Second argument will be passed
+      # to an attacher module.
+      def initialize(name, **options)
+        @name    = name.to_sym
+        @options = options
+
+        define_attachment_methods!
+      end
+
+      # Defines attachment methods for the specified attachment name. These
+      # methods will be added to any model that includes this module.
+      def define_attachment_methods!
+        attachment = self
+        name = attachment_name
+
+        define_method :"#{name}_attacher" do |**options|
+          if !instance_variable_get(:"@#{name}_attacher") || options.any?
+            instance_variable_set(:"@#{name}_attacher", attachment.build_attacher(self, options))
+          else
+            instance_variable_get(:"@#{name}_attacher")
+          end
+        end
+
+        define_method :"#{name}=" do |value|
+          send(:"#{name}_attacher").assign(value)
+        end
+
+        define_method :"#{name}" do
+          send(:"#{name}_attacher").get
+        end
+
+        define_method :"#{name}_url" do |*args|
+          send(:"#{name}_attacher").url(*args)
+        end
+      end
+
+      # Creates an instance of the corresponding Attacher subclass.
+      def build_attacher(object, options)
+        shrine_class::Attacher.new(object, @name, @options.merge(options))
+      end
+
+      # Returns name of the attachment this module provides.
+      def attachment_name
+        @name
+      end
+
+      # Returns options that are to be passed to the Attacher.
+      def options
+        @options
+      end
+
+      # Returns class name with attachment name included.
+      #
+      #     Shrine[:image].to_s #=> "#<Shrine::Attachment(image)>"
+      def to_s
+        "#<#{self.class.inspect}(#{attachment_name})>"
+      end
+
+      # Returns class name with attachment name included.
+      #
+      #     Shrine[:image].inspect #=> "#<Shrine::Attachment(image)>"
+      def inspect
+        "#<#{self.class.inspect}(#{attachment_name})>"
+      end
+
+      # Returns the Shrine class that this attachment's class is namespaced
+      # under.
+      def shrine_class
+        self.class.shrine_class
+      end
+    end
+  end
+end

data/lib/shrine/plugins.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Shrine
+  # Module in which all Shrine plugins should be stored. Also contains logic
+  # for registering and loading plugins.
+  module Plugins
+    @plugins = {}
+
+    # If the registered plugin already exists, use it. Otherwise, require it
+    # and return it. This raises a LoadError if such a plugin doesn't exist,
+    # or a Shrine::Error if it exists but it does not register itself
+    # correctly.
+    def self.load_plugin(name)
+      unless plugin = @plugins[name]
+        require "shrine/plugins/#{name}"
+        raise Error, "plugin #{name} did not register itself correctly in Shrine::Plugins" unless plugin = @plugins[name]
+      end
+      plugin
+    end
+
+    # Register the given plugin with Shrine, so that it can be loaded using
+    # `Shrine.plugin` with a symbol. Should be used by plugin files. Example:
+    #
+    #     Shrine::Plugins.register_plugin(:plugin_name, PluginModule)
+    def self.register_plugin(name, mod)
+      @plugins[name] = mod
+    end
+  end
+end

data/lib/shrine/plugins/_urlsafe_serialization.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+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
+
+      def self.configure(uploader, opts = {})
+        uploader.opts[:urlsafe_serialization] ||= {}
+        uploader.opts[:urlsafe_serialization].merge!(opts)
+      end
+
+      module FileMethods
+        def urlsafe_dump(**options)
+          self.class.urlsafe_dump(self, **options)
+        end
+      end
+
+      module FileClassMethods
+        def urlsafe_dump(file, metadata: [])
+          data = file.data.dup
+          data["metadata"] = metadata
+            .map { |name| [name, file.metadata[name]] }
+            .to_h
+
+          urlsafe_serializer.dump(data)
+        end
+
+        def urlsafe_load(string)
+          data = urlsafe_serializer.load(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)
+          base64_encode(json_encode(data))
+        end
+
+        def load(data)
+          json_decode(base64_decode(data))
+        end
+
+        private
+
+        def json_encode(data)
+          JSON.generate(data)
+        end
+
+        def base64_encode(data)
+          Base64.urlsafe_encode64(data, padding: false)
+        end
+
+        def base64_decode(data)
+          Base64.urlsafe_decode64(data)
+        end
+
+        def json_decode(data)
+          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)
+  end
+end