shrine 2.19.4 → 3.0.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f87dfd3785a6b526ee6bea2746ee7218a3bf817a0935ce11daa4f3d01fdd53ad
-  data.tar.gz: c11cc48b95b4dce2d3da10232dd148e94e93079e594b1fe81a39f949fdc89ac8
+  metadata.gz: 36715577aa30205e12419931f31b3dfad46e30e659372c88e5e926d536984dfc
+  data.tar.gz: fd74dd99deef2030ebc5c2935bccb15447e5a5eb9a916c8379e6d57db87bba23
 SHA512:
-  metadata.gz: 319325474e6a12e40943d3d969fb4b1c06d17136c64aa7a241d319d4b7d765391be68c847ba920d58b36ab61807e934aee543c9ab6bedac1681be4806bce5f5f
-  data.tar.gz: cd919fd2e5fd4e69da13f2723c17702d235f1f41b33eb51d75e42f12e1eed06778261c11622a2c2ebe2a08fbe3eaf5959c2cf3d76657ca4d7fd051433cd53ed3
+  metadata.gz: 2fbc8cce3080e6728d04c59e6e56b2653b47df3c0d8dece92f62590cebcd5d30a54c9f7f31ba11ff6fcf6041190438ee20785075c7ca3dce6863ac77311ca69b
+  data.tar.gz: '038a34aade2923b6c5ce0f36d6d8897dc1ac7cc06b06a06dd46cbffc26cc57db0345ead5674562ac1d84a7a8825e49a8a536ce0321321d7edbf3f429795fa492'

data/CHANGELOG.md

@@ -1,24 +1,312 @@
-## 2.19.4 (2020-01-16)
+## 3.0.0.alpha (2019-08-19)
 
-* Relax Down version to allow 5.x (@janko)
+* `form_assign` – Add new plugin for assigning attachment from form params without a form object (@janko)
 
-## 2.19.3 (2019-08-09)
+* `derivation_endpoint` – Allow passing generic IO objects to `Derivation#upload` (@janko)
 
-* `store_dimensions` – Ignore dimensions extraction errors by default (@janko)
+* `derivation_endpoint` – Accept additional uploader options in `Derivation#upload` (@janko)
 
-* `file_system` – Un-deprecate `FileSystem#upload` receiving unrecognized options (@janko)
+* `derivation_endpoint` – Close the uploaded file in `Derivation#upload` (@janko)
 
-## 2.19.2 (2019-07-25)
+* `core` – Stop rescuing `IO#close` exceptions in `Shrine#upload` (@janko)
 
-* `default_url_options` – Allow deleting passed options when using a block (@janko)
+* `core` – Add `:delete` option to `Shrine#upload` for deleting uploaded file (@janko)
 
-* `activerecord` – Make it work with ActiveRecord 3 (@texpert)
+* `s3` – Stop returning `:object` in `Down::ChunkedIO#data` in `S3#open` (@janko)
 
-* `infer_extension` – Fix compatibility with `pretty_location` plugin (@janko)
+* `s3` – Eliminate `#head_object` request in `S3#open` (@janko)
 
-## 2.19.1 (2019-07-20)
+* `download_endpoint` – Remove extra `Storage#exists?` check (@janko)
 
