shrine 1.0.0 → 1.1.0

data/lib/shrine/plugins/download_endpoint.rb

@@ -0,0 +1,157 @@
+require "roda"
+
+class Shrine
+  module Plugins
+    # The download_endpoint plugin provides a [Roda] endpoint for downloading
+    # uploaded files from specified storages. This is useful when files from
+    # your storages aren't accessible over URL (e.g. database storages) or if
+    # you want to authenticate your downloads.
+    #
+    #     plugin :download_endpoint, storages: [:store], prefix: "attachments"
+    #
+    # After loading the plugin the endpoint should be mounted:
+    #
+    #     Rails.appliations.routes.draw do
+    #       mount Shrine::DownloadEndpoint => "/attachments"
+    #     end
+    #
+    # Now all stored files can be downloaded through the endpoint, and the
+    # endpoint will efficiently stream the file from the storage when the
+    # storage supports it. `UploadedFile#url` will automatically return the URL
+    # to the endpoint for specified storages, so it's not needed to change the
+    # code:
+    #
+    #     user.avatar_url #=> "/attachments/store/sdg0lsf8.jpg"
+    #
+    # :storages
+    # :  An array of storage keys which the download endpoint should be used for.
+    #
+    # :prefix
+    # :  The location where the download endpoint was mounted. If it was
+    #    mounted at the root level, this should be set to nil.
+    #
+    # :host
+    # :  The host that you want the download URLs to use (e.g. your app's domain
+    #    name or a CDN). By default URLs are relative.
+    #
+    # :disposition
+    # :  Can be set to "attachment" if you want that the user is always
+    #    prompted to download the file when visiting the download URL.
+    #    The default is "inline".
+    #
+    # This plugin is also suitable on Heroku when using FileSystem storage for
+    # cache. On Heroku files cannot be stored to the "public" folder but rather
+    # to the "tmp" folder, which means that by default it's not possible to
+    # show the URL to the cached file. The download endpoint generates the URL
+    # to any file, regardless of its location.
+    #
+    # [Roda]: https://github.com/jeremyevans/roda
+    module DownloadEndpoint
+      def self.configure(uploader, storages:, prefix:, disposition: "inline", host: nil)
+        uploader.opts[:download_endpoint_storages] = storages
+        uploader.opts[:download_endpoint_prefix] = prefix
+        uploader.opts[:download_endpoint_disposition] = disposition
+        uploader.opts[:download_endpoint_host] = host
+
+        uploader.assign_download_endpoint(App) unless uploader.const_defined?(:DownloadEndpoint)
+      end
+
+      module ClassMethods
+        # Assigns the subclass a copy of the download endpoint class.
+        def inherited(subclass)
+          super
+          subclass.assign_download_endpoint(self::DownloadEndpoint)
+        end
+
+        # Assigns the subclassed endpoint as the `DownloadEndpoint` constant.
+        def assign_download_endpoint(klass)
+          endpoint_class = Class.new(klass)
+          endpoint_class.opts[:shrine_class] = self
+          const_set(:DownloadEndpoint, endpoint_class)
+        end
+      end
+
+      module FileMethods
+        # Constructs the URL from the optional host, prefix, storage key and
+        # uploaded file's id. For other uploaded files that aren't in the list
+        # of storages it just returns their original URL.
+        def url(**options)
+          if shrine_class.opts[:download_endpoint_storages].include?(storage_key.to_sym)
+            [
+              shrine_class.opts[:download_endpoint_host],
+              *shrine_class.opts[:download_endpoint_prefix],
+              storage_key,
+              id,
+            ].join("/")
+          else
+            super(options)
+          end
+        end
+      end
+
+      # Routes incoming requests. It first asserts that the storage is existent
+      # and allowed. Afterwards it proceeds with the file download using
+      # streaming.
+      class App < Roda
+        plugin :streaming
+
+        route do |r|
+          r.on ":storage" do |storage_key|
+            allow_storage!(storage_key)
+            @storage = shrine_class.find_storage(storage_key)
+
+            r.get /(.*)/ do |id|
+              filename = request.path.split("/").last
+              extname = File.extname(filename)
+
+              response["Content-Disposition"] = "#{disposition}; filename=#{filename.inspect}"
+              response["Content-Type"] = Rack::Mime.mime_type(extname)
+
+              stream do |out|
+                if @storage.respond_to?(:stream)
+                  @storage.stream(id) { |chunk| out << chunk }
+                else
+                  io, buffer = @storage.open(id), ""
+                  out << io.read(16384, buffer) until io.eof?
+                  io.close
+                  io.delete if io.class.name == "Tempfile"
+                end
+              end
+            end
+          end
+        end
+
+        private
+
+        # Halts the request if storage is not allowed.
+        def allow_storage!(storage)
+          if !allowed_storages.map(&:to_s).include?(storage)
+            error! 403, "Storage #{storage.inspect} is not allowed."
+          end
+        end
+
+        # Halts the request with the error message.
+        def error!(status, message)
+          response.status = status
+          response["Content-Type"] = "application/json"
+          response.write({error: message}.to_json)
+          request.halt
+        end
+
+        def disposition
+          shrine_class.opts[:download_endpoint_disposition]
+        end
+
+        def allowed_storages
+          shrine_class.opts[:download_endpoint_storages]
+        end
+
+        def shrine_class
+          opts[:shrine_class]
+        end
+      end
+    end
+
+    register_plugin(:download_endpoint, DownloadEndpoint)
+  end
+end

