shrine 1.0.0 → 1.1.0

data/lib/shrine/plugins/backup.rb

@@ -0,0 +1,88 @@
+class Shrine
+  module Plugins
+    # The backup plugin allows you to automatically backup up stored files to
+    # an additional storage.
+    #
+    #     storages[:backup_store] = Shrine::Storage::S3.new(options)
+    #     plugin :backup, storage: :backup_store
+    #
+    # After the cached file is promoted to store, it will be reuploaded from
+    # store to the provided "backup" storage.
+    #
+    #     user.update(avatar: file) # uploaded both to :store and :backup_store
+    #
+    # By default whenever stored files are deleted backed up files are deleted
+    # as well, but you can keep files on the "backup" storage by passing
+    # `delete: false`:
+    #
+    #     plugin :backup, storage: :backup_store, delete: false
+    #
+    # Note that when adding this plugin with already existing stored files,
+    # Shrine won't know whether a stored file is backed up or not, so
+    # attempting to delete the backup could result in an error. To avoid that
+    # you can set `delete: false` until you manually back up the existing
+    # stored files.
+    module Backup
+      def self.configure(uploader, storage:, delete: true)
+        uploader.opts[:backup_storage] = storage
+        uploader.opts[:backup_delete] = delete
+      end
+
+      module AttacherMethods
+        def backup_file(uploaded_file)
+          uploaded_file(uploaded_file) { |f| f.data["storage"] = backup_storage.to_s }
+          uploaded_file(uploaded_file.to_json)
+        end
+
+        private
+
+        # Back up the stored file and return it.
+        def store!(io, phase:)
+          super.tap { |stored_file| store_backup!(stored_file) }
+        end
+
+        # Delete the backed up file unless `:delete` was set to false.
+        def delete!(uploaded_file, phase:)
+          super.tap { |deleted_file| delete_backup!(deleted_file) if backup_delete? }
+        end
+
+        # Upload the stored file to the backup storage.
+        def store_backup!(stored_file)
+          backup_store.upload(stored_file, context.merge(phase: :backup))
+        end
+
+        # Deleted the stored file from the backup storage.
+        def delete_backup!(deleted_file)
+          backup_store.delete(backup_file(deleted_file), context.merge(phase: :backup))
+        end
+
+        def backup_store
+          @backup_store ||= shrine_class.new(backup_storage)
+        end
+
+        def backup_storage
+          shrine_class.opts[:backup_storage]
+        end
+
+        def backup_delete?
+          shrine_class.opts[:backup_delete]
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        # We preserve the location when uploading from store to backup.
+        def get_location(io, context)
+          if context[:phase] == :backup
+            io.id
+          else
+            super
+          end
+        end
+      end
+    end
+
+    register_plugin(:backup, Backup)
+  end
+end

data/lib/shrine/plugins/data_uri.rb

@@ -1,4 +1,5 @@
 require "base64"
+require "stringio"
 
 class Shrine
   module Plugins
@@ -11,10 +12,10 @@ class Shrine
     # `#avatar_data_uri` and `#avatar_data_uri=` methods to your model.
     #
     #     user.avatar #=> nil
-    #     user.avatar_data_uri = "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
+    #     user.avatar_data_uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
     #     user.avatar #=> #<Shrine::UploadedFile>
     #
-    #     user.avatar.mime_type         #=> "image/jpeg"
+    #     user.avatar.mime_type         #=> "image/png"
     #     user.avatar.size              #=> 43423
     #     user.avatar.original_filename #=> nil
     #
@@ -24,12 +25,18 @@ class Shrine
     #     plugin :data_uri, error_message: "data URI was invalid"
     #     plugin :data_uri, error_message: ->(uri) { I18n.t("errors.data_uri_invalid") }
     #