-* Bring back support for Ruby 2.3 (@janko)
+* `derivation_endpoint` – Remove support for derivative being deleted during upload (@janko)
+
+* `derivation_endpoint` – Add `Derivation#opened` for retrieving an opened derivation result (@janko)
+
+* `derivation_endpoint` – Remove extra `Storage#exists?` check when `:upload` is enabled but not `:upload_redirect` (@janko)
+
+* `derivation_endpoint` - Don't pass source `UploadedFile` object when `:download` is `false` (@janko)
+
+* `derivation_endpoint` – Remove `:include_uploaded_file` option (@janko)
+
+* `derivation_endpoint` – Evaluate derivation block in context of `Shrine::Derivation` (@janko)
+
+* `derivation_endpoint` – Remove `:download_errors` option (@janko)
+
+* `memory` – Raise `Shrine::FileNotFound` on nonexistent file in `Memory#open` (@janko)
+
+* `file_system` – Raise `Shrine::FileNotFound` on nonexistent file in `FileSystem#open` (@janko)
+
+* `s3` – Raise `Shrine::FileNotFound` on nonexistent object in `S3#open` (@janko)
+
+* `core` – Add `Shrine::FileNotFound` exception and require storages to raise it on `Storage#open` (janko)
+
+* `instrumentation` – Remove `:metadata` from `:options` in `metadata.shrine` event (@janko)
+
+* `instrumentation` – Remove `:location`, `:upload_options` and `:metadata` from `:options` in `upload.shrine` event (@janko)
+
+* `instrumentation` – Add `:metadata` to the `upload.shrine` event (@janko)
+
+* `download_endpoint` – Drop support for legacy `/:storage/:id` URLs (@janko)
+
+* `core` – In `UploadedFile#==` require files to be of the same class (@janko)
+
+* `core` – Add `:close` option to `Shrine#upload` for preventing closing file after upload (@janko)
+
+* `memory` – Add `Shrine::Storage::Memory` from `shrine-memory` gem (@janko)
+
+* `default_url_options` – Rename to just `url_options` (@janko)
+
+* `delete_raw` – Deprecate plugin in favour of `derivatives` (@janko)
+
+* `recache` – Deprecate plugin in favour of `derivatives` (@janko)
+
+* `processing` – Deprecate plugin in favour of `derivatives` (@janko)
+
+* `versions` – Deprecate plugin in favour of `derivatives` (@janko)
+
+* `derivatives` – Add new plugin for storing processed files (@janko)
+
+* `derivation_endpoint` – Allow using symbol and string derivation names interchangeably (@janko)
+
+* `dynamic_storage` – Remove `Shrine.dynamic_storages` method (@janko)
+
+* `core` – Deep duplicate `Shrine.opts` on subclassing (@janko)
+
+* `core` – Add `Attacher#file!` which asserts that a file is attached (@janko)
+
+* `core` – Change `Shrine.uploaded_file` to raise `ArgumentError` on invalid input (@janko)
+
+* `module_include` – Deprecate plugin over overriding core classes directly (@janko)
+
+* `core` – Add `Attacher#cache_key` and `Attacher#store_key` which return storage identifiers (@janko)
+
+* `linter` – Call `Storage#open` with options as second argument (@janko)
+
+* `core` – Allow data hash passed to `UploadedFile.new` to have symbol keys (@janko)
+
+* `core` – Change how `Shrine::UploadedFile` sets its state from the given data hash (@janko)
+
+* `core` – Deprecate `Storage#open` not accepting additional options (@janko)
+
+* `refresh_metadata` – Add `Attacher#refresh_metadata!` method which integrates with `model` plugin (@janko)
+
+* `instrumentation` – Instrument any `Storage#open` calls in a new `open.shrine` event (@janko)
+
+* `restore_cached_data` – Forward options passed to `Attacher#attach_cached` to metadata extraction (@janko)
+
+* `attacher_options` – Add new plugin for setting default attacher operation options (@janko)
+
+* `validation` – Add `Attacher#validate_options` for registering default validation options (@janko)
+
+* `validation` – Allow skipping validations on attaching by passing `validate: false` (@janko)
+
+* `validation` – Add `:validate` option to `Attacher#assign` or `Attacher#attach` for passing options to validation block (@janko)
+
+* `validation` – Extract validation functionality into the new plugin (@janko)
+
+* `upload_options` – Upload options from the block are now merged with passed options instead of replaced (@janko)
+
+* `upload_endpoint` – Stop passing `Rack::Request` object to the uploader (@janko)
+
+* `remote_url` – Require custom downlodaers to raise `Shrine::Plugins::RemoteUrl::DownloadError` for conversion into a validation error (@janko)
+
+* `remote_url` – Remove `Attacher#remote_url=` and `Attacher#remote_url` (@janko)
+
+* `infer_extension` – Fix compatibility with the `pretty_location` plugin (@janko)
+
+* `presign_endpoint` – Remove deprecated `Shrine::Plugins::PresignEndpoint::App` constant (@janko)
+
+* `keep_files` – Remove the ability to choose whether to keep only destroyed or only replaced files (@janko)
+
+* `infer_extension` – Remove `Shrine#infer_extension` method (@janko)
+
+* `default_url_options` – Allow overriding passed URL options by deleting them inside the block (@janko)
+
+* `data_uri` – Remove `Attacher#data_uri=` and `Attacher#data_uri` methods (@janko)
+
+* `cached_attachment_data` – Rename `Attacher#read_cached` to `Attacher#cached_data` (@janko)
+
+* `sequel` – Add `Attacher#atomic_promote` and `Attacher#atomic_persist` (@janko)
+
+* `sequel` – Remove adding persistence to `Attacher#promote` (@janko)
+
+* `activerecord` – Add `Attacher#atomic_promote` and `Attacher#atomic_persist` (@janko)
+
+* `activerecord` – Remove adding persistence to `Attacher#promote` (@janko)
+
+* `atomic_helpers` – Add new plugin with helper methods for atomic promotion and persistence (@janko)
+
+* `backgrounding` – Add `Attacher#promote_block` & `Attacher#destroy_block` for overriding class level blocks (@janko)
+
+* `backgrounding` – Add `Attacher.promote_block` & `Attacher.destroy_block` on class level (@janko)
+
+* `backgrounding` – Remove overriding `Attacher#swap` with atomic promotion (@janko)
+
+* `backgrounding` – Remove `Attacher.promote`, `Attacher.delete`, `Attacher.dump`, `Attacher#dump`, `Attacher.load`, `Attacher.load_record` (@janko)
+
+* `model` – Allow disabling caching to temporary storage on assignment (@janko)
+
+* `model` – Add `Attacher.from_model`, `Attacher#write` (@janko)
+
+* `model` – Add new plugin for integrating with mutable structs (@janko)
+
+* `entity` – Add `Attacher.from_entity`, `Attacher#reload`, `Attacher#column_values`, `Attacher#attribute` (@janko)
+
+* `entity` – Add new plugin for integrating with immutable structs (@janko)
+
+* `column` – Allow changing column serializer from default `JSON` library (@janko)
+
+* `column` – Add `Attacher#column_data` and `Attacher.from_column` methods (@janko)
+
+* `column` – Add new plugin for (de)serializing attacher data (@janko)
+
+* `attachment` – Removed any default attachment methods (@janko)
+
+* `core` – Require context hash passed as second argument to `Shrine#upload` to have symbol keys (@janko)
+
+* `core` – Change `Shrine.uploaded_file` not to yield files anymore (@janko)
+
+* `core` – Allow `Shrine.uploaded_file` to accept file data hashes with symbol keys (@janko)
+
+* `core` – Remove `Shrine#uploaded?`
+
+* `core` – Remove `Shrine#delete`, `Shrine#_delete`, `Shrine#remove` (@janko)
+
+* `core` – Remove `Shrine#store`, `Shrine#_store`, `Shrine#put`, `Shrine#copy` (@janko)
+
+* `core` – Remove `Shrine#processed`, `Shrine#process` (@janko)
+
+* `core` – Don't pass `:phase` anymore on uploads (@janko)
+
+* `core` – Read attachment from the record attribute only on initialization (@janko)
+
+* `core` – Don't require a temporary storage (@janko)
+
+* `core` – Add `Attacher#data` and `Attacher.from_data` for dumping to and loading from a Hash (@janko)
+
+* `core` – Enable `Attacher#assign` to accept cached file data as a Hash (@janko)
+
+* `core` – Add `Attacher#file` alias for `Attacher#get` (@janko)
+
+* `core` – Change `Attacher#attached?` to return whether a file is attached (@janko)
+
+* `core` – Change `Attacher#promote` to always only save promoted file in memory (@janko)
+
+* `core` – Rename `Attacher#replace` to `Attacher#destroy_previous` (@janko)
+
+* `core` – Remove `Attacher#_promote` and `Attacher#_delete`, add `Attacher#promote_cached` and `Attacher#destroy_attached` (@janko)
+
+* `core` – Rename `Attacher#set` and `Attacher#_set` to `Attacher#change` and `Attacher#set` (@janko)
+
+* `core` – Remove `Attacher#cache!` and `Attacher#store!`, add `Attacher#upload` (@janko)
+
+* `core` – Rename `Attacher#validate_block` to `Attacher#_validate` (@janko)
+
+* `core` – Add `Attacher#attach`, `Attacher#attach_cached`, extracted from `Attacher#assign` (@janko)
+
+* `core` – Remove `Attacher#swap`, `Attacher#update`, `Attacher#read`, `Attacher#write`, `Attacher#data_attribute`, `Attacher#convert_to_data`, `Attacher#convert_before_write`, and `Attacher#convert_after_read` (@janko)
+
+* `core` – Change `Attacher.new` to not accept a model anymore (@janko)
+
+* `delete_promoted` – Remove plugin (@janko)
+
+* `parsed_json` – Remove plugin (@janko)
+
+* `parallelize` – Remove plugin (@janko)
+
+* `hooks` – Remove plugin (@janko)
+
+* `s3` – Replace source object metadata when copying a file from S3 (@janko)
+
+* `core` – Change `UploadedFile#storage_key` to return a Symbol instead of a String (@janko)
+
+* `infer_extension` – Make `:mini_mime` the default analyzer (@janko)
+
+* Bring back Ruby 2.3 support (@janko)
+
+* `versions` – Remove deprecated `:version_names`, `Shrine.version_names` and `Shrine.version?` (@janko)
+
+* `validation_helpers` – Remove support for regexes in MIME type or extension validations (@janko)
+
+* `validation_helpers` – Don't require `#width` and `#height` methods to be defined on `UploadedFile` (@janko)
+
+* `validation_helpers` – Fail dimensions validations when `width` or `height` metadata is missing (@janko)
+
+* `upload_endpoint` – Remove deprecated `Shrine::Plugins::UploadEndpoint::App` constant (@janko)
+
+* `determine_mime_type` – Remove `Shrine#mime_type_analyzers` method (@janko)
+
+* `store_dimensions` – Remove `Shrine#extract_dimensions` and `Shrine#dimensions_analyzers` methods (@janko)
+
+* `rack_file` – Remove deprecated `Shrine::Plugins::RackFile::UploadedFile` constant (@janko)
+
+* `rack_file` – Drop support for passing file hash to `Shrine#upload` and `Shrine#store` (@janko)
+
+* `download_endpoint` – Move `Shrine::Plugins::DownloadEndpoint::App` into `Shrine::DownloadEndpoint` (@janko)
+
+* `download_endpoint` – Remove deprecated `Shrine::DownloadEndpoint` constant (@janko)
+
+* `download_endpoint` – Remove deprecated `:storages` option (@janko)
+
+* `determine_mime_type` – Remove deprecated `:default` analyzer alias (@janko)
+
+* `default_url` – Remove deprecated block argument when loading the plugin (@janko)
+
+* `data_uri` – Remove deprecated `Shrine::Plugins::DataUri::DataFile` constant (@janko)
+
+* `data_uri` – Remove deprecated `:filename` plugin option (@janko)
+
+* `cached_attachment_data` – Remove deprecated model setter (@janko)
+
+* `file_system` – Remove deprecated `:older_than` option in `FileSystem#clear!` (@janko)
+
+* `file_system` – Don't accept a block anymore in `FileSystem#open` (@janko)
+
+* `file_system` – Remove deprecated `FileSystem#download` method (@janko)
+
+* `file_system` – Make `FileSystem#movable?` and `FileSystem#move` methods private (@janko)
+
+* `file_system` – Remove deprecation warning on unrecognized options in `FileSystem#upload` (@janko)
+
+* `file_system` – Remove deprecated `:host` option for `FileSystem#initialize` (@janko)
+
+* `moving` – Remove deprecated plugin (@janko)
+
+* `multi_delete` – Remove deprecated plugin (@janko)
+
+* `direct_upload` – Remove deprecated plugin (@janko)
+
+* `backup` – Remove deprecated plugin (@janko)
+
+* `background_helpers` – Remove deprecated plugin (@janko)
+
+* `migration_helpers` – Remove deprecated plugin (@janko)
+
+* `copy` – Remove deprecated plugin (@janko)
+
+* `logging` – Remove deprecated plugin (@janko)
+
+* `s3` – Remove deprecated `S3#download` method (@janko)
+
+* `s3` – Remove deprecated `S3#stream` method (@janko)
+
+* `presign_endpoint` – Drop support for presign objects that don't respond to `#to_h` (@janko)
+
+* `s3` – Return a Hash in `S3#presign` when method is POST (@janko)
+
+* `s3` – Remove `:download` option in `S3#url` (@janko)
+
+* `s3` – Remove support for non URI-escaped content disposition values (@janko)
+
+* `s3` – Remove `S3#s3` method (@janko)
+
+* `s3` – Remove support for specifying `:multipart_threshold` as an integer (@janko)
+
+* `s3` – Remove `:host` option on `S3#initialize` (@janko)
+
+* `s3` – Drop support for `aws-sdk-s3` versions lower than 1.14 (@janko)
+
+* `s3` – Drop support for `aws-sdk` 2.x (@janko)
 
 ## 2.19.0 (2019-07-18)
 