data/lib/shrine/plugins/hooks.rb

@@ -18,7 +18,7 @@ class Shrine
     #
     # Each hook will be called with 2 arguments, `io` and `context`. You should
     # always call `super` when overriding a hook, as other plugins may be using
-    # hooks internally, and without `super` they wouldn't get executed.
+    # hooks internally, and without `super` those wouldn't get executed.
     #
     # Shrine calls hooks in the following order when uploading a file:
     #
@@ -41,6 +41,17 @@ class Shrine
     #     * DELETE
     #     * `after_delete`
     #
+    # By default every `around_*` hook returns the result of the corresponding
+    # operation:
+    #
+    #     class ImageUploader < Shrine
+    #       def around_store(io, context)
+    #         result = super
+    #         result.class #=> Shrine::UploadedFile
+    #         result # it's good to always return the result for consistent behaviour
+    #       end
+    #     end
+    #
     # It may be useful to know that you can realize some form of communication
     # between the hooks; whatever you save to the `context` hash will be
     # forwarded further down:
@@ -70,8 +81,9 @@ class Shrine
 
         def around_upload(*args)
           before_upload(*args)
-          yield
+          result = yield
           after_upload(*args)
+          result
         end
 
         def before_upload(*)
@@ -90,8 +102,9 @@ class Shrine
 
         def around_process(*args)
           before_process(*args)
-          yield
+          result = yield
           after_process(*args)
+          result
         end
 
         def before_process(*)
@@ -109,8 +122,9 @@ class Shrine
 
         def around_store(*args)
           before_store(*args)
-          yield
+          result = yield
           after_store(*args)
+          result
         end
 
         def before_store(*)
@@ -128,7 +142,7 @@ class Shrine
 
         def around_delete(*args)
           before_delete(*args)
-          yield
+          result = yield
           after_delete(*args)
         end
 

data/lib/shrine/plugins/keep_location.rb

@@ -0,0 +1,43 @@
+class Shrine
+  module Plugins
+    # The keep_location plugin allows you to preserve locations when
+    # transferring files from one storage to another. This can be useful for
+    # debugging purposes or for backups.
+    #
+    #     plugin :keep_location, :cache => :store
+    #
+    # The above will preserve location of cached files uploaded to store. More
+    # precisely, if a Shrine::UploadedFile from cache is begin uploaded to
+    # store, the stored file will have the same location as the cached file.
+    #
+    # The destination storage can also be specified as an array:
+    #
+    #     plugin :keep_location, :cache => [:storage1, :storage2]
+    module KeepLocation
+      def self.configure(uploader, mappings = {})
+        uploader.opts[:keep_location_mappings] = mappings
+      end
+
+      module InstanceMethods
+        private
+
+        def get_location(io, context)
+          if io.is_a?(UploadedFile) && keep_location?(io)
+            io.id
+          else
+            super
+          end
+        end
+
+        def keep_location?(uploaded_file)
+          opts[:keep_location_mappings].any? do |source, destination|
+            source == uploaded_file.storage_key.to_sym &&
+              Array(destination).include?(self.storage_key)
+          end
+        end
+      end
+    end
+
+    register_plugin(:keep_location, KeepLocation)
+  end
+end

data/lib/shrine/plugins/moving.rb

@@ -11,9 +11,9 @@ class Shrine
     #     plugin :moving, storages: [:cache]
     #
     # The `:storages` option specifies which storages the file will be moved
-    # to. The above will move Rails's uploaded files to cache (without this
-    # plugin it's simply copied over). However, you may want to move cached
-    # files to `:store` as well:
+    # to. The above will move raw files to cache (without this plugin it's
+    # simply copied over). However, you may want to move cached files to
+    # `:store` as well:
     #
     #     plugin :moving, storages: [:cache, :store]
     #
@@ -21,7 +21,7 @@ class Shrine
     # being uploaded will be deleted afterwards. However, if both the file
     # being uploaded and the destination are on the filesystem, a `mv` command
     # will be executed instead. Some other storages may implement moving as
-    # well, usually if also both the `:cache` and `:store` are using the same
+    # well, usually if also both the cache and store are using the same
     # storage.
     module Moving
       def self.configure(uploader, storages:)
@@ -31,11 +31,9 @@ class Shrine
       module InstanceMethods
         private
 
