shrine 2.17.1 → 2.18.0

data/doc/advantages.md

@@ -84,9 +84,7 @@ Storage provides, you can ditch the Shrine's attachment implementation and use
 uploaders and uploaded files that are decoupled from attachment:
 
 ```rb
-uploader      = ImageUploader.new(:store)
-uploaded_file = uploader.upload(image) # metadata extraction, upload location generation
-
+uploaded_file = ImageUploader.upload(image, :store) # metadata extraction, upload location generation
 uploaded_file.id       #=> "44ccafc10ce6a4ff22829e8f579ee6b9.jpg"
 uplaoded_file.metadata #=> { ... extracted metadata ... }
 

data/doc/attacher.md

@@ -11,7 +11,7 @@ class Photo < Sequel::Model
 end
 ```
 
-However, you don't want to add additional methods on the model and prefer
+However, if you don't want to add additional methods on the model and prefer
 explicitness, or you need more control, you can achieve the same behaviour
 using the `Shrine::Attacher` object, which is what the attachment interface
 uses under the hood.
@@ -22,7 +22,14 @@ attacher.assign(file)                                 # equivalent to `photo.ima
 attacher.get                                          # equivalent to `photo.image`
 ```
 
-## Attributes
+The attacher will use the `<attachment>_data` attribute for storing information
+about the attachment.
+
+```rb
+attacher.data_attribute #=> :image_data
+```
+
+## Initializing
 
 The attacher object exposes the objects it uses:
 
@@ -38,9 +45,15 @@ also tell it to use different temporary and permanent storage:
 
 ```rb
 ImageUploader::Attacher.new(photo, :image, cache: :other_cache, store: :other_store)
+
+# OR
+
+photo.image_attacher(cache: :other_cache, store: :other_store)
+photo.image = file # uploads to :other_cache storage
+photo.save         # promotes to :other_store storage
 ```
 
-Note that you can pass the `:cache` and `:store` options via `Attachment.new` too:
+You can pass the `:cache` and `:store` options via `Attachment.new` too:
 
 ```rb
 class Photo < Sequel::Model
@@ -48,12 +61,8 @@ class Photo < Sequel::Model
 end
 ```
 
-The attacher will use the `<attachment>_data` attribute for storing information
-about the attachment.
-
-```rb
-attacher.data_attribute #=> :image_data
-```
+Note that it's not necessary to use the temporary storage, see the next section
+for more details.
 
 ## Assignment
 
@@ -92,10 +101,12 @@ attacher.assign(cached_file.to_json)
 
 For security reasons `#assign` doesn't accept files uploaded to permanent
 storage, but you can use `#set` to attach any `Shrine::UploadedFile` object.
+You can use this to skip temporary storage altogether and upload files directly
+to permanent storage:
 
 ```rb
-uploaded_file #=> #<Shrine::UploadedFile>
-attacher.set(uploaded_file)
+uploaded_file = attacher.store!(file) # upload a file directly to permanent storage
+attacher.set(uploaded_file)          # attach the uploaded file
 ```
 
 ## Retrieval

data/doc/carrierwave.md

@@ -62,8 +62,7 @@ deleting files, they also represent the uploaded file. Shrine has a separate
 `Shrine::UploadedFile` class which represents the uploaded file.
 
 ```rb
-uploader = ImageUploader.new(:store)
-uploaded_file = uploader.upload(image)
+uploaded_file = ImageUploader.upload(file, :store)
 uploaded_file          #=> #<Shrine::UploadedFile>
 uploaded_file.url      #=> "https://my-bucket.s3.amazonaws.com/store/kfds0lg9rer.jpg"
 uploaded_file.download #=> #<Tempfile>
@@ -381,12 +380,12 @@ end
 
 #### `#store!`, `#cache!`
 
-In Shrine you store and cache files by instantiating it with a corresponding
-storage, and calling `#upload`:
+In Shrine you store and cache files by passing the corresponding storage to
+`Shrine.upload`:
 
 ```rb
-ImageUploader.new(:cache).upload(file)
-ImageUploader.new(:store).upload(file)
+ImageUploader.upload(file, :cache)
+ImageUploader.upload(file, :store)
 ```
 
 Note that in Shrine you cannot pass in a path to the file, you always have to
@@ -398,8 +397,8 @@ pass an IO-like object, which is required to respond to: `#read(*args)`,
 In Shrine you simply call `#download` on the uploaded file:
 
 ```rb
-uploaded_file = ImageUploader.new(:store).upload(file)
-uploaded_file.download #=> #<Tempfile>
+uploaded_file = ImageUploader.upload(file, :store)
+uploaded_file.download #=> #<Tempfile:/path/to/file>
 ```
 
 #### `#url`

data/doc/design.md

