shrine 2.6.1 → 2.7.0

data/lib/shrine/plugins/direct_upload.rb

@@ -3,6 +3,9 @@ require "json"
 
 class Shrine
   module Plugins
+    # *[OBSOLETE] This plugin is obsolete, you should use `upload_endpoint` or
+    # `presign_endpoint` plugins instead.*
+    #
     # The `direct_upload` plugin provides a Rack endpoint which can be used for
     # uploading individual files asynchronously. It requires the [Roda] gem.
     #
@@ -283,7 +286,7 @@ class Shrine
 
         # Generates a presign that points to the direct upload endpoint.
         def generate_fake_presign(location, options)
-          url = request.url.sub(/presign$/, "upload")
+          url = request.url.sub(/presign[^\/]*$/, "upload")
           {url: url, fields: {key: location}}
         end
 

data/lib/shrine/plugins/download_endpoint.rb

@@ -1,5 +1,7 @@
 require "roda"
-require "down"
+
+require "base64"
+require "json"
 
 class Shrine
   module Plugins
@@ -10,23 +12,23 @@ class Shrine
     #
     #     plugin :download_endpoint, storages: [:store], prefix: "attachments"
     #
-    # After loading the plugin the endpoint can be mounted:
+    # After loading the plugin the endpoint should be mounted on the specified
+    # prefix:
     #
     #     Rails.appliations.routes.draw do
-    #       mount Shrine::DownloadEndpoint => "/attachments"
+    #       mount Shrine.download_endpoint => "/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:
+    # to the endpoint for files uploaded to specified storages:
     #
-    #     user.avatar.url #=> "/attachments/store/sdg0lsf8.jpg"
+    #     user.avatar.url #=> "/attachments/eyJpZCI6ImFkdzlyeTM5ODJpandoYWla"
     #
     # :storages
-    # :  An array of storage keys which the download endpoint should be applied
-    #    on.
+    # :  An array of storage keys for which `UploadedFile#url` should generate
+    #    download endpoint URLs.
     #
     # :prefix
     # :  The location where the download endpoint was mounted. If it was
@@ -42,22 +44,20 @@ class Shrine
     #    The default is "inline".
     #
     # Note that streaming the file through your app might impact the request
-    # throughput of your app, because on most popular web servers (Puma,
-    # Unicorn, Passenger) workers handling this endpoint will not be able to
-    # serve new requests until the client has fully downloaded the response
-    # body.
+    # throughput of your app, depending on which web server is used. In any
+    # case, it's recommended to use some kind of cache in front of the web
+    # server.
     #
-    # To prevent download endpoint from impacting your request throughput, use
-    # a web server that handles streaming responses and slow clients well, like
-    # [Thin], [Rainbows] or any other [EventMachine]-based web server that
-    # implements `async.callback`.
+    # If you want to authenticate the downloads, it's recommended you use the
+    # `rack_response` plugin directly. With it you can return file responses
+    # from inside your router/controller.
     #
     # [Roda]: https://github.com/jeremyevans/roda
-    # [Thin]: https://github.com/macournoyer/thin
-    # [Rainbows]: https://rubygems.org/gems/rainbows
-    # [Reel]: https://github.com/celluloid/reel
-    # [EventMachine]: https://github.com/eventmachine
     module DownloadEndpoint
+      def self.load_dependencies(uploader, opts = {})
+        uploader.plugin :rack_response
+      end
+
       def self.configure(uploader, opts = {})
         uploader.opts[:download_endpoint_storages] = opts.fetch(:storages, uploader.opts[:download_endpoint_storages])
         uploader.opts[:download_endpoint_prefix] = opts.fetch(:prefix, uploader.opts[:download_endpoint_prefix])
@@ -73,14 +73,28 @@ class Shrine
         # Assigns the subclass a copy of the download endpoint class.
         def inherited(subclass)
           super
