shrine 0.9.0 → 1.0.0

data/lib/shrine.rb

@@ -157,7 +157,7 @@ class Shrine
         # model class.  Example:
         #
         #     class User
-        #       include Shrine[:avatar] # alias for `Shrine.attachment[:avatar]`
+        #       include Shrine[:avatar] # alias for `Shrine.attachment(:avatar)`
         #     end
         def attachment(name)
           self::Attachment.new(name)
@@ -184,30 +184,6 @@ class Shrine
             raise Error, "cannot convert #{object.inspect} to a #{self}::UploadedFile"
           end
         end
-
-        # Delete a Shrine::UploadedFile.
-        #
-        #     Shrine.delete(uploaded_file)
-        def delete(uploaded_file, context = {})
-          uploader_for(uploaded_file).delete(uploaded_file, context)
-        end
-
-        # Checks if the object is a valid IO by checking that it responds to
-        # `#read`, `#eof?`, `#rewind`, `#size` and `#close`, otherwise raises
-        # Shrine::InvalidFile.
-        def io!(io)
-          missing_methods = IO_METHODS.reject do |m, a|
-            io.respond_to?(m) && [a.count, -1].include?(io.method(m).arity)
-          end
-
-          raise InvalidFile.new(io, missing_methods) if missing_methods.any?
-        end
-
-        # Instantiates the Shrine uploader instance for this file.
-        def uploader_for(uploaded_file)
-          uploaders = storages.keys.map { |key| new(key) }
-          uploaders.find { |uploader| uploader.uploaded?(uploaded_file) }
-        end
       end
 
       module InstanceMethods
@@ -272,7 +248,7 @@ class Shrine
           uploaded_file.storage_key == storage_key.to_s
         end
 
-        # Called by `Shrine.delete`.
+        # Deletes the given uploaded file.
         def delete(uploaded_file, context = {})
           _delete(uploaded_file, context)
           uploaded_file
@@ -345,7 +321,7 @@ class Shrine
           )
         end
 
-        # Removes the file. Called by `Shrine.delete`.
+        # Removes the file. Called by #delete.
         def _delete(uploaded_file, context)
           remove(uploaded_file, context)
         end
@@ -376,9 +352,15 @@ class Shrine
           process(io, context)
         end
 
-        # Calls `Shrine#io!`.
+        # Checks if the object is a valid IO by checking that it responds to
+        # `#read`, `#eof?`, `#rewind`, `#size` and `#close`, otherwise raises
+        # Shrine::InvalidFile.
         def _enforce_io(io)
-          self.class.io!(io)
+          missing_methods = IO_METHODS.reject do |m, a|
+            io.respond_to?(m) && [a.count, -1].include?(io.method(m).arity)
+          end
+
+          raise InvalidFile.new(io, missing_methods) if missing_methods.any?
         end
 
         # Generates a UID to use in location for uploaded files.
@@ -459,7 +441,7 @@ class Shrine
         # validation.  Example:
         #
         #     Shrine::Attacher.validate do
-        #       if get.size > 5.megabytes
+        #       if get.size > 5*1024*1024
         #         errors << "is too big (max is 5 MB)"
         #       end
         #     end
@@ -484,7 +466,7 @@ class Shrine
         # file (e.g. when it persisted after validation errors).
         # Otherwise it assumes that it's an IO object and caches it.
         def assign(value)
-          if value.is_a?(String) || value.is_a?(Hash)
+          if value.is_a?(String)
             assign_cached(value) unless value == ""
           else
             uploaded_file = cache!(value, phase: :cache) if value
@@ -495,7 +477,7 @@ class Shrine
         # Assigns a Shrine::UploadedFile, runs validation and schedules the
         # old file for deletion.
         def set(uploaded_file)
-          @old_attachment = get unless get == uploaded_file
+          @old = get unless get == uploaded_file
           _set(uploaded_file)
           validate
 
@@ -507,20 +489,30 @@ class Shrine
           uploaded_file(read) if read
         end
 
+        # Returns true if a new file has been attached.
+        def attached?
+          instance_variable_defined?("@old")
+        end
+
         # Plugins can override this if they want something to be done on save.
         def save
         end
 
+        # Deletes the old file and promotes the new one. Typically this should
+        # be called after saving.
+        def finalize
+          replace
+          _promote
+        end
+
         # Calls #promote if attached file is cached.
         def _promote
           promote(get) if promote?(get)
         end
 