@@ -66,7 +66,7 @@ name:
 Shrine.storages[:file_system] = Shrine::Storage::FileSystem.new("uploads")
 ```
 
-Now we can instantiate an uploader with this identifier, and upload files:
+Now we can instantiate an uploader with this identifier and upload files:
 
 ```rb
 uploader = Shrine.new(:file_system)

data/doc/direct_s3.md

@@ -29,7 +29,7 @@ temporary storage uploading to the `cache/` prefix:
 ```rb
 # Gemfile
 gem "shrine", "~> 2.11"
-gem "aws-sdk-s3", "~> 1.2"
+gem "aws-sdk-s3", "~> 1.14"
 ```
 ```rb
 require "shrine/storage/s3"
@@ -55,7 +55,7 @@ default. You can do that from the AWS S3 Console by going to your bucket,
 clicking on the "Permissions" tab and then on "CORS Configuration".
 
 If you're using [Uppy], this is the recommended CORS configuration for the
-[Aws S3 plugin] that should work for both POST and PUT uploads:
+[AWS S3 plugin][uppy aws-s3] that should work for both POST and PUT uploads:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -70,6 +70,7 @@ If you're using [Uppy], this is the recommended CORS configuration for the
     <AllowedHeader>x-amz-date</AllowedHeader>
     <AllowedHeader>x-amz-content-sha256</AllowedHeader>
     <AllowedHeader>content-type</AllowedHeader>
+    <AllowedHeader>content-disposition</AllowedHeader>
   </CORSRule>
   <CORSRule>
     <AllowedOrigin>*</AllowedOrigin>
@@ -114,13 +115,6 @@ Shrine.plugin :presign_endpoint, presign_options: -> (request) {
 }
 ```
 ```rb
-# config.ru (Rack)
-map "/s3/params" do
-  run Shrine.presign_endpoint(:cache)
-end
-
-# OR
-
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
   mount Shrine.presign_endpoint(:cache) => "/s3/params"
@@ -149,7 +143,7 @@ and request headers.
 }
 ```
 
