shrine 3.0.0 → 3.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c4cf7d403c331ddb66dc01ea8e9210a827065c08fd206d89be8aa1dac24775b
-  data.tar.gz: 9a1b304b4fd4c9640f1bda7904c6402490af9456c896d69bd815fcf8f34ea1e2
+  metadata.gz: 26dd77c39f9d5b7cc4240eacea23823453959aad469acc1d86571f129c24c347
+  data.tar.gz: 9c25f9de3f8c8be835e096da01b47c0636e03158b423a306b89895de05ca4294
 SHA512:
-  metadata.gz: 0eeb00bf6fa625a51f993bda58e0d016b6c85d0831f9be4ce6f914c720054f03684f83617b963f894b51216b96f9ad42eddbcfcf4f717521123d474397c8e3d6
-  data.tar.gz: dd07bd03ea16adf721fdbd8568aa33f1f47a36a32ac5c82537721492c12a21e1b169ebbf8b2872fcb4c938f68bbbde9a1aff6b447fee0a50663898c105e2c62e
+  metadata.gz: 4ae941f20c889d15300bb0a3bb522f8ad9f0cbd9bb80578246bc4d5ed37b1177ecc911172a405872919210bdaa05b1e67f23d77fc97d9c827ef85b01898dd336
+  data.tar.gz: 16fbafcc5d29e70f6d0d4a36fc2123a4a8f705345021b00e87c863826d73970a7bd8116aa19ad5c3a2a03763b0e5e435398ae15a21428d0b932c52a7bb648f8e

data/CHANGELOG.md

@@ -1,4 +1,56 @@
-## 3.0.0 (14-10-2019)
+## 3.2.2 (2020-08-05)
+
+* `s3` – Fix `S3#open` not working on aws-sdk-core 3.104 and above (@janko)
+
+## 3.2.1 (2020-01-12)
+
+* `derivation_endpoint` – Use `Rack::Files` constant on Rack >= 2.1 (@janko)
+
+* Fix Ruby 2.7 warnings regarding separation of positional and keyword arguments (@janko)
+
+* `s3` – Make `S3#open` handle empty S3 objects (@janko)
+
+## 3.2.0 (2019-12-17) [[release notes]](https://shrinerb.com/docs/release_notes/3.2.0)
+
+* `validation` – Run validation on `Attacher#attach` & `Attacher#attach_cached` instead of `Attacher#change` (@janko)
+
+* `remove_invalid` – Activate also when `Attacher#validate` is run manually (@janko)
+
+* `remove_invalid` – Fix incompatibility with `derivatives` plugin (@janko)
+
+* `type_predicates` – Add new plugin with convenient `UploadedFile` predicate methods based on MIME type (@janko)
+
+* `core` – Allow assigning back current attached file data (@janko)
+
+* `derivatives` – Fix `:derivative` value inconsistency when derivatives are being promoted (@janko)
+
+* `add_metadata` – Add `#add_metadata` method for adding metadata to uploaded files (@janko)
+
+* `derivatives` – Add `:io` and `:attacher` values to instrumentation event payload (@janko)
+
+## 3.1.0 (2019-11-15) [[release notes]](https://shrinerb.com/docs/release_notes/3.1.0)
+
+* `default_storage` – Coerce storage key to symbol in `Attacher#cache_key` & `Attacher#store_key` (@janko)
+
+* `core` – Coerce storage key to symbol in `Attacher#cache_key` & `Attacher#store_key` (@janko)
+
+* `add_metadata` – Define metadata methods only for the target uploader class (@janko)
+
+* `derivatives` – Add `:storage` option to `Attacher#create_derivatives` (@janko)
+
+* `store_dimensions` – Propagate exceptions on loading `ruby-vips` in `:vips` analyzer (@janko)
+
+* `signature` – Allow skipping rewinding by passing `rewind: false` to `Shrine.signature` (@janko)
+
+* `derivatives` – Add `Attacher.derivatives` alias for `Attacher.derivatives_processor` (@janko)
+
+## 3.0.1 (2019-10-17) [[release notes]](https://shrinerb.com/docs/release_notes/3.0.1)
+
+* `metadata_attributes` – Fix exception being raised when there is no attached file (@janko)
+
+* `core` – Simplify `UploadedFile#inspect` output (@janko)
+
+## 3.0.0 (2019-10-14) [[release notes]](https://shrinerb.com/docs/release_notes/3.0.0)
 
 * `derivation_endpoint` – Pass `action: :derivation` when uploading derivation results (@janko)
 
