shrine 2.14.0 → 2.15.0

data/doc/plugins/keep_files.md

@@ -0,0 +1,20 @@
+# Keep Files
+
+The `keep_files` plugin gives you the ability to prevent files from being
+deleted. This functionality is useful when implementing soft deletes, or when
+implementing some kind of [event store] where you need to track history.
+
+The plugin accepts the following options:
+
+| Option       | Description                                                                     |
+| :------      | :----------                                                                     |
+| `:destroyed` | If set to `true`, destroying the record won't delete the associated attachment. |
+| `:replaced`  | If set to `true`, uploading a new attachment won't delete the old one.          |
+
+For example, the following will keep destroyed and replaced files:
+
+```rb
+plugin :keep_files, destroyed: true, replaced: true
+```
+
+[event store]: http://docs.geteventstore.com/introduction/event-sourcing-basics/

data/doc/plugins/logging.md

@@ -0,0 +1,39 @@
+# Logging
+
+The `logging` plugin logs any storing/processing/deleting that is performed.
+
+```rb
+plugin :logging
+```
+
+This plugin is useful when you want to have overview of what exactly is going
+on, or you simply want to have it logged for future debugging. By default the
+logging output looks something like this:
+
+```
+2015-10-09T20:06:06.676Z #25602: STORE[cache] ImageUploader[:avatar] User[29543] 1 file (0.1s)
+2015-10-09T20:06:06.854Z #25602: PROCESS[store]: ImageUploader[:avatar] User[29543] 1-3 files (0.22s)
+2015-10-09T20:06:07.133Z #25602: DELETE[destroyed]: ImageUploader[:avatar] User[29543] 3 files (0.07s)
+```
+
+The plugin accepts the following options:
+
+| Option    | Description                                                                                                                                                                                    |
+| :-------- | :----------                                                                                                                                                                                    |
+| `:format` | This allows you to change the logging output into something that may be easier to grep. Accepts `:human` (default), `:json` and `:logfmt`.                                                     |
+| `:stream` | The default logging stream is `$stdout`, but you may want to change it, e.g. if you log into a file. This option is passed directly to `Logger.new` (from the "logger" Ruby standard library). |
+| `:logger` | This allows you to change the logger entirely. This is useful for example in Rails applications, where you might want to assign this option to `Rails.logger`.                                 |
+
+The default format is probably easiest to read, but may not be easiest to grep.
+If this is important to you, you can switch to another format:
+
+```rb
+plugin :logging, format: :json
+# {"action":"upload","phase":"cache","uploader":"ImageUploader","attachment":"avatar",...}
+
+plugin :logging, format: :logfmt
+# action=upload phase=cache uploader=ImageUploader attachment=avatar record_class=User ...
+```
+
+Logging is by default disabled in tests, but you can enable it by setting
+`Shrine.logger.level = Logger::INFO`.

data/doc/plugins/metadata_attribues.md

@@ -0,0 +1,43 @@
+# Metadata Attributes
+
+The `metadata_attributes` plugin allows you to sync attachment metadata to
+additional record attributes. You can provide a hash of mappings to the plugin
+call itself or the `Attacher.metadata_attributes` method:
+
+```rb
+plugin :metadata_attributes, :size => :size, :mime_type => :type
+# or
+plugin :metadata_attributes
+Attacher.metadata_attributes :size => :size, :mime_type => :type
+```
+
+The above configuration will sync `size` metadata field to `<attachment>_size`
+record attribute, and `mime_type` metadata field to `<attachment>_type` record
+attribute.
+
+```rb
+user.avatar = image
+user.avatar.metadata["size"]      #=> 95724
+user.avatar_size                  #=> 95724
+user.avatar.metadata["mime_type"] #=> "image/jpeg"
+user.avatar_type                  #=> "image/jpeg"
+
+user.avatar = nil
+user.avatar_size #=> nil
+user.avatar_type #=> nil
+```
+
+If you want to specify the full record attribute name, pass the record
+attribute name as a string instead of a symbol.
+
+```rb
+Attacher.metadata_attributes :filename => "original_filename"
+
+# ...
+
+photo.image = image
+photo.original_filename #=> "nature.jpg"
+```
+
+If any corresponding metadata attribute doesn't exist on the record, that
+metadata sync will be silently skipped.

data/doc/plugins/migration_helpers.md

