shrine 2.6.1 → 2.7.0

data/doc/refile.md

@@ -193,20 +193,22 @@ multiple uploads directly to S3.
 
 ## Direct uploads
 
-Shrine borrows Refile's idea of direct uploads, and ships with a
-direct_upload plugin which provides an endpoint for uploading files and
-generating presigns.
+Shrine borrows Refile's idea of direct uploads, and ships with
+`upload_endpoint` and `presign_endpoint` plugins which provide endpoints for
+uploading files and generating presigns.
 
 ```rb
-Shrine.plugin :direct_upload
-# POST /:storage/upload
-# GET /:storage/presign
+Shrine.plugin :upload_endpoint
+Shrine.upload_endpoint(:cache) # Rack app that uploads files to specified storage
+
+Shrine.plugin :upload_endpoint
+Shrine.presign_endpoint(:cache) # Rack app that generates presigns for specified storage
 ```
 
 Unlike Refile, Shrine doesn't ship with complete JavaScript which you can just
 include to make it work. Instead, you're expected to use one of the excellent
-JavaScript libraries for generic file uploads like [jQuery-File-Upload]. See
-also the [Direct Uploads to S3] guide.
+JavaScript libraries for generic file uploads like [FineUploader], [Dropzone]
+or [jQuery-File-Upload]. See also the [Direct Uploads to S3] guide.
 
 ## Migrating from Refile
 