@@ -230,6 +282,8 @@
 
 * `core` – Add `Attacher#data` and `Attacher.from_data` for dumping to and loading from a Hash (@janko)
 
+* `core` – Change `Attacher#assign` to raise exception when non-cached file is assigned (@janko)
+
 * `core` – Enable `Attacher#assign` to accept cached file data as a Hash (@janko)
 
 * `core` – Add `Attacher#file` alias for `Attacher#get` (@janko)
@@ -356,7 +410,7 @@
 
 * `s3` – Drop support for `aws-sdk` 2.x (@janko)
 
-## 2.19.0 (2019-07-18)
+## 2.19.0 (2019-07-18) [[release notes]](https://shrinerb.com/docs/release_notes/2.19.0)
 
 * `pretty_location` – Allow specifying a different identifier from `id` (@00dav00)
 
@@ -412,7 +466,7 @@
 
 * `core` – Allow registering storage objects under string keys (@janko)
 
-## 2.18.0 (2019-06-24)
+## 2.18.0 (2019-06-24) [[release notes]](https://shrinerb.com/docs/release_notes/2.18.0)
 
 * `core` – Add `Shrine.upload` method as a shorthand for `Shrine.new(...).upload(...)` (@janko)
 
@@ -436,7 +490,7 @@
 
 * `parsed_json` – Fix overriden `Attacher#assign` not accepting second argument (@janko)
 
-## 2.17.0 (2019-05-06)
+## 2.17.0 (2019-05-06) [[release notes]](https://shrinerb.com/docs/release_notes/2.17.0)
 
 * `data_uri` – Add `Attacher#assign_data_uri` which accepts additional `Shrine#upload` options (@janko)
 
@@ -486,7 +540,7 @@
 
 * `parsed_json` – Accepts hashes with symbols keys (@aglushkov)
 
-## 2.16.0 (2019-02-18)
+## 2.16.0 (2019-02-18) [[release notes]](https://shrinerb.com/docs/release_notes/2.16.0)
 
 * `derivation_endpoint` – Add `:upload_open_options` for download option for derivation result (@janko)
 
@@ -512,7 +566,7 @@
 
 * Fix `store_dimensions` plugin making second argument in `Shrine#extract_metadata` mandatory (@jrochkind)
 
-## 2.15.0 (2019-02-08)
+## 2.15.0 (2019-02-08) [[release notes]](https://shrinerb.com/docs/release_notes/2.15.0)
 
 * Add `derivation_endpoint` plugin for processing uploaded files on-the-fly (@janko)
 
@@ -522,7 +576,7 @@
 
 * Yield a new File object on `Shrine.with_file` when `tempfile` plugin is loaded (@janko)
 
-## 2.14.0 (2018-12-27)
+## 2.14.0 (2018-12-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.14.0)
 
 * Add `tempfile` plugin for easier reusing of the same uploaded file copy on disk (@janko)
 
@@ -592,7 +646,7 @@
 
 * Use a guard raise cause for `bucket` argument in S3 for an appropriate error message (@ardecvz)
 
-## 2.13.0 (2018-11-04)
+## 2.13.0 (2018-11-04) [[release notes]](https://shrinerb.com/docs/release_notes/2.13.0)
 
 * Specify UTF-8 charset in `Content-Type` response header in `presign_endpoint` plugin (@janko)
 
@@ -624,7 +678,7 @@
 
 * In `S3#upload` deprecate using aws-sdk-s3 lower than 1.14 when uploading IO objects of unknown size (@janko)
 
-## 2.12.0 (2018-08-22)
+## 2.12.0 (2018-08-22) [[release notes]](https://shrinerb.com/docs/release_notes/2.12.0)
 
 * Ignore nil values when assigning files from a remote URL (@janko)
 
@@ -652,7 +706,7 @@
 
 * Make `UploadedFile#open` always open a new IO object and close the previous one (@janko)
 
-## 2.11.0 (2018-04-28)
+## 2.11.0 (2018-04-28) [[release notes]](https://shrinerb.com/docs/release_notes/2.11.0)
 
 * Add `Shrine.with_file` for temporarily converting an IO-like object into a file (@janko)
 
@@ -680,7 +734,7 @@
 
 * Deprecate `direct_upload` plugin in favor of `upload_endpoint` and `presign_endpoint` plugins (@janko)
 
