shrine 2.19.3 → 3.6.0

data/doc/plugins/direct_upload.md

@@ -1,172 +0,0 @@
-# Direct Upload
-
-*[OBSOLETE] This plugin is obsolete, you should use `upload_endpoint` or
-`presign_endpoint` plugins instead.*
-
-The [`direct_upload`][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.
-
-[direct_upload]: /lib/shrine/plugins/direct_upload.rb
-[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/hooks.md

@@ -1,58 +0,0 @@
-# Hooks
-
-The [`hooks`][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
-```
-
-[hooks]: /lib/shrine/plugins/hooks.rb

data/doc/plugins/logging.md

@@ -1,42 +0,0 @@
-# Logging
-
-The [`logging`][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`.
-
-[logging]: /lib/shrine/plugins/logging.rb

data/doc/plugins/migration_helpers.md

@@ -1,60 +0,0 @@
-# Migration Helpers
-
-The [`migration_helpers`][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
-```
-
-[migration_helpers]: /lib/shrine/plugins/migration_helpers.rb

data/doc/plugins/moving.md

@@ -1,19 +0,0 @@
-# Moving
-
-The [`moving`][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]
-```
-
-[moving]: /lib/shrine/plugins/moving.rb

data/doc/plugins/multi_delete.md

@@ -1,20 +0,0 @@
-# Multi Delete
-
-The [`multi_delete`][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.
-
-[multi_delete]: /lib/shrine/plugins/multi_delete.rb

data/doc/plugins/parallelize.md

@@ -1,16 +0,0 @@
-# Parallelize
-
-The [`parallelize`][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
-```
-
-[parallelize]: /lib/shrine/plugins/parallelize.rb

data/doc/plugins/parsed_json.md

@@ -1,23 +0,0 @@
-# Parsed JSON
-
-The [`parsed_json`][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
-```
-
-```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/regenerating_versions.md

@@ -1,143 +0,0 @@
-# Reprocessing Versions
-
-While your app is serving uploads in production, you may realize that you want
-to change how your attachment's versions are generated. This means that, in
-addition to changing your processing code, you also need to reprocess the
-existing attachments. This guide is aimed to help doing this migration with
-zero downtime and no unused files left in the main storage.
-
-## Adding versions
-
-Most common scenario is when initially you're not doing any processing, but
-later decide that you want to generate versions. First you need to update your
-code to generate versions, and you also need to change your views to use those
-versions:
-
-```rb
-class ImageUploader < Shrine
-  # ...
-
-  process(:store) do |io, context|
-    thumbnail = process_thumbnail(io.download)
-    {original: io, thumbnail: thumbnail}
-  end
-end
-```
-```rb
-# In your views add the version name to all <attachment>_url calls.
-user.avatar_url(:thumb)
-```
-
-Note that you should deploy both of these changes at once, because the
-`<attachment>_url` method will fail if there are versions generated but no
-version name was passed in. If a version name was passed in but versions aren't
-generated yet (which will be the case here), it will just return the
-unprocessed file URL.
-
-Afterwards you should run a script which reprocesses the versions for existing
-files:
-
-```rb
-User.paged_each do |user|
-  attacher, attachment = user.avatar_attacher, user.avatar
-  if attacher.stored? && !attachment.is_a?(Hash)
-    file = some_processing(attachment.download)
-    thumb = attacher.store!(file, version: :thumb)
-    attacher.swap({original: attachment, thumb: thumb})
-  end
-end
-```
-
-## Reprocessing a single version
-
-The simplest scenario is where you need to regenerate an existing version.
-First you need to change and deploy your updated processing code, and
-afterwards you can run a script like this on your production database:
-
-```rb
-User.paged_each do |user|
-  attacher, attachment = user.avatar_attacher, user.avatar
-  if attacher.stored?
-    file = some_processing(attachment[:original].download)
-    thumb = attachment[:thumb].replace(thumb)
-    attacher.swap(attachment.merge(thumb: thumb))
-  end
-end
-```
-
-### Adding a new version
-
-When adding a new version to a production app, first add it to the list and
-update your processing code to generate it, and deploy it:
-
-```rb
-class ImageUploader < Shrine
-  # ...
-
-  process(:store) do |io, context|
-    # ...
-    new = some_processing(io.download, *args)
-    {small: small, medium: medium, new: new} # we generate the ":new" version
-  end
-end
-```
-
-After you've deployed this change, you should run a script that will generate
-the new version for all existing records:
-
-```rb
-User.paged_each do |user|
-  attacher, attachment = user.avatar_attacher, user.avatar
-  if attacher.stored? && !attachment[:new]
-    file = some_processing(attachment[:original].download, *args)
-    new = attacher.store!(file, version: :new)
-    attacher.swap(attachment.merge(new: new))
-  end
-end
-```
-
-After you've run this script on your production database, all records should
-have the new version, and now you should be able to safely update your app to
-use it.
-
-### Removing a version
-
-Before removing a version, you first need to update your processing to not
-generate it (but keep the version name in the list), as well as update your app
-not to use the new version, and deploy that code. After you've done that, you
-can run a script which removes that version:
-
-```rb
-old_versions = []
-
-User.paged_each do |user|
-  attacher, attachment = user.avatar_attacher, user.avatar
-  if attacher.stored? && attachment[:old_version]
-    old_versions << attachment.delete(:old_version)
-    attacher.swap(attachment)
-  end
-end
-
-if old_versions.any?
-  uploader = old_versions.first.uploader
-  uploader.delete(old_versions)
-end
-```
-
-After the script has finished, you should be able to safely remove the version
-name from the list.
-
-## Reprocessing all versions
-
-If you made a lot of changes to versions, it might make sense to simply
-regenerate all versions. After you've deployed the change in processing, you
-can run a script which updates existing records:
-
-```rb
-User.paged_each do |user|
-  if user.avatar_attacher.stored?
-    # assuming your largest version is named ":original"
-    user.update(avatar: user.avatar[:original])
-  end
-end
-```

data/lib/shrine/plugins/background_helpers.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-Shrine.deprecation("The background_helpers plugin has been renamed to \"backgrounding\". Loading the plugin through \"background_helpers\" will stop working in Shrine 3.")
-require "shrine/plugins/backgrounding"
-Shrine::Plugins.register_plugin(:background_helpers, Shrine::Plugins::Backgrounding)

data/lib/shrine/plugins/backup.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-Shrine.deprecation("The backup plugin has been deprecated, the new preferred way to implement mirroring is via the instrumentation plugin – see https://github.com/shrinerb/shrine/wiki/Mirroring-Uploads. The backup plugin will be removed in Shrine 3.")
-
-class Shrine
-  module Plugins
-    # Documentation lives in [doc/plugins/backup.md] on GitHub.
-    #
-    # [doc/plugins/backup.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/backup.md
-    module Backup
-      def self.configure(uploader, opts = {})
-        uploader.opts[:backup_storage] = opts.fetch(:storage, uploader.opts[:backup_storage])
-        uploader.opts[:backup_delete] = opts.fetch(:delete, uploader.opts.fetch(:backup_delete, true))
-
-        raise Error, "The :storage option is required for backup plugin" if uploader.opts[:backup_storage].nil?
-      end
-
-      module AttacherMethods
-        # Backs up the stored file after promoting.
-        def promote(*)
-          result = super
-          store_backup!(result) if result
-          result
-        end
-
-        # Deletes the backup file in addition to the stored file.
-        def replace
-          result = super
-          delete_backup!(@old) if result && delete_backup?
-          result
-        end
-
-        # Deletes the backup file in addition to the stored file.
-        def destroy
-          result = super
-          delete_backup!(get) if result && delete_backup?
-          result
-        end
-
-        # Returns a copy of the given uploaded file with storage changed to
-        # backup storage.
-        def backup_file(uploaded_file)
-          uploaded_file(uploaded_file.to_json) do |file|
-            file.data["storage"] = backup_storage.to_s
-          end
-        end
-
-        private
-
-        # Upload the stored file to the backup storage.
-        def store_backup!(stored_file)
-          options = _equalize_phase_and_action(action: :backup, move: false)
-          backup_store.upload(stored_file, context.merge(options))
-        end
-
-        # Deleted the stored file from the backup storage.
-        def delete_backup!(deleted_file)
-          _delete(backup_file(deleted_file), action: :backup)
-        end
-
-        def backup_store
-          @backup_store ||= shrine_class.new(backup_storage)
-        end
-
-        def backup_storage
-          shrine_class.opts[:backup_storage]
-        end
-
-        def delete_backup?
-          shrine_class.opts[:backup_delete]
-        end
-      end
-
-      module InstanceMethods
-        private
-
-        # We preserve the location when uploading from store to backup.
-        def get_location(io, context)
-          if context[:action] == :backup
-            io.id
-          else
-            super
-          end
-        end
-      end
-    end
-
-    register_plugin(:backup, Backup)
-  end
-end