shrine 3.0.0.rc → 3.0.0

data/doc/retrieving_uploads.md

@@ -1,4 +1,7 @@
-# Retrieving Uploads
+---
+id: retrieving-uploads
+title: Retrieving Uploads
+---
 
 Uploaded file content is typically retrieved from the storage using a
 `Shrine::UploadedFile` object. This guide explains the various methods of

data/doc/securing_uploads.md

@@ -1,4 +1,7 @@
-# Securing uploads
+---
+id: securing-uploads
+title: Securing uploads
+---
 
 Shrine does a lot to make your file uploads secure, but there are still a lot
 of security measures that could be added by the user on the application's side.

data/doc/storage/file_system.md

@@ -1,4 +1,7 @@
-# Shrine::Storage::FileSystem
+---
+id: file-system
+title: Shrine::Storage::FileSystem
+---
 
 The FileSystem storage handles uploads to the filesystem, and it is most
 commonly initialized with a "base" folder and a "prefix":
@@ -64,7 +67,12 @@ File.exist?(file.path) #=> false
 ```
 
 If you want to make this option default, you can use the
-[`upload_options`][upload_options] plugin.
+[`upload_options`][upload_options] plugin, provided that both `:cache` and
+`:store` storages are `FileSystem`):
+
+```rb
+plugin :upload_options, cache: { move: true }, store: { move: true }
+```
 
 ## Path
 
@@ -80,7 +88,7 @@ If you want to delete all files in some directory, you can use
 `FileSystem#delete_prefixed`:
 
 ```rb
-storage.delete_prefixed("some_directory") # deletes all files in "some_directory/"
+storage.delete_prefixed("some_directory/") # deletes all files in "some_directory/"
 ```
 
 ## Clearing cache
@@ -120,4 +128,4 @@ also means that deploying the app can cancel someone's uploading if you're
 using backgrounding. Also, by default you cannot generate URLs to files in the
 "tmp" directory, but you can with the `download_endpoint` plugin.
 
-[upload_options]: /doc/plugins/upload_options.md#readme
+[upload_options]: https://shrinerb.com/docs/plugins/upload_options

data/doc/storage/s3.md

@@ -1,4 +1,6 @@
-# Shrine::Storage::S3
+---
+title: Shrine::Storage::S3
+---
 
 The S3 storage handles uploads to Amazon S3 service, using the [aws-sdk-s3]
 gem:
@@ -265,7 +267,7 @@ If you want to delete all objects in some prefix, you can use
 `S3#delete_prefixed`:
 
 ```rb
-s3.delete_prefixed("some_prefix") # deletes all objects in "some_prefix/"
+s3.delete_prefixed("some_prefix/") # deletes all objects in "some_prefix/"
 ```
 
 ## Clearing cache

data/doc/testing.md

@@ -1,4 +1,6 @@
-# Testing with Shrine
+---
+title: Testing with Shrine
+---
 
 The goal of this guide is to provide some useful tips for testing file
 attachments implemented with Shrine in your application.
@@ -99,7 +101,8 @@ We want to keep our tests fast, so when we're setting up files for tests, we
 want to avoid expensive operations such as file processing and metadata
 extraction.
 
-We can start by creating a method which would generate fake attachment data:
+We can create a helper method that will create attached file data for us, and
+use that with our factories/fixtures.
 
 ```rb
 module TestData
@@ -134,24 +137,19 @@ module TestData
   end
 end
 ```
-```rb
-TestData.image_data #=> '{"id":"...","storage":"...","metadata":{...},"derivatives":{...}}'
-```
-
-With [factory_bot] you can then assign the test attachment data like this:
-
+<!--DOCUSAURUS_CODE_TABS-->
+<!--FactoryBot-->
 ```rb
 factory :photo do
   image_data { TestData.image_data }
 end
 ```
