shrine 2.17.1 → 2.18.0

data/doc/plugins/versions.md

@@ -61,7 +61,7 @@ The plugin also extends the `Attacher#url` to accept versions:
 
 ```rb
 user.avatar_url(:large)
-user.avatar_url(:small, download: true) # with URL options
+user.avatar_url(:small, public: true) # with URL options
 ```
 
 `Shrine.uploaded_file` will also instantiate a hash of `Shrine::UploadedFile`

data/doc/refile.md

@@ -14,18 +14,15 @@ named "storages", it uses the same IO abstraction for uploading and representing
 uploaded files, similar attachment logic, and direct uploads are also supported.
 
 While in Refile you work with storages directly, Shrine uses *uploaders* which
-act as wrappers around storages:
+wrap storage uploads:
 
 ```rb
 storage = Shrine.storages[:store]
-storage #=> #<Shrine::Storage::S3 ...>
+storage #=> #<Shrine::Storage::S3>
 
-uploader = Shrine.new(:store)
-uploader         #=> #<Shrine @storage_key=:store @storage=#<Shrine::Storage::S3>>
-uploader.storage #=> #<Shrine::Storage::S3 ...>
-
-uploaded_file = uploader.upload(image)
-uploaded_file #=> #<Shrine::UploadedFile>
+uploaded_file = Shrine.upload(image, :store)
+uploaded_file #=> #<Shrine::UploadedFile ...>
+uploaded_file.storage #=> #<Shrine::Storage::S3>
 ```
 
 This way Shrine can perform tasks like generating location, extracting
@@ -352,7 +349,7 @@ In Shrine equivalents are (private) methods `Shrine#extract_filename` and
 #### `.app_url`
 
 You should use your framework to generate the URL to your mounted direct
-enpdoint.
+endpoint.
 
 #### `.attachment_url`, `.file_url`
 

data/doc/release_notes/2.17.0.md

@@ -4,7 +4,7 @@
   endpoint instance, which override any plugin options.
 
   ```rb
-  Shrine.download_enpdoint(disposition: "attachment")
+  Shrine.download_endpoint(disposition: "attachment")
   ```
 
 * The `Shrine::Attacher#assign_remote_url` method in the `remote_url` plugin
@@ -119,7 +119,7 @@
   anymore, it's now a PORO whose instance responds to `#call`. This shouldn't
   affect your code unless you were calling Roda methods on that class.
 
-* The plugin options of `upload_enpdoint`, `presign_endpoint`, and
+* The plugin options of `upload_endpoint`, `presign_endpoint`, and
   `download_endpoint` are now internally stored in a different place in
   `Shrine.opts`. This shouldn't affect your code unless you were accessing
   these options directly.

data/doc/release_notes/2.18.0.md

@@ -0,0 +1,155 @@
+## New features
+
+* Added `Shrine.upload_response` to `upload_endpoint` plugin for handling
+  uploads inside a custom controller. This allows authenticating uploads on the
+  controller level:
+
+  ```rb
+  # config/routes.rb (Rails)
+  Rails.application.routes.draw do
+    # ...
+    post "/images/upload" => "uploads#image"
+  end
+  ```
+  ```rb
+  # app/controllers/uploads_controller.rb (Rails)
+  class UploadsController < ApplicationController
+    def image
+      authenticate_user!
+
+      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
+  ```
+
+* Added `Shrine.presign_response` to `presign_endpoint` plugin for handling
+  uploads inside a custom controller. This allows authenticating uploads on the
+  controller level:
+
+  ```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
+      authenticate_user!
+
+      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
+  ```
+
+* The `:url` option has been added to the `upload_endpoint` plugin for
+  returning the uploaded file URL in the response.
+
+  ```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)
+  }
+  ```
+  ```rb
+  {
+    "data": { "id": "...", "storage": "...", "metadata": {...} },
+    "url": "https://example.com/path/to/file"
+  }
+  ```
+
+  This will additionally be recognized by Uppy, so e.g. the Dashboard plugin
+  will display preview link to the file.
+
+  ```js
+  uppy.on('upload-success', (file, response) => {
+    response.uploadURL // => "https://example.com/path/to/file"
+  })
+  ```
+
+## Other improvements
+
+* The `upload_endpoint` now accepts the `files[]` array that Uppy's XHR Upload
+  plugin sends by default. This means the `fieldName` parameter can now be
+  omitted.
+
+  ```js
+  // BEFORE
+  uppy.use(Uppy.XHRUpload, {
+    endpoint: '/upload',
+    fieldName: 'file',
+  })
+
+  // AFTER
+  uppy.use(Uppy.XHRUpload, {
+    endpoint: '/upload',
+  })
+  ```
+
+* The `Shrine.upload` convenience method has been added, which is a bit shorter
+  when you don't need the uploader instance.
+
+  ```rb
+  Shrine.upload(io, :storage)
+
+  # expands to
+
+  uploader = Shrine.new(:storage)
+  uploader.upload(io)
+  ```
+
+* The `Shrine.Attachment(...)` shorthand for `Shrine::Attachment.new(...)` has
+  been added.
+
+  ```rb
+  class Photo
+    include Shrine::Attachment(:image) # expands to Shrine::Attachment.new(:image)
+  end
+  ```
+
+* The `parsed_json` and `rack_file` plugins now correctly retain the second
+  argument in the `Attacher#assign` method signature.
+
+## Backwards compatibility
+
+* The `aws-sdk-s3` version lower than `1.14.0` has been deprecated for
+  `Shrine::Storage::S3` and will be removed in Shrine 3.
+
+* The `:download` option in `Shrine::Storage::S3#url` has been deprecated and
+  will be removed in Shrine 3. The `:response_content_disposition` option
+  should be used instead.
+
+  ```rb
+  # This is deprecated:
+  uploaded_file.url(download: true)
+
+  # Use this:
+  uploaded_file.url(response_content_disposition: "attachment")
+  ```
+
+* `Shrine::Storage::S3#upload` doesn't backfill the `size` metadata value for
+  input IOs with unknown size (e.g. pipes, sockets). This behaviour was not
+  documented and added unnecessary complexity. Moreover, this functionality
+  should be storage agnostic, so if someone requests it we can add it back in
+  form of a plugin.