+    # This plugin also adds a `UploadedFile#data_uri` method (and `#base64`),
+    # which returns a base64-encoded data URI of any UploadedFile:
+    #
+    #     user.avatar.data_uri #=> "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
+    #     user.avatar.base64   #=> "iVBORw0KGgoAAAANSUhEUgAAAAUA"
+    #
     # [data URIs]: https://tools.ietf.org/html/rfc2397
     # [HTML5 Canvas]: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API
     module DataUri
       DEFAULT_ERROR_MESSAGE = "data URI was invalid"
       DEFAULT_CONTENT_TYPE = "text/plain"
-      DATA_URI_REGEXP = /\Adata:([-\w]+\/[-\w\+\.]+)?;base64,(.*)/m
+      DATA_URI_REGEXP = /\Adata:([-\w.+]+\/[-\w.+]+)?(;base64)?,(.*)\z/m
 
       def self.configure(uploader, error_message: DEFAULT_ERROR_MESSAGE)
         uploader.opts[:data_uri_error_message] = error_message
@@ -61,7 +68,7 @@ class Shrine
 
           if match = uri.match(DATA_URI_REGEXP)
             content_type = match[1] || DEFAULT_CONTENT_TYPE
-            content      = Base64.decode64(match[2])
+            content      = match[2] ? Base64.decode64(match[3]) : match[3]
 
             assign DataFile.new(content, content_type: content_type)
           else
@@ -78,6 +85,20 @@ class Shrine
         end
       end
 
+      module FileMethods
+        # Returns the data URI representation of the file.
+        def data_uri
+          @data_uri ||= "data:#{mime_type || "text/plain"};base64,#{base64}"
+        end
+
+        # Returns contents of the file base64-encoded.
+        def base64
+          content = storage.read(id)
+          base64 = Base64.encode64(content)
+          base64.chomp
+        end
+      end
+
       class DataFile < StringIO
         attr_reader :content_type
 

data/lib/shrine/plugins/default_url.rb

@@ -0,0 +1,37 @@
+class Shrine
+  module Plugins
+    # The default_url plugin allows setting the URL which will be returned when
+    # the attachment is missing.
+    #
+    #     plugin :default_url do |context|
+    #       "/#{context[:name]}/missing.jpg"
+    #     end
+    #
+    # The default URL gets triggered when calling `<attachment>_url` on the
+    # model:
+    #
+    #     user.avatar     #=> nil
+    #     user.avatar_url # "/avatar/missing.jpg"
+    #
+    # Any additional URL options will be present in the `context` hash.
+    module DefaultUrl
+      def self.configure(uploader, &block)
+        uploader.opts[:default_url] = block
+      end
+
+      module AttacherMethods
+        private
+
+        def default_url(**options)
+          default_url_block.call(options.merge(context))
+        end
+
+        def default_url_block
+          shrine_class.opts[:default_url]
+        end
+      end
+    end
+
+    register_plugin(:default_url, DefaultUrl)
+  end
+end

data/lib/shrine/plugins/delete_uploaded.rb

@@ -0,0 +1,40 @@
+class Shrine
+  module Plugins
+    # The delete_uploaded plugin will automatically delete files after they
+    # have been uploaded. This is especially useful when doing processing, to
+    # ensure that temporary files have been deleted after upload. One exception
+    # are `Shrine::UploadedFile` files, they won't get deleted for stability
+    # reasons.
+    #
+    #     plugin :delete_uploaded
+    #
+    # By default this behaviour will be applied to all storages, but you can
+    # limit this only to specified storages:
+    #
+    #     plugin :delete_uploaded, storages: [:store]
+    module DeleteUploaded
+      def self.configure(uploader, storages: :all)
+        uploader.opts[:delete_uploaded_storages] = storages
+      end
+
+      module InstanceMethods
+        private
+
+        # Deletes the uploaded file unless it's an UploadedFile.
+        def copy(io, context)
+          super
+          if io.respond_to?(:delete) && !io.is_a?(UploadedFile)
+            io.delete if delete_uploaded?(io)
+          end
+        end
+
+        def delete_uploaded?(io)
+          opts[:delete_uploaded_storages] == :all ||
+          opts[:delete_uploaded_storages].include?(storage_key)
+        end
+      end
+    end
+
+    register_plugin(:delete_uploaded, DeleteUploaded)
+  end
+end