@@ -0,0 +1,58 @@
+# Migration Helpers
+
+The migration_helpers plugin gives the attacher additional helper methods which
+are convenient when doing file migrations.
+
+The plugin also allows convenient delegating to these methods through the
+model, by setting `:delegate`:
+
+```rb
+plugin :migration_helpers, delegate: true
+```
+
+## `update_stored`
+
+This method updates the record's attachment with the result of the given block.
+
+```rb
+user.avatar_attacher.update_stored do |avatar|
+  user.avatar_attacher.store.upload(avatar) # saved to the record
+end
+
+# with model delegation
+user.update_avatar do |avatar|
+  user.avatar_store.upload(avatar) # saved to the record
+end
+```
+
+The block will get triggered _only_ if the attachment is present and not
+cached, *and* will save the record only if the record's attachment hasn't
+changed in the time it took to execute the block. This method is most useful
+for adding/removing versions and changing locations of files.
+
+## `cached?` and `stored?`
+
+These methods return true if attachment exists and is cached/stored:
+
+```rb
+user.avatar_attacher.cached? # user.avatar && user.avatar_attacher.cache.uploaded?(user.avatar)
+user.avatar_attacher.stored? # user.avatar && user.avatar_attacher.store.uploaded?(user.avatar)
+
+# with model delegation
+user.avatar_cached?
+user.avatar_stored?
+```
+
+## `attachment_cache` and `attachment_store`
+
+These methods return cache and store uploaders used by the underlying attacher:
+
+```rb
+# these methods already exist without migration_helpers
+user.avatar_attacher.cache #=> #<Shrine @storage_key=:cache @storage=#<Shrine::Storage::FileSystem @directory=public/uploads>>
+user.avatar_attacher.store #=> #<Shrine @storage_key=:store @storage=#<Shrine::Storage::S3:0x007fb8343397c8 @bucket=#<Aws::S3::Bucket name="foo">>>
+
+# with model delegation
+user.avatar_cache
+user.avatar_store
+```

data/doc/plugins/module_include.md

@@ -0,0 +1,40 @@
+# Module Include
+
+The `module_include` plugin allows you to extend Shrine's core classes for the
+given uploader with modules/methods.
+
+```rb
+plugin :module_include
+```
+
+To add a module to a core class, call the appropriate method:
+
+```rb
+attachment_module CustomAttachmentMethods
+attacher_module CustomAttacherMethods
+file_module CustomFileMethods
+```
+
+Alternatively you can pass in a block (which internally creates a module):
+
+```rb
+attachment_module do
+  def included(model)
+    super
+
+    name = attachment_name
+
+    define_method :"#{name}_size" do |version|
+      attachment = send(name)
+      if attachment.is_a?(Hash)
+        attachment[version].size
+      elsif attachment
+        attachment.size
+      end
+    end
+  end
+end
+```
+
+The above defines an additional `#<attachment>_size` method on the attachment
+module, which is what is included in your model.

data/doc/plugins/moving.md

@@ -0,0 +1,17 @@
+# Moving
+
+The `moving` plugin will *move* files to storages instead of copying them, when
+the storage supports it. For FileSystem this will issue a `mv` command, which
+is instantaneous regardless of the filesize, so in that case loading this
+plugin can significantly speed up the attachment process.
+
+```rb
+plugin :moving
+```
+
+By default files will be moved whenever the storage supports it. If you want
+moving to happen only for certain storages, you can set `:storages`:
+
+```rb
+plugin :moving, storages: [:cache]
+```

data/doc/plugins/multi_delete.md

@@ -0,0 +1,18 @@
+# Multi Delete
+
+The `multi_delete` plugins allows you to leverage your storage's multi delete
+capabilities.
+
+```rb
+plugin :multi_delete
+```
+
+This plugin allows you pass an array of files to `Shrine#delete`.
+
+```rb
+uploader.delete([file1, file2, file3])
+```
+
+Now if you're using Storage::S3, deleting an array of files will issue a single
+HTTP request. Some other storages may support multi deletes as well. The
+`versions` plugin uses this plugin for deleting multiple versions at once.

data/doc/plugins/parallelize.md

@@ -0,0 +1,14 @@
+# Parallelize
+
+The `parallelize` plugin parallelizes uploads and deletes of multiple versions
+using threads.
+
+```rb
+plugin :parallelize
+```
+
+By default a pool of 3 threads will be used, but you can change that:
+
+```rb
+plugin :parallelize, threads: 5
+```

data/doc/plugins/parsed_json.md

@@ -0,0 +1,9 @@
+# Parsed JSON
+
+The `parsed_json` plugin is suitable for the case when your framework is
+automatically parsing JSON query parameters, allowing you to assign cached
+files with hashes/arrays.
+
+```rb
+plugin :parsed_json
+```

data/doc/plugins/presign_endpoint.md