-        # Promotes a cached file to store, afterwards deleting the cached file.
-        # It does the promoting only if the cached file matches the current
-        # one. This check is done so that it can safely be used in background
-        # jobs in case the user quickly changes their mind and replaces the
-        # attachment before the old one was finished promoting.
+        # Promotes a cached file to store, taking into account to check whether
+        # the attachment has changed in the meanwhile. Afterwards the cached
+        # file is deleted.
         def promote(cached_file)
           stored_file = store!(cached_file, phase: :store)
           unless changed?(cached_file)
@@ -528,21 +520,20 @@ class Shrine
           else
             delete!(stored_file, phase: :stored)
           end
-          delete!(cached_file, phase: :cached)
         end
 
-        # Deletes the attachment that was replaced.  Typically this should be
-        # called after saving, to ensure that the file is deleted only after
-        # the record has been successfuly saved.
+        # Deletes the attachment that was replaced, and is called after saving
+        # by ORM integrations. If also removes `@old` so that #save and #finalize
+        # don't get called for the current attachment anymore.
         def replace
-          delete!(@old_attachment, phase: :replaced) if @old_attachment
-          @old_attachment = nil
+          delete!(@old, phase: :replaced) if @old && !cache.uploaded?(@old)
+          remove_instance_variable("@old")
         end
 
         # Deletes the attachment. Typically this should be called after
         # destroying a record.
         def destroy
-          delete!(get, phase: :destroyed) if get
+          delete!(get, phase: :destroyed) if get && !cache.uploaded?(get)
         end
 
         # Returns the URL to the attached file (internally calls `#url` on the
@@ -600,9 +591,9 @@ class Shrine
           store.upload(io, context.merge(phase: phase))
         end
 
-        # Deletes the file (calls `Shrine.delete`).
+        # Deletes the file (calls `Shrine#delete`).
         def delete!(uploaded_file, phase:)
-          shrine_class.delete(uploaded_file, context.merge(phase: phase))
+          store.delete(uploaded_file, context.merge(phase: phase))
         end
 
         # Delegates to `Shrine#default_url`.
@@ -792,6 +783,11 @@ class Shrine
           self.class.shrine_class
         end
 
+        # Show only the data hash in inspect output.
+        def inspect
+          "#{to_s.chomp(">")} @data=#{data.inspect}>"
+        end
+
         private
 
         def io

data/lib/shrine/plugins/activerecord.rb

@@ -14,9 +14,16 @@ class Shrine
     # * `after_commit on: [:create, :update]` -- Promotes the attachment, deletes replaced ones.
     # * `after_commit on: [:destroy]` -- Deletes the attachment.
     #
-    # Note that if your tests are wrapped in transactions, the `after_commit`
-    # callbacks won't get called, so in order to test uploading you should first
-    # disable these transactions for those tests.
+    # Note that ActiveRecord versions 3.x and 4.x have errors automatically
+    # silenced in hooks, which can make debugging more difficult, so it's
+    # recommended that you enable errors:
+    #
+    #     # This is the default in ActiveRecord 5
+    #     ActiveRecord::Base.raise_in_transactional_callbacks = true
+    #
+    # Also note that if your tests are wrapped in transactions, the
+    # `after_commit` callbacks won't get called, so in order to test uploading
+    # you should first disable these transactions for those tests.
     #
     # If you want to put some parts of this lifecycle into a background job, see
     # the background_helpers plugin.
@@ -42,12 +49,11 @@ class Shrine
             end
 
             before_save do
-              #{@name}_attacher.save
+              #{@name}_attacher.save if #{@name}_attacher.attached?
             end
 
             after_commit on: [:create, :update] do
-              #{@name}_attacher.replace
-              #{@name}_attacher._promote
+              #{@name}_attacher.finalize if #{@name}_attacher.attached?
             end
 
             after_commit on: :destroy do

data/lib/shrine/plugins/background_helpers.rb

@@ -88,7 +88,7 @@ class Shrine
         end
 
         # If block is passed in, stores it to be called on deletion. Otherwise
-        # resolves data into objects and calls Shrine.delete.
+        # resolves data into objects and calls `Shrine#delete`.
         def delete(data = nil, &block)
           if block
             shrine_class.opts[:background_delete] = block
@@ -98,11 +98,11 @@ class Shrine
             record.id = record_id
 
             name, phase = data["attachment"], data["phase"]
-            shrine_class = record.send("#{name}_attacher").shrine_class
-            uploaded_file = shrine_class.uploaded_file(data["uploaded_file"])
+            attacher = record.send("#{name}_attacher")
+            uploaded_file = attacher.uploaded_file(data["uploaded_file"])
             context = {name: name.to_sym, record: record, phase: phase.to_sym}
 
-            shrine_class.delete(uploaded_file, context)
+            attacher.store.delete(uploaded_file, context)
           end
         end
       end