data/README.md

@@ -639,7 +639,7 @@ Now we can generate URLs from attached files that will perform the desired
 processing:
 
 ```rb
-photo.image.derivation_url(:thumbnail, "600", "400")
+photo.image.derivation_url(:thumbnail, 600, 400)
 #=> "/derivations/image/thumbnail/600/400/eyJpZCI6ImZvbyIsInN0b3JhZ2UiOiJzdG9yZSJ9?signature=..."
 ```
 
@@ -933,13 +933,19 @@ Some plugins add their own instrumentation as well when they detect that the
 | `data_uri`            | instruments data URI parsing            |
 
 For instrumentation, warnings, and other logging, Shrine uses its internal
-logger. You can tell Shrine to use a different logger, for example if you're
-using Rails:
+logger. You can tell Shrine to use a different logger. For example, if you're
+using Rails, you might want to tell it to use the Rails logger:
 
 ```rb
 Shrine.logger = Rails.logger
 ```
 
+In tests you might want to tell Shrine to log only warnings:
+
+```rb
+Shrine.logger.level = Logger::WARN
+```
+
 ## Inspiration
 
 Shrine was heavily inspired by [Refile] and [Roda]. From Refile it borrows the

data/doc/advantages.md

@@ -196,7 +196,7 @@ class ImageUploader < Shrine
 end
 ```
 ```rb