-        # If the file is movable (usually this means that both the file and
-        # the destination are on the filesystem), use the underlying storage's
-        # ability to move. Otherwise we "imitate" moving by deleting the file
-        # after it was uploaded.
-        def put(io, context)
+        # If the storage supports moving we use that, otherwise we do moving by
+        # copying and deleting.
+        def copy(io, context)
           if move?(io, context)
             if movable?(io, context)
               move(io, context)
@@ -48,7 +46,10 @@ class Shrine
           end
         end
 
-        # Ask the storage if the given file is movable.
+        def move(io, context)
+          storage.move(io, context[:location], context[:metadata])
+        end
+
         def movable?(io, context)
           storage.respond_to?(:move) && storage.movable?(io, context[:location])
         end

data/lib/shrine/plugins/parallelize.rb

@@ -35,11 +35,7 @@ class Shrine
 
         private
 
-        def copy(io, context)
-          context[:thread_pool].process { super }
-        end
-
-        def move(io, context)
+        def put(io, context)
           context[:thread_pool].process { super }
         end
 

data/lib/shrine/plugins/parsed_json.rb

@@ -8,12 +8,18 @@ class Shrine
     module ParsedJson
       module AttacherMethods
         def assign(value)
-          if value.is_a?(Hash) && value.keys.any? { |key| key.is_a?(String) }
+          if value.is_a?(Hash) && parsed_json?(value)
             assign(value.to_json)
           else
             super
           end
         end
+
+        private
+
+        def parsed_json?(hash)
+          hash.keys.any? { |key| key.is_a?(String) }
+        end
       end
     end
 

data/lib/shrine/plugins/pretty_location.rb

@@ -24,6 +24,12 @@ class Shrine
 
           [type, id, name, original].compact.join("/")
         end
+
+        private
+
+        def generate_uid(io)
+          SecureRandom.hex(5)
+        end
       end
     end
 

data/lib/shrine/plugins/rack_file.rb

@@ -25,12 +25,18 @@ class Shrine
         # Checks whether a file is a Rack file hash, and in that case wraps the
         # hash in an IO-like object.
         def assign(value)
-          if value.is_a?(Hash) && value.key?(:tempfile)
+          if value.is_a?(Hash) && rack_file?(value)
             assign(UploadedFile.new(value))
           else
             super
           end
         end
+
+        private
+
+        def rack_file?(hash)
+          hash.key?(:tempfile)
+        end
       end
 
       # This is used to wrap the Rack hash into an IO-like object which Shrine

data/lib/shrine/plugins/remove_invalid.rb

@@ -0,0 +1,22 @@
+class Shrine
+  module Plugins
+    # The remove_invalid plugin automatically deletes a cached file if it was
+    # invalid and deassigns it from the record.
+    #
+    #     plugin :remove_invalid
+    module RemoveInvalid
+      module AttacherMethods
+        def validate
+          super
+        ensure
+          if errors.any? && cache.uploaded?(get)
+            delete!(get, phase: :invalid)
+            _set(nil)
+          end
+        end
+      end
+    end
+
+    register_plugin(:remove_invalid, RemoveInvalid)
+  end
+end

data/lib/shrine/plugins/sequel.rb

@@ -20,7 +20,7 @@ class Shrine
     # tests.
     #
     # If you want to put some parts of this lifecycle into a background job, see
-    # the background_helpers plugin.
+    # the backgrounding plugin.
     #
     # Additionally, any Shrine validation errors will added to Sequel's
     # errors upon validation. Note that if you want to validate presence of the
@@ -62,7 +62,7 @@ class Shrine
       end
 
       module AttacherClassMethods
-        # Needed by the background_helpers plugin.
+        # Needed by the backgrounding plugin.
         def find_record(record_class, record_id)
           record_class.with_pk!(record_id)
         end

data/lib/shrine/plugins/upload_options.rb

@@ -0,0 +1,41 @@
+class Shrine
+  module Plugins
+    # The upload_options allows you to create additional upload options depending
+    # on file and context, and forward them to the underlying storage.
+    #
+    #     plugin :upload_options, store: ->(io, context) do
+    #       if [:original, :thumb].include?(context[:version])
+    #         {acl: "public-read"}
+    #       else
+    #         {acl: "private"}
+    #       end
+    #     end
+    #
+    # Keys are names of the registered storages, and values are either blocks
+    # or hashes.
+    module UploadOptions
+      def self.configure(uploader, options = {})
+        uploader.opts[:upload_options_options] = options
+      end
+
+      module InstanceMethods
+        def put(io, context)
+          upload_options = get_upload_options(io, context)
+          key = storage.class.name.split("::").last.downcase
+          context[:metadata][key] = upload_options if upload_options
+          super
+        end
+
+        private
+
+        def get_upload_options(io, context)
+          options = opts[:upload_options_options][storage_key]
+          options = options.call(io, context) if options.respond_to?(:call)
+          options
+        end
+      end
+    end
+
+    register_plugin(:upload_options, UploadOptions)
+  end
+end