data/doc/retrieving_uploads.md

@@ -25,12 +25,9 @@ uploaded_file.eof?   # => false
 uploaded_file.close  # closes the underlying IO object (this should be called when you're done)
 ```
 
-In reality these methods are simply delegated on the IO object returned by the
-`Storage#open` method of the underlying Shrine storage. For
-`Shrine::Storage::FileSystem` this IO object will be a `File` object, while for
-`Shrine::Storage::S3` (and most other remote storages) it will be a
-[`Down::ChunkedIO`] object. `Storage#open` is implicitly called when any of
-these IO methods are called for the first time.
+These methods are simply delegated on the IO object returned by the
+`Storage#open` method of the underlying Shrine storage. `Storage#open` is
+implicitly called when any of these IO methods are called for the first time.
 
 ```rb
 uploaded_file.read(10) # calls `Storage#open` and assigns result to an instance variable
@@ -45,6 +42,48 @@ You can retrieve the underlying IO object returned by `Storage#open` with
 uploaded_file.to_io # the underlying IO object returned by `Storage#open`
 ```
 
+## `Storage#open`
+
+The underlying IO object that `Shrine::UploadedFile` will use depends on the
+storage. The `FileSystem` storage will return a `File` object, while `S3` and
+most other remote storages will return [`Down::ChunkedIO`] that downloads file
+content on-demand.
+
+```rb
+Shrine.storages = {
+  file_system: Shrine::Storage::FileSystem.new(...),
+  s3:          Shrine::Storage::S3.new(...),
+}
+
+local_file = Shrine.upload(file, :file_system)
+local_file.to_io #=> #<File:/path/to/file>
+
+remote_file = Shrine.upload(file, :s3)
+remote_file.to_io #=> #<Down::ChunkedIO> (opens HTTP connection)
+remote_file.read(1*1024*1024) # downloads first 1MB
+remote_file.read(1*1024*1024) # downloads next 1MB
+remote_file.close # closes HTTP connection
+```
+
+The `Down::ChunkedIO` object will cache downloaded content to disk in order to
+be rewindable, which is used in a places such as metadata extraction.
+
+```rb
+remote_file.read(1*1024*1024) # downloads and caches first 1MB
+remote_file.rewind
+remote_file.read(1*1024*1024) # reads first 1MB from the cache
+remote_file.read(1*1024*1024) # downloads and caches next 1MB
+```
+
+If you want to turn off caching to disk, most storages allow you to pass
+`:rewindable` to `Storage#open`:
+
+```rb
+remote_file.open(rewindable: false)
+remote_file.read(1*1024*1024) # downloads first 1MB (no caching to disk)
+remote_file.rewind #~> IOError: this Down::ChunkedIO is not rewindable
+```
+
 ## Opening
 
 The `Shrine::UploadedFile#open` method can be used to open the uploaded file

data/doc/storage/s3.md

@@ -4,7 +4,7 @@ The S3 storage handles uploads to Amazon S3 service, using the [aws-sdk-s3]
 gem:
 
 ```rb
-gem "aws-sdk-s3", "~> 1.2"
+gem "aws-sdk-s3", "~> 1.14"
 ```
 
 It can be initialized by providing the bucket name and credentials:
@@ -101,18 +101,16 @@ are generated using the storage directly.
 
 ## URL options
 