-          subclass.assign_download_endpoint(self::DownloadEndpoint)
+          subclass.assign_download_endpoint(@download_endpoint)
+        end
+
+        # Returns the Rack application that retrieves requested files.
+        def download_endpoint
+          @download_endpoint
         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
+          endpoint_class.opts[:disposition]  = opts[:download_endpoint_disposition]
+
+          @download_endpoint = endpoint_class
+
           const_set(:DownloadEndpoint, endpoint_class)
+          deprecate_constant(:DownloadEndpoint) if RUBY_VERSION > "2.3"
+        end
+
+        def download_endpoint_serializer
+          @download_endpoint_serializer ||= Serializer.new
         end
       end
 
@@ -90,85 +104,134 @@ class Shrine
         # 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("/")
+            download_url
           else
             super
           end
         end
+
+        private
+
+        def download_url
+          [download_host, *download_prefix, download_identifier].join("/")
+        end
+
+        # Generates URL-safe identifier from data, filtering only a subset of
+        # metadata that the endpoint needs to prevent the URL from being too
+        # long.
+        def download_identifier
+          semantical_metadata = metadata.select { |name, _| %w[filename size mime_type].include?(name) }
+          download_serializer.dump(data.merge("metadata" => semantical_metadata))
+        end
+
+        def download_serializer
+          shrine_class.download_endpoint_serializer
+        end
+
+        def download_host
+          shrine_class.opts[:download_endpoint_host]
+        end
+
+        def download_prefix
+          shrine_class.opts[:download_endpoint_prefix]
+        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|
-            @storage = get_storage(storage_key)
-
+          # handle legacy ":storage/:id" URLs
+          r.on storage_names do |storage_name|
             r.get /(.*)/ do |id|
-              filename = request.path.split("/").last
-              extname = File.extname(filename)
-
-              response["Content-Disposition"] = "#{disposition}; filename=\"#{filename}\""
-              response["Content-Type"] = Rack::Mime.mime_type(extname)
-
-              io = storage.open(id)
-              response["Content-Length"] = io.size.to_s if io.size
-
-              stream(callback: ->{io.close}) do |out|
-                if io.respond_to?(:each_chunk) # Down::ChunkedIO
-                  io.each_chunk { |chunk| out << chunk }
-                else
-                  out << io.read(16*1024) until io.eof?
-                end
-              end
+              data = { "id" => id, "storage" => storage_name, "metadata" => {} }
+              stream_file(data)
             end
           end
+
+          r.get /(.*)/ do |identifier|
+            data = serializer.load(identifier)
+            stream_file(data)
+          end
         end
 
         private
 
-        attr_reader :storage
+        def stream_file(data)
+          uploaded_file = get_uploaded_file(data)
+
+          status, headers, body = uploaded_file.to_rack_response(disposition: disposition)
+          headers["Cache-Control"] = "max-age=#{365*24*60*60}" # cache for a year
 
-        def get_storage(storage_key)
-          allow_storage!(storage_key)
-          shrine_class.find_storage(storage_key)
+          request.halt [status, headers, body]
         end
 
-        # Halts the request if storage is not allowed.
-        def allow_storage!(storage_key)
-          if !allowed_storages.map(&:to_s).include?(storage_key)
-            error! 403, "Storage #{storage_key.inspect} is not allowed."
-          end
+        # Returns a Shrine::UploadedFile, or returns 404 if file doesn't exist.
+        def get_uploaded_file(data)
+          uploaded_file = shrine_class.uploaded_file(data)
+          not_found! unless uploaded_file.exists?
+          uploaded_file
+        rescue Shrine::Error
+          not_found!
+        end
+
+        def not_found!
+          error!(404, "File Not Found")
         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)
+          response["Content-Type"] = "text/plain"
+          response.write(message)
           request.halt
         end
 
-        def disposition
-          shrine_class.opts[:download_endpoint_disposition]
+        def storage_names
+          shrine_class.storages.keys.map(&:to_s)
         end
 
