shrine 2.1.1 → 2.2.0

data/lib/shrine/plugins/direct_upload.rb

@@ -1,7 +1,5 @@
 require "roda"
-
 require "json"
-require "securerandom"
 
 class Shrine
   module Plugins
@@ -10,18 +8,33 @@ class Shrine
     #
     #     plugin :direct_upload
     #
-    # This is how you could mount the endpoint in a Rails application:
+    # The Roda endpoint provides two routes:
+    #
+    # * `POST /:storage/upload`
+    # * `GET /:storage/presign`
+    #
+    # This first route is for doing direct uploads to your app, the received
+    # file will be uploaded the underlying storage. The second route is for
+    # doing direct uploads to a 3rd-party service, it will return the URL where
+    # the file can be uploaded to, along with the necessary request parameters.
+    #
+    # This is how you can mount the endpoint in a Rails application:
     #
     #     Rails.application.routes.draw do
-    #       mount ImageUploader::UploadEndpoint => "/attachments/images"
+    #       mount ImageUploader::UploadEndpoint => "/images"
     #     end
     #
-    # 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/upload` route, which accepts a "file" query
-    # parameter, and returns the uploaded file in JSON format:
+    # Now your application will get `POST /images/cache/upload` and `GET
+    # /images/cache/presign` routes. Whether you upload files to your app or to
+    # to a 3rd-party service, you'll probably want to use a JavaScript file
+    # upload library like [jQuery-File-Upload] or [Dropzone].
+    #
+    # ## Uploads
     #
-    #     # POST /attachments/images/cache/upload (file upload)
+    # The upload route accepts a "file" query parameter, and returns the
+    # uploaded file in JSON format:
+    #
+    #     # POST /images/cache/upload
     #     {
     #       "id": "43kewit94.jpg",
     #       "storage": "cache",
@@ -32,14 +45,13 @@ class Shrine
     #       }
     #     }
     #
+    # Once you've uploaded the file, you can assign the result to the hidden
+    # attachment field in the form, or immediately send it to the server.
+    #
     # Note that the endpoint uploads the file standalone, without any knowledge
     # of the record, so `context[:record]` and `context[:name]` will be nil.
     #
-    # Once you've uploaded the file, you need to assign the result to the
-    # hidden attachment field in the form. There are many great JavaScript
-    # libraries for file uploads, most popular being [jQuery-File-Upload].
-    #
-    # ## Limiting filesize
+    # ### Limiting filesize
     #
     # 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
@@ -47,22 +59,15 @@ class Shrine
     #
     #     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 (currently only supported by Amazon S3). These uploads
-    # usually require extra information from the server, you can enable that
-    # route by passing `presign: true`:
+    # Note that this option doesn't affect presigned uploads, there you can
+    # apply filesize limit when generating a presign.
     #
-    #     plugin :direct_upload, presign: true
+    # ## Presigns
     #
-    # This will add `GET /:storage/presign`, and disable the default `POST
-    # /:storage/:name` (for security reasons) The response for that request
-    # looks something like this:
+    # The presign route returns the URL to the 3rd-party service to which you
+    # can upload the file, along with the necessary query parameters.
     #
+    #     # GET /images/cache/presign
     #     {
     #       "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",
     #       "fields" => {
@@ -75,39 +80,40 @@ 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 without an extension, but you can add it:
+    # If you want that the generated location includes a file extension, you
+    # can specify the `extension` query parameter: `GET
+    # /:storage/presign?extension=.png`.
     #
-    #     GET /cache/presign?extension=.png
+    # You can also completely change how the key is generated, with
+    # `:presign_location`:
     #
-    # You can change how the key is generated with `:presign_location`:
+    #     plugin :direct_upload, presign_location: ->(request) { "${filename}" }
     #
-    #     plugin :direct_upload, presign: true, presign_location: ->(request) { "${filename}" }
+    # This presign route internally calls `#presign` on the storage, which also
+    # accepts some service-specific options. You can generate these additional
+    # options per-request with `:presign_options`:
     #
-    # If you want additional options to be passed to Storage::S3#presign, you
-    # can pass `:presign_options` with a hash or a block (which gets yielded
-    # Roda's request object):
+    #     plugin :direct_upload, presign_options: {acl: "public-read"}
     #