@@ -287,22 +289,21 @@ Shrine.storages = {
 
 #### `.app`, `.mount_point`, `.automount`
 
-The `direct_upload` plugin provides a subset of Refile's app's functionality,
-and you have to mount it in your framework's router:
+The `upload_endpoint` and `presign_endpoint` plugins provide methods for
+generating Rack apps, but you need to mount them explicitly:
 
 ```rb
 # config/routes.rb
 Rails.application.routes.draw do
-  # adds `POST /attachments/images/:storage/:name`
-  mount ImageUploader::UploadEndpoint => "/attachments/images"
+  # adds `POST /images/upload` endpoint
+  mount ImageUploader.upload_endpoint(:cache) => "/images/upload"
 end
 ```
 
 #### `.allow_uploads_to`
 
-```rb
-Shrine.plugin :direct_upload, storages: [:cache]
-```
+The `Shrine.upload_endpoint` and `Shrine.presign_endpoint` require you to
+specify the storage that will be used.
 
 #### `.logger`
 
@@ -477,6 +478,8 @@ Shrine.plugin :remote_url
 [shrine-uploadcare]: https://github.com/janko-m/shrine-uploadcare
 [Attache]: https://github.com/choonkeat/attache
 [image_processing]: https://github.com/janko-m/image_processing
+[FineUploader]: https://github.com/FineUploader/fine-uploader
+[Dropzone]: https://github.com/enyo/dropzone
 [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
 [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [demo app]: https://github.com/janko-m/shrine/tree/master/demo

data/doc/regenerating_versions.md

@@ -2,7 +2,7 @@
 
 While your app is serving uploads in production, you may realize that you want
 to change how your attachment's versions are generated. This means that, in
-addition to changing you processing code, you also need to reprocess the
+addition to changing your processing code, you also need to reprocess the
 existing attachments. This guide is aimed to help doing this migration with
 zero downtime and no unused files left in the main storage.
 

data/doc/securing_uploads.md

@@ -50,20 +50,20 @@ being uploaded to cache and the temporary directory.
 
 ### Limiting filesize in direct uploads
 
-If you're doing direct uploads with the `direct_upload` plugin, you can pass
-in the `:max_size` option, which will refuse too large files and automatically
-delete it from temporary storage.
+If you're doing direct uploads with the `upload_endpoint` plugin, you can pass
+in the `:max_size` option to reject files that are larger than the specified
+limit:
 
 ```rb
-plugin :direct_upload, max_size: 20*1024*1024 # 20 MB
+plugin :upload_endpoint, max_size: 20*1024*1024 # 20 MB
 ```
 
-This option doesn't apply to presigned uploads, if you're using S3 you can
-limit the filesize on presigning:
+If you're doing direct uploads to Amazon S3 using the `presign_endpoint`
+plugin, you can pass in the `:content_length_range` presign option:
 
 ```rb
-plugin :direct_upload, presign: ->(request) do
-  {content_length_range: 0..20*1024*1024}
+plugin :presign_endpoint, presign_options: -> (request) do
+  { content_length_range: 0..20*1024*1024 }
 end
 ```
 

data/doc/testing.md

@@ -58,16 +58,8 @@ Shrine.storages = {
 }
 ```
 
-Alternatively, if you're using Amazon S3 storage, in tests (and development)
-you can swap it out for [FakeS3]. You just need tell aws-sdk that instead of
-`s3.amazonaws.com` it should use the host of your FakeS3 server when generating
-URLs.
-
-```rb
-Shrine::Storage::S3.new(endpoint: "http://localhost:10000")
-```
-
-Note that for using FakeS3 you need aws-sdk version 2.2.25 or higher.
+Alternatively, if you're using Amazon S3 storage, in tests you can use
+[aws-sdk-ruby stubs].
 
 ## Test data
 
@@ -76,14 +68,14 @@ you can have the test file assigned dynamically when the record is created:
 
 ```rb
 factory :photo do
-  image File.open("test/files/image.jpg")
+  image { File.open("test/files/image.jpg") }
 end
 ```
 
 On the other hand, if you're setting up test data using Rails' YAML fixtures,
 you unfortunately won't be able to use them for assigning files. This is
 because Rails fixtures only allow assigning primitive data types, and don't
-allow you to specify Shrine attributes, you can only assign to columns
+allow you to specify Shrine attributes - you can only assign to columns
 directly.
 
 ## Background jobs
@@ -250,15 +242,29 @@ isolation.
 
 ## Direct upload
 
-In case you're doing direct uploads to S3 on production and staging
-environments, in development and test you might want to just store files on
-the filesystem for speed.
+If you've set up direct uploads to Amazon S3 (using the `presign_endpoint`
+plugin), in tests you'll probably want to just use filesystem or memory storage
+to avoid network requests.
+
+The easiest way to do that is to add an `upload_endpoint`, modify it so that it
+behaves like S3, and change `presign_endpoint` response to point to the upload
+endpoint. Here is how one could modify the test helper in a Rails application:
 
-In that case you can swap out S3 for FileSystem, and the `direct_upload` app
-should still continue to work without any changes. This is because Shrine
-detects that you're using a storage which isn't an external service, and in
-that case the presign endpoint returns an URL to the upload route that's also
-provided by the `direct_upload` app mounted in your routes.
+```rb
+# test/test_helper.rb
+
+# create and mount a fake S3 upload endpoint
+Shrine.plugin :upload_endpoint
+fake_s3 = Shrine.upload_endpoint(:cache, upload_context: -> (request) {
+  { location: request.params["key"].match(/^cache\//).post_match }
+})
+Rails.application.routes.prepend { mount fake_s3 => "/s3" }
+
+# override presigns to return URLs to the fake S3 upload endpoint
+Shrine.plugin :presign_endpoint, presign: -> (id, options, request) do
+  Struct.new(:url, :fields).new("#{request.base_url}/s3", { "key" => "cache/#{id}" })
+end
+```
 
 [DatabaseCleaner]: https://github.com/DatabaseCleaner/database_cleaner
 [shrine-memory]: https://github.com/janko-m/shrine-memory
@@ -267,4 +273,4 @@ provided by the `direct_upload` app mounted in your routes.
 [`#attach_file`]: http://www.rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions#attach_file-instance_method
 [Rack::Test]: https://github.com/brynary/rack-test
 [Rack::TestApp]: https://github.com/kwatch/rack-test_app
-[FakeS3]: https://github.com/jubos/fake-s3
+[aws-sdk-ruby stubs]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/ClientStubs.html

data/lib/shrine.rb

@@ -154,8 +154,8 @@ class Shrine
         #     class Photo
         #       include Shrine.attachment(:image) # creates a Shrine::Attachment object
         #     end
-        def attachment(name)
-          self::Attachment.new(name)
+        def attachment(name, **options)
+          self::Attachment.new(name, **options)
         end
         alias [] attachment
 
@@ -167,7 +167,6 @@ class Shrine
         def uploaded_file(object, &block)
           case object
           when String
-            deprecation("Giving a string to Shrine.uploaded_file is deprecated and won't be possible in Shrine 3. Use Attacher#uploaded_file instead.")
             uploaded_file(JSON.parse(object), &block)
           when Hash
             uploaded_file(self::UploadedFile.new(object), &block)
@@ -390,17 +389,22 @@ class Shrine
 
       module AttachmentMethods
         # Instantiates an attachment module for a given attribute name, which
-        # can then be included to a model class.
-        def initialize(name)
-          @name = name
-
-          # We store the attacher class so that the model can instantiate the
-          # correct attacher instance.
-          class_variable_set(:"@@#{name}_attacher_class", shrine_class::Attacher)
+        # can then be included to a model class. Second argument will be passed
+        # to an attacher module.
+        def initialize(name, **options)
+          @name    = name
+          @options = options
 
           module_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{name}_attacher
-              @#{name}_attacher ||= @@#{name}_attacher_class.new(self, :#{name})
+              @#{name}_attacher ||= (
+                attachments    = self.class.ancestors.grep(Shrine::Attachment)
+                attachment     = attachments.find { |mod| mod.attachment_name == :#{name} }
+                attacher_class = attachment.shrine_class::Attacher
+                options        = attachment.options
+
+                attacher_class.new(self, :#{name}, options)
+              )
             end
 
             def #{name}=(value)
@@ -417,18 +421,28 @@ class Shrine
           RUBY
         end
 
-        # Includes the attachment name in the output.
+        # Returns name of the attachment this module provides.
+        def attachment_name
+          @name
+        end
+
+        # Returns options that are to be passed to the Attacher.
+        def options
+          @options
+        end
+
+        # Returns class name with attachment name included.
         #
         #     Shrine[:image].to_s #=> "#<Shrine::Attachment(image)>"
         def to_s
-          "#<#{self.class.inspect}(#{@name})>"
+          "#<#{self.class.inspect}(#{attachment_name})>"
         end
 
-        # Includes the attachment name in the output.
+        # Returns class name with attachment name included.
         #
         #     Shrine[:image].inspect #=> "#<Shrine::Attachment(image)>"
         def inspect
-          "#<#{self.class.inspect}(#{@name})>"
+          "#<#{self.class.inspect}(#{attachment_name})>"
         end
 
         # Returns the Shrine class that this attachment's class is namespaced
@@ -459,7 +473,8 @@ class Shrine
         #       end
         #     end
         def validate(&block)
-          shrine_class.opts[:validate] = block
+          define_method(:validate_block, &block)
+          private :validate_block
         end
       end
 
@@ -519,7 +534,7 @@ class Shrine
         # Runs the validations defined by `Attacher.validate`.
         def validate
           errors.clear
-          instance_exec(&validate_block) if validate_block && get
+          validate_block if get
         end
 
         # Returns true if a new file has been attached.
@@ -629,11 +644,7 @@ class Shrine
         # Enhances `Shrine.uploaded_file` with the ability to recognize uploaded
         # files as JSON strings.
         def uploaded_file(object, &block)
-          if object.is_a?(String)
-            uploaded_file(JSON.parse(object), &block)
-          else
-            shrine_class.uploaded_file(object, &block)
-          end
+          shrine_class.uploaded_file(object, &block)
         end
 
         # The name of the attribute on the model instance that is used to store
@@ -661,9 +672,9 @@ class Shrine
           _set(uploaded_file)
         end
 
-        # The validation block registered with `Attacher.validate`.
+        # Performs validation actually.
+        # This method is redefined with `Attacher.validate`.
         def validate_block
-          shrine_class.opts[:validate]
         end
 
         # Converts the UploadedFile to a data hash and writes it to the

data/lib/shrine/plugins/activerecord.rb

@@ -40,6 +40,10 @@ class Shrine
     #       end
     #     end
     #
+    # Note that ActiveRecord currently has a [bug with transaction callbacks],
+    # so if you have any "after commit" callbacks, make sure to include Shrine's
+    # attachment module *after* they have all been defined.
+    #
     # If you don't want the attachment module to add any callbacks to the
     # model, and would instead prefer to call these actions manually, you can
     # disable callbacks:
@@ -49,8 +53,21 @@ class Shrine
     # ## Validations
     #
     # Additionally, any Shrine validation errors will be added to
-    # ActiveRecord's errors upon validation. If you want to validate presence
-    # of the attachment, you can do it directly on the model.
+    # ActiveRecord's errors upon validation. Note that Shrine validation
+    # messages don't have to be strings, they can also be symbols or symbols
+    # and options, which allows them to be internationalized together with
+    # other ActiveRecord validation messages.
+    #
+    # class MyUploader < Shrine
+    #   plugin :validation_helpers
+    #
+    #   Attacher.validate do
+    #     validate_max_size 256 * 1024**2, message: ->(max) { [:max_size, max: max] }
+    #   end
+    # end
+    #
+    # If you want to validate presence of the attachment, you can do it
+    # directly on the model.
     #
     #     class User < ActiveRecord::Base
     #       include ImageUploader::Attachment.new(:avatar)
@@ -61,6 +78,8 @@ class Shrine
     # model errors, you can disable it:
     #
     #     plugin :activerecord, validations: false
+    #
+    # [bug with transaction callbacks]: https://github.com/rails/rails/issues/14493
     module Activerecord
       def self.configure(uploader, opts = {})
         uploader.opts[:activerecord_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:activerecord_callbacks, true))
@@ -78,7 +97,7 @@ class Shrine
           model.class_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:activerecord_validations]
             validate do
               #{@name}_attacher.errors.each do |message|
-                errors.add(:#{@name}, message)
+                errors.add(:#{@name}, *message)
               end
             end
           RUBY

data/lib/shrine/plugins/copy.rb

@@ -19,7 +19,7 @@ class Shrine
         def initialize(*)
           super
 
-          module_eval <<-RUBY
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1
             def initialize_copy(record)
               super
               @#{@name}_attacher = nil # reload the attacher

data/lib/shrine/plugins/data_uri.rb

@@ -1,6 +1,6 @@
 require "base64"
 require "strscan"
-require "cgi/util"
+require "cgi"
 require "stringio"
 require "forwardable"
 
@@ -169,7 +169,7 @@ class Shrine
         # Returns contents of the file base64-encoded.
         def base64
           binary = open { |io| io.read }
-          result = Base64.encode64(binary).chomp
+          result = Base64.strict_encode64(binary)
           binary.clear # deallocate string
           result
         end
@@ -189,7 +189,7 @@ class Shrine
         end
 
         extend Forwardable
-        delegate Shrine::IO_METHODS.keys => :@io
+        delegate [:read, :size, :rewind, :eof?] => :@io
 
         def close
           @io.close

data/lib/shrine/plugins/determine_mime_type.rb

@@ -30,7 +30,12 @@ class Shrine
     #
     # :mime_types
     # : Uses the [mime-types] gem to determine the MIME type from the file
-    #   *extension*. Note that unlike other solutions, this analyzer is not
+    #   extension. Note that unlike other solutions, this analyzer is not
+    #   guaranteed to return the actual MIME type of the file.
+    #
+    # :mini_mime
+    # : Uses the [mini_mime] gem to determine the MIME type from the file
+    #   extension. Note that unlike other solutions, this analyzer is not
     #   guaranteed to return the actual MIME type of the file.
     #
     # :default
@@ -65,6 +70,7 @@ class Shrine
     # [ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic
     # [mimemagic]: https://github.com/minad/mimemagic
     # [mime-types]: https://github.com/mime-types/ruby-mime-types
+    # [mini_mime]: https://github.com/discourse/mini_mime
     module DetermineMimeType
       def self.configure(uploader, opts = {})
         uploader.opts[:mime_type_analyzer] = opts.fetch(:analyzer, uploader.opts.fetch(:mime_type_analyzer, :file))
@@ -115,7 +121,7 @@ class Shrine
       end
 
       class MimeTypeAnalyzer
-        SUPPORTED_TOOLS = [:file, :filemagic, :mimemagic, :mime_types]
+        SUPPORTED_TOOLS = [:file, :filemagic, :mimemagic, :mime_types, :mini_mime]
         MAGIC_NUMBER    = 256 * 1024
 
         def initialize(tool)
@@ -125,8 +131,11 @@ class Shrine
         end
 
         def call(io)
+          return nil if io.eof? # empty file doesn't have a MIME type
+
           mime_type = send(:"extract_with_#{@tool}", io)
           io.rewind
+
           mime_type
         end
 
@@ -135,8 +144,8 @@ class Shrine
         def extract_with_file(io)
           require "open3"
 
-          cmd = ["file", "--mime-type", "--brief", "-"]
-          options = {stdin_data: io.read(MAGIC_NUMBER), binmode: true}
+          cmd     = %W[file --mime-type --brief -]
+          options = { stdin_data: io.read(MAGIC_NUMBER), binmode: true }
 
           begin
             stdout, stderr, status = Open3.capture3(*cmd, options)
@@ -168,15 +177,20 @@ class Shrine
         end
 
         def extract_with_mime_types(io)
-          begin
-            require "mime/types/columnar"
-          rescue LoadError
-            require "mime/types"
-          end
+          require "mime/types"
 
           if filename = extract_filename(io)
             mime_type = MIME::Types.of(filename).first
-            mime_type.to_s if mime_type
+            mime_type.content_type if mime_type
+          end
+        end
+
+        def extract_with_mini_mime(io)
+          require "mini_mime"
+
+          if filename = extract_filename(io)
+            info = MiniMime.lookup_by_filename(filename)
+            info.content_type if info
           end
         end