data/lib/shrine/plugins/determine_mime_type.rb

@@ -8,8 +8,9 @@ class Shrine
     # The plugin accepts the following analyzers:
     #
     # :file
-    # : (Default). Uses the UNIX [file] utility to determine the MIME type
-    #   from file contents.
+    # : (Default). Uses the [file] utility to determine the MIME type from file
+    #   contents. It is installed by default on most operating systems, but the
+    #   [Windows equivalent] you need to install separately.
     #
     # :filemagic
     # : Uses the [ruby-filemagic] gem to determine the MIME type from file
@@ -42,6 +43,7 @@ class Shrine
     #     end
     #
     # [file]: http://linux.die.net/man/1/file
+    # [Windows equivalent]: http://gnuwin32.sourceforge.net/packages/file.htm
     # [ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic
     # [mimemagic]: https://github.com/minad/mimemagic
     # [mime-types]: https://github.com/mime-types/ruby-mime-types

data/lib/shrine/plugins/direct_upload.rb

@@ -5,22 +5,21 @@ require "securerandom"
 
 class Shrine
   module Plugins
-    # The direct_upload plugin provides a Rack endpoint (implemented in [Roda])
-    # which you can use to implement AJAX uploads.
+    # The direct_upload plugin provides a [Roda] endpoint which can be used for
+    # uploading individual files asynchronously.
     #
     #     plugin :direct_upload
     #
     # This is how you could mount the endpoint in a Rails application:
     #
     #     Rails.application.routes.draw do
-    #       # adds `POST /attachments/images/:storage/:name`
-    #       mount ImageUploader.direct_endpoint => "/attachments/images"
+    #       mount ImageUploader::UploadEndpoint => "/attachments/images"
     #     end
     #
-    # Note that you should mount a separate endpoint for each uploader that you
-    # want to use it with. This now gives your Ruby application a
-    # `POST /attachments/images/:storage/:name` route, which accepts a `file`
-    # query parameter, and returns the uploaded file in JSON format:
+    # You should always mount a new endpoint for each uploader that you want to
+    # enable direct uploads for. This now gives your Ruby application a `POST
+    # /attachments/images/:storage/:name` route, which accepts a `file` query
+    # parameter, and returns the uploaded file in JSON format:
     #
     #     # POST /attachments/images/cache/avatar
     #     {
@@ -33,16 +32,26 @@ class Shrine
     #       }
     #     }
     #
-    # There are many great JavaScript libraries for AJAX file uploads which can
-    # be hooked up to this endpoint, [jQuery-File-Upload] being the most
-    # popular one.
+    # Once you've uploaded the file, you need to assign this JSON to the hidden
+    # attachment field in the form. There are many great JavaScript libraries
+    # for file uploads, most popular being [jQuery-File-Upload].
     #
-    # ## Presigned
+    # ## Limiting filesize
     #
-    # An alternative to the direct endpoint is doing direct uploads to the
-    # underlying storage. These uploads usually requires extra information
-    # from the server, and this plugin can provide an endpoint to it, which
-    # you can enable by passing in `presign: true`:
+    # It's good idea to limit the maximum filesize of uploaded files, if you
+    # set the `:max_size` option, files which are too big will get
+    # automatically deleted and 413 status will be returned:
+    #
+    #     plugin :direct_upload, max_size: 5*1024*1024 # 5 MB
+    #
+    # Note that this option doesn't affect presigned uploads, but there you can
+    # limit the filesize with storage options.
+    #
+    # ## Presigning
+    #
+    # An alternative to the direct endpoint is uploading directly to the
+    # underlying storage (S3). These uploads usually require extra information
+    # from the server, you can enable that route by passing `presign: true`:
     #
     #     plugin :direct_upload, presign: true
     #
@@ -51,7 +60,7 @@ class Shrine
     # request looks something like this:
     #
     #     {