-    #     plugin :direct_upload, presign: true, presign_options: {acl: "public-read"}
-    #
-    #     plugin :direct_upload, presign: true, presign_options: ->(request) do
+    #     plugin :direct_upload, presign_options: ->(request) do
     #       options = {}
     #       options[:content_length_range] = 0..(5*1024*1024)       # limit the filesize to 5 MB
     #       options[:content_type] = request.params["content_type"] # use "content_type" query parameter
     #       options
     #     end
     #
+    # Both `:presign_location` and `:presign_options` in their block versions
+    # are yielded an instance of [`Roda::Request`].
+    #
     # See the [Direct Uploads to S3] guide for further instructions on how to
     # hook the presigned uploads to a form.
     #
     # ### Testing presigns
     #
-    # If you want to test presigned uploads, but don't want to pay the
-    # performance cost of using Amazon S3 storage in tests, you can simply swap
-    # out S3 with a storage like FileSystem. The presigns will still get
-    # generated, but will simply point to this endpoint's upload route.
+    # If you want to test presigned uploads, but don't want to use Amazon S3 in
+    # tests for performance reasons, you can simply swap out S3 with a storage
+    # like FileSystem. The presigns will still get generated, but will simply
+    # point to this endpoint's upload route instead.
     #
     # ## Allowed storages
     #
@@ -117,18 +123,6 @@ class Shrine
     #
     #     plugin :direct_upload, allowed_storages: [:cache, :store]
     #
-    # ## Authentication
-    #
-    # If you want to authenticate the endpoint, you should be able to do it
-    # easily if your web framework has a good enough router. For example, in
-    # Rails you could add a `constraints` directive:
-    #
-    #     Rails.application.routes.draw do
-    #       constraints(->(r){r.env["warden"].authenticate!}) do
-    #         mount ImageUploader::UploadEndpoint => "/attachments/images"
-    #       end
-    #     end
-    #
     # ## Customizing endpoint
     #
     # Since the endpoint is a [Roda] app, it can be easily customized via
@@ -150,6 +144,7 @@ class Shrine
     #
     # [Roda]: https://github.com/jeremyevans/roda
     # [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+    # [Dropzone]: https://github.com/enyo/dropzone
     # [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
@@ -161,7 +156,6 @@ class Shrine
 
       def self.configure(uploader, opts = {})
         uploader.opts[:direct_upload_allowed_storages] = opts.fetch(:allowed_storages, uploader.opts.fetch(:direct_upload_allowed_storages, [:cache]))
-        uploader.opts[:direct_upload_presign] = opts.fetch(:presign, uploader.opts[:direct_upload_presign])
         uploader.opts[:direct_upload_presign_options] = opts.fetch(:presign_options, uploader.opts.fetch(:direct_upload_presign_options, {}))
         uploader.opts[:direct_upload_presign_location] = opts.fetch(:presign_location, uploader.opts[:direct_upload_presign_location])
         uploader.opts[:direct_upload_max_size] = opts.fetch(:max_size, uploader.opts[:direct_upload_max_size])
@@ -201,7 +195,7 @@ class Shrine
               uploaded_file = upload(file, context)
 
               json uploaded_file
-            end unless presign? && presign_storage?
+            end
 
             r.get "presign" do
               location = get_presign_location
@@ -210,7 +204,7 @@ class Shrine
               presign_data = generate_presign(location, options)
 
               json presign_data
-            end if presign?
+            end
           end
         end
 
@@ -226,14 +220,14 @@ class Shrine
 
         # Retrieves the context for the upload.
         def get_context(name)
-          context = {phase: :cache}
+          context = {action: :cache, phase: :cache}
 
           if name != "upload"
             warn "The \"POST /:storage/:name\" route of the direct_upload Shrine plugin is deprecated, and it will be removed in Shrine 3. Use \"POST /:storage/upload\" instead."
             context[:name] = name
           end
 
-          if presign? && !presign_storage?
+          unless presign_storage?
             context[:location] = request.params["key"]
           end
 
@@ -339,10 +333,6 @@ class Shrine
           shrine_class.opts[:direct_upload_allowed_storages]
         end
 