-        def allowed_storages
-          shrine_class.opts[:download_endpoint_storages]
+        def serializer
+          shrine_class.download_endpoint_serializer
+        end
+
+        def disposition
+          opts[:disposition]
         end
 
         def shrine_class
           opts[:shrine_class]
         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)
+        end
+
+        def base64_decode(data)
+          Base64.urlsafe_decode64(data)
+        end
+
+        def json_decode(data)
+          JSON.parse(data)
+        end
+      end
     end
 
     register_plugin(:download_endpoint, DownloadEndpoint)

data/lib/shrine/plugins/keep_files.rb

@@ -16,7 +16,7 @@ class Shrine
     #
     # For example, the following will keep destroyed and replaced files:
     #
-    #     plugin :keep_files, destroyed: true, :replaced: true
+    #     plugin :keep_files, destroyed: true, replaced: true
     #
     # [event store]: http://docs.geteventstore.com/introduction/event-sourcing-basics/
     module KeepFiles

data/lib/shrine/plugins/logging.rb

@@ -1,5 +1,6 @@
 require "logger"
 require "json"
+require "time"
 
 class Shrine
   module Plugins

data/lib/shrine/plugins/metadata_attributes.rb

@@ -3,7 +3,7 @@ class Shrine
     # The `metadata_attributes` plugin allows you to sync attachment metadata
     # to additional record attributes.
     #
-    #     plugin :metadata_values
+    #     plugin :metadata_attributes
     #
     # It provides `Attacher.metadata_attributes` method which allows you to
     # specify mappings between metadata fields on the attachment and attribute

data/lib/shrine/plugins/presign_endpoint.rb