-    #       "url" => "https://shrine-testing.s3-eu-west-1.amazonaws.com",
+    #       "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",
     #       "fields" => {
     #         "key" => "b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
     #         "policy" => "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzaHJpbmUtdGVzdGluZyJ9LHsia2V5IjoiYjdkNTc1ODUwYmE2MWI0NGU3Y2M4YTliZmY4OGU5ZGZkYjE2NTQ0ZDk4OGNkYzI1ZjhkZDEyMTAwNGM4In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUlKRjU1VE1aWlk0NVVUNlEvMjAxNTEwMjQvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTUxMDI0VDAwMTEyOVoifV19",
@@ -65,29 +74,22 @@ class Shrine
     # The `url` is where the file needs to be uploaded to, and `fields` is
     # additional data that needs to be send on the upload. The `fields.key`
     # attribute is the location where the file will be uploaded to, it is
-    # generated randomly, but you can add an extension to it:
+    # generated randomly without an extension, but you can add it:
     #
     #     GET /cache/presign?extension=.png
     #
     # If you want additional options to be passed to Storage::S3#presign, you
-    # can pass a block to `:presign` and return additional options:
+    # can pass a block to `:presign`, and it will yield Roda's request object:
     #
     #     plugin :direct_upload, presign: ->(request) do
     #       {
     #         content_length_range: 0..(5*1024*1024), # limit the filesize to 5 MB
-    #         success_action_redirect: "http://example.com/webhook",
+    #         content_type: request.params["content_type"], # use "content_type" query parameter
     #       }
     #     end
     #
-    # The yielded object is an instance of [`Roda::RodaRequest`] (a subclass of
-    # `Rack::Request`), which allows you to pass different options depending on
-    # the request. For example, you could accept a `content_type` query
-    # parameter and add it to options:
-    #
-    #     plugin :direct_upload, presign: ->(request) do
-    #       {content_type: request.params["content_type"]} if request.params["content_type"]
-    #     end
-    #     # Now you can do `GET /cache/presign?content_type=image/jpeg`
+    # See the [Direct Uploads to S3] guide for further instructions on how to
+    # hook this up in a form.
     #
     # ## Allowed storages
     #
@@ -105,76 +107,99 @@ class Shrine
     #
     #     Rails.application.routes.draw do
     #       constraints(->(r){r.env["warden"].authenticate!}) do
-    #         mount ImageUploader.direct_endpoint => "/attachments/images"
+    #         mount ImageUploader::UploadEndpoint => "/attachments/images"
     #       end
     #     end
     #
+    # ## Customizing endpoint
+    #
+    # Since the endpoint is a [Roda] app, it can be easily customized via
+    # plugins:
+    #
+    #     class MyUploader
+    #       class UploadEndpoint
+    #         plugin :hooks
+    #
+    #         after do |response|
+    #           # ...
+    #         end
+    #       end
+    #     end
+    #
+    # Upon subclassing uploader the upload endpoint is also subclassed. You can
+    # also call the plugin again in an uploader subclass to change its
+    # configuration.
+    #
     # [Roda]: https://github.com/jeremyevans/roda
     # [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
     # [supports]: https://github.com/blueimp/jQuery-File-Upload/wiki/Options#progress
     # ["accept" attribute]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-accept
     # [`Roda::RodaRequest`]: http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/RequestMethods.html
+    # [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
     module DirectUpload
       def self.load_dependencies(uploader, *)
         uploader.plugin :rack_file
       end
 
-      def self.configure(uploader, allowed_storages: [:cache], presign: nil, **)
+      def self.configure(uploader, allowed_storages: [:cache], presign: nil, max_size: nil)
         uploader.opts[:direct_upload_allowed_storages] = allowed_storages
         uploader.opts[:direct_upload_presign] = presign
+        uploader.opts[:direct_upload_max_size] = max_size
+
+        uploader.assign_upload_endpoint(App) unless uploader.const_defined?(:UploadEndpoint)
       end
 
       module ClassMethods