-## 2.10.0 (2018-03-28)
+## 2.10.0 (2018-03-28) [[release notes]](https://shrinerb.com/docs/release_notes/2.10.0)
 
 * Add `:fastimage` analyzer to `determine_mime_type` plugin (@mokolabs)
 
@@ -702,7 +756,7 @@
 
 * Inherit the logger on subclassing `Shrine` and make it shared across subclasses (@hmistry)
 
-## 2.9.0 (2018-01-27)
+## 2.9.0 (2018-01-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.9.0)
 
 * Support arrays of files in `versions` plugin (@janko)
 
@@ -726,7 +780,7 @@
 
 * Allow passing options to `Model#<attachment>_attacher` for overriding `Attacher` options (@janko)
 
-## 2.8.0 (2017-10-11)
+## 2.8.0 (2017-10-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.8.0)
 
 * Expand relative directory paths when initializing `Storage::FileSystem` (@janko)
 
@@ -756,7 +810,7 @@
 
 * Update `direct_upload` plugin to support Roda 3 (@janko)
 
-## 2.7.0 (2017-09-11)
+## 2.7.0 (2017-09-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.7.0)
 
 * Deprecate the `Shrine::DownloadEndpoint` constant over `Shrine.download_endpoint` (@janko)
 
@@ -824,11 +878,11 @@
 
 * Don't add a newline at the end of the base64-formatted signature (@janko)
 
-## 2.6.1 (2017-04-12)
+## 2.6.1 (2017-04-12) [[release notes]](https://shrinerb.com/docs/release_notes/2.6.1)
 
 * Fix `download_endpoint` returning incorrect reponse body in some cases (@janko)
 
-## 2.6.0 (2017-04-04)
+## 2.6.0 (2017-04-04) [[release notes]](https://shrinerb.com/docs/release_notes/2.6.0)
 
 * Make `Shrine::Storage::FileSystem#path` public which returns path to the file as a `Pathname` object (@janko)
 
@@ -900,7 +954,7 @@
 
 * Raise `Shrine::Error` when `Shrine#generate_location` returns nil (@janko)
 
-## 2.5.0 (2016-11-11)
+## 2.5.0 (2016-11-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.5.0)
 
 * Add `Attacher.default_url` as the idiomatic way of declaring default URLs (@janko)
 
@@ -926,7 +980,7 @@
 
 * Make it possible to extract multiple metadata values at once with the `add_metadata` plugin (@janko)
 
-## 2.4.1 (2016-10-17)
+## 2.4.1 (2016-10-17) [[release notes]](https://shrinerb.com/docs/release_notes/2.4.1)
 
 * Move back JSON serialization from `Attacher#write` to `Attacher#_set` (@janko)
 
@@ -936,7 +990,7 @@
 
 * In `UploadedFile#download` use extension from `#original_filename` if `#id` doesn't have it (@janko)
 
-## 2.4.0 (2016-10-11)
+## 2.4.0 (2016-10-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.4.0)
 
 * Add `#convert_before_write` and `#convert_after_read` on the Attacher for data attribute conversion (@janko)
 
@@ -972,11 +1026,11 @@
 
 * Override `#to_s` in `Shrine::Attachment` for better introspection with `puts` (@janko)
 
-## 2.3.1 (2016-09-01)
+## 2.3.1 (2016-09-01) [[release notes]](https://shrinerb.com/docs/release_notes/2.3.1)
 
 * Don't change permissions of existing directories in FileSystem storage (@janko)
 
-## 2.3.0 (2016-08-27)
+## 2.3.0 (2016-08-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.3.0)
 
 * Prevent client from caching the presign response in direct_upload plugin (@janko)
 
@@ -1002,7 +1056,7 @@
 
 * Add `:directory_permissions` to `Storage::FileSystem` (@janko)
 
-## 2.2.0 (2016-07-29)
+## 2.2.0 (2016-07-29) [[release notes]](https://shrinerb.com/docs/release_notes/2.2.0)
 
 * Soft deprecate `:phase` over `:action` in `context` (@janko)
 
@@ -1034,11 +1088,11 @@
 
 * Avoid an additional HEAD request to determine content length in multipart S3 copy (@janko)
 
-## 2.1.1 (2016-07-14)
+## 2.1.1 (2016-07-14) [[release notes]](https://shrinerb.com/docs/release_notes/2.1.1)
 
 * Fix `S3#open` throwing a NameError if `net/http` isn't required (@janko)
 
-## 2.1.0 (2016-06-27)
+## 2.1.0 (2016-06-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.1.0)
 
 * Remove `:names` from versions plugin, and deprecate generating versions in :cache phase (@janko)
 
