shrine 3.0.0 → 3.2.2
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of shrine might be problematic. Click here for more details.
- checksums.yaml +4 -4
- data/CHANGELOG.md +87 -33
- data/LICENSE.txt +1 -1
- data/README.md +94 -4
- data/doc/advantages.md +35 -18
- data/doc/attacher.md +16 -17
- data/doc/carrierwave.md +75 -34
- data/doc/changing_derivatives.md +39 -39
- data/doc/design.md +134 -85
- data/doc/external/articles.md +56 -41
- data/doc/external/extensions.md +38 -34
- data/doc/getting_started.md +182 -112
- data/doc/metadata.md +79 -43
- data/doc/multiple_files.md +5 -3
- data/doc/paperclip.md +110 -42
- data/doc/plugins/activerecord.md +5 -5
- data/doc/plugins/add_metadata.md +92 -35
- data/doc/plugins/backgrounding.md +12 -2
- data/doc/plugins/column.md +36 -7
- data/doc/plugins/data_uri.md +2 -2
- data/doc/plugins/default_url.md +6 -3
- data/doc/plugins/derivation_endpoint.md +26 -28
- data/doc/plugins/derivatives.md +205 -169
- data/doc/plugins/determine_mime_type.md +2 -2
- data/doc/plugins/entity.md +3 -3
- data/doc/plugins/form_assign.md +5 -5
- data/doc/plugins/included.md +25 -5
- data/doc/plugins/infer_extension.md +2 -2
- data/doc/plugins/instrumentation.md +1 -1
- data/doc/plugins/metadata_attributes.md +21 -10
- data/doc/plugins/model.md +4 -4
- data/doc/plugins/persistence.md +1 -0
- data/doc/plugins/refresh_metadata.md +5 -4
- data/doc/plugins/remote_url.md +8 -3
- data/doc/plugins/remove_invalid.md +9 -1
- data/doc/plugins/sequel.md +4 -4
- data/doc/plugins/signature.md +11 -2
- data/doc/plugins/store_dimensions.md +2 -2
- data/doc/plugins/type_predicates.md +96 -0
- data/doc/plugins/upload_endpoint.md +7 -11
- data/doc/plugins/upload_options.md +1 -1
- data/doc/plugins/url_options.md +2 -2
- data/doc/plugins/validation.md +14 -4
- data/doc/plugins/validation_helpers.md +3 -3
- data/doc/plugins/versions.md +11 -11
- data/doc/processing.md +289 -125
- data/doc/refile.md +39 -18
- data/doc/release_notes/2.19.0.md +1 -1
- data/doc/release_notes/3.0.0.md +275 -258
- data/doc/release_notes/3.0.1.md +22 -0
- data/doc/release_notes/3.1.0.md +73 -0
- data/doc/release_notes/3.2.0.md +96 -0
- data/doc/release_notes/3.2.1.md +32 -0
- data/doc/release_notes/3.2.2.md +14 -0
- data/doc/securing_uploads.md +3 -3
- data/doc/storage/file_system.md +1 -1
- data/doc/storage/memory.md +19 -0
- data/doc/storage/s3.md +105 -86
- data/doc/testing.md +2 -2
- data/doc/upgrading_to_3.md +115 -33
- data/doc/validation.md +3 -2
- data/lib/shrine.rb +8 -8
- data/lib/shrine/attacher.rb +19 -14
- data/lib/shrine/attachment.rb +5 -5
- data/lib/shrine/plugins.rb +22 -0
- data/lib/shrine/plugins/add_metadata.rb +12 -3
- data/lib/shrine/plugins/default_storage.rb +6 -6
- data/lib/shrine/plugins/default_url.rb +1 -1
- data/lib/shrine/plugins/derivation_endpoint.rb +10 -6
- data/lib/shrine/plugins/derivatives.rb +19 -17
- data/lib/shrine/plugins/determine_mime_type.rb +3 -3
- data/lib/shrine/plugins/entity.rb +6 -6
- data/lib/shrine/plugins/metadata_attributes.rb +1 -1
- data/lib/shrine/plugins/model.rb +3 -3
- data/lib/shrine/plugins/presign_endpoint.rb +2 -2
- data/lib/shrine/plugins/pretty_location.rb +1 -1
- data/lib/shrine/plugins/processing.rb +1 -1
- data/lib/shrine/plugins/refresh_metadata.rb +2 -2
- data/lib/shrine/plugins/remote_url.rb +3 -3
- data/lib/shrine/plugins/remove_invalid.rb +10 -5
- data/lib/shrine/plugins/signature.rb +7 -6
- data/lib/shrine/plugins/store_dimensions.rb +18 -9
- data/lib/shrine/plugins/type_predicates.rb +113 -0
- data/lib/shrine/plugins/upload_endpoint.rb +3 -3
- data/lib/shrine/plugins/upload_options.rb +2 -2
- data/lib/shrine/plugins/url_options.rb +2 -2
- data/lib/shrine/plugins/validation.rb +9 -7
- data/lib/shrine/storage/linter.rb +4 -4
- data/lib/shrine/storage/s3.rb +62 -38
- data/lib/shrine/uploaded_file.rb +5 -1
- data/lib/shrine/version.rb +2 -2
- data/shrine.gemspec +6 -7
- metadata +23 -29
@@ -95,16 +95,9 @@ plugin :upload_endpoint, max_size: 20*1024*1024 # 20 MB
|
|
95
95
|
If the uploaded file is larger than the specified value, a `413 Payload Too
|
96
96
|
Large` response will be returned.
|
97
97
|
|
98
|
-
##
|
98
|
+
## Uploader options
|
99
99
|
|
100
|
-
|
101
|
-
upload happens independently of a database record. The endpoint will send the
|
102
|
-
following upload context:
|
103
|
-
|
104
|
-
* `:action` – holds the value `:upload`
|
105
|
-
* `:request` – holds an instance of `Rack::Request`
|
106
|
-
|
107
|
-
You can update the upload context via `:upload_context`:
|
100
|
+
You can pass additional uploader options via `:upload_context`:
|
108
101
|
|
109
102
|
```rb
|
110
103
|
plugin :upload_endpoint, upload_context: -> (request) do
|
@@ -112,13 +105,16 @@ plugin :upload_endpoint, upload_context: -> (request) do
|
|
112
105
|
end
|
113
106
|
```
|
114
107
|
|
108
|
+
Note that the uploader will *not* receive `:record` and `:name` values, as the
|
109
|
+
upload happens independently of a database record.
|
110
|
+
|
115
111
|
## Upload
|
116
112
|
|
117
113
|
You can also customize the upload itself via the `:upload` option:
|
118
114
|
|
119
115
|
```rb
|
120
|
-
plugin :upload_endpoint, upload: -> (io,
|
121
|
-
Shrine.upload(io, :cache,
|
116
|
+
plugin :upload_endpoint, upload: -> (io, options, request) do
|
117
|
+
Shrine.upload(io, :cache, **options)
|
122
118
|
end
|
123
119
|
```
|
124
120
|
|
@@ -13,7 +13,7 @@ Keys are names of the registered storages, and values are either hashes or
|
|
13
13
|
blocks.
|
14
14
|
|
15
15
|
```rb
|
16
|
-
plugin :upload_options, store: -> (io,
|
16
|
+
plugin :upload_options, store: -> (io, options) do
|
17
17
|
if options[:derivative]
|
18
18
|
{ acl: "public-read" }
|
19
19
|
else
|
data/doc/plugins/url_options.md
CHANGED
@@ -15,8 +15,8 @@ which will receive the UploadedFile object along with any options that were
|
|
15
15
|
passed to `UploadedFile#url`.
|
16
16
|
|
17
17
|
```rb
|
18
|
-
plugin :url_options, store: -> (
|
19
|
-
{ response_content_disposition: ContentDisposition.attachment(
|
18
|
+
plugin :url_options, store: -> (file, options) do
|
19
|
+
{ response_content_disposition: ContentDisposition.attachment(file.original_filename) }
|
20
20
|
end
|
21
21
|
```
|
22
22
|
|
data/doc/plugins/validation.md
CHANGED
@@ -34,11 +34,12 @@ The validation block is executed in context of a `Shrine::Attacher` instance:
|
|
34
34
|
```rb
|
35
35
|
class VideoUploader < Shrine
|
36
36
|
Attacher.validate do
|
37
|
-
self
|
37
|
+
self #=> #<Shrine::Attacher>
|
38
38
|
|
39
|
-
|
40
|
-
|
41
|
-
|
39
|
+
file #=> #<Shrine::UploadedFile>
|
40
|
+
record #=> #<Movie>
|
41
|
+
name #=> :video
|
42
|
+
context #=> { ... }
|
42
43
|
end
|
43
44
|
end
|
44
45
|
```
|
@@ -83,5 +84,14 @@ You can also skip validation by passing `validate: false`:
|
|
83
84
|
attacher.assign(file, validate: false) # skips validation
|
84
85
|
```
|
85
86
|
|
87
|
+
## Manual validation
|
88
|
+
|
89
|
+
You can also run validation manually via `Attacher#validate`:
|
90
|
+
|
91
|
+
```rb
|
92
|
+
attacher.set(uploaded_file) # doesn't trigger validation
|
93
|
+
attacher.validate # runs validation
|
94
|
+
```
|
95
|
+
|
86
96
|
[validation]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/validation.rb
|
87
97
|
[validation_helpers]: https://shrinerb.com/docs/plugins/validation_helpers
|
@@ -150,11 +150,11 @@ the `:default_messages` option to the plugin:
|
|
150
150
|
```rb
|
151
151
|
plugin :validation_helpers, default_messages: {
|
152
152
|
max_size: -> (max) { I18n.t("errors.file.max_size", max: max) },
|
153
|
-
min_size: -> (
|
153
|
+
min_size: -> (min) { I18n.t("errors.file.min_size", min: min) },
|
154
154
|
max_width: -> (max) { I18n.t("errors.file.max_width", max: max) },
|
155
|
-
min_width: -> (
|
155
|
+
min_width: -> (min) { I18n.t("errors.file.min_width", min: min) },
|
156
156
|
max_height: -> (max) { I18n.t("errors.file.max_height", max: max) },
|
157
|
-
min_height: -> (
|
157
|
+
min_height: -> (min) { I18n.t("errors.file.min_height", min: min) },
|
158
158
|
max_dimensions: -> (dims) { I18n.t("errors.file.max_dimensions", dims: dims) },
|
159
159
|
min_dimensions: -> (dims) { I18n.t("errors.file.min_dimensions", dims: dims) },
|
160
160
|
mime_type_inclusion: -> (list) { I18n.t("errors.file.mime_type_inclusion", list: list) },
|
data/doc/plugins/versions.md
CHANGED
@@ -17,7 +17,7 @@ require "image_processing/mini_magick"
|
|
17
17
|
|
18
18
|
plugin :processing
|
19
19
|
|
20
|
-
process(:store) do |io,
|
20
|
+
process(:store) do |io, **options|
|
21
21
|
versions = { original: io } # retain original
|
22
22
|
|
23
23
|
io.download do |original|
|
@@ -49,10 +49,10 @@ user.avatar_data #=>
|
|
49
49
|
|
50
50
|
user.avatar #=>
|
51
51
|
# {
|
52
|
-
# :original => #<Shrine::UploadedFile
|
53
|
-
# :large => #<Shrine::UploadedFile
|
54
|
-
# :medium => #<Shrine::UploadedFile
|
55
|
-
# :small => #<Shrine::UploadedFile
|
52
|
+
# :original => #<Shrine::UploadedFile id=0gsdf.jpg" ...}>,
|
53
|
+
# :large => #<Shrine::UploadedFile id=lg043.jpg" ...}>,
|
54
|
+
# :medium => #<Shrine::UploadedFile id=kd9fk.jpg" ...}>,
|
55
|
+
# :small => #<Shrine::UploadedFile id=932fl.jpg" ...}>,
|
56
56
|
# }
|
57
57
|
|
58
58
|
user.avatar[:medium] #=> #<Shrine::UploadedFile>
|
@@ -120,7 +120,7 @@ In addition to Hashes, the plugin also supports Arrays of files. For example,
|
|
120
120
|
you might want to split a PDf into pages:
|
121
121
|
|
122
122
|
```rb
|
123
|
-
process(:store) do |io,
|
123
|
+
process(:store) do |io, **options|
|
124
124
|
versions = { pages: [] }
|
125
125
|
|
126
126
|
io.download do |pdf|
|
@@ -146,7 +146,7 @@ which you can do by adding the yielded `Shrine::UploadedFile` object as one of
|
|
146
146
|
the versions, by convention named `:original`:
|
147
147
|
|
148
148
|
```rb
|
149
|
-
process(:store) do |io,
|
149
|
+
process(:store) do |io, **options|
|
150
150
|
# processing thumbnail
|
151
151
|
{ original: io, thumbnail: thumbnail }
|
152
152
|
end
|
@@ -163,12 +163,12 @@ The version name will be available via `:version` when generating location or a
|
|
163
163
|
default URL.
|
164
164
|
|
165
165
|
```rb
|
166
|
-
def generate_location(io,
|
167
|
-
"uploads/#{
|
166
|
+
def generate_location(io, version: nil, **)
|
167
|
+
"uploads/#{version}-#{super}"
|
168
168
|
end
|
169
169
|
|
170
|
-
Attacher.default_url do |
|
171
|
-
"/images/defaults/#{
|
170
|
+
Attacher.default_url do |version: nil, **|
|
171
|
+
"/images/defaults/#{version}.jpg"
|
172
172
|
end
|
173
173
|
```
|
174
174
|
|
data/doc/processing.md
CHANGED
@@ -2,18 +2,18 @@
|
|
2
2
|
title: File Processing
|
3
3
|
---
|
4
4
|
|
5
|
-
Shrine allows you to process attached files
|
5
|
+
Shrine allows you to process attached files eagerly or on-the-fly. For
|
6
6
|
example, if your app is accepting image uploads, you can generate a predefined
|
7
7
|
set of of thumbnails when the image is attached to a record, or you can have
|
8
8
|
thumbnails generated dynamically as they're needed.
|
9
9
|
|
10
10
|
How you're going to implement processing is entirely up to you. For images it's
|
11
11
|
recommended to use the **[ImageProcessing]** gem, which provides wrappers for
|
12
|
-
processing with [
|
13
|
-
[libvips]
|
14
|
-
|
12
|
+
processing with [MiniMagick][ImageProcessing::MiniMagick] and
|
13
|
+
[libvips][ImageProcessing::Vips]. Here is an example of generating a thumbnail
|
14
|
+
with ImageProcessing:
|
15
15
|
|
16
|
-
```
|
16
|
+
```
|
17
17
|
$ brew install imagemagick
|
18
18
|
```
|
19
19
|
```rb
|
@@ -24,17 +24,21 @@ gem "image_processing", "~> 1.8"
|
|
24
24
|
require "image_processing/mini_magick"
|
25
25
|
|
26
26
|
thumbnail = ImageProcessing::MiniMagick
|
27
|
-
.source(image)
|
28
|
-
.resize_to_limit
|
27
|
+
.source(image) # input file
|
28
|
+
.resize_to_limit(600, 400) # resize macro
|
29
|
+
.colorspace("grayscale") # custom operation
|
30
|
+
.convert("jpeg") # output type
|
31
|
+
.saver(quality: 90) # output options
|
32
|
+
.call # run the pipeline
|
29
33
|
|
30
34
|
thumbnail #=> #<Tempfile:...> (a 600x400 thumbnail of the source image)
|
31
35
|
```
|
32
36
|
|
33
|
-
##
|
37
|
+
## Eager processing
|
34
38
|
|
35
39
|
Let's say we're handling images, and want to generate a predefined set of
|
36
|
-
thumbnails with various dimensions. We can use the
|
37
|
-
upload and save the processed files:
|
40
|
+
thumbnails with various dimensions. We can use the
|
41
|
+
**[`derivatives`][derivatives]** plugin to upload and save the processed files:
|
38
42
|
|
39
43
|
```rb
|
40
44
|
Shrine.plugin :derivatives
|
@@ -43,7 +47,7 @@ Shrine.plugin :derivatives
|
|
43
47
|
require "image_processing/mini_magick"
|
44
48
|
|
45
49
|
class ImageUploader < Shrine
|
46
|
-
Attacher.
|
50
|
+
Attacher.derivatives do |original|
|
47
51
|
magick = ImageProcessing::MiniMagick.source(original)
|
48
52
|
|
49
53
|
{
|
@@ -71,27 +75,54 @@ photo.image(:large).size #=> 5825949
|
|
71
75
|
photo.image(:large).mime_type #=> "image/jpeg"
|
72
76
|
```
|
73
77
|
|
74
|
-
###
|
78
|
+
### Conditional derivatives
|
75
79
|
|
76
|
-
|
77
|
-
|
78
|
-
promotion:
|
80
|
+
The `Attacher.derivatives` block is evaluated in context of a
|
81
|
+
`Shrine::Attacher` instance:
|
79
82
|
|
80
83
|
```rb
|
81
|
-
|
82
|
-
|
83
|
-
|
84
|
-
|
84
|
+
Attacher.derivatives do |original|
|
85
|
+
self #=> #<Shrine::Attacher>
|
86
|
+
|
87
|
+
file #=> #<Shrine::UploadedFile>
|
88
|
+
record #=> #<Photo>
|
89
|
+
name #=> :image
|
90
|
+
context #=> { ... }
|
91
|
+
|
92
|
+
# ...
|
93
|
+
end
|
94
|
+
```
|
95
|
+
|
96
|
+
This gives you the ability to branch the processing logic based on the
|
97
|
+
attachment information:
|
98
|
+
|
99
|
+
```rb
|
100
|
+
Attacher.derivatives do |original|
|
101
|
+
magick = ImageProcessing::MiniMagick.source(original)
|
102
|
+
result = {}
|
103
|
+
|
104
|
+
if record.is_a?(Photo)
|
105
|
+
result[:jpg] = magick.convert!("jpeg")
|
106
|
+
result[:gray] = magick.colorspace!("grayscale")
|
107
|
+
end
|
108
|
+
|
109
|
+
if file.mime_type == "image/svg+xml"
|
110
|
+
result[:png] = magick.loader(transparent: "white").convert!("png")
|
85
111
|
end
|
112
|
+
|
113
|
+
result
|
86
114
|
end
|
87
115
|
```
|
88
116
|
|
117
|
+
The [`type_predicates`][type_predicates] plugin provides convenient predicate
|
118
|
+
methods for branching based on the file type.
|
119
|
+
|
89
120
|
### Backgrounding
|
90
121
|
|
91
122
|
Since file processing can be time consuming, it's recommended to move it into a
|
92
123
|
background job.
|
93
124
|
|
94
|
-
####
|
125
|
+
#### A) Creating derivatives with promotion
|
95
126
|
|
96
127
|
The simplest way is to use the [`backgrounding`][backgrounding] plugin to move
|
97
128
|
promotion into a background job, and then create derivatives as part of
|
@@ -120,7 +151,7 @@ class PromoteJob
|
|
120
151
|
end
|
121
152
|
```
|
122
153
|
|
123
|
-
####
|
154
|
+
#### B) Creating derivatives separately from promotion
|
124
155
|
|
125
156
|
Derivatives don't need to be created as part of the attachment flow, you can
|
126
157
|
create them at any point after promotion:
|
@@ -151,7 +182,7 @@ class DerivativesJob
|
|
151
182
|
end
|
152
183
|
```
|
153
184
|
|
154
|
-
####
|
185
|
+
#### C) Creating derivatives concurrently
|
155
186
|
|
156
187
|
You can also generate derivatives concurrently:
|
157
188
|
|
@@ -163,7 +194,7 @@ class ImageUploader < Shrine
|
|
163
194
|
small: [300, 300],
|
164
195
|
}
|
165
196
|
|
166
|
-
Attacher.
|
197
|
+
Attacher.derivatives do |original, name:|
|
167
198
|
thumbnail = ImageProcessing::MiniMagick
|
168
199
|
.source(original)
|
169
200
|
.resize_to_limit!(*THUMBNAILS.fetch(name))
|
@@ -204,67 +235,97 @@ class DerivativeJob
|
|
204
235
|
end
|
205
236
|
```
|
206
237
|
|
207
|
-
###
|
238
|
+
### URL fallbacks
|
208
239
|
|
209
|
-
|
210
|
-
|
211
|
-
|
212
|
-
Shrine integration, the ImageProcessing gem that we saw earlier is a completely
|
213
|
-
generic gem.
|
240
|
+
If you're creating derivatives in a background job, you'll likely want to use
|
241
|
+
some fallbacks for derivative URLs while the background job is still
|
242
|
+
processing. You can do that with the [`default_url`][default_url] plugin.
|
214
243
|
|
215
|
-
|
216
|
-
|
244
|
+
```rb
|
245
|
+
Shrine.plugin :default_url
|
246
|
+
```
|
247
|
+
|
248
|
+
#### A) Fallback to original
|
249
|
+
|
250
|
+
You can fall back to the original file URL when the derivative is missing:
|
217
251
|
|
218
252
|
```rb
|
219
|
-
|
220
|
-
|
253
|
+
Attacher.default_url do |derivative: nil, **|
|
254
|
+
file&.url if derivative
|
255
|
+
end
|
221
256
|
```
|
222
257
|
```rb
|
223
|
-
|
258
|
+
photo.image_url(:large) #=> "https://example.com/path/to/original.jpg"
|
259
|
+
# ... background job finishes ...
|
260
|
+
photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
|
261
|
+
```
|
224
262
|
|
225
|
-
|
226
|
-
Attacher.derivatives_processor do |original|
|
227
|
-
transcoded = Tempfile.new ["transcoded", ".mp4"]
|
228
|
-
screenshot = Tempfile.new ["screenshot", ".jpg"]
|
263
|
+
#### B) Fallback to derivative
|
229
264
|
|
230
|
-
|
231
|
-
movie.transcode(transcoded.path)
|
232
|
-
movie.screenshot(screenshot.path)
|
265
|
+
You can fall back to another derivative URL when the derivative is missing:
|
233
266
|
|
234
|
-
|
235
|
-
|
267
|
+
```rb
|
268
|
+
Attacher.default_url do |derivative: nil, **|
|
269
|
+
derivatives[:optimized]&.url if derivative
|
270
|
+
end
|
271
|
+
```
|
272
|
+
```rb
|
273
|
+
photo.image_url(:large) #=> "https://example.com/path/to/optimized.jpg"
|
274
|
+
# ... background job finishes ...
|
275
|
+
photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
|
276
|
+
```
|
277
|
+
|
278
|
+
#### C) Fallback to on-the-fly
|
279
|
+
|
280
|
+
You can also fall back to [on-the-fly processing](#on-the-fly-processing),
|
281
|
+
which should generally provide the best user experience.
|
282
|
+
|
283
|
+
```rb
|
284
|
+
THUMBNAILS = {
|
285
|
+
small: [300, 300],
|
286
|
+
medium: [500, 500],
|
287
|
+
large: [800, 800],
|
288
|
+
}
|
289
|
+
|
290
|
+
Attacher.default_url do |derivative: nil, **|
|
291
|
+
file&.derivation_url(:thumbnail, *THUMBNAILS.fetch(derivative)) if derivative
|
236
292
|
end
|
237
293
|
```
|
294
|
+
```rb
|
295
|
+
photo.image_url(:large) #=> "../derivations/thumbnail/800/800/..."
|
296
|
+
# ... background job finishes ...
|
297
|
+
photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
|
298
|
+
```
|
238
299
|
|
239
300
|
## On-the-fly processing
|
240
301
|
|
241
|
-
|
302
|
+
Having eagerly created image thumbnails can be a pain to maintain, because
|
242
303
|
whenever you need to add a new version or change an existing one, you need to
|
243
|
-
retroactively apply it to all existing
|
244
|
-
guide for more details).
|
304
|
+
retroactively apply it to all existing attachments (see the [Managing
|
305
|
+
Derivatives] guide for more details).
|
245
306
|
|
246
|
-
|
247
|
-
|
248
|
-
|
249
|
-
processing such as creating image thumbnails or document
|
307
|
+
Sometimes it makes more sense to generate thumbnails dynamically as they're
|
308
|
+
requested, and then cache them for future requests. This strategy is known as
|
309
|
+
processing "**on-the-fly**" or "**on-demand**", and it's suitable for
|
310
|
+
short-running processing such as creating image thumbnails or document
|
311
|
+
previews.
|
250
312
|
|
251
313
|
Shrine provides on-the-fly processing functionality via the
|
252
|
-
[`derivation_endpoint`][derivation_endpoint] plugin.
|
253
|
-
|
254
|
-
|
255
|
-
|
256
|
-
2. mount the endpoint into your main app's router
|
257
|
-
3. define a processing block for the type files you want to generate
|
258
|
-
|
259
|
-
Together it might look something like this:
|
314
|
+
**[`derivation_endpoint`][derivation_endpoint]** plugin. You set it up by
|
315
|
+
loading the plugin with a secret key and a path prefix, mount its Rack app in
|
316
|
+
your routes on the configured path prefix, and define processing you want to
|
317
|
+
perform:
|
260
318
|
|
319
|
+
```rb
|
320
|
+
# config/initializers/shrine.rb (Rails)
|
321
|
+
# ...
|
322
|
+
Shrine.plugin :derivation_endpoints, secret_key: "<YOUR_SECRET_KEY>"
|
323
|
+
```
|
261
324
|
```rb
|
262
325
|
require "image_processing/mini_magick"
|
263
326
|
|
264
327
|
class ImageUploader < Shrine
|
265
|
-
plugin :derivation_endpoint,
|
266
|
-
secret_key: "<YOUR SECRET KEY>",
|
267
|
-
prefix: "derivations/image"
|
328
|
+
plugin :derivation_endpoint, prefix: "derivations/image" # matches mount point
|
268
329
|
|
269
330
|
derivation :thumbnail do |file, width, height|
|
270
331
|
ImageProcessing::MiniMagick
|
@@ -273,11 +334,11 @@ class ImageUploader < Shrine
|
|
273
334
|
end
|
274
335
|
end
|
275
336
|
```
|
276
|
-
|
277
337
|
```rb
|
278
338
|
# config/routes.rb (Rails)
|
279
339
|
Rails.application.routes.draw do
|
280
|
-
|
340
|
+
# ...
|
341
|
+
mount ImageUploader.derivation_endpoint => "/derivations/image"
|
281
342
|
end
|
282
343
|
```
|
283
344
|
|
@@ -293,8 +354,137 @@ The plugin is highly customizable, be sure to check out the
|
|
293
354
|
[documentation][derivation_endpoint], especially the [performance
|
294
355
|
section][derivation_endpoint performance].
|
295
356
|
|
357
|
+
### Dynamic derivation
|
358
|
+
|
359
|
+
If you have multiple types of transformations and don't want to have a
|
360
|
+
derivation for each one, you can set up a single derivation that applies any
|
361
|
+
series of transformations:
|
362
|
+
|
363
|
+
```rb
|
364
|
+
class ImageUploader < Shrine
|
365
|
+
derivation :transform do |original, transformations|
|
366
|
+
transformations = Shrine.urlsafe_deserialize(transformations)
|
367
|
+
|
368
|
+
vips = ImageProcessing::Vips.source(original)
|
369
|
+
vips.apply!(transformations)
|
370
|
+
end
|
371
|
+
end
|
372
|
+
```
|
373
|
+
```rb
|
374
|
+
photo.image.derivation_url :transform, Shrine.urlsafe_serialize(
|
375
|
+
crop: [10, 10, 500, 500],
|
376
|
+
resize_to_fit: [300, 300],
|
377
|
+
gaussblur: 1,
|
378
|
+
)
|
379
|
+
```
|
380
|
+
|
381
|
+
You can create a helper method for convenience:
|
382
|
+
|
383
|
+
```rb
|
384
|
+
def derivation_url(file, transformations)
|
385
|
+
file.derivation_url(:transform, Shrine.urlsafe_serialize(transformations))
|
386
|
+
end
|
387
|
+
```
|
388
|
+
```rb
|
389
|
+
derivation_url photo.image,
|
390
|
+
crop: [10, 10, 500, 500],
|
391
|
+
resize_to_fit: [300, 300],
|
392
|
+
gaussblur: 1
|
393
|
+
```
|
394
|
+
|
395
|
+
## Processing other filetypes
|
396
|
+
|
397
|
+
So far we've only been talking about processing images. However, there is
|
398
|
+
nothing image-specific in Shrine's processing API, you can just as well process
|
399
|
+
any other types of files. The processing tool doesn't need to have any special
|
400
|
+
Shrine integration, the ImageProcessing gem that we saw earlier is a completely
|
401
|
+
generic gem.
|
402
|
+
|
403
|
+
To demonstrate, here is an example of transcoding videos using
|
404
|
+
[streamio-ffmpeg]:
|
405
|
+
|
406
|
+
```rb
|
407
|
+
# Gemfile
|
408
|
+
gem "streamio-ffmpeg"
|
409
|
+
```
|
410
|
+
```rb
|
411
|
+
require "streamio-ffmpeg"
|
412
|
+
|
413
|
+
class VideoUploader < Shrine
|
414
|
+
Attacher.derivatives do |original|
|
415
|
+
transcoded = Tempfile.new ["transcoded", ".mp4"]
|
416
|
+
screenshot = Tempfile.new ["screenshot", ".jpg"]
|
417
|
+
|
418
|
+
movie = FFMPEG::Movie.new(original.path)
|
419
|
+
movie.transcode(transcoded.path)
|
420
|
+
movie.screenshot(screenshot.path)
|
421
|
+
|
422
|
+
{ transcoded: transcoded, screenshot: screenshot }
|
423
|
+
end
|
424
|
+
end
|
425
|
+
```
|
426
|
+
|
427
|
+
### Polymorphic uploader
|
428
|
+
|
429
|
+
Sometimes you might want an attachment attribute to accept multiple types of
|
430
|
+
files, and apply different processing depending on the type. Since Shrine's
|
431
|
+
processing blocks are evaluated dynamically, you can use conditional logic:
|
432
|
+
|
433
|
+
```rb
|
434
|
+
class PolymorphicUploader < Shrine
|
435
|
+
IMAGE_TYPES = %w[image/jpeg image/png image/webp]
|
436
|
+
VIDEO_TYPES = %w[video/mp4 video/quicktime]
|
437
|
+
PDF_TYPES = %w[application/pdf]
|
438
|
+
|
439
|
+
Attacher.validate do
|
440
|
+
validate_mime_type IMAGE_TYPES + VIDEO_TYPES + PDF_TYPES
|
441
|
+
# ...
|
442
|
+
end
|
443
|
+
|
444
|
+
Attacher.derivatives do |original|
|
445
|
+
case file.mime_type
|
446
|
+
when *IMAGE_TYPES then process_derivatives(:image, original)
|
447
|
+
when *VIDEO_TYPES then process_derivatives(:video, original)
|
448
|
+
when *PDF_TYPES then process_derivatives(:pdf, original)
|
449
|
+
end
|
450
|
+
end
|
451
|
+
|
452
|
+
Attacher.derivatives :image do |original|
|
453
|
+
# ...
|
454
|
+
end
|
455
|
+
|
456
|
+
Attacher.derivatives :video do |original|
|
457
|
+
# ...
|
458
|
+
end
|
459
|
+
|
460
|
+
Attacher.derivatives :pdf do |original|
|
461
|
+
# ...
|
462
|
+
end
|
463
|
+
end
|
464
|
+
```
|
465
|
+
|
296
466
|
## Extras
|
297
467
|
|
468
|
+
### Automatic derivatives
|
469
|
+
|
470
|
+
If you would like derivatives to be automatically created with promotion, you
|
471
|
+
can override `Attacher#promote` for call `Attacher#create_derivatives` before
|
472
|
+
promotion:
|
473
|
+
|
474
|
+
```rb
|
475
|
+
class Shrine::Attacher
|
476
|
+
def promote(*)
|
477
|
+
create_derivatives
|
478
|
+
super
|
479
|
+
end
|
480
|
+
end
|
481
|
+
```
|
482
|
+
|
483
|
+
This shouldn't be needed if you're processing in the
|
484
|
+
[background](#backgrounding), as in that case you have a background worker that
|
485
|
+
will be called for each attachment, so you can call
|
486
|
+
`Attacher#create_derivatives` there.
|
487
|
+
|
298
488
|
### libvips
|
299
489
|
|
300
490
|
As mentioned, ImageProcessing gem also has an alternative backend for
|
@@ -304,9 +494,9 @@ characteristics – it's often **multiple times faster** than ImageMagick and ha
|
|
304
494
|
low memory usage (see [Why is libvips quick]).
|
305
495
|
|
306
496
|
Using libvips is as easy as installing it and switching to the
|
307
|
-
`ImageProcessing::Vips` backend:
|
497
|
+
[`ImageProcessing::Vips`][ImageProcessing::Vips] backend:
|
308
498
|
|
309
|
-
```
|
499
|
+
```
|
310
500
|
$ brew install vips
|
311
501
|
```
|
312
502
|
|
@@ -326,7 +516,7 @@ thumbnail = ImageProcessing::Vips
|
|
326
516
|
thumbnail #=> #<Tempfile:...> (a 600x400 thumbnail of the source image)
|
327
517
|
```
|
328
518
|
|
329
|
-
### Parallelize
|
519
|
+
### Parallelize uploads
|
330
520
|
|
331
521
|
If you're generating derivatives, you can parallelize the uploads using the
|
332
522
|
[concurrent-ruby] gem:
|
@@ -351,86 +541,60 @@ Concurrent::Promises.zip(*tasks).wait!
|
|
351
541
|
|
352
542
|
### External processing
|
353
543
|
|
354
|
-
|
355
|
-
|
356
|
-
|
357
|
-
|
544
|
+
You can also integrate Shrine with 3rd-party processing services such as
|
545
|
+
[Cloudinary] and [Imgix]. In the most common case, you'd serve images directly
|
546
|
+
from these services, see the corresponding plugin docs for more details
|
547
|
+
([shrine-cloudinary], [shrine-imgix] and [others][external storages])
|
548
|
+
|
549
|
+
You can also choose to use these services as an implementation detail of your
|
550
|
+
application, by downloading the processed images and saving them to your
|
551
|
+
storage. Here is how you might store files processed by Imgix as derivatives:
|
358
552
|
|
359
553
|
```rb
|
360
554
|
# Gemfile
|
361
555
|
gem "down", "~> 5.0"
|
362
556
|
gem "http", "~> 4.0"
|
557
|
+
gem "shrine-imgix", "~> 0.5"
|
558
|
+
```
|
559
|
+
```rb
|
560
|
+
Shrine.plugin :derivatives
|
561
|
+
Shrine.plugin :imgix, client: { host: "my-app.imgix.net", secure_url_token: "secret" }
|
363
562
|
```
|
364
|
-
|
365
563
|
```rb
|
366
564
|
require "down/http"
|
367
565
|
|
368
566
|
class ImageUploader < Shrine
|
369
|
-
|
370
|
-
|
371
|
-
prefix: "derivations/image",
|
372
|
-
download: false
|
373
|
-
|
374
|
-
derivation :thumbnail do |width, height|
|
375
|
-
# generate thumbnails using ImageOptim.com
|
376
|
-
down = Down::Http.new(method: :post)
|
377
|
-
down.download("https://im2.io/<USERNAME>/#{width}x#{height}/#{source.url}")
|
567
|
+
IMGIX_THUMBNAIL = -> (file, width, height) do
|
568
|
+
Down::Http.download(file.imgix_url(w: width, h: height))
|
378
569
|
end
|
379
|
-
end
|
380
|
-
```
|
381
570
|
|
382
|
-
|
383
|
-
|
384
|
-
[
|
385
|
-
|
386
|
-
[
|
387
|
-
|
388
|
-
|
389
|
-
|
390
|
-
# Gemfile
|
391
|
-
gem "shrine-cloudinary"
|
392
|
-
```
|
393
|
-
|
394
|
-
```rb
|
395
|
-
require "cloudinary"
|
396
|
-
require "shrine/storage/cloudinary"
|
397
|
-
|
398
|
-
Cloudinary.config(
|
399
|
-
cloud_name: "<YOUR_CLOUD_NAME>",
|
400
|
-
api_key: "<YOUR_API_KEY>",
|
401
|
-
api_secret: "<YOUR_API_SECRET>",
|
402
|
-
)
|
403
|
-
|
404
|
-
Shrine.storages = {
|
405
|
-
cache: Shrine::Storage::Cloudinary.new(prefix: "cache"),
|
406
|
-
store: Shrine::Storage::Cloudinary.new,
|
407
|
-
}
|
408
|
-
```
|
409
|
-
|
410
|
-
Now when we upload our images to Cloudinary, we can generate URLs with various
|
411
|
-
processing parameters:
|
412
|
-
|
413
|
-
```rb
|
414
|
-
photo.image_url(width: 100, height: 100, crop: :fit)
|
415
|
-
#=> "http://res.cloudinary.com/myapp/image/upload/w_100,h_100,c_fit/nature.jpg"
|
571
|
+
Attacher.derivatives do
|
572
|
+
{
|
573
|
+
large: IMGIX_THUMBNAIL[file, 800, 800],
|
574
|
+
medium: IMGIX_THUMBNAIL[file, 500, 500],
|
575
|
+
small: IMGIX_THUMBNAIL[file, 300, 300],
|
576
|
+
}
|
577
|
+
end
|
578
|
+
end
|
416
579
|
```
|
417
580
|
|
418
581
|
[`Shrine::UploadedFile`]: http://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
|
419
582
|
[ImageProcessing]: https://github.com/janko/image_processing
|
420
|
-
[
|
421
|
-
[
|
422
|
-
[libvips]: http://libvips.github.io/libvips/
|
423
|
-
[Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
|
424
|
-
[ImageOptim.com]: https://imageoptim.com/api
|
583
|
+
[ImageProcessing::MiniMagick]: https://github.com/janko/image_processing/blob/master/doc/minimagick.md#readme
|
584
|
+
[ImageProcessing::Vips]: https://github.com/janko/image_processing/blob/master/doc/vips.md#readme
|
425
585
|
[streamio-ffmpeg]: https://github.com/streamio/streamio-ffmpeg
|
426
586
|
[Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
|
427
|
-
[Cloudinary]: https://cloudinary.com
|
587
|
+
[Cloudinary]: https://cloudinary.com/
|
588
|
+
[Imgix]: https://www.imgix.com/
|
428
589
|
[shrine-cloudinary]: https://github.com/shrinerb/shrine-cloudinary
|
590
|
+
[shrine-imgix]: https://github.com/shrinerb/shrine-imgix
|
429
591
|
[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding
|
430
|
-
[ruby-vips]: https://github.com/libvips/ruby-vips
|
431
|
-
[MiniMagick]: https://github.com/minimagick/minimagick
|
432
592
|
[derivation_endpoint]: https://shrinerb.com/docs/plugins/derivation_endpoint
|
433
593
|
[derivation_endpoint performance]: https://shrinerb.com/docs/plugins/derivation_endpoint#performance
|
434
594
|
[derivatives]: https://shrinerb.com/docs/plugins/derivatives
|
435
595
|
[concurrent-ruby]: https://github.com/ruby-concurrency/concurrent-ruby
|
436
|
-
[
|
596
|
+
[default_url]: https://shrinerb.com/docs/plugins/default_url
|
597
|
+
[external storages]: https://shrinerb.com/docs/external/extensions#storages
|
598
|
+
[libvips]: https://libvips.github.io/libvips/
|
599
|
+
[Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
|
600
|
+
[type_predicates]: https://shrinerb.com/docs/plugins/type_predicates
|