@@ -137,7 +137,7 @@ class Shrine
 
             instance_exec(data, &background_delete)
           else
-            super
+            super(uploaded_file, phase: phase)
           end
         end
       end

data/lib/shrine/plugins/default_storage.rb

@@ -29,7 +29,7 @@ class Shrine
             options[:store] = store
           end
 
-          super
+          super(record, name, **options)
         end
       end
     end

data/lib/shrine/plugins/default_url_options.rb

@@ -0,0 +1,31 @@
+class Shrine
+  module Plugins
+    # The default_url_options plugin allows you to specify URL options that
+    # will be applied by default for uploaded files of specified storages.
+    #
+    #     plugin :default_url_options, store: {download: true}
+    #
+    # The default options are merged with options passed to `UploadedFile#url`,
+    # and the latter will always have precedence over default options.
+    module DefaultUrlOptions
+      def self.configure(uploader, **options)
+        uploader.opts[:default_url_options] = options
+      end
+
+      module FileMethods
+        def url(**options)
+          super(default_options.merge(options))
+        end
+
+        private
+
+        def default_options
+          options = shrine_class.opts[:default_url_options]
+          options[storage_key.to_sym] || {}
+        end
+      end
+    end
+
+    register_plugin(:default_url_options, DefaultUrlOptions)
+  end
+end

data/lib/shrine/plugins/determine_mime_type.rb

@@ -64,6 +64,10 @@ class Shrine
         uploader.opts[:mime_type_analyzer] = analyzer
       end
 
+      # How many bytes we have to read to get the magic file header which
+      # contains the MIME type of the file.
+      MAGIC_NUMBER = 1024
+
       module InstanceMethods
         # If a Shrine::UploadedFile was given, it returns its MIME type, since
         # that value was already determined by this analyzer. Otherwise it calls
@@ -86,16 +90,22 @@ class Shrine
         # if it's a file, because even though the utility accepts standard
         # input, it would mean that we have to read the whole file in memory.
         def _extract_mime_type_with_file(io)
+          cmd = ["file", "--mime-type", "--brief"]
+
           if io.respond_to?(:path)
-            mime_type, _ = Open3.capture2("file", "-b", "--mime-type", io.path)
-            mime_type.strip unless mime_type.empty?
+            mime_type, _ = Open3.capture2(*cmd, io.path)
+          else
+            mime_type, _ = Open3.capture2(*cmd, "-", stdin_data: io.read(MAGIC_NUMBER), binmode: true)
+            io.rewind
           end
+
+          mime_type.strip unless mime_type.empty?
         end
 
         # Uses the ruby-filemagic gem to magically extract the MIME type.
         def _extract_mime_type_with_filemagic(io)
           filemagic = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
-          data = io.read(1024); io.rewind
+          data = io.read(MAGIC_NUMBER); io.rewind
           filemagic.buffer(data)
         end
 

data/lib/shrine/plugins/direct_upload.rb

@@ -1,7 +1,6 @@
 require "roda"
 
 require "json"
-require "forwardable"
 require "securerandom"
 
 class Shrine
@@ -9,7 +8,7 @@ class Shrine
     # The direct_upload plugin provides a Rack endpoint (implemented in [Roda])
     # which you can use to implement AJAX uploads.
     #
-    #     plugin :direct_upload, max_size: 20*1024*1024
+    #     plugin :direct_upload
     #
     # This is how you could mount the endpoint in a Rails application:
     #
@@ -20,35 +19,23 @@ class Shrine
     #
     # 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:
+    # `POST /attachments/images/:storage/:name` route, which accepts a `file`
+    # query parameter, and returns the uploaded file in JSON format:
     #
-    #     $ curl -F "file=@/path/to/avatar.jpg" localhost:3000/attachments/images/cache/avatar
-    #     # {"id":"43kewit94.jpg","storage":"cache","metadata":{...}}
-    #
-    # The endpoint returns all responses in JSON format. There are many great
-    # JavaScript libraries for AJAX file uploads, so for example if we have
-    # this form:
-    #
-    #     <%= form_for @user do |f| %>
-    #       <%= f.hidden_field :avatar, value: @user.avatar_data %>
-    #       <%= f.file_field :avatar %>
-    #     <% end %>
-    #
-    # this is how we could hook up [jQuery-File-Upload] to our direct upload
-    # endpoint:
-    #
-    #     $('[type="file"]').fileupload({
-    #       url: '/attachments/images/cache/avatar',
-    #       paramName: 'file',
-    #       done: function(e, data) { $(this).prev().value(data.result) }
-    #     });
+    #     # POST /attachments/images/cache/avatar
+    #     {
+    #       "id": "43kewit94.jpg",
+    #       "storage": "cache",
+    #       "metadata": {
+    #         "size": 384393,
+    #         "filename": "nature.jpg",
+    #         "mime_type": "image/jpeg"
+    #       }
+    #     }
     #