-        # Return the cached Roda endpoint.
-        def direct_endpoint
-          @direct_endpoint ||= build_direct_endpoint
+        # Assigns the subclass a copy of the upload endpoint class.
+        def inherited(subclass)
+          super
+          subclass.assign_upload_endpoint(self::UploadEndpoint)
         end
 
-        private
+        # Assigns the subclassed endpoint as the `UploadEndpoint` constant.
+        def assign_upload_endpoint(klass)
+          endpoint_class = Class.new(klass)
+          endpoint_class.opts[:shrine_class] = self
+          const_set(:UploadEndpoint, endpoint_class)
+        end
 
-        # Builds the endpoint and assigns it the current Shrine class.
-        def build_direct_endpoint
-          app = Class.new(App)
-          app.opts[:shrine_class] = self
-          app.app
+        # Returns the Roda direct upload endpoint.
+        def direct_endpoint
+          warn "#{self}.direct_endpoint is deprecated and will be removed in Shrine 2, you should use #{self}::UploadEndpoint instead."
+          self::UploadEndpoint
         end
       end
 
+      # Routes incoming requests. It first asserts that the storage is existent
+      # and allowed, then the filesize isn't too large. Afterwards it proceeds
+      # with the file upload and returns the uploaded file as JSON.
       class App < Roda
         plugin :default_headers, "Content-Type"=>"application/json"
-        plugin :halt
 
-        # Routes incoming requests. We first check if the storage is allowed,
-        # then proceed further with the upload, returning the uploaded file
-        # as JSON.
         route do |r|
           r.on ":storage" do |storage_key|
             allow_storage!(storage_key)
             @uploader = shrine_class.new(storage_key.to_sym)
 
-            unless presign
-              r.post ":name" do |name|
-                file = get_file
-                context = {name: name, phase: :cache}
+            r.post ":name" do |name|
+              file = get_file
+              context = {name: name, phase: :cache}
 
-                json @uploader.upload(file, context)
-              end
-            else
-              r.get "presign" do
-                location = SecureRandom.hex(30) + r.params["extension"].to_s
-                options = presign.call(r) if presign.respond_to?(:call)
+              json @uploader.upload(file, context)
+            end unless presign
 
-                signature = @uploader.storage.presign(location, options || {})
+            r.get "presign" do
+              location = SecureRandom.hex(30) + request.params["extension"].to_s
+              options = presign.call(request) if presign.respond_to?(:call)
 
-                json Hash[url: signature.url, fields: signature.fields]
-              end
-            end
+              signature = @uploader.storage.presign(location, options || {})
+
+              json Hash[url: signature.url, fields: signature.fields]
+            end if presign
           end
         end
 
-        def json(object)
-          object.to_json
-        end
+        private
 
         # Halts the request if storage is not allowed.
         def allow_storage!(storage)
@@ -188,10 +213,20 @@ class Shrine
         def get_file
           file = require_param!("file")
           error! 400, "The \"file\" query parameter is not a file." if !(file.is_a?(Hash) && file.key?(:tempfile))
+          check_filesize!(file[:tempfile]) if max_size
 
           RackFile::UploadedFile.new(file)
         end
 
+        # If the file is too big, deletes the file and halts the request.
+        def check_filesize!(file)
+          if file.size > max_size
+            file.delete
+            megabytes = max_size.to_f / 1024 / 1024
+            error! 413, "The file is too big (maximum size is #{megabytes} MB)."
+          end
+        end
+
         # Loudly requires the param.
         def require_param!(name)
           request.params.fetch(name)
@@ -201,7 +236,13 @@ class Shrine
 
         # Halts the request with the error message.
         def error!(status, message)
-          request.halt status, {error: message}.to_json
+          response.status = status
+          response.write({error: message}.to_json)
+          request.halt
+        end
+
+        def json(object)
+          object.to_json
         end
 
         def shrine_class
@@ -215,6 +256,10 @@ class Shrine
         def presign
           shrine_class.opts[:direct_upload_presign]
         end
+
+        def max_size
+          shrine_class.opts[:direct_upload_max_size]
+        end
       end
     end