-        def presign?
-          shrine_class.opts[:direct_upload_presign]
-        end
-
         def presign_options
           shrine_class.opts[:direct_upload_presign_options]
         end

data/lib/shrine/plugins/download_endpoint.rb

@@ -25,7 +25,8 @@ class Shrine
     #     user.avatar.url #=> "/attachments/store/sdg0lsf8.jpg"
     #
     # :storages
-    # :  An array of storage keys which the download endpoint should be used for.
+    # :  An array of storage keys which the download endpoint should be applied
+    #    on.
     #
     # :prefix
     # :  The location where the download endpoint was mounted. If it was
@@ -110,17 +111,20 @@ class Shrine
               io = get_stream_io(id)
               response["Content-Length"] = io.size.to_s if io.size
 
-              chunks = Enumerator.new do |y|
+              body = Enumerator.new do |y|
                 if io.respond_to?(:each_chunk)
                   io.each_chunk { |chunk| y.yield(chunk) }
                 else
                   y.yield io.read(16*1024, buffer ||= "") until io.eof?
                 end
+              end
+
+              proxy = Rack::BodyProxy.new(body) do
                 io.close
                 io.delete if io.class.name == "Tempfile"
               end
 
-              r.halt response.finish_with_body(chunks)
+              r.halt response.finish_with_body(proxy)
             end
           end
         end

data/lib/shrine/plugins/logging.rb