-This storage supports various URL options that will be forwarded from uploaded
-file.
+Other than [`:host`](#url-host) and [`:public`](#public-uploads) URL options,
+all additional options are forwarded to [`Aws::S3::Object#presigned_url`].
 
 ```rb
-s3.url(public: true)   # public URL without signed parameters
-s3.url(download: true) # forced download URL
-```
-
-All other options are forwarded to the aws-sdk-s3 gem:
-
-```rb
-s3.url(expires_in: 15, response_content_disposition: "...")
+s3.url(
+  expires_in: 15,
+  response_content_disposition: ContentDisposition.attachment("my-filename"),
+  response_content_type: "foo/bar",
+  # ...
+)
 ```
 
 ## URL Host
@@ -258,7 +256,7 @@ To use Amazon S3's [Transfer Acceleration] feature, set
 `:use_accelerate_endpoint` to `true` when initializing the storage:
 
 ```rb
-Shrine::Storage::S3.new(use_accelerate_enpdoint: true, **other_options)
+Shrine::Storage::S3.new(use_accelerate_endpoint: true, **other_options)
 ```
 
 ## Clearing cache
@@ -285,6 +283,7 @@ can scale exponentially by using more prefixes.
 [uploading]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#put-instance_method
 [copying]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#copy_from-instance_method
 [presigning]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
+[`Aws::S3::Object#presigned_url`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_url-instance_method
 [aws-sdk-s3]: https://github.com/aws/aws-sdk-ruby/tree/master/gems/aws-sdk-s3
 [Transfer Acceleration]: http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html
 [object lifecycle]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html

data/lib/shrine.rb

@@ -91,10 +91,9 @@ class Shrine
     end
 
     # Retrieves the storage under the given identifier (can be a Symbol or
-    # a String), and raises Shrine::Error if the storage is missing.
+    # a String), raising Shrine::Error if the storage is missing.
     def find_storage(name)
-      storages.each { |key, value| return value if key.to_s == name.to_s }
-      raise Error, "storage #{name.inspect} isn't registered on #{self}"
+      storages[name.to_sym] or fail Error, "storage #{name.inspect} isn't registered on #{self}"
     end
 
     # Generates an instance of Shrine::Attachment to be included in the
@@ -103,10 +102,18 @@ class Shrine
     #     class Photo
     #       include Shrine.attachment(:image) # creates a Shrine::Attachment object
     #     end
-    def attachment(name, *args)
+    def Attachment(name, *args)
       self::Attachment.new(name, *args)
     end
-    alias [] attachment
+    alias attachment Attachment
+    alias [] Attachment
+
+    # Uploads the file to the specified storage. It delegates to `Shrine#upload`.
+    #
+    #     Shrine.upload(io, :store) #=> #<Shrine::UploadedFile>
+    def upload(io, storage, context = {})
+      new(storage).upload(io, context)
+    end
 
     # Instantiates a Shrine::UploadedFile from a hash, and optionally
     # yields the returned object.
@@ -161,6 +168,8 @@ class Shrine
     attr_reader :storage
 
     # Accepts a storage symbol registered in `Shrine.storages`.
+    #
+    #     Shrine.new(:store)
     def initialize(storage_key)
       @storage = self.class.find_storage(storage_key)
       @storage_key = storage_key.to_sym
@@ -176,6 +185,11 @@ class Shrine
     # optional context hash (used internally by Shrine::Attacher). It calls
     # user-defined #process, and afterwards it calls #store. The `io` is
     # closed after upload.
+    #
+    #   uploader.upload(io)
+    #   uploader.upload(io, metadata: { "foo" => "bar" })           # add metadata
+    #   uploader.upload(io, location: "path/to/file")               # specify location
+    #   uploader.upload(io, upload_options: { acl: "public-read" }) # add upload options
     def upload(io, context = {})
       io = processed(io, context) || io
       store(io, context)

data/lib/shrine/attacher.rb

@@ -52,7 +52,7 @@ class Shrine
       def initialize(record, name, cache: :cache, store: :store)
         @cache   = shrine_class.new(cache)
         @store   = shrine_class.new(store)
-        @context = {record: record, name: name}
+        @context = { record: record, name: name }
         @errors  = []
       end
 

data/lib/shrine/plugins/data_uri.rb

@@ -63,11 +63,9 @@ class Shrine
       end
 
       module AttachmentMethods
-        def initialize(*)
+        def initialize(name, **options)
           super
 
-          name = attachment_name
-
           define_method :"#{name}_data_uri=" do |uri|
             send(:"#{name}_attacher").data_uri = uri
           end

data/lib/shrine/plugins/presign_endpoint.rb

@@ -31,6 +31,27 @@ class Shrine
             **options,
           )
         end
+
+        # Calls the presign endpoint passing the request information, and
+        # returns the Rack response triple.
+        #
+        # It performs the same mounting logic that Rack and other web
+        # frameworks use, and is meant for cases where statically mounting the
+        # endpoint in the router isn't enough.
+        def presign_response(storage_key, env, **options)
+          script_name = env["SCRIPT_NAME"]
+          path_info   = env["PATH_INFO"]
+
+          begin
+            env["SCRIPT_NAME"] += path_info
+            env["PATH_INFO"]    = ""
+
+            presign_endpoint(storage_key, **options).call(env)
+          ensure
+            env["SCRIPT_NAME"] = script_name
+            env["PATH_INFO"]   = path_info
+          end
+        end
       end
     end
 

data/lib/shrine/plugins/remote_url.rb

@@ -17,11 +17,9 @@ class Shrine
       end
 
       module AttachmentMethods
-        def initialize(*)
+        def initialize(name, **options)
           super
 
-          name = attachment_name
-
           define_method :"#{name}_remote_url=" do |url|
             send(:"#{name}_attacher").remote_url = url
           end