-photo.image.derivation_url(:thumbnail, "600", "400")
+photo.image.derivation_url(:thumbnail, 600, 400)
 #=> ".../thumbnail/600/400/eyJpZCI6ImZvbyIsInN0b3JhZ2UiOiJzdG9yZSJ9?signature=..."
 ```
 

data/doc/carrierwave.md

@@ -684,7 +684,7 @@ Shrine::Storage::S3.new(
 The object data can be configured via the `:upload_options` hash:
 
 ```rb
-Shrine::Storage::S3.new(upload_options: {content_disposition: "attachment"}, **options)
+Shrine::Storage::S3.new(upload_options: { content_disposition: "attachment" }, **options)
 ```
 
 #### `:fog_public`
@@ -692,16 +692,16 @@ Shrine::Storage::S3.new(upload_options: {content_disposition: "attachment"}, **o
 The object permissions can be configured with the `:acl` upload option:
 
 ```rb
-Shrine::Storage::S3.new(upload_options: {acl: "private"}, **options)
+Shrine::Storage::S3.new(upload_options: { acl: "private" }, **options)
 ```
 
 #### `:fog_authenticated_url_expiration`
 
 The `#url` method accepts the `:expires_in` option, you can set the default
-expiration with the `default_url_options` plugin:
+expiration with the `url_options` plugin:
 
 ```rb
-plugin :default_url_options, store: {expires_in: 600}
+plugin :url_options, store: { expires_in: 600 }
 ```
 
 #### `:fog_use_ssl_for_aws`, `:fog_aws_accelerate`