@@ -1054,11 +1108,11 @@
 
 * Deprecate `#cached_<attachment>_data=` over using `<attachment>` for the hidden field (@janko)
 
-## 2.0.1 (2016-05-30)
+## 2.0.1 (2016-05-30) [[release notes]](https://shrinerb.com/docs/release_notes/2.0.1)
 
 * Don't override previously set default_url in versions plugin (@janko)
 
-## 2.0.0 (2016-05-19)
+## 2.0.0 (2016-05-19) [[release notes]](https://shrinerb.com/docs/release_notes/2.0.0)
 
 * Include query parameters in CDN-ed S3 URLs, making them work for private objects (@janko)
 
@@ -1138,17 +1192,17 @@
 
 * Deprecate loading the backgrounding plugin through the old "background_helpers" alias (@janko)
 
-## 1.4.2 (2016-04-19)
+## 1.4.2 (2016-04-19) [[release notes]](https://shrinerb.com/docs/release_notes/1.4.2)
 
 * Removed ActiveRecord's automatic support for optimistic locking as it wasn't stable (@janko)
 
 * Fixed record's dataset being modified after promoting preventing further updates with the same instance (@janko)
 
-## 1.4.1 (2016-04-18)
+## 1.4.1 (2016-04-18) [[release notes]](https://shrinerb.com/docs/release_notes/1.4.1)
 
 * Bring back triggering callbacks on promote in ORM plugins, and add support for optimistic locking (@janko)
 
-## 1.4.0 (2016-04-15)
+## 1.4.0 (2016-04-15) [[release notes]](https://shrinerb.com/docs/release_notes/1.4.0)
 
 * Return "Content-Length" response header in download_endpoint plugin (@janko)
 
@@ -1204,7 +1258,7 @@
 
 * Fix keep_files not to spawn a background job when file will not be deleted (@janko)
 
-## 1.3.0 (2016-03-12)
+## 1.3.0 (2016-03-12) [[release notes]](https://shrinerb.com/docs/release_notes/1.3.0)
 
 * Add `<attachment>_cached?` and `<attachment>_stored?` to migration_helpers plugin (@janko)
 
@@ -1246,7 +1300,7 @@
 
 * Fix `NameError` when silencing "missing record" errors in backgrounding (@janko)
 
-## 1.2.0 (2016-01-26)
+## 1.2.0 (2016-01-26) [[release notes]](https://shrinerb.com/docs/release_notes/1.2.0)
 
 * Make `Shrine::Attacher.promote` and `Shrine::Attacher.delete` return the record in backgrounding plugin (@janko)
 
@@ -1262,7 +1316,7 @@
 
 * Make custom metadata inherited from uploaded files and make `#extract_metadata` called only on caching (@janko)
 
-## 1.1.0 (2015-12-26)
+## 1.1.0 (2015-12-26) [[release notes]](https://shrinerb.com/docs/release_notes/1.1.0)
 
 * Rename the "background_helpers" plugin to "backgrounding" (@janko)
 
@@ -1332,7 +1386,7 @@
 
 * Reduce length of URLs generated with pretty_location plugin (@gshaw)
 
-## 1.0.0 (2015-11-27)
+## 1.0.0 (2015-11-27) [[release notes]](https://shrinerb.com/docs/release_notes/1.0.0)
 
 * Improve Windows compatibility in the FileSystem storage (@janko)
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2017 Janko Marohnić
+Copyright (c) 2015-2019 Janko Marohnić
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,18 +1,22 @@
 # [Shrine]
 
+<img src="https://shrinerb.com/img/logo.png" width="100" alt="Shrine logo: a red paperclip" align="right" />
+
 Shrine is a toolkit for handling file attachments in Ruby applications. Some highlights:
 
 * **Modular design** – the [plugin system] allows you to load only the functionality you need
 * **Memory friendly** – streaming uploads and [downloads][Retrieving Uploads] make it work great with large files
 * **Cloud storage** – store files on [disk][FileSystem], [AWS S3][S3], [Google Cloud][GCS], [Cloudinary] and others
 * **Persistence integrations** – works with [Sequel], [ActiveRecord], [ROM], [Hanami] and [Mongoid] and others