@@ -0,0 +1,258 @@
+require "rack"
+
+require "json"
+
+class Shrine
+  module Plugins
+    # The `presign_endpoint` plugin provides a Rack endpoint which generates
+    # the URL, fields, and headers that can be used to upload files directly to
+    # a storage service. It can be used with client-side file upload libraries
+    # like [FineUploader], [Dropzone] or [jQuery-File-Upload] for asynchronous
+    # uploads. Storage services that support direct uploads include [Amazon
+    # S3], [Google Cloud Storage], [Microsoft Azure Storage] and more.
+    #
+    #     plugin :presign_endpoint
+    #
+    # The plugin adds a `Shrine.presign_endpoint` method which accepts a
+    # storage identifier and returns a Rack application that accepts GET
+    # requests and generates a presign for the specified storage.
+    #
+    #     Shrine.presign_endpoint(:cache) # rack app
+    #
+    # Asynchronous upload is typically meant to replace the caching phase in
+    # the default synchronous workflow, so we want to generate parameters for
+    # uploads to the temporary (`:cache`) storage.
+    #
+    # We can mount the returned Rack application inside our application:
+    #
+    #     Rails.application.routes.draw do
+    #       mount Shrine.presign_endpoint(:cache) => "/presign"
+    #     end
+    #
+    # The above will create a `GET /presign` endpoint, which generates presign
+    # URL, fields, and headers using the specified storage, and returns it in
+    # JSON format.
+    #
+    #     # GET /presign
+    #     {
+    #       "url": "https://my-bucket.s3-eu-west-1.amazonaws.com",
+    #       "fields": {
+    #         "key": "b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
+    #         "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzaHJpbmUtdGVzdGluZyJ9LHsia2V5IjoiYjdkNTc1ODUwYmE2MWI0NGU3Y2M4YTliZmY4OGU5ZGZkYjE2NTQ0ZDk4OGNkYzI1ZjhkZDEyMTAwNGM4In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUlKRjU1VE1aWlk0NVVUNlEvMjAxNTEwMjQvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTUxMDI0VDAwMTEyOVoifV19",
+    #         "x-amz-credential": "AKIAIJF55TMZYT6Q/20151024/eu-west-1/s3/aws4_request",
+    #         "x-amz-algorithm": "AWS4-HMAC-SHA256",
+    #         "x-amz-date": "20151024T001129Z",
+    #         "x-amz-signature": "c1eb634f83f96b69bd675f535b3ff15ae184b102fcba51e4db5f4959b4ae26f4"
+    #       },
+    #       "headers": {}
+    #     }
+    #
+    # This gives the client all the information it needs to make the upload
+    # request to the selected file to the storage service. The `url` field is
+    # the request URL, `fields` are the required POST parameters, and `headers`
+    # are the required request headers.
+    #
+    # ## Location
+    #
+    # By default the generated location won't have any file extension, but you
+    # can specify one by sending the `filename` query parameter:
+    #
+    #     GET /presign?filename=nature.jpg
+    #
+    # It's also possible to customize how the presign location is generated:
+    #
+    #     plugin :presign_endpoint, presign_location: -> (request) do
+    #       "#{SecureRandom.hex}/#{request.params["filename"]}"
+    #     end
+    #
+    # ## Options
+    #
+    # Some storages accept additional presign options, which you can pass in via
+    # `:presign_options`:
+    #
+    #     plugin :presign_endpoint, presign_options: -> (request) do
+    #       filename     = request.params["filename"]
+    #       extension    = File.extname(filename)
+    #       content_type = Rack::Mime.mime_type(extension)
+    #
+    #       {
+    #         content_length_range: 0..(10*1024*1024),                     # limit filesize to 10MB
+    #         content_disposition: "attachment; filename=\"#{filename}\"", # download with original filename
+    #         content_type:        content_type,                           # set correct content type
+    #       }
+    #     end
+    #
+    # ## Presign
+    #
+    # You can also customize how the presign itself is generated via the
+    # `:presign` option:
+    #
+    #     plugin :presign_endpoint, presign: -> (id, options, request) do
+    #       # return an object that responds to #url, #fields, and #headers
+    #     end
+    #
+    # ## Response
+    #
+    # The response returned by the endpoint can be customized via the
+    # `:rack_response` option:
+    #
+    #     plugin :presign_endpoint, rack_response: -> (hash, request) do
+    #       body = { endpoint: hash[:url], params: hash[:fields], headers: hash[:headers] }.to_json
+    #       [201, { "Content-Type" => "application/json" }, [body]]
+    #     end
+    #
+    # ## Ad-hoc options
+    #
+    # You can override any of the options above when creating the endpoint:
+    #
+    #     Shrine.presign_endpoint(:cache, presign_location: "${filename}")
+    #
+    # [Amazon S3]: https://aws.amazon.com/s3/
+    # [Google Cloud Storage]: https://cloud.google.com/storage/
+    # [Microsoft Azure Storage]: https://azure.microsoft.com/en-us/services/storage/
+    module PresignEndpoint
+      def self.configure(uploader, opts = {})
+        uploader.opts[:presign_endpoint_presign_location] = opts.fetch(:presign_location, uploader.opts[:presign_endpoint_presign_location])
+        uploader.opts[:presign_endpoint_presign_options] = opts.fetch(:presign_options, uploader.opts[:presign_endpoint_presign_options])
+        uploader.opts[:presign_endpoint_presign] = opts.fetch(:presign, uploader.opts[:presign_endpoint_presign])
+        uploader.opts[:presign_endpoint_rack_response] = opts.fetch(:rack_response, uploader.opts[:presign_endpoint_rack_response])
+      end
+
+      module ClassMethods
+        # Returns a Rack application (object that responds to `#call`) which
+        # accepts GET requests to the root URL, calls the specified storage to
+        # generate the presign, and returns that information in JSON format.
+        #
+        # The `storage_key` needs to be one of the registered Shrine storages.
+        # Additional options can be given to override the options given on
+        # plugin initialization.
+        def presign_endpoint(storage_key, **options)
+          App.new({
+            shrine_class:     self,
+            storage_key:      storage_key,
+            presign_location: opts[:presign_endpoint_presign_location],
+            presign_options:  opts[:presign_endpoint_presign_options],
+            presign:          opts[:presign_endpoint_presign],
+            rack_response:    opts[:presign_endpoint_rack_response],
+          }.merge(options))
+        end
+      end
+
+      # Rack application that accepts GET request to the root URL, calls
+      # `#presign` on the specified storage, and returns that information in
+      # JSON format.
+      class App
+        # Writes given options to instance variables.
+        def initialize(options)
+          options.each do |name, value|
+            instance_variable_set("@#{name}", value)
+          end
+        end
+
+        # Accepts a Rack env hash, routes GET requests to the root URL, and
+        # returns a Rack response triple.
+        #
+        # If request isn't to the root URL, a `404 Not Found` response is
+        # returned. If request verb isn't GET, a `405 Method Not Allowed`
+        # response is returned.
+        def call(env)
+          request = Rack::Request.new(env)
+
+          status, headers, body = catch(:halt) do
+            error!(404, "Not Found") unless ["", "/"].include?(request.path_info)
+            error!(405, "Method Not Allowed") unless request.get?
+
+            handle_request(request)
+          end
+
+          headers["Content-Length"] = body.map(&:bytesize).inject(0, :+).to_s
+
+          [status, headers, body]
+        end
+
+        private
+
+        # Accepts a `Rack::Request` object, generates the presign, and returns a
+        # Rack response.
+        def handle_request(request)
+          location = get_presign_location(request)
+          options  = get_presign_options(request)
+
+          presign = generate_presign(location, options, request)
+
+          make_response(presign, request)
+        end
+
+        # Generates the location using `Shrine#generate_uid`, and extracts the
+        # extension from the `filename` query parameter. If `:presign_location`
+        # option is given, calls that instead.
+        def get_presign_location(request)
+          if @presign_location
+            @presign_location.call(request)
+          else
+            extension = File.extname(request.params["filename"].to_s)
+            uploader.send(:generate_uid, nil) + extension
+          end
+        end
+
+        # Calls `:presign_options` option block if given.
+        def get_presign_options(request)
+          options = @presign_options
+          options = options.call(request) if options.respond_to?(:call)
+          options || {}
+        end
+
+        # Calls `#presign` on the storage, and returns the `url`, `fields`, and
+        # `headers` information in a serialializable format. If `:presign`
+        # option is given, calls that instead of calling `#presign`.
+        def generate_presign(location, options, request)
+          if @presign
+            presign = @presign.call(location, options, request)
+          else
+            presign = storage.presign(location, options)
+          end
+
+          url     = presign.url
+          fields  = presign.fields
+          headers = presign.headers if presign.respond_to?(:headers)
+
+          { url: url, fields: fields.to_h, headers: headers.to_h }
+        end
+
+        # Transforms the presign hash into a JSON response. It returns a Rack
+        # response triple - an array consisting of a status number, hash of
+        # headers, and a body enumerable. If `:rack_response` option is given,
+        # calls that instead.
+        def make_response(object, request)
+          if @rack_response
+            response = @rack_response.call(object, request)
+          else
+            response = [200, {"Content-Type" => "application/json"}, [object.to_json]]
+          end
+
+          # prevent browsers from caching the response
+          response[1]["Cache-Control"] = "no-store" unless response[1].key?("Cache-Control")
+
+          response
+        end
+
+        # Used for early returning an error response.
+        def error!(status, message)
+          throw :halt, [status, {"Content-Type" => "text/plain"}, [message]]
+        end
+
+        # Returns the uploader around the specified storage.
+        def uploader
+          @shrine_class.new(@storage_key)
+        end
+
+        # Returns the storage object.
+        def storage
+          @shrine_class.find_storage(@storage_key)
+        end
+      end
+    end
+
+    register_plugin(:presign_endpoint, PresignEndpoint)
+  end
+end