shrine 2.18.1 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4204298709b7223ea632ea58204336270385de2b2dd97a4f26ef776b39354257
-  data.tar.gz: c7e68dd8920a9ca4ea4eda5ace97d27530c82dc06c3aebad334a74fe23a6cdf4
+  metadata.gz: 4986c5f02d23d23bb5b40c9c9d6bab5bdc3ed10506fd3ef5d171a8176e5f75fb
+  data.tar.gz: b09a2c063f78e9711feec2a9a026e7198ae31623af96e609dc0683d7969e9b7f
 SHA512:
-  metadata.gz: bc8552fbc8459a1d85dd2d7bc510477d6c7df59efe2efca13e018b0cabe974e504715f0860eaf14474c5535b399f849898c3ef7581f019526dee25fcfeac6bf6
-  data.tar.gz: cfedad27afd82bbf95c7b45808bf8a1d8027d408a4d4faa76ec18f67b6306f17a86fab8cf479011ea7a335334715899ec8aabc9e52dc0ea7ce07be57247ab3e1
+  metadata.gz: 93df569fa078dddc0dd0ca60a74e15b929f633bc3614b4fcec608814e8578fc29ef5398803a0b3d02a9cfc4e436aff4125f8f59644fa4e014913f5be2e9eb7b3
+  data.tar.gz: 41a66f59ba0195a7ecac244ff687a87562005eb801d0d3651e08148dcfee6b3f598b91fd410a0c3ad11be84561c9f295f540e2c17e036a0882ec8828aebe3383

data/CHANGELOG.md