-    # Now whenever a file gets chosen, the upload will automatically start in
-    # the background. It's typically good to show a progress bar to the user,
-    # which jQuery-File-Upload [supports]. After the upload has finished, the
-    # uploaded file JSON is written to the hidden field, and will be sent on
-    # form submit.
+    # 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.
     #
     # ## Presigned
     #
@@ -78,33 +65,29 @@ 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. `GET /:storage/presign` accepts additional parameters:
-    #
-    # :extension
-    # : The extension of the file being uploaded (e.g ".jpg").
+    # generated randomly, but you can add an extension to it:
     #
-    # :content_type
-    # : Sets the Content-Type header for the uploaded file on S3.
-    #
-    # Example:
-    #
-    #     GET /cache/presign?content_type=image/jpeg
     #     GET /cache/presign?extension=.png
     #
-    # ## Constraints
+    # If you want additional options to be passed to Storage::S3#presign, you
+    # can pass a block to `:presign` and return additional options:
     #
-    # Note that the direct upload doesn't run validations, they are only run
-    # when attached to the record. If you want to limit the MIME type of files,
-    # you could add an ["accept" attribute] to your file field. You could also
-    # add client side validations for the maximum file size.
+    #     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",
+    #       }
+    #     end
     #
-    # It's encouraged that you set the `:max_size` option for the endpoint.
-    # Once set, when a file that is too big is uploaded, the endpoint will
-    # automatically delete the file and return a 413 response.  However, if for
-    # whatever reason you don't want to impose a limit on filesize, you can set
-    # the option to nil:
+    # 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, max_size: nil
+    #     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`
     #
     # ## Allowed storages
     #
@@ -130,10 +113,14 @@ class Shrine
     # [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
     module DirectUpload
-      def self.configure(uploader, allowed_storages: [:cache], max_size:, presign: nil)
+      def self.load_dependencies(uploader, *)
+        uploader.plugin :rack_file
+      end
+
+      def self.configure(uploader, allowed_storages: [:cache], presign: nil, **)
         uploader.opts[:direct_upload_allowed_storages] = allowed_storages
-        uploader.opts[:direct_upload_max_size] = max_size
         uploader.opts[:direct_upload_presign] = presign
       end
 
@@ -165,23 +152,23 @@ class Shrine
             allow_storage!(storage_key)
             @uploader = shrine_class.new(storage_key.to_sym)
 
-            r.post ":name" do |name|
-              file = get_file
-              context = {name: name, phase: :cache}
+            unless presign
+              r.post ":name" do |name|
+                file = get_file
+                context = {name: name, phase: :cache}
 
-              json @uploader.upload(file, context)
-            end unless presign?
+                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)
 
-            r.get "presign" do
-              location = SecureRandom.hex(30).to_s + r.params["extension"].to_s
-              options = {}
-              options[:content_length_range] = 0..max_size if max_size
-              options[:content_type] = r.params["content_type"] if r.params["content_type"]
+                signature = @uploader.storage.presign(location, options || {})
 
-              signature = @uploader.storage.presign(location, options)
-
-              json Hash[url: signature.url, fields: signature.fields]
-            end if presign?
+                json Hash[url: signature.url, fields: signature.fields]
+              end
+            end
           end
         end
 
@@ -201,18 +188,8 @@ 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.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
+          RackFile::UploadedFile.new(file)
         end
 
         # Loudly requires the param.
@@ -235,38 +212,10 @@ class Shrine
           shrine_class.opts[:direct_upload_allowed_storages]
         end
 
-        def max_size
-          shrine_class.opts[:direct_upload_max_size]
-        end
-
-        def presign?
+        def presign
           shrine_class.opts[:direct_upload_presign]
         end
       end
-
-      # This is used to wrap the Rack hash into an IO-like object which Shrine
-      # can upload.
-      class RackFile
-        attr_reader :original_filename, :content_type
-        attr_accessor :tempfile
-
-        def initialize(tempfile:, filename: nil, type: nil, **)
-          @tempfile          = tempfile
-          @original_filename = filename
-          @content_type      = type
-        end
-
-        def path
-          @tempfile.path
-        end
-
-        def to_io
-          @tempfile
-        end
-
-        extend Forwardable
-        delegate Shrine::IO_METHODS.keys => :@tempfile
-      end
     end
 
     register_plugin(:direct_upload, DirectUpload)