@@ -102,7 +102,7 @@ class Shrine
 
           _log(
             action:       action,
-            phase:        context[:phase],
+            phase:        context[:action],
             uploader:     self.class,
             attachment:   context[:name],
             record_class: (context[:record].class if context[:record]),

data/lib/shrine/plugins/moving.rb

@@ -1,14 +1,15 @@
 class Shrine
   module Plugins
-    # The moving plugin makes so that when files are supposed to be uploaded,
-    # they are moved instead. For example, on FileSystem moving is
-    # instantaneous regardless of the filesize, so it's suitable for speeding
-    # up uploads for larger files.
+    # The moving plugin will *move* files to storages instead of copying them,
+    # when the storage supports it. For FileSystem this will issue a `mv`
+    # command, which is instantaneous regardless of the filesize, so in that
+    # case loading this plugin can significantly speed up the attachment
+    # process.
     #
     #     plugin :moving
     #
     # By default files will be moved whenever the storage supports it. If you
-    # want moving to happen only for certain storages, you can set `storages`:
+    # want moving to happen only for certain storages, you can set `:storages`:
     #
     #     plugin :moving, storages: [:cache]
     module Moving

data/lib/shrine/plugins/processing.rb

@@ -0,0 +1,50 @@
+class Shrine
+  module Plugins
+    # The process plugin allows you to declaratively define
+    # file processing for specified actions, allowing you to transform
+    #
+    #     def process(io, context)
+    #       if context[:action] == :store
+    #         # ...
+    #       end
+    #     end
+    #
+    # into
+    #
+    #     process(:store) do |io, context|
+    #       # ...
+    #     end
+    #
+    # The declarations are additive and inherited, so for the same action you
+    # can declare multiple blocks, and they will be performed in the same order,
+    # where output from previous will be input to next. You can return `nil`
+    # in any block to signal that no processing was performed and that the
+    # original file should be used.
+    module Processing
+      def self.configure(uploader)
+        uploader.opts[:processing] = {}
+      end
+
+      module ClassMethods
+        def process(action, &block)
+          opts[:processing][action] ||= []
+          opts[:processing][action] << block
+        end
+      end
+
+      module InstanceMethods
+        def process(io, context = {})
+          pipeline = opts[:processing][context[:action]] || []
+
+          result = pipeline.inject(io) do |input, processing|
+            instance_exec(input, context, &processing) || input
+          end
+
+          result unless result == io
+        end
+      end
+    end
+
+    register_plugin(:processing, Processing)
+  end
+end

data/lib/shrine/plugins/rack_file.rb

@@ -20,6 +20,9 @@ class Shrine
     # and this is what is passed to `Shrine#upload`.
     #
     #     plugin :rack_file
+    #
+    # Note that this plugin is not needed in Rails applications, because Rails
+    # already wraps Rack uploaded files in `ActionDispatch::Http::UploadedFile`.
     module RackFile
       module AttacherMethods
         # Checks whether a file is a Rack file hash, and in that case wraps the

data/lib/shrine/plugins/recache.rb

@@ -6,25 +6,21 @@ class Shrine
     # the user immediately sees them) and other versions you want to generate
     # in the promotion phase in a background job.
     #
-    # The phase will be set to `:recache`:
+    #     plugin :recache
+    #     plugin :processing
     #
-    #     class ImageUploader
-    #       plugin :recache
+    #     process(:recache) do |io, context|
+    #       # perform cheap processing
+    #     end
     #
-    #       def process(io, context)
-    #         case context[:phase]
-    #         when :recache
-    #           # generate cheap versions
-    #         when :store
-    #           # generate more expensive versions
-    #         end
-    #       end
+    #     process(:store) do |io, context|
+    #       # perform more expensive processing
     #     end
     module Recache
       module AttacherMethods
         def save
           if get && cache.uploaded?(get)
-            _set cache!(get, phase: :recache)
+            _set cache!(get, action: :recache)
           end
           super
         end

data/lib/shrine/plugins/remove_invalid.rb

@@ -10,7 +10,7 @@ class Shrine
           super
         ensure
           if errors.any? && cache.uploaded?(get)
-            _delete(get, phase: :validate)
+            _delete(get, action: :validate)
             _set(nil)
           end
         end

data/lib/shrine/plugins/restore_cached_data.rb

@@ -12,10 +12,8 @@ class Shrine
 
         def assign_cached(cached_file)
           uploaded_file(cached_file) do |file|
-            file.to_io # open
-            real_metadata = cache.extract_metadata(file, context)
+            real_metadata = file.open { cache.extract_metadata(file, context) }
             file.metadata.update(real_metadata)
-            file.close
           end
 
           super(cached_file)

data/lib/shrine/plugins/sequel.rb

@@ -41,6 +41,11 @@ class Shrine
     #       end
     #     end
     #
+    # If you don't want callbacks (e.g. you want to use the attacher object
+    # directly), you can turn them off:
+    #
+    #     plugin :sequel, callbacks: false
+    #
     # ## Validations
     #
     # Additionally, any Shrine validation errors will added to Sequel's
@@ -51,36 +56,52 @@ class Shrine
     #       include ImageUploader[:avatar]
     #       validates_presence_of :avatar
     #     end
+    #
+    # If you're doing validation separately from your models, you can turn off
+    # validations for your models:
+    #
+    #     plugin :sequel, validations: false
     module Sequel
+      def self.configure(uploader, opts = {})
+        uploader.opts[:sequel_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:sequel_callbacks, true))
+        uploader.opts[:sequel_validations] = opts.fetch(:validations, uploader.opts.fetch(:sequel_validations, true))
+      end
+
       module AttachmentMethods
         def included(model)
           super
 
           return unless model < ::Sequel::Model
 
-          module_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def validate
-              super
-              #{@name}_attacher.errors.each do |message|
-                errors.add(:#{@name}, message)
+          if shrine_class.opts[:sequel_validations]
+            module_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def validate
+                super
+                #{@name}_attacher.errors.each do |message|
+                  errors.add(:#{@name}, message)
+                end
               end
-            end
+            RUBY
+          end
 
-            def before_save
-              super
-              #{@name}_attacher.save if #{@name}_attacher.attached?
-            end
+          if shrine_class.opts[:sequel_callbacks]
+            module_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def before_save
+                super
+                #{@name}_attacher.save if #{@name}_attacher.attached?
+              end
 
-            def after_commit
-              super
-              #{@name}_attacher.finalize if #{@name}_attacher.attached?
-            end
+              def after_commit
+                super
+                #{@name}_attacher.finalize if #{@name}_attacher.attached?
+              end
 
-            def after_destroy_commit
-              super
-              #{@name}_attacher.destroy
-            end
-          RUBY
+              def after_destroy_commit
+                super
+                #{@name}_attacher.destroy
+              end
+            RUBY
+          end
         end
       end