@@ -1,4 +1,56 @@
-## 2.18.1 (2019-07-05)
+## 2.19.0 (2019-07-18)
+
+* `pretty_location` – Allow specifying a different identifier from `id` (@00dav00)
+
+* `data_uri` – Soft-move `Shrine::Plugins::DataUri::DataFile` to `Shrine::DataFile` (@janko)
+
+* `rack_file` – Soft-move `Shrine::Plugins::RackFile::UploadedFile` to `Shrine::RackFile` (@janko)
+
+* `backup` – Deprecate the plugin over [mirroring uploads](https://github.com/shrinerb/shrine/wiki/Mirroring-Uploads) via the `instrumentation` plugin (@janko)
+
+* `moving` – Deprecate the plugin in favor of the `:move` option for `FileSystem#upload` (@janko)
+
+* `file_system` – Add `:move` option for `FileSystem#upload` (@janko)
+
+* `file_system` – Don't fill `size` metadata if missing in `FileSystem#upload` (@janko)
+
+* `logging` – Deprecate plugin in favour of `instrumentation` (@janko)
+
+* `instrumentation` – Add plugin which sends events via `ActiveSupport::Notifications` or `dry-monitor` (@janko)
+
+* `core` – Add `UploadedFile#[]` shorthand for accessing metadata (@janko)
+
+* `add_metadata` – Allow calling `super` when overriding dynamically defined `UploadedFile` methods (@janko)
+
+* `store_dimensions` – Add `:on_error` option for specifying the exception strategy (@janko)
+
+* `store_dimensions` – Print warnings when exception occurred while extracting dimensions (@janko)
+
+* `core` – Add `Shrine.logger` and make any warnings go through it (@janko)
+
+* `copy` – Deprecate the plugin (@janko)
+
+* `core` – Add ability to force metadata extraction by passing `metadata: true` to `Shrine#upload` (@janko)
+
+* `core` – Add ability to skip metadata extraction by passing `metadata: false` to `Shrine#upload` (@janko)
+
+* `file_system` – Deprecate `:older_than` option for `FileSystem#clear!` in favour of a block (@janko)
+
+* `file_system` – Add the ability for `FileSystem#clear!` to take a block (@janko)
+
+* `signature` – Add `Shrine.signature` alias for `Shrine.calculcate_signature` (@janko)
+
+* `store_dimensions` – Add `Shrine.dimensions` alias for `Shrine.extract_dimensions` (@janko)
+
+* `determine_mime_type` – Add `Shrine.mime_type` alias for `Shrine.determine_mime_type` (@janko)
+
+* `validation_helpers` – Add `#validate_max_dimensions`, `#validate_min_dimensions`, and `#validate_dimensions` (@janko)
+
+* `validation_helpers` - Add `#validate_size`, `#validate_width`, and `#validate_height` shorthands (@janko)
+
+* `validation_helpers` – Add `#validate_mime_type` and `#validate_extension` aliases for inclusion (@janko)
+
+* `validation_helpers` – Simplify default validation error messages (@janko)
 
 * `core` – Allow registering storage objects under string keys (@janko)
 

data/README.md

@@ -50,7 +50,7 @@ If you're curious how it compares to other file attachment libraries, see the [A
   - [Resumable direct upload](#resumable-direct-upload)
 * [Backgrounding](#backgrounding)
 * [Clearing cache](#clearing-cache)
-* [Settings](#settings)
+* [Logging](#logging)
 
 ## Quick start
 
@@ -197,7 +197,7 @@ the uploaded file with `#<attachment>_url` and display it on the page:
 A "storage" in Shrine is an object that encapsulates communication with a
 specific storage service, by implementing a common public interface. Storage
 instances are registered under an identifier in `Shrine.storages`, so that they
-can later by used by [uploaders][uploader].
+can later be used by [uploaders][uploader].
 
 Previously we've shown the [FileSystem] storage which saves files to disk, but
 Shrine also ships with [S3] storage which stores files on [AWS S3] (or any
@@ -324,7 +324,7 @@ uploaded_file = uploader.upload(file)
 uploaded_file.data #=> {"id"=>"949sdjg834.jpg","storage"=>"store","metadata"=>{...}}
 
 uploaded_file.id       #=> "949sdjg834.jpg"
-uploaded_file.storage  #=> #<Shrine::Storage::FileSystem>
+uploaded_file.storage  #=> #<Shrine::Storage::S3>
 uploaded_file.metadata #=> {...}
 ```
 
@@ -355,7 +355,7 @@ For more details, see the [Retrieving Uploads] guide and
 
 ## Attachment
 
-Storages, uploaders, and uploaded file objects are Shrine's foundational
+Storage objects, uploaders, and uploaded file objects are Shrine's foundational
 components. To help you actually attach uploaded files to database records in
 your application, Shrine comes with a high-level attachment interface built on
 top of these components.
@@ -456,7 +456,7 @@ ship with Shrine. This way you can choose exactly what and how much Shrine does
 for you, and you load the code only for features that you use.
 
 ```rb
-Shrine.plugin :logging # adds logging
+Shrine.plugin :instrumentation # adds instrumentation
 ```
 
 Plugins add behaviour by extending Shrine core classes via module inclusion, and
@@ -494,23 +494,23 @@ uploaded_file.size              #=> 345993
 
 ### MIME type
 
-By default, `mime_type` metadata will be inherited from the `#content_type`
-attribute of the uploaded file, which is generally not secure and will trigger
-a warning. You can load the [`determine_mime_type`][determine_mime_type plugin]
-plugin to have MIME type extracted from file *content* instead.
+By default, `mime_type` metadata will be set from the `#content_type` attribute
+of the uploaded file (if it exists), which is generally not secure and will
+trigger a warning. You can load the [`determine_mime_type`][determine_mime_type
+plugin] plugin to have MIME type extracted from file *content* instead.
 
 ```rb
-Shrine.plugin :determine_mime_type
+# Gemfile
+gem "marcel", "~> 0.3"
+```
+```rb
+Shrine.plugin :determine_mime_type, analyzer: :marcel
 ```
 ```rb
 photo = Photo.create(image: StringIO.new("<?php ... ?>"))
-photo.image.mime_type #=> "text/x-php"
+photo.image.mime_type #=> "application/x-php"
 ```
 
-By the default the UNIX [`file`] utility is used to determine the MIME type,
-but you can also choose a different analyzer, see the
-[`determine_mime_type`][determine_mime_type plugin] docs for more details.
-
 ### Other metadata
 
 In addition to basic metadata, you can also extract [image
@@ -711,19 +711,27 @@ can also access the extracted metadata through `context[:metadata]`.
 
 To improve the user experience, it's recommended to upload files asynchronously
 as soon as the user selects them. The direct uploads would go to temporary
-storage, just like in the synchronous flow.
+storage, just like in the synchronous flow. Then, instead of attaching a raw
+file to your model, you assign the cached file JSON data.
+
+```rb
+# in the regular synchronous flow
+photo.image = file
 
-On the client side it's highly recommended to use **[Uppy]**, a very flexible
-modern JavaScript file upload library that happens to integrate nicely with
-Shrine.
+# in the direct upload flow
+photo.image = '{"id":"...","storage":"cache","metadata":{...}}'
+```
+
+On the client side it's highly recommended to use **[Uppy]** :dog:, a very
+flexible modern JavaScript file upload library that happens to integrate nicely
+with Shrine.
 
 ### Simple direct upload
 
-The simplest approach is creating an upload endpoint in your app that will
-forward uploads to the specified storage. The
+The simplest approach is to upload directly to an endpoint in your app, which
+forwards uploads to the specified storage. The
 [`upload_endpoint`][upload_endpoint plugin] Shrine plugin provides a
-[mountable][Mounting Endpoints] Rack application that does that, and you can
-combine it with Uppy's [XHR Upload][uppy xhr-upload] plugin:
+[mountable][Mounting Endpoints] Rack app that implements this endpoint:
 
 ```rb
 Shrine.plugin :upload_endpoint
@@ -735,22 +743,11 @@ Rails.application.routes.draw do
   mount ImageUploader.upload_endpoint(:cache) => "/images/upload" # POST /images/upload
 end
 ```
-```js
-// upload.js
-// ...
-uppy.use(Uppy.XHRUpload, {
-  endpoint: '/images/upload'
-})
-
-uppy.on('upload-success', (file, response) => {
-  const uploadedFileData = JSON.stringify(response.body)
-  // ... add this data to your form or submit it to your app ...
-})
-```
 
-For adding simple direct uploads from scratch, see [this walkthrough][Adding
-Direct App Uploads] (there is also the [Roda][roda demo] / [Rails][rails demo]
-demo app).
+Then you can configure Uppy's [XHR Upload][uppy xhr-upload] plugin to upload to
+this endpoint. See [this walkthrough][Adding Direct App Uploads] for adding
+simple direct uploads from scratch, it includes a complete JavaScript example
+(there is also the [Roda][roda demo] / [Rails][rails demo] demo app).
 
 ### Presigned direct upload
 
@@ -768,10 +765,9 @@ Shrine.storages = {
 ```
 
 In this flow, the client needs to first fetch upload parameters from the
-server, and then use these parameters for the upload to the cloud service. The
-[`presign_endpoint`][presign_endpoint plugin] Shrine plugin provides a
-[mountable][Mounting Endpoints] Rack application that generates upload
-parameters, and you can combine it with Uppy's [AWS S3][uppy aws-s3] plugin:
+server, and then use these parameters for the upload to the cloud service.
+The [`presign_endpoint`][presign_endpoint plugin] Shrine plugin provides a
+[mountable][Mounting Endpoints] Rack app that generates upload parameters:
 
 ```rb
 Shrine.plugin :presign_endpoint
@@ -783,43 +779,24 @@ Rails.application.routes.draw do
   mount Shrine.presign_endpoint(:cache) => "/s3/params" # GET /s3/params
 end
 ```
-```js
-// upload.js
-// ...
-uppy.use(Uppy.AwsS3, {
-  companionUrl: '/' // uses '/s3/params'
-})
-
-uppy.on('upload-success', (file, response) => {
-  const uploadedFileData = JSON.stringify({
-    id: file.meta['key'].match(/^cache\/(.+)/)[1], // object key without prefix
-    storage: 'cache',
-    metadata: {
-      size:      file.size,
-      filename:  file.name,
-      mime_type: file.type,
-    }
-  })
-  // ... add this data to your form or submit it to your app ...
-})
-```
-
-For adding direct S3 uploads from scratch, see [this walkthrough][Adding Direct
-S3 Uploads] (there is also the [Roda][roda demo] / [Rails][rails demo] demo).
-See also the [Direct Uploads to S3] guide for more details.
+
+Then you can configure Uppy's [AWS S3][uppy aws-s3] plugin to fetch params from
+your endpoint before uploading to S3. See [this walkthrough][Adding Direct S3
+Uploads] for adding direct uploads to S3 from scratch, it includes a complete
+JavaScript example (there is also the [Roda][roda demo] / [Rails][rails demo]
+demo). See also the [Direct Uploads to S3] guide for more details.
 
 ### Resumable direct upload
 
-If your app is accepting large uploads, you can make the uploads **resumable**.
-This can significantly improve experience for users on slow and flaky internet
-connections.
+If your app is accepting large uploads, you can improve resilience by making
+the uploads **resumable**. This can significantly improve experience for users
+on slow and flaky internet connections.
 
 #### Uppy S3 Multipart
 
 You can achieve resumable uploads directly to S3 with the [AWS S3
-Multipart][uppy aws-s3-multipart] Uppy plugin, accompanied with the Shrine
-plugin provided by the [uppy-s3_multipart] gem (assuming your temporary storage
-is `Shrine::Storage::S3`):
+Multipart][uppy aws-s3-multipart] Uppy plugin, accompanied with
+`uppy_s3_multipart` Shrine plugin provided by the [uppy-s3_multipart] gem.
 
 ```rb
 # Gemfile
@@ -835,35 +812,15 @@ Rails.application.routes.draw do
   mount Shrine.uppy_s3_multipart(:cache) => "/s3/multipart"
 end
 ```
-```js
-// upload.js
-// ...
-uppy.use(Uppy.AwsS3Multipart, {
-  companionUrl: '/' // uses '/s3/multipart/*' routes
-})
-
-uppy.on('upload-success', (file, response) => {
-  const uploadedFileData = JSON.stringify({
-    id: response.uploadURL.match(/\/cache\/([^\?]+)/)[1], // object key without prefix
-    storage: 'cache',
-    metadata: {
-      size:      file.size,
-      filename:  file.name,
-      mime_type: file.type,
-    }
-  })
-  // ... add this data to your form or submit it to your app ...
-})
-```
 
 See the [uppy-s3_multipart] docs for more details.
 
 #### Tus protocol
 
 If you want a more generic approach, you can build your resumable uploads on
-**[tus]**, an open resumable upload protocol. On the server side you can use
+**[tus]** – an open resumable upload protocol. On the server side you can use
 the [tus-ruby-server] gem, on the client side Uppy's [Tus][uppy tus] plugin,
-and the [shrine-tus] gem for the glue:
+and the [shrine-tus] gem for the glue.
 
 ```rb
 # Gemfile
@@ -885,31 +842,11 @@ Rails.application.routes.draw do
   mount Tus::Server => "/files"
 end
 ```
-```js
-// upload.js
-// ...
-uppy.use(Uppy.Tus, {
-  endpoint:  '/files',
-  chunkSize: 5*1024*1024,
-})
-
-uppy.on('upload-success', (file, response) => {
-  const uploadedFileData = JSON.stringify({
-    id: response.uploadURL,
-    storage: "cache",
-    metadata: {
-      filename:  file.name,
-      size:      file.size,
-      mime_type: file.type,
-    }
-  })
-  // ... add this data to your form or submit it to your app ...
-})
-```
-
-For adding tus-powered resumable uploads from scratch, see [this
-walkthrough][Adding Resumable Uploads] (there is also a [demo app][resumable
-demo]). See also [shrine-tus] and [tus-ruby-server] docs for more details.
+
+See [this walkthrough][Adding Resumable Uploads] for adding tus-powered
+resumable uploads from scratch, it includes a complete JavaScript example
+(there is also a [demo app][resumable demo]). See also [shrine-tus] and
+[tus-ruby-server] docs for more details.
 
 ## Backgrounding
 
@@ -946,13 +883,13 @@ Shrine doesn't automatically delete files uploaded to temporary storage, instead
 you should set up a separate recurring task that will automatically delete old
 cached files.
 
-Most of Shrine storage classes come with a `#clear!` method, which you can call
-in a recurring script. For FileSystem and S3 storage it would look like this:
+Most Shrine storage classes come with a `#clear!` method, which you can call in
+a recurring script. For FileSystem and S3 storage it would look like this:
 
 ```rb
 # FileSystem storage
 file_system = Shrine.storages[:cache]
-file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+file_system.clear! { |path| path.mtime < Time.now - 7*24*60*60 } # delete files older than 1 week
 ```
 ```rb
 # S3 storage
@@ -960,27 +897,48 @@ s3 = Shrine.storages[:cache]
 s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 } # delete files older than 1 week
 ```
 
-## Settings
+## Logging
 
-Each uploader can store generic settings in the `opts` hash, which can be
-accessed in other uploader actions. You can store there anything that you find
-convenient.
+The [`instrumentation`][instrumentation plugin] plugin sends and logs events for
+important operations:
 
 ```rb
-Shrine.opts[:type] = "file"
-
-class DocumentUploader < Shrine; end
-class ImageUploader < Shrine
-  opts[:type] = "image"
-end
+Shrine.plugin :instrumentation, notifications: ActiveSupport::Notifications
 
-DocumentUploader.opts[:type] #=> "file"
-ImageUploader.opts[:type]    #=> "image"
+uploaded_file = Shrine.upload(io, :store)
+uploaded_file.exists?
+uploaded_file.download
+uploaded_file.delete
+```
+```
+Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
+Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
+Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :download_options=>{}, :uploader=>Shrine}
+Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
 ```
 
-Because `opts` is cloned in subclasses, overriding settings works with
-inheritance. The `opts` hash is used internally by plugins to store
-configuration.
+Some plugins add their own instrumentation as well when they detect that the
+`instrumentation` plugin has been loaded. For that to work, the
+`instrumentation` plugin needs to be loaded *before* any of these plugins.
+
+| Plugin                | Instrumentation                         |
+| :-----                | :--------------                         |
+| `derivation_endpoint` | instruments file processing             |
+| `determine_mime_type` | instruments analyzing MIME type         |
+| `store_dimensions`    | instruments extracting image dimensions |
+| `signature`           | instruments calculating signature       |
+| `infer_extension`     | instruments inferring extension         |
+| `remote_url`          | instruments remote URL downloading      |
+| `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:
+
+```rb
+Shrine.logger = Rails.logger
+```
 
 ## Inspiration
 
@@ -1081,6 +1039,7 @@ The gem is available as open source under the terms of the [MIT License].
 [backgrounding plugin]: /doc/plugins/backgrounding.md#readme
 [derivation_endpoint plugin]: /doc/plugins/derivation_endpoint.md#readme
 [determine_mime_type plugin]: /doc/plugins/determine_mime_type.md#readme
+[instrumentation plugin]: /doc/plugins/instrumentation.md#readme
 [hanami plugin]: https://github.com/katafrakt/hanami-shrine
 [mongoid plugin]: https://github.com/shrinerb/shrine-mongoid
 [presign_endpoint plugin]: /doc/plugins/presign_endpoint.md#readme

data/doc/advantages.md

@@ -69,12 +69,12 @@ that you want. Moreover, you're only loading the code for features that you
 use, which means that Shrine will generally load very fast.
 
 ```rb
-Shrine.plugin :logging
+Shrine.plugin :instrumentation
 
 # translates to
 
-require "shrine/plugins/logging"
-Shrine.plugin Shrine::Plugins::Logging
+require "shrine/plugins/instrumentation"
+Shrine.plugin Shrine::Plugins::Instrumentation
 ```
 
 Shrine comes with a complete attachment functionality, but it also exposes many
@@ -135,7 +135,7 @@ other plugins would be loaded only for a specific uploader.
 
 ```rb
 Shrine.plugin :activerecord
-Shrine.plugin :logging
+Shrine.plugin :instrumentation
 ```
 ```rb
 class ImageUploader < Shrine