-* **Flexible processing** – generate thumbnails [up front] or [on-the-fly] using [ImageMagick] or [libvips]
+* **Flexible processing** – generate thumbnails [eagerly] or [on-the-fly] using [ImageMagick] or [libvips]
 * **Metadata validation** – [validate files][validation] based on [extracted metadata][metadata]
 * **Direct uploads** – upload asynchronously [to your app][simple upload] or [to the cloud][presigned upload] using [Uppy]
 * **Resumable uploads** – make large file uploads [resumable][resumable upload] on [S3][uppy-s3_multipart] or [tus][tus-ruby-server]
 * **Background jobs** – built-in support for [background processing][backgrounding] that supports [any backgrounding library][Backgrounding Libraries]
 
-Please follow along with the **[Getting Started guide]**.
+If you're curious how it compares to other file attachment libraries, see the
+[Advantages of Shrine]. Otherwise, follow along with the **[Getting Started
+guide]**.
 
 ## Links
 
@@ -23,6 +27,91 @@ Please follow along with the **[Getting Started guide]**.
 | Wiki                    | [github.com/shrinerb/shrine/wiki](https://github.com/shrinerb/shrine/wiki)     |
 | Help & Discussion       | [discourse.shrinerb.com](https://discourse.shrinerb.com)                       |
 
+## Setup
+
+Add the gem to your Gemfile:
+
+```rb
+# Gemfile
+gem "shrine", "~> 3.0"
+```
+
+Then add `config/initializers/shrine.rb` which sets up the storage and loads
+ORM integration:
+
+```rb
+require "shrine"
+require "shrine/storage/file_system"
+
+Shrine.storages = {
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads"),       # permanent
+}
+
+Shrine.plugin :activerecord           # loads Active Record integration
+Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
+Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files
+```
+
+Next, add the `<name>_data` column to the table you want to attach files to. For
+an "image" attachment on a `photos` table this would be an `image_data` column:
+
+```
+$ rails generate migration add_image_data_to_photos image_data:text
+```
+
+Now create an uploader class (which you can put in `app/uploaders`) and
+register the attachment on your model:
+
+```rb
+class ImageUploader < Shrine
+  # plugins and uploading logic
+end
+```
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image) # adds an `image` virtual attribute
+end
+```
+
+In our views let's now add form fields for our attachment attribute that will
+allow users to upload files:
+
+```erb
+<%= form_for @photo do |f| %>
+  <%= f.hidden_field :image, value: @photo.cached_image_data %>
+  <%= f.file_field :image %>
+  <%= f.submit %>
+<% end %>
+```
+
+When the form is submitted, in your controller you can assign the file from
+request params to the attachment attribute on the model:
+
+```rb
+class PhotosController < ApplicationController
+  def create
+    Photo.create(photo_params) # attaches the uploaded file
+    # ...
+  end
+
+  private
+
+  def photo_params
+    params.require(:photo).permit(:image)
+  end
+end
+```
+
+Once a file is uploaded and attached to the record, you can retrieve the file
+URL and display it on the page:
+
+```erb
+<%= image_tag @photo.image_url %>
+```
+
+See the **[Getting Started guide]** for further documentation.
+
 ## Inspiration
 
 Shrine was heavily inspired by [Refile] and [Roda]. From Refile it borrows the
@@ -48,6 +137,7 @@ mailing lists is expected to follow the [Shrine code of conduct][CoC].
 The gem is available as open source under the terms of the [MIT License].
 
 [Shrine]: https://shrinerb.com
+[Advantages of Shrine]: https://shrinerb.com/docs/advantages
 [plugin system]: https://shrinerb.com/docs/getting-started#plugin-system
 [Retrieving Uploads]: https://shrinerb.com/docs/retrieving-uploads
 [FileSystem]: https://shrinerb.com/docs/storage/file-system
@@ -59,8 +149,8 @@ The gem is available as open source under the terms of the [MIT License].
 [ROM]: https://github.com/shrinerb/shrine-rom
 [Hanami]: https://github.com/katafrakt/hanami-shrine
 [Mongoid]: https://github.com/shrinerb/shrine-mongoid
-[up front]: https://shrinerb.com/docs/getting-started#processing-up-front
-[on-the-fly]: https://shrinerb.com/docs/getting-started#processing-on-the-fly
+[eagerly]: https://shrinerb.com/docs/getting-started#eager-processing
+[on-the-fly]: https://shrinerb.com/docs/getting-started#on-the-fly-processing
 [ImageMagick]: https://github.com/janko/image_processing/blob/master/doc/minimagick.md#readme
 [libvips]: https://github.com/janko/image_processing/blob/master/doc/vips.md#readme
 [validation]: https://shrinerb.com/docs/validation