@@ -0,0 +1,133 @@
+# Presign Endpoint
+
+The `presign_endpoint` plugin provides a Rack endpoint which generates the URL,
+fields, and headers that can be used to upload files directly to a storage
+service. On the client side it's recommended to use [Uppy] for asynchronous
+uploads. Storage services that support direct uploads include [Amazon S3],
+[Google Cloud Storage], [Microsoft Azure Storage] and more.
+
+```rb
+plugin :presign_endpoint
+```
+
+The plugin adds a `Shrine.presign_endpoint` method which, given a storage
+identifier, returns a Rack application that accepts GET requests and generates
+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
+```
+
+Asynchronous upload is typically meant to replace the caching phase in the
+default synchronous workflow, so we want to generate parameters for uploads to
+the temporary (`:cache`) storage.
+
+The above will create a `GET /images/presign` endpoint, which calls `#presign`
+on the storage and returns the HTTP verb, URL, params, and headers needed for a
+single upload directly to the storage service, in JSON format.
+
+```rb
+# GET /images/presign
+{
+  "method": "post",
+  "url": "https://my-bucket.s3-eu-west-1.amazonaws.com",
+  "fields": {
+    "key": "b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
+    "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJ...",
+    "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"
+  },
+  "headers": {}
+}
+```
+
+## Location
+
+By default the generated location won't have any file extension, but you can
+specify one by sending the `filename` query parameter:
+
+```
+GET /images/presign?filename=nature.jpg
+```
+
+It's also possible to customize how the presign location is generated:
+
+```rb
+plugin :presign_endpoint, presign_location: -> (request) do
+  "#{SecureRandom.hex}/#{request.params["filename"]}"
+end
+```
+
+## Options
+
+Some storages accept additional presign options, which you can pass in via
+`:presign_options`, here is an example for S3 storage:
+
+```rb
+plugin :presign_endpoint, presign_options: -> (request) do
+  # Uppy will send the "filename" and "type" query parameters
+  filename = request.params["filename"]
+  type     = request.params["type"]
+
+  {
+    content_length_range: 0..(10*1024*1024),                  # limit filesize to 10MB
+    content_disposition: ContentDisposition.inline(filename), # download with original filename
+    content_type:        type,                                # set correct content type
+  }
+end
+```
+
+The example above uses the [content_disposition] gem to correctly format the
+`Content-Disposition` header value.
+
+The `:presign_options` can be a Proc or a Hash.
+
+## Presign
+
+You can also customize how the presign itself is generated via the `:presign`
+option:
+
+```rb
+plugin :presign_endpoint, presign: -> (id, options, request) do
+  # return a Hash with :url, :fields, and :headers keys
+end
+```
+
+## Response
+
+The response returned by the endpoint can be customized via the
+`:rack_response` option:
+
+```rb
+plugin :presign_endpoint, rack_response: -> (data, request) do
+  body = { endpoint: data[:url], params: data[:fields], headers: data[:headers] }.to_json
+  [201, { "Content-Type" => "application/json" }, [body]]
+end
+```
+
+## Ad-hoc options
+
+You can override any of the options above when creating the endpoint:
+
+```rb
+Shrine.presign_endpoint(:cache, presign_location: "${filename}")
+```
+
+[Uppy]: https://uppy.io
+[Amazon S3]: https://aws.amazon.com/s3/
+[Google Cloud Storage]: https://cloud.google.com/storage/
+[Microsoft Azure Storage]: https://azure.microsoft.com/en-us/services/storage/
+[content_disposition]: https://github.com/shrinerb/content_disposition

data/doc/plugins/pretty_location.md

@@ -0,0 +1,29 @@
+# Pretty Location
+
+The `pretty_location` plugin attempts to generate a nicer folder structure for
+uploaded files.
+
+```rb
+plugin :pretty_location
+```
+
+This plugin uses the context information from the Attacher to try to generate a
+nested folder structure which separates files for each record. The newly
+generated locations will typically look like this:
+
+```rb
+"user/564/avatar/thumb-493g82jf23.jpg"
+# :model/:id/:attachment/:version-:uid.:extension
+```
+
+By default if a record class is inside a namespace, only the "inner" class name
+is used in the location. If you want to include the namespace, you can pass in
+the `:namespace` option with the desired separator as the value:
+
+```rb
+plugin :pretty_location, namespace: "_"
+# "blog_user/.../493g82jf23.jpg"
+
+plugin :pretty_location, namespace: "/"
+# "blog/user/.../493g82jf23.jpg"
+```

data/doc/plugins/processing.md

@@ -0,0 +1,68 @@
+# Processing
+
+Shrine uploaders can define the `#process` method, which will get called
+whenever a file is uploaded. It is given the original file, and is expected to
+return the processed files.
+
+```rb
+def process(io, context)
+  # you can process the original file `io` and return processed file(s)
+end
+```
+
+However, when handling files as attachments, the same file is uploaded to
+temporary and permanent storage. Since we only want to apply the same
+processing once, we need to branch based on the context.
+
+```rb
+def process(io, context)
+  if context[:action] == :store # promote phase
+    # ...
+  end
+end
+```
+
+The `processing` plugin simplifies this by allowing us to declaratively define
+file processing for specified actions.
+
+```rb
+plugin :processing
+
+process(:store) do |io, context|
+  # ...
+end
+```
+
+An example of resizing an image using the [image_processing] library:
+
+```rb
+require "image_processing/mini_magick"
+
+process(:store) do |io, context|
+  io.download do |original|
+    ImageProcessing::MiniMagick
+      .source(original)
+      .resize_to_limit!(800, 800)
+  end
+end
+```
+
+The declarations are additive and inheritable, so for the same action you can
+declare multiple blocks, and they will be performed in the same order, with
+output from previous block being the input to next.
+
+## Manually Run Processing
+
+You can manually trigger the defined processing via the uploader by calling
+`#upload` or `#process` and setting `:action` to the name of your processing
+block:
+
+```rb
+uploader.upload(file, action: :store)  # process and upload
+uploader.process(file, action: :store) # only process
+```
+
+If you want the result of processing to be multiple files, use the `versions`
+plugin.
+
+[image_processing]: https://github.com/janko/image_processing