shrine 2.8.0 → 2.9.0

data/doc/multiple_files.md

@@ -87,11 +87,10 @@ to add the `multiple` attribute to the file field.
 <input type="file" multiple name="file">
 ```
 
-You can then use a generic JavaScript file upload library like
-[jQuery-File-Upload], [Dropzone] or [FineUploader] to asynchronously upload
-each of the selected files to your app or to an external service. See the
-`upload_endpoint` and `presign_endpoint` plugins, and [Direct Uploads to S3]
-guide for more details.
+On the client side you can then asynchronously upload each of the selected
+files to a direct upload endpoint. See documenation for the `upload_endpoint`
+and `presign_endpoint` plugins, as well as the [Direct Uploads to S3] guide for
+more details.
 
 After each upload finishes, you can generate a nested hash for the new
 associated record, and write the uploaded file JSON to the attachment field:
@@ -113,7 +112,4 @@ automatically take care of the attachment management.
 
 [`Sequel::Model.nested_attributes`]: http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/NestedAttributes.html
 [`ActiveRecord::Base.accepts_nested_attributes_for`]: http://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html
-[jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
-[Dropzone]: https://github.com/enyo/dropzone
-[FineUploader]: https://github.com/FineUploader/fine-uploader
 [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html

data/doc/paperclip.md

@@ -9,8 +9,7 @@ consists of three parts:
 
 ## Storages
 
-While in Paperclip you configure storage in the model, a Shrine storage is just
-a class which you configure individually:
+In Paperclip the storage is configure inside the global options:
 
 ```rb
 class Photo < ActiveRecord::Base
@@ -20,24 +19,24 @@ class Photo < ActiveRecord::Base
       bucket:            "my-bucket",
       access_key_id:     "abc",
       secret_access_key: "xyz",
-    },
-    s3_host_alias: "http://abc123.cloudfront.net",
+    }
 end
 ```
+
+In contrast, a Shrine storage is just a class which you configure individually:
+
 ```rb
 Shrine.storages[:store] = Shrine::Storage::S3.new(
   bucket:            "my-bucket",
   access_key_id:     "abc",
   secret_access_key: "xyz",
 )