-Uppy's [AWS S3][uppy aws s3] plugin would then make a request to this endpoint
+Uppy's [AWS S3][uppy aws-s3] plugin would then make a request to this endpoint
 and use these parameters to upload the file directly to S3. Once the file has
 been uploaded, you can generate a JSON representation of the uploaded file on
 the client side, and write it to the hidden attachment field (or send it
@@ -178,11 +172,11 @@ as the [Roda][roda demo] / [Rails][rails demo] demo app for a complete example
 of multiple direct S3 uploads.
 
 Also, if you're dealing with larger files, you may want to make the uploads
-resumable by using the [Aws S3 Multipart][uppy aws s3 multipart] Uppy plugin
+resumable by using the [AWS S3 Multipart][uppy aws-s3-multipart] Uppy plugin
 instead, with the [uppy-s3_multipart] gem on the backend. Your back-end
 implementation is similar, just using `Shrine.uppy_s3_multipart` in place of
-`Shrine.presign_endpoint`. Instructions can be found in uppy-s3_multipart
-README.
+`Shrine.presign_endpoint`. Instructions can be found in the [gem
+docs][uppy-s3_multipart shrine].
 
 ## Strategy B (static)
 
@@ -391,10 +385,11 @@ setup] guide.
 [roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
 [rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
 [Uppy]: https://uppy.io
-[uppy aws s3]: https://uppy.io/docs/aws-s3/
+[uppy aws-s3]: https://uppy.io/docs/aws-s3/
 [uppy aws-s3 cors]: https://uppy.io/docs/aws-s3/#S3-Bucket-configuration
-[uppy aws s3 multipart]: https://uppy.io/docs/aws-s3/
+[uppy aws-s3-multipart]: https://uppy.io/docs/aws-s3/
 [uppy-s3_multipart]: https://github.com/janko/uppy-s3_multipart
+[uppy-s3_multipart shrine]: https://github.com/janko/uppy-s3_multipart#shrine
 [Amazon S3 Data Consistency Model]: http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#ConsistencyMode
 [CORS guide]: http://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html
 [CORS API]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#put_bucket_cors-instance_method

data/doc/metadata.md

@@ -1,8 +1,7 @@
 # Extracting Metadata
 
 Before a file is uploaded, Shrine automatically extracts metadata from it, and
-stores them in the `Shrine::UploadedFile` object. By default it extracts
-`size`, `filename` and `mime_type`.
+stores them in the `Shrine::UploadedFile` object.
 
 ```rb
 uploaded_file = uploader.upload(file)
@@ -14,6 +13,15 @@ uploaded_file.metadata #=>
 # }
 ```
 
+The following metadata is extracted by default:
+
+| Key         | Default source                                     |
+| :-----      | :------                                            |
+| `filename`  | extracted from `io.original_filename` or `io.path` |
+| `mime_type` | extracted from `io.content_type`                   |
+| `size`      | extracted from `io.size`                           |
+
+
 Under the hood `Shrine#extract_metadata` is called, which you can also use
 directly to extract metadata from any IO object.
 
@@ -107,7 +115,7 @@ require "mini_magick"
 class ImageUploader < Shrine
   plugin :add_metadata
 
-  add_metadata :exif do |io|
+  add_metadata :exif do |io, context|
     Shrine.with_file(io) do |file|
       begin
         MiniMagick::Image.new(file.path).exif

data/doc/paperclip.md

@@ -73,8 +73,7 @@ Among other things, this allows you to use uploader classes standalone, which
 gives you more power:
 
 ```rb
-uploader = ImageUploader.new(:store)
-uploaded_file = uploader.upload(File.open("nature.jpg"))
+uploaded_file = ImageUploader.upload(File.open("nature.jpg"), :store)
 uploaded_file     #=> #<Shrine::UploadedFile>
 uploaded_file.url #=> "https://my-bucket.s3.amazonaws.com/store/kfds0lg9rer.jpg"
 ```

data/doc/plugins/default_url_options.md

@@ -5,7 +5,7 @@ URL options that will be applied by default for uploaded files of specified
 storages.
 
 ```rb
-plugin :default_url_options, store: { download: true }
+plugin :default_url_options, store: { expires_in: 24*60*60 }
 ```
 
 You can also generate the default URL options dynamically by using a block,

data/doc/plugins/derivation_endpoint.md

@@ -163,7 +163,8 @@ end
 # app/controllers/derivations_controller.rb
 class DerivationsController < ApplicationController
   def image
-    # we can perform authentication here
+    # ... we can perform authentication here ...
+
     set_rack_response ImageUploader.derivation_response(request.env)
   end
 

data/doc/plugins/download_endpoint.md

@@ -12,26 +12,18 @@ mounted on.
 plugin :download_endpoint, prefix: "attachments"
 ```
 
-The endpoint should then be mounted on the specified prefix:
+The plugin adds a `Shrine.download_endpoint` method which returns a Rack
+application that handles downloads using the `rack_response` plugin. You can
+run this Rack app inside your app on the prefix that you specified:
 
 ```rb
-# config.ru (Rack)
-map "/attachments" do
-  run Shrine.download_endpoint
-end
-
-# OR
-
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
+  # ...
   mount Shrine.download_endpoint => "/attachments"
 end
 ```
 
-Any uploaded file can be downloaded through this endpoint. When a file is
-requested, its content will be efficiently streamed from the storage into the
-response body.
-
 Links to the download endpoint are generated by calling
 `UploadedFile#download_url` instead of the usual `UploadedFile#url`.
 
@@ -70,7 +62,7 @@ plugin :download_endpoint, download_options: {
 You can also specify a proc to generate download options dynamically:
 
 ```rb
-plugin :download_enpdoint, download_options: -> (uploaded_file, request) {
+plugin :download_endpoint, download_options: -> (uploaded_file, request) {
   {
     sse_customer_algorithm: "AES256",
     sse_customer_key:       "secret_key",

data/doc/plugins/parsed_json.md

@@ -8,4 +8,16 @@ assign cached files with hashes/arrays.
 plugin :parsed_json
 ```
 
+```rb
+photo.image = {
+  "id"       => "sdf90s2443.jpg",
+  "storage"  => "cache",
+  "metadata" => {
+    "filename"  => "nature.jpg",
+    "size"      => 29475,
+    "mime_type" => "image/jpeg",
+  }
+}
+```
+
 [parsed_json]: /lib/shrine/plugins/parsed_json.rb

data/doc/plugins/presign_endpoint.md

@@ -17,15 +17,9 @@ a presign for the specified storage. You can run this Rack application inside
 your app:
 
 ```rb
-# config.ru (Rack)
-map "/images/presign" do
-  run ImageUploader.presign_endpoint(:cache)
-end
-
-# OR
-
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
+  # ...
   mount ImageUploader.presign_endpoint(:cache) => "/images/presign"
 end
 ```
@@ -55,6 +49,39 @@ single upload directly to the storage service, in JSON format.
 }
 ```
 
+## Calling from a controller
+
+If you want to run additional code around the presign (such as authentication),
+mounting the presign endpoint in your router might be limiting. You can instead
+create a custom controller action and handle presign requests there using
+`Shrine.presign_response`:
+
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  post "/images/presign", to: "presigns#image"
+end
+```
+```rb
+# app/controllers/presigns_controller.rb (Rails)
+class PresignsController < ApplicationController
+  def image
+    # ... we can perform authentication here ...
+
+    set_rack_response ImageUploader.presign_response(:cache, env)
+  end
+
+  private
+
+  def set_rack_response((status, headers, body))
+    self.status = status
+    self.headers.merge!(headers)
+    self.response_body = body
+  end
+end
+```
+
 ## Location
 
 By default the generated location won't have any file extension, but you can
@@ -121,10 +148,12 @@ end
 
 ## Ad-hoc options
 
-You can override any of the options above when creating the endpoint:
+You can override any of the options above when creating the endpoint/response:
 
 ```rb
 Shrine.presign_endpoint(:cache, presign_location: "${filename}")
+# or
+Shrine.presign_response(:cache, env, presign_location: "${filename}")
 ```
 
 [presign_endpoint]: /lib/shrine/plugins/presign_endpoint.rb

data/doc/plugins/upload_endpoint.md

@@ -11,18 +11,12 @@ plugin :upload_endpoint
 The plugin adds a `Shrine.upload_endpoint` method which, given a storage
 identifier, returns a Rack application that accepts multipart POST requests,
 and uploads received files to the specified storage. You can run this Rack
-papplication inside your app:
+application inside your app:
 
 ```rb
-# config.ru (Rack)
-map "/images/upload" do
-  run ImageUploader.upload_endpoint(:cache)
-end
-
-# OR
-
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
+  # ...
   mount ImageUploader.upload_endpoint(:cache) => "/images/upload"
 end
 ```
@@ -52,6 +46,39 @@ This JSON string can now be assigned to an attachment attribute instead of a
 raw file. In a form it can be written to a hidden attachment field, and then it
 can be assigned as the attachment.
 
+## Calling from a controller
+
+If you want to run additional code around the upload (such as authentication),
+mounting the upload endpoint in your router might be limiting. You can instead
+create a custom controller action and handle upload requests there using
+`Shrine.upload_response`:
+
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  post "/images/upload", to: "uploads#image"
+end
+```
+```rb
+# app/controllers/uploads_controller.rb (Rails)
+class UploadsController < ApplicationController
+  def image
+    # ... we can perform authentication here ...
+
+    set_rack_response ImageUploader.upload_response(:cache, env)
+  end
+
+  private
+
+  def set_rack_response((status, headers, body))
+    self.status = status
+    self.headers.merge!(headers)
+    self.response_body = body
+  end
+end
+```
+
 ## Limiting filesize
 
 It's good practice to limit the accepted filesize of uploaded files. You can do
@@ -64,15 +91,6 @@ plugin :upload_endpoint, max_size: 20*1024*1024 # 20 MB
 If the uploaded file is larger than the specified value, a `413 Payload Too
 Large` response will be returned.
 
-## Checksum
-
-If you want the upload endpoint to verify the integrity of the uploaded file,
-you can include the `Content-MD5` header in the request filled with the
-base64-encoded MD5 hash of the file that was calculated prior to the upload,
-and the endpoint will automatically use it to verify the uploaded data.
-
-If the checksums don't match, a `460 Checksum Mismatch` response is returned.
-
 ## Context
 
 The upload context will *not* contain `:record` and `:name` values, as the
@@ -96,10 +114,34 @@ You can also customize the upload itself via the `:upload` option:
 
 ```rb
 plugin :upload_endpoint, upload: -> (io, context, request) do
-  Shrine.new(:cache).upload(io, context)
+  Shrine.upload(io, :cache, context)
 end
 ```
 
+## URL
+
+You can have the endpoint include the uploaded file URL in the response body
+by specifying the `:url` option:
+
+```rb
+plugin :upload_endpoint, url: true
+# or
+plugin :upload_endpoint, url: { public: true }
+# or
+plugin :upload_endpoint, url: -> (uploaded_file, request) {
+  uploaded_file.url(**options)
+}
+```
+
+In this case the response body will be:
+
+```rb
+{
+  "data": { "id": "...", "storage": "...", "metadata": {...} },
+  "url": "https://example.com/path/to/file"
+}
+```
+
 ## Response
 
 The response returned by the endpoint can be customized via the
@@ -114,11 +156,22 @@ end
 
 ## Ad-hoc options
 
-You can override any of the options above when creating the endpoint:
+You can override any of the options above when creating the endpoint/response:
 
 ```rb
 Shrine.upload_endpoint(:cache, max_size: 20*1024*1024)
+# or
+Shrine.upload_response(:cache, env, max_size: 20*1024*1024)
 ```
 
+## Checksum
+
+If you want the upload endpoint to verify the integrity of the uploaded file,
+you can include the `Content-MD5` header in the request filled with the
+base64-encoded MD5 hash of the file that was calculated prior to the upload,
+and the endpoint will automatically use it to verify the uploaded data.
+
+If the checksums don't match, a `460 Checksum Mismatch` response is returned.
+
 [upload_endpoint]: /lib/shrine/plugins/upload_endpoint.rb
 [Uppy]: https://uppy.io