shrine 2.14.0 → 2.15.0

data/doc/plugins/determine_mime_type.md

@@ -0,0 +1,64 @@
+# Determine MIME Type
+
+The `determine_mime_type` plugin allows you to determine and store the actual
+MIME type of the file analyzed from file content.
+
+```rb
+plugin :determine_mime_type
+```
+
+By default the UNIX [file] utility is used to determine the MIME type, and the
+result is automatically written to the `mime_type` metadata field. You can
+choose a different built-in MIME type analyzer:
+
+```rb
+plugin :determine_mime_type, analyzer: :marcel
+```
+
+The following analyzers are accepted:
+
+| Name            | Description                                                                                                                                                                                                                                                                       |
+| :------         | :-----------                                                                                                                                                                                                                                                                      |
+| `:file`         | (Default). Uses the [file] utility to determine the MIME type from file contents. It is installed by default on most operating systems, but the [Windows equivalent] needs to be installed separately.                                                                            |
+| `:fastimage`    | Uses the [fastimage] gem to determine the MIME type from file contents. Fastimage is optimized for speed over accuracy. Best used for image content.                                                                                                                              |
+| `:filemagic`    | Uses the [ruby-filemagic] gem to determine the MIME type from file contents, using a similar MIME database as the `file` utility. Unlike the `file` utility, ruby-filemagic works on Windows without any setup.                                                                   |
+| `:mimemagic`    | Uses the [mimemagic] gem to determine the MIME type from file contents. Unlike ruby-filemagic, mimemagic is a pure-ruby solution, so it will work across all Ruby implementations.                                                                                                |
+| `:marcel`       | Uses the [marcel] gem to determine the MIME type from file contents. Marcel is Basecamp's wrapper around mimemagic, it adds priority logic (preferring magic over name when given both), some extra type definitions, and common type subclasses (including Keynote, Pages, etc). |
+| `:mime_types`   | Uses the [mime-types] gem to determine the MIME type from the file extension. Note that unlike other solutions, this analyzer is not guaranteed to return the actual MIME type of the file.                                                                                       |
+| `:mini_mime`    | Uses the [mini_mime] gem to determine the MIME type from the file extension. Note that unlike other solutions, this analyzer is not guaranteed to return the actual MIME type of the file.                                                                                        |
+| `:content_type` | Retrieves the value of the `#content_type` attribute of the IO object. Note that this value normally comes from the "Content-Type" request header, so it's not guaranteed to hold the actual MIME type of the file.                                                               |
+
+A single analyzer is not going to properly recognize all types of files, so you
+can build your own custom analyzer for your requirements, where you can combine
+the built-in analyzers. For example, if you want to correctly determine MIME
+type of .css, .js, .json, .csv, .xml, or similar text-based files, you can
+combine `file` and `mime_types` analyzers:
+
+```rb
+plugin :determine_mime_type, analyzer: -> (io, analyzers) do
+  mime_type = analyzers[:file].call(io)
+  mime_type = analyzers[:mime_types].call(io) if mime_type == "text/plain"
+  mime_type
+end
+```
+
+You can also use methods for determining the MIME type directly:
+
+```rb
+# or YourUploader.determine_mime_type(io)
+Shrine.determine_mime_type(io) # calls the defined analyzer
+#=> "image/jpeg"
+
+# or YourUploader.mime_type_analyzers
+Shrine.mime_type_analyzers[:file].call(io) # calls a built-in analyzer
+#=> "image/jpeg"
+```
+
+[file]: http://linux.die.net/man/1/file
+[Windows equivalent]: http://gnuwin32.sourceforge.net/packages/file.htm
+[ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic
+[mimemagic]: https://github.com/minad/mimemagic
+[marcel]: https://github.com/basecamp/marcel
+[mime-types]: https://github.com/mime-types/ruby-mime-types
+[mini_mime]: https://github.com/discourse/mini_mime
+[fastimage]: https://github.com/sdsykes/fastimage

data/doc/plugins/direct_upload.md

@@ -0,0 +1,170 @@
+# Direct Upload
+
+*[OBSOLETE] This plugin is obsolete, you should use `upload_endpoint` or
+`presign_endpoint` plugins instead.*
+
+The `direct_upload` plugin provides a Rack endpoint which can be used for
+uploading individual files asynchronously. It requires the [Roda] gem.
+
+```rb
+plugin :direct_upload
+```
+
+The Roda endpoint provides two routes:
+
+* `POST /:storage/upload`
+* `GET /:storage/presign`
+
+This first route is for doing direct uploads to your app, the received file
+will be uploaded the underlying storage. The second route is for doing direct
+uploads to a 3rd-party service, it will return the URL where the file can be
+uploaded to, along with the necessary request parameters.
+
+This is how you can mount the endpoint in a Rails application:
+
+```rb
+Rails.application.routes.draw do
+  mount ImageUploader::UploadEndpoint => "/images"
+end
+```
+
+Now your application will get `POST /images/cache/upload` and `GET
+/images/cache/presign` routes. On the client side it is recommended to use
+[Uppy] for uploading files to the app or directly to the 3rd-party service.
+
+## Uploads
+
+The upload route accepts a "file" query parameter, and returns the uploaded
+file in JSON format:
+
+```rb
+# POST /images/cache/upload
+{
+  "id": "43kewit94.jpg",
+  "storage": "cache",
+  "metadata": {
+    "size": 384393,
+    "filename": "nature.jpg",
+    "mime_type": "image/jpeg"
+  }
+}
+```
+
+Once you've uploaded the file, you can assign the result to the hidden
+attachment field in the form, or immediately send it to the server.
+
+Note that the endpoint uploads the file standalone, without any knowledge of
+the record, so `context[:record]` and `context[:name]` will be nil.
+
+### Limiting filesize
+
+It's good idea to limit the maximum filesize of uploaded files, if you set the
+`:max_size` option, files which are too big will get automatically deleted and
+413 status will be returned:
+
+```rb
+plugin :direct_upload, max_size: 5*1024*1024 # 5 MB
+```
+
+Note that this option doesn't affect presigned uploads, there you can apply
+filesize limit when generating a presign. The filesize constraint here is for
+security purposes, you should still perform file validations on attaching.
+
+## Presigns
+
+The presign route returns the URL to the 3rd-party service to which you can
+upload the file, along with the necessary query parameters.
+
+```rb
+# GET /images/cache/presign
+{
+  "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",
+  "fields" => {
+    "key" => "b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
+    "policy" => "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb2...",
+    "x-amz-credential" => "AKIAIJF55TMZYT6Q/20151024/eu-west-1/s3/aws4_request",
+    "x-amz-algorithm" => "AWS4-HMAC-SHA256",
+    "x-amz-date" => "20151024T001129Z",
+    "x-amz-signature" => "c1eb634f83f96b69bd675f535b3ff15ae184b102fcba51e4db5f4959b4ae26f4"
+  }
+}
+```
+
+If you want that the generated location includes a file extension, you can
+specify the `extension` query parameter: `GET
+/:storage/presign?extension=.png`.
+
+You can also completely change how the key is generated, with
+`:presign_location`:
+
+```rb
+plugin :direct_upload, presign_location: -> (request) { "${filename}" }
+```
+
+This presign route internally calls `#presign` on the storage, and many
+storages accept additional service-specific options. You can generate these
+additional options per-request through `:presign_options`:
+
+```rb
+plugin :direct_upload, presign_options: { acl: "public-read" }
+
+plugin :direct_upload, presign_options: ->(request) do
+  filename = request.params["filename"]
+  content_type = Rack::Mime.mime_type(File.extname(filename))
+
+  {
+    content_length_range: 0..(10*1024*1024),                     # limit filesize to 10MB
+    content_disposition: "attachment; filename=\"#{filename}\"", # download with original filename
+    content_type:        content_type,                           # set correct content type
+  }
+end
+```
+
+Both `:presign_location` and `:presign_options` in their block versions are
+yielded an instance of [Roda request], which is a subclass of `Rack::Request`.
+
+See the [Direct Uploads to S3] guide for further instructions on how to hook
+the presigned uploads to a form.
+
+## Allowed storages
+
+By default only uploads to `:cache` are allowed, to prevent the possibility of
+having orphan files in your main storage. But you can allow more storages:
+
+```rb
+plugin :direct_upload, allowed_storages: [:cache, :store]
+```
+
+## Customizing endpoint
+
+Since the endpoint is a [Roda] app, it is very customizable. For example, you
+can add a Rack middleware to change the response status and headers:
+
+```rb
+class ShrineUploadMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    result = @app.call(env)
+
+    if result[0] == 200 && env["PATH_INFO"].end_with?("upload")
+      result[0] = 201
+      result[1]["Location"] = Shrine.uploaded_file(result[2].first).url
+    end
+
+    result
+  end
+end
+
+Shrine::UploadEndpoint.use ShrineUploadMiddleware
+```
+
+Upon subclassing uploader the upload endpoint is also subclassed. You can also
+call the plugin again in an uploader subclass to change its configuration.
+
+[Roda]: https://github.com/jeremyevans/roda
+[Uppy]: https://uppy.io
+[Roda request]: http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/RequestMethods.html
+[Direct Uploads to S3]: /doc/direct_s3.md#readme

data/doc/plugins/download_endpoint.md

@@ -0,0 +1,83 @@
+# Download Endpoint
+
+The `download_endpoint` plugin provides a Rack app for downloading uploaded
+files from specified storages. This can be useful when files from your storage
+isn't accessible over URL (e.g. database storages) or if you want to
+authenticate your downloads. It requires the [Roda] gem.
+
+```rb
+# Gemfile
+gem "roda" # dependency of the download_endpoint plugin
+```
+
+You can configure the plugin with the path prefix which the endpoint will be
+mounted on.
+
+```rb
+plugin :download_endpoint, prefix: "attachments"
+```
+
+The endpoint should then be mounted on the specified prefix:
+
+```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`.
+
+```rb
+uploaded_file.download_url #=> "/attachments/eyJpZCI6ImFkdzlyeTM..."
+```
+
+## Host
+
+You can specify download URL host via the `:host` plugin option:
+
+```rb
+plugin :download_endpoint, host: "http://example.com"
+```
+
+or by passing `:host` to `UploadedFile#download_url`:
+
+```rb
+uploaded_file.download_url(host: "http://example.com")
+#=> "http//example.com/attachments/eyJpZCI6ImFkdzlyeTM..."
+```
+
+## Performance considerations
+
+Streaming files through the app might impact the request throughput, depending
+on the web server you're using. So it's recommended to use a CDN, which can be
+set via the `:host` option.
+
+Alternatively, you can have the endpoint redirect to the direct file URL:
+
+```rb
+plugin :download_endpoint, redirect: true
+# or
+plugin :download_endpoint, redirect: -> (uploaded_file, request) do
+  # return URL which the request will redirect to
+end
+```
+
+## Custom endpoint
+
+If you want to have more control on download requests, you can use the
+`rack_response` plugin which this plugin uses internally.
+
+[Roda]: https://github.com/jeremyevans/roda

data/doc/plugins/dynamic_storage.md

@@ -0,0 +1,20 @@
+# Dynamic Storage
+
+The `dynamic_storage` plugin allows you to register a storage using a regex,
+and evaluate the storage class dynamically depending on the regex.
+
+Example:
+
+```rb
+plugin :dynamic_storage
+
+storage /store_(\w+)/ do |match|
+  Shrine::Storages::S3.new(bucket: match[1])
+end
+```
+
+The above example uses S3 storage where the bucket name depends on the storage
+name suffix. For example, `:store_foo` will use S3 storage which saves files to
+the bucket "foo". The block is yielded an instance of `MatchData`.
+
+This can be useful in combination with the `default_storage` plugin.

data/doc/plugins/hooks.md

@@ -0,0 +1,56 @@
+# Hooks
+
+The `hooks` plugin allows you to trigger some code around
+processing/storing/deleting of each file.
+
+```rb
+plugin :hooks
+```
+
+Shrine uses instance methods for hooks. To define a hook for an uploader, you
+just add an instance method to the uploader:
+
+```rb
+class ImageUploader < Shrine
+  def around_process(io, context)
+    super
+  rescue
+    ExceptionNotifier.processing_failed(io, context)
+  end
+end
+```
+
+Each hook will be called with 2 arguments, `io` and `context`. You should
+always call `super` when overriding a hook, as other plugins may be using hooks
+internally, and without `super` those wouldn't get executed.
+
+Shrine calls hooks in the following order when uploading a file:
+
+* `before_upload`
+* `around_upload`
+  - `before_process`
+  - `around_process`
+  - `after_process`
+  - `before_store`
+  - `around_store`
+  - `after_store`
+* `after_upload`
+
+Shrine calls hooks in the following order when deleting a file:
+
+* `before_delete`
+* `around_delete`
+* `after_delete`
+
+By default every `around_*` hook returns the result of the corresponding
+operation:
+
+```rb
+class ImageUploader < Shrine
+  def around_store(io, context)
+    result = super
+    result.class #=> Shrine::UploadedFile
+    result # it's good to always return the result for consistent behaviour
+  end
+end
+```

data/doc/plugins/included.md

@@ -0,0 +1,15 @@
+# Included
+
+The `included` plugin allows you to hook up to the `.included` hook of the
+attachment module, and call additional methods on the model which includes it.
+
+```rb
+plugin :included do |name|
+  before_save do
+    # ...
+  end
+end
+```
+
+If you want to define additional methods on the model, it's recommended to use
+the `module_include` plugin instead.

data/doc/plugins/infer_extension.md

@@ -0,0 +1,57 @@
+# Infer Extension
+
+The `infer_extension` plugin allows deducing the appropriate file extension for
+the upload location based on the MIME type of the file. This is useful when
+using `data_uri` and `remote_url` plugins, where the file extension might not
+be known.
+
+```rb
+plugin :infer_extension
+```
+
+Ordinarily, the upload location will gain the inferred extension only if it
+couldn't be determined from the filename. However, you can pass `force: true`
+to force the inferred extension to be used rather than an extension from the
+original filename. This can be used to canonicalize extensions (jpg, jpeg =>
+jpeg), or replace an incorrect original extension.
+
+```rb
+plugin :infer_extension, force: true
+```
+
+By default `MIME::Types` will be used for inferring the extension, but you can
+also choose a different inferrer:
+
+```rb
+plugin :infer_extension, inferrer: :mini_mime
+```
+
+The following inferrers are accepted:
+
+| Name          | Description                                                                             |
+| :------------ | :-----------                                                                            |
+| `:mime_types` | (Default). Uses the [mime-types] gem to infer the appropriate extension from MIME type. |
+| `:mini_mime`  | Uses the [mini_mime] gem to infer the appropriate extension from MIME type.             |
+
+You can also define your own inferrer, with the possibility to call the
+built-in inferrers:
+
+```rb
+plugin :infer_extension, inferrer: -> (mime_type, inferrers) do
+  # don't add extension if the file is a text file
+  inferrers[:rack_mime].call(mime_type) unless mime_type == "text/plain"
+end
+```
+
+You can also use methods for inferring extension directly:
+
+```rb
+Shrine.infer_extension("image/jpeg")
+# => ".jpeg"
+
+Shrine.extension_inferrers[:mime_types].call("image/jpeg")
+# => ".jpeg"
+```
+
+[mime-types]: https://github.com/mime-types/ruby-mime-types
+[mini_mime]: https://github.com/discourse/mini_mime