-
-Shrine.plugin :default_url_options, store: {host: "http://abc123.cloudfront.net"}
 ```
 
 Paperclip doesn't have a concept of "temporary" storage, so it cannot retain
 uploaded files in case of validation errors, and [direct S3 uploads] cannot be
-implemented in a safe way. Shrine conceptually separates a "temporary" and
-"permanent" storage:
+implemented in a safe way. Shrine uses separate "temporary" and "permanent"
+storage for attaching files:
 
 ```rb
 Shrine.storages = {
@@ -285,9 +284,6 @@ can be done by including the below module to all models that have Paperclip
 attachments:
 
 ```rb
-require "fastimage"
-require "mime/types"
-
 module PaperclipShrineSynchronization
   def self.included(model)
     model.before_save do
@@ -328,8 +324,8 @@ module PaperclipShrineSynchronization
       metadata: {
         size: attachment.size,
         filename: attachment.original_filename,
-        content_type: attachment.content_type,
-      },
+        mime_type: attachment.content_type,
+      }
     }
   end
 
@@ -337,25 +333,10 @@ module PaperclipShrineSynchronization
   # files on the filesystem, make sure to subtract the appropriate part
   # from the path assigned to `:id`.
   def style_to_shrine_data(style)
-    attachment = style.attachment
-    path = attachment.path(style.name)
-    url = attachment.url(style.name)
-    file = attachment.instance_variable_get("@queued_for_write")[style.name]
-
-    size   = file.size if file
-    size ||= FastImage.new(url).content_length # OPTIONAL (makes an HTTP request)
-    size ||= File.size(path) if File.exist?(path)
-    filename = File.basename(path)
-    mime_type = MIME::Types.type_for(path).first.to_s.presence
-
     {
       storage: :store,
-      id: path,
-      metadata: {
-        size: size,
-        filename: filename,
-        mime_type: mime_type,
-      }
+      id: style.attachment.path(style.name),
+      metadata: {}
     }
   end
 end
@@ -385,6 +366,19 @@ instead of Paperclip, using equivalent Shrine storages. For help with
 translating the code from Paperclip to Shrine, you can consult the reference
 below.
 
+You'll notice that Shrine metadata will be absent from the migrated files' data
+(specifically versions). You can run a script that will fill in any missing
+metadata defined in your Shrine uploader:
+
+```rb
+Shrine.plugin :refresh_metadata
+
+Photo.find_each do |photo|
+  attachment = ImageUploader.uploaded_file(photo.image, &:refresh_metadata!)
+  photo.update(image_data: attachment.to_json)
+end
+```
+
 ## Paperclip to Shrine direct mapping
 
 ### `has_attached_file`
@@ -502,9 +496,82 @@ user.avatar.id #=> "users/342/avatar/398543qjfdsf.jpg"
 
 #### `#reprocess!`
 
-Shrine doesn't have an equivalent to this, but the [Regenerating versions]
+Shrine doesn't have an equivalent to this, but the [Reprocessing versions]
 guide provides some useful tips on how to do this.
 
+### `Paperclip::Storage::S3`
+
+The built-in [`Shrine::Storage::S3`] storage is a direct replacement for
+`Paperclip::Storage::S3`.
+
+#### `:s3_credentials`, `:s3_region`, `:bucket`
+
+The Shrine storage accepts `:access_key_id`, `:secret_access_key`, `:region`,
+and `:bucket` options in the initializer:
+
+```rb
+Shrine::Storage::S3.new(
+  access_key_id:     "...",
+  secret_access_key: "...",
+  region:            "...",
+  bucket:            "...",
+)
+```
+
+#### `:s3_headers`
+
+The object data can be configured via the `:upload_options` hash:
+
+```rb
+Shrine::Storage::S3.new(upload_options: {content_disposition: "attachment"}, **options)
+```
+
+You can use the `upload_options` plugin to set upload options dynamically.
+
+#### `:s3_permissions`
+
+The object permissions can be configured with the `:acl` upload option:
+
+```rb
+Shrine::Storage::S3.new(upload_options: {acl: "private"}, **options)
+```
+
+You can use the `upload_options` plugin to set upload options dynamically.
+
+#### `:s3_metadata`
+
+The object metadata can be configured with the `:metadata` upload option:
+
+```rb
+Shrine::Storage::S3.new(upload_options: {metadata: {"key" => "value"}}, **options)
+```
+
+You can use the `upload_options` plugin to set upload options dynamically.
+
+#### `:s3_protocol`, `:s3_host_alias`, `:s3_host_name`
+
+The `#url` method accepts a `:host` option for specifying a CDN host. You can
+use the `default_url_options` plugin to set it by default:
+
+```rb
+Shrine.plugin :default_url_options, store: {host: "http://abc123.cloudfront.net"}
+```
+
+#### `:path`
+
+The `#upload` method accepts the destination location as the second argument.
+
+```rb
+s3 = Shrine::Storage::S3.new(**options)
+s3.upload(io, "object/destination/path")
+```
+
+#### `:url`
+
+The Shrine storage has no replacement for the `:url` Paperclip option, and it
+isn't needed.
+
 [file]: http://linux.die.net/man/1/file
 [Reprocessing versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html
 [direct S3 uploads]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[`Shrine::Storage::S3`]:  http://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html

data/doc/refile.md

@@ -206,9 +206,9 @@ Shrine.presign_endpoint(:cache) # Rack app that generates presigns for specified
 ```
 
 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 [FineUploader], [Dropzone]
-or [jQuery-File-Upload]. See also the [Direct Uploads to S3] guide.
+include to make it work. However, [Uppy] is an excellent JavaScript file upload
+library that integrates wonderfully with Shrine, see the [demo app] for a
+complete example.
 
 ## Migrating from Refile
 
@@ -478,9 +478,7 @@ 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
+[Uppy]: https://uppy.io
 [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
 [Multiple Files]: http://shrinerb.com/rdoc/files/doc/multiple_files_md.html

data/doc/testing.md

@@ -63,7 +63,7 @@ Alternatively, if you're using Amazon S3 storage, in tests you can use
 
 ## Test data
 
-If you're creating test data dynamically using libraries like [factory_girl],
+If you're creating test data dynamically using libraries like [factory_bot],
 you can have the test file assigned dynamically when the record is created:
 
 ```rb
@@ -240,37 +240,40 @@ end
 This also has the benefit of allowing you to test `ImageThumbnailsGenerator` in
 isolation.
 
-## Direct upload
+## Direct S3 uploads
 
-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.
+If you want to do direct uploads to Amazon S3 in production, in development and
+tests you'll probably want to keep using filesystem storage to avoid making
+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:
+The simplest way to do that is to use [Minio]. Minio is an open source object
+storage server with Amazon S3 compatible API. If you're on a Mac you can
+install it with Homebrew:
 
-```rb
-# test/test_helper.rb
+```
+$ brew install minio
+$ minio server data/
+```
 
-# 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" }
+Then you can open the Minio UI in the browser and create a new bucket. Once
+you've done that, all that's left to do is point aws-sdk-s3 to your Minio
+server:
 
-# 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
+```
+Shrine::Storage::S3.new(
+  access_key_id:     "MINIO_ACCESS_KEY_ID",
+  secret_access_key: "MINIO_SECRET_ACCESS_KEY",
+  bucket:            "MINIO_BUCKET",
+  region:            "us-east-1",
+)
 ```
 
 [DatabaseCleaner]: https://github.com/DatabaseCleaner/database_cleaner
 [shrine-memory]: https://github.com/janko-m/shrine-memory
-[factory_girl]: https://github.com/thoughtbot/factory_girl
+[factory_bot]: https://github.com/thoughtbot/factory_bot
 [Capybara]: https://github.com/jnicklas/capybara
 [`#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
 [aws-sdk-ruby stubs]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/ClientStubs.html
+[Minio]: https://minio.io

data/lib/shrine.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "shrine/version"
 
 require "securerandom"
@@ -154,8 +156,8 @@ class Shrine
         #     class Photo
         #       include Shrine.attachment(:image) # creates a Shrine::Attachment object
         #     end
-        def attachment(name, **options)
-          self::Attachment.new(name, **options)
+        def attachment(name, *args)
+          self::Attachment.new(name, *args)
         end
         alias [] attachment
 
@@ -251,13 +253,13 @@ class Shrine
         def generate_location(io, context = {})
           extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
           extension ||= File.extname(extract_filename(io).to_s).downcase
-          basename  = generate_uid(io)
+          basename    = generate_uid(io)
 
-          basename + extension.to_s
+          basename + extension
         end
 
         # Extracts filename, size and MIME type from the file, which is later
-        # accessible through `UploadedFile#metadata`.
+        # accessible through UploadedFile#metadata.
         def extract_metadata(io, context = {})
           {
             "filename"  => extract_filename(io),
@@ -323,8 +325,8 @@ class Shrine
         # and any upload options. The storage might modify the location or
         # metadata that were passed in. The uploaded IO is then closed.
         def copy(io, context)
-          location = context[:location]
-          metadata = context[:metadata]
+          location       = context[:location]
+          metadata       = context[:metadata]
           upload_options = context[:upload_options] || {}
 
           storage.upload(io, location, shrine_metadata: metadata, **upload_options)
@@ -396,12 +398,13 @@ class Shrine
           @options = options
 
           module_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def #{name}_attacher
+            def #{name}_attacher(options = {})
+              @#{name}_attacher   = nil if options.any?
               @#{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
+                options        = attachment.options.merge(options)
 
                 attacher_class.new(self, :#{name}, options)
               )
@@ -775,19 +778,23 @@ class Shrine
         end
         alias content_type mime_type
 
-        # Opens an IO object of the uploaded file for reading and yields it to
-        # the block, closing it after the block finishes. For opening without
-        # a block #to_io can be used.
+        # Opens an IO object of the uploaded file for reading, yields it to
+        # the block, and closes it after the block finishes. If opening without
+        # a block, it returns an opened IO object for the uploaded file.
         #
         #     uploaded_file.open do |io|
         #       puts io.read # prints the content of the file
         #     end
         def open(*args)
-          @io = storage.open(id, *args)
-          yield @io
-        ensure
-          @io.close if @io
-          @io = nil
+          return to_io unless block_given?
+
+          begin
+            @io = storage.open(id, *args)
+            yield @io
+          ensure
+            @io.close if @io
+            @io = nil
+          end
         end
 
         # Calls `#download` on the storage if the storage implements it,
@@ -796,9 +803,14 @@ class Shrine
           if storage.respond_to?(:download)
             storage.download(id, *args)
           else
-            tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
-            open(*args) { |io| IO.copy_stream(io, tempfile.path) }
-            tempfile.tap(&:open)
+            begin
+              tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
+              open(*args) { |io| IO.copy_stream(io, tempfile.path) }
+              tempfile.tap(&:open)
+            rescue
+              tempfile.close! if tempfile
+              raise
+            end
           end
         end
 

data/lib/shrine/plugins/activerecord.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "active_record"
 
 class Shrine

data/lib/shrine/plugins/add_metadata.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Shrine
   module Plugins
     # The `add_metadata` plugin provides a convenient method for extracting and

data/lib/shrine/plugins/background_helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Shrine.deprecation("The background_helpers plugin has been renamed to \"backgrounding\". Loading the plugin through \"background_helpers\" will stop working in Shrine 3.")
 require "shrine/plugins/backgrounding"
 Shrine::Plugins.register_plugin(:background_helpers, Shrine::Plugins::Backgrounding)

data/lib/shrine/plugins/backgrounding.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Shrine
   module Plugins
     # The `backgrounding` plugin enables you to move promoting and deleting of
@@ -10,13 +12,17 @@ class Shrine
     # jobs, by passing a block.
     #
     #     Shrine.plugin :backgrounding
+    #
+    #     # makes all uploaders use background jobs
     #     Shrine::Attacher.promote { |data| PromoteJob.perform_async(data) }
     #     Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
     #
     # If you don't want to apply backgrounding for all uploaders, you can
-    # declare the hooks only for specific uploaders.
+    # declare the hooks only for specific uploaders (in this case it's still
+    # recommended to keep the plugin loaded globally).
     #
     #     class MyUploader < Shrine
+    #       # makes this uploader use background jobs
     #       Attacher.promote { |data| PromoteJob.perform_async(data) }
     #       Attacher.delete { |data| DeleteJob.perform_async(data) }
     #     end
@@ -176,12 +182,13 @@ class Shrine
           record = load_record(data)
           name = data["name"].to_sym
 
-          if data["shrine_class"]
+          if record.respond_to?(:"#{name}_attacher")
+            attacher = record.send(:"#{name}_attacher")
+          elsif data["shrine_class"]
             shrine_class = Object.const_get(data["shrine_class"])
             attacher = shrine_class::Attacher.new(record, name)
           else
-            # anonymous uploader class, try to retrieve attacher from record
-            attacher = record.send("#{name}_attacher")
+            fail Error, "cannot load anonymous uploader class"
           end
 
           attacher