-
-With [Rails' YAML fixtures][fixtures] it would look like this:
-
+<!--Rails YAML fixtures-->
 ```erb
 photo:
   image_data: <%= TestData.image_data %>
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Unit tests
 
@@ -182,35 +180,26 @@ end
 ## Acceptance tests
 
 In acceptance tests you're testing your app end-to-end, and you likely want to
-also test file attachments here. There are a variety of libraries that you
-might be using for your acceptance tests.
-
-### Capybara
-
-If you're testing with the [Capybara] acceptance test framework, you can use
-[`#attach_file`] to select a file from your filesystem in the form:
+also test file attachments here. Here are examples for some common use cases:
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Capybara-->
 ```rb
 attach_file("#image-field", "test/files/image.jpg")
 ```
-
-### Rack::Test
-
-Regular routing tests in Rails use [Rack::Test], in which case you can create
-`Rack::Test::UploadedFile` objects and pass them as form parameters:
-
+<!--Rack::Test-->
 ```rb
-post "/photos", photo: { image: Rack::Test::UploadedFile.new("test/files/image.jpg", "image/jpeg") }
+post "/photos", photo: {
+  image: Rack::Test::UploadedFile.new("test/files/image.jpg", "image/jpeg")
+}
 ```
-
-### Rack::TestApp
-
-With [Rack::TestApp] you can create multipart file upload requests by using the
-`:multipart` option and passing a `File` object:
-
+<!--Rack::TestApp-->
 ```rb
-http.post "/photos", multipart: {"photo[image]" => File.open("test/files/image.jpg")}
+app.post "/photos", multipart: {
+  "photo[image]" => File.open("test/files/image.jpg")
+}
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Background jobs
 
@@ -218,19 +207,21 @@ If you're using background jobs with Shrine, you probably want to make them
 synchronous in tests. See your backgrounding library docs for how to make jobs
 synchronous.
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--ActiveJob-->
 ```rb
-# ActiveJob
 ActiveJob::Base.queue_adapter = :inline
 ```
+<!--Sidekiq-->
 ```rb
-# Sidekiq
 require "sidekiq/testing"
 Sidekiq::Testing.inline!
 ```
+<!--SuckerPunch-->
 ```rb
-# SuckerPunch
 require "sucker_punch/testing/inline"
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Processing
 
@@ -261,12 +252,7 @@ end
 ```
 
 [DatabaseCleaner]: https://github.com/DatabaseCleaner/database_cleaner
-[factory_bot]: https://github.com/thoughtbot/factory_bot
-[fixtures]: https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures
-[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://min.io/
-[derivatives]: /doc/plugins/derivatives.md#readme
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives

data/doc/upgrading_to_3.md

@@ -1,17 +1,10 @@
-# Upgrading to Shrine 3.x
+---
+id: upgrading-to-3
+title: Upgrading to Shrine 3.x
+---
 
 This guide provides instructions for upgrading Shrine in your apps to version
-3.x. We will cover the following areas:
-
-* [Attacher](#attacher)
-* [Backgrounding](#backgrounding)
-* [Versions](#versions)
-* [Miscellaneous](#miscellaneous)
-  - [Logging](#logging)
-  - [Backup](#backup)
-  - [Copy](#copy)
-  - [Moving](#moving)
-  - [Memory](#memory)
+3.x. If you're looking for a full list of changes, see the [3.0 release notes].
 
 ## Attacher
 
@@ -25,7 +18,7 @@ attacher without a model:
 
 ```rb
 attacher = Shrine::Attacher.new
-# ...
+#=> #<Shrine::Attacher>
 
 attacher = Shrine::Attacher.new(photo, :image)
 # ~> ArgumentError: invalid number of arguments
@@ -337,6 +330,22 @@ else
 end
 ```
 
+If you have multiple places where you need to generate derivatives, and want it
+to happen automatically like it did with the `versions` plugin, you can
+override `Attacher#promote` to call `Attacher#create_derivatives` before
+promotion:
+
+```rb
+class Shrine::Attacher
+  def promote(*)
+    create_derivatives
+    super
+  end
+end
+```
+
+### Accessing derivatives
+
 The derivative URLs are accessed in the same way as versions:
 
 ```rb
@@ -495,12 +504,43 @@ end
 However, it doesn't implement any other URL fallbacks that the `versions`
 plugin has for missing derivatives.
 
-## Miscellaneous
+## Other
+
+### Processing
+
+The `processing` plugin has been deprecated over the new
+[`derivatives`][derivatives] plugin. If you were modifying the original file:
+
+```rb
+class MyUploader < Shrine
+  plugin :processing
+
+  process(:store) do |io, context|
+    ImageProcessing::MiniMagick
+      .source(io.download)
+      .resize_to_limit!(1600, 1600)
+  end
+end
+```
+
+you should now add the processed file as a derivative:
+
+```rb
+class MyUploader < Shrine
+  plugin :derivatives
+
+  Attacher.derivatives_processor do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
+
+    { normalized: magick.resize_to_limit!(1600, 1600) }
+  end
+end
+```
 
 ### Logging
 
 The `logging` plugin has been removed in favour of the
-[`instrumentation`][instrumentation] plugin. You can replace
+[`instrumentation`][instrumentation] plugin. You can replace code like
 
 ```rb
 Shrine.plugin :logging, logger: Rails.logger
@@ -517,7 +557,7 @@ Shrine.plugin :instrumentation
 ### Backup
 
 The `backup` plugin has been removed in favour of the new
-[`mirroring`][mirroring] plugin. You can replace
+[`mirroring`][mirroring] plugin. You can replace code like
 
 ```rb
 Shrine.plugin :backup, storage: :backup_store
@@ -531,7 +571,8 @@ Shrine.plugin :mirroring, mirror: { store: :backup_store }
 
 ### Copy
 
-The `copy` plugin has been removed. You can replace
+The `copy` plugin has been removed as its behaviour can now be achieved easily.
+You can replace code like
 
 ```rb
 Shrine.plugin :copy
@@ -550,16 +591,54 @@ attacher.add_derivatives other_attacher.derivatives # if using derivatives
 ### Moving
 
 The `moving` plugin has been removed in favour of the `:move` option for
-`FileSystem#upload`. You can set up moving in basic places with the
-`upload_options` plugin:
+`FileSystem#upload`. You can set this option as default using the
+`upload_options` plugin (the example assumes both `:cache` and `:store` are
+FileSystem storages):
+
+```rb
+Shrine.plugin :upload_options, cache: { move: true }, store: { move: true }
+```
+
+### Parsed JSON
+
+The `parsed_json` plugin has been removed as it's now the default behaviour.
+
+```rb
+# this now works by default
+photo.image = { "id" => "d7e54d6ef2.jpg", "storage" => "cache", "metadata" => { ... } }
+```
+
+### Module Include
+
+The `module_include` plugin has been deprecated over overriding core classes
+directly. You can replace code like
+
+```rb
+class MyUploader < Shrine
+  plugin :module_include
+
+  file_methods do
+    def image?
+      mime_type.start_with?("image")
+    end
+  end
+end
+```
+
+with
 
 ```rb
-Shrine.plugin :upload_options,
-  cache: -> (io, action: nil, **) { { move: true } if action == :cache },
-  store: -> (io, action: nil, **) { { move: true } if action == :store }
+class MyUploader < Shrine
+  class UploadedFile
+    def image?
+      mime_type.start_with?("image")
+    end
+  end
+end
 ```
 
-[model]: /doc/plugins/model.md#readme
-[derivatives]: /doc/plugins/derivatives.md#readme
-[instrumentation]: /doc/plugins/instrumentation.md#readme
-[mirroring]: /doc/plugins/mirroring.md#readme
+[3.0 release notes]: https://shrinerb.com/docs/release_notes/3.0.0
+[model]: https://shrinerb.com/docs/plugins/model
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives
+[instrumentation]: https://shrinerb.com/docs/plugins/instrumentation
+[mirroring]: https://shrinerb.com/docs/plugins/mirroring

data/doc/validation.md

@@ -1,4 +1,6 @@
-# File Validation
+---
+title: File Validation
+---
 
 Shrine allows validating assigned files using the [`validation`][validation]
 plugin. Validation code is defined inside an `Attacher.validate` block:
@@ -15,9 +17,9 @@ end
 ```
 
 The validation block is run when a new file is assigned, and any validation
-errors are stored in `Shrine::Attacher#errors`. ORM plugins like `sequel` and
-`activerecord` will automatically merge these validation errors into the
-`#errors` hash on the model instance.
+errors are stored in `Shrine::Attacher#errors`. Persistence plugins like
+`sequel` and `activerecord` will automatically merge these validation errors
+into the `#errors` hash on the model instance.
 
 ```rb
 photo = Photo.new
@@ -105,5 +107,5 @@ you can have it automatically removed and deleted by loading the
 Shrine.plugin :remove_invalid # remove and delete files that failed validation
 ```
 
-[validation]: /doc/plugins/validation.md#readme
-[validation_helpers]: /doc/plugins/validation_helpers.md#readme
+[validation]: https://shrinerb.com/docs/plugins/validation
+[validation_helpers]: https://shrinerb.com/docs/plugins/validation_helpers

data/lib/shrine/attacher.rb

@@ -154,7 +154,7 @@ class Shrine
       #     attacher.promote_cached
       #     attacher.stored? #=> true
       def promote_cached(**options)
-        promote(action: :store, **options) if promote?
+        promote(**options) if promote?
       end
 
       # Uploads current file to permanent storage and sets the stored file.
@@ -163,7 +163,7 @@ class Shrine
       #     attacher.promote
       #     attacher.stored? #=> true
       def promote(storage: store_key, **options)
-        set upload(file, storage, **options)
+        set upload(file, storage, action: :store, **options)
       end
 
       # Delegates to `Shrine.upload`, passing the #context.

data/lib/shrine/attachment.rb

@@ -18,6 +18,13 @@ class Shrine
       def inspect
         "#{shrine_class.inspect}::Attachment"
       end
+
+      # Shorthand for `Attachment.new`.
+      #
+      #   Shrine::Attachment[:image]
+      def [](*args)
+        new(*args)
+      end
     end
 
     module InstanceMethods
@@ -29,16 +36,6 @@ class Shrine
         @options = options
       end
 
-      def included(klass)
-        super
-
-        attachment = self
-
-        klass.send(:define_singleton_method, :"#{@name}_attacher") do |**options|
-          attachment.shrine_class::Attacher.new(**attachment.options, **options)
-        end
-      end
-
       # Returns name of the attachment this module provides.
       def attachment_name
         @name