data/doc/creating_persistence_plugins.md

@@ -0,0 +1,172 @@
+# Writing an Persistence Plugin
+
+This guide explains some conventions for writing Shrine plugins that integrate
+with persistence libraries such as Active Record, Sequel, ROM and Mongoid. It
+assumes you've read the [Writing a Plugin] guide.
+
+Let's say we're writing a plugin for a persistence library called "Raptor":
+
+```rb
+# lib/shrine/plugins/raptor.rb
+
+require "raptor"
+
+class Shrine
+  module Plugins
+    module Raptor
+      # ...
+    end
+
+    register_plugin(:raptor, Raptor)
+  end
+end
+```
+
+## Attachment
+
+If your database library uses the [Active Record pattern], it's recommended to
+load the [`model`][model] plugin as a dependency.
+
+```rb
+module Shrine::Plugins::Raptor
+  def self.load_dependencies(uploader, **)
+    uploader.plugin :model # for Active Record pattern
+  end
+  # ...
+end
+```
+
+Otherwise if it uses the [Repository pattern], you can load the
+[`entity`][entity] plugin as a dependency.
+
+```rb
+module Shrine::Plugins::Raptor
+  def self.load_dependencies(uploader, **)
+    uploader.plugin :entity # for Repository pattern
+  end
+  # ...
+end
+```
+
+If you want to add library-specific integration when `Shrine::Attachment` is
+included into a model/entity, it's recommended to do this in the `included`
+hook, so that you can perform this logic only for models/entities that belong
+to that persistence library.
+
+```rb
+module Shrine::Plugins::Raptor
+  # ...
+  module AttachmentMethods
+    def included(klass)
+      super
+
+      return unless klass < ::Raptor::Model
+
+      # library specific integration
+    end
+  end
+  # ...
+end
+```
+
+## Attacher
+
+### Persistence
+
+It's recommended to implement an `Attacher#persist` method which persists
+the attached file to the record.
+
+```rb
+module Shrine::Plugins::Raptor
+  # ...
+  module AttacherMethods
+    # ...
+    def persist(...)
+      # persist attachment data
+    end
+    # ...
+  end
+  # ...
+end
+```
+
+This way other 3rd-party plugins can use `Attacher#persist` and know it will do
+the right thing regardless of which persistence plugin is used.
+
+### Atomic promotion & persistence
+
+When using [`backgrounding`][backgrounding] plugin, it's useful to be able to
+make promotion/persistence atomic. The [`atomic_helpers`][atomic_helpers]
+plugin provides the abstract interface, and in your persistence plugin you can
+provide wrappers.
+
+```rb
+module Shrine::Plugins::Raptor
+  def self.load_dependencies(uploader, **)
+    # ...
+    uploader.plugin :atomic_helpers
+  end
+  # ...
+  module AttacherMethods
+    # ...
+    def atomic_promote(...)
+      # call #abstract_atomic_promote from atomic_helpers plugin
+    end
+
+    def atomic_persist(...)
+      # call #abstract_atomic_persist from atomic_helpers plugin
+    end
+    # ...
+  end
+  # ...
+end
+```
+
+See the [`activerecord`][activerecord]/[`sequel`][sequel] plugin source code on
+how this integration should look like.
+
+### With other persistence plugins
+
+It's recommended to prefix each of the above methods with the name of the
+database library, and make non-prefixed versions aliases.
+
+```rb
+module Shrine::Plugins::Raptor
+  # ...
+  module AttacherMethods
+    # ...
+    def raptor_atomic_promote(...)
+      # ...
+    end
+    alias atomic_promote raptor_atomic_promote
+
+    def raptor_atomic_persist(...)
+      # ...
+    end
+    alias atomic_persist raptor_atomic_persist
+
+    def raptor_persist(...)
+      # ...
+    end
+    alias persist raptor_persist
+    # ...
+  end
+  # ...
+end
+```
+
+That way the user can always specify from which persistence plugin they're
+calling a certain method, even when multiple persistence plugins are loaded
+simultaneously. The latter can be the case if the user is using multiple
+database libraries in a single application, or if they're transitioning from
+one library to another.
+
+[Writing a Plugin]: /doc/creating_plugins.md#readme
+[Active Record pattern]: https://www.martinfowler.com/eaaCatalog/activeRecord.html
+[model]: /doc/plugins/model.md#readme
+[entity]: /doc/plugins/entity.md#readme
+[Repository pattern]: https://martinfowler.com/eaaCatalog/repository.html
+[backgrounding]: /doc/plugins/backgrounding.md#readme
+[atomic_helpers]: /doc/plugins/atomic_helpers.md#readme
+[activerecord]: /lib/shrine/plugins/activerecord.rb
+[sequel]: /lib/shrine/plugins/sequel.rb