shrine 2.19.4 → 3.0.0.alpha

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/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

data/lib/shrine/plugins/copy.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-Shrine.deprecation("The copy plugin is deprecated and will be removed in Shrine 3.")
-
-class Shrine
-  module Plugins
-    # Documentation lives in [doc/plugins/copy.md] on GitHub.
-    #
-    # [doc/plugins/copy.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/copy.md
-    module Copy
-      module AttachmentMethods
-        def initialize(*)
-          super
-
-          name = attachment_name
-
-          define_method :initialize_copy do |record|
-            super(record)
-            instance_variable_set(:"@#{name}_attacher", nil) # reload the attacher
-            attacher = send(:"#{name}_attacher")
-            attacher.send(:write, nil) # remove original attachment
-            attacher.copy(record.public_send(:"#{name}_attacher"))
-          end
-
-          # Fix for JRuby
-          private :initialize_copy
-        end
-      end
-
-      module AttacherMethods
-        def copy(attacher)
-          options = {action: :copy, move: false}
-
-          copied_attachment = if attacher.cached?
-                                cache!(attacher.get, **options)
-                              elsif attacher.stored?
-                                store!(attacher.get, **options)
-                              else
-                                nil
-                              end
-
-          @old = get
-          _set(copied_attachment)
-        end
-      end
-    end
-
-    register_plugin(:copy, Copy)
-  end
-end

data/lib/shrine/plugins/delete_promoted.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-class Shrine
-  module Plugins
-    # Documentation lives in [doc/plugins/delete_promoted.md] on GitHub.
-    #
-    # [doc/plugins/delete_promoted.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/delete_promoted.md
-    module DeletePromoted
-      module AttacherMethods
-        def promote(uploaded_file = get, **options)
-          result = super
-          _delete(uploaded_file, action: :promote)
-          result
-        end
-      end
-    end
-
-    register_plugin(:delete_promoted, DeletePromoted)
-  end
-end

data/lib/shrine/plugins/direct_upload.rb

@@ -1,217 +0,0 @@
-# frozen_string_literal: true
-
-Shrine.deprecation("The direct_upload plugin has been deprecated in favor of upload_endpoint and presign_endpoint plugins. The direct_upload plugin will be removed in Shrine 3.")
-
-require "roda"
-require "json"
-
-class Shrine
-  module Plugins
-    # Documentation lives in [doc/plugins/direct_upload.md] on GitHub.
-    #
-    # [doc/plugins/direct_upload.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/direct_upload.md
-    module DirectUpload
-      def self.load_dependencies(uploader, *)
-        uploader.plugin :rack_file
-      end
-
-      def self.configure(uploader, opts = {})
-        uploader.opts[:direct_upload_allowed_storages] = opts.fetch(:allowed_storages, uploader.opts.fetch(:direct_upload_allowed_storages, [:cache]))
-        uploader.opts[:direct_upload_presign_options] = opts.fetch(:presign_options, uploader.opts.fetch(:direct_upload_presign_options, {}))
-        uploader.opts[:direct_upload_presign_location] = opts.fetch(:presign_location, uploader.opts[:direct_upload_presign_location])
-        uploader.opts[:direct_upload_max_size] = opts.fetch(:max_size, uploader.opts[:direct_upload_max_size])
-
-        uploader.assign_upload_endpoint(App) unless uploader.const_defined?(:UploadEndpoint)
-      end
-
-      module ClassMethods
-        # Assigns the subclass a copy of the upload endpoint class.
-        def inherited(subclass)
-          super
-          subclass.assign_upload_endpoint(self::UploadEndpoint)
-        end
-
-        # Assigns the subclassed endpoint as the `UploadEndpoint` constant.
-        def assign_upload_endpoint(klass)
-          endpoint_class = Class.new(klass)
-          endpoint_class.opts[:shrine_class] = self
-          const_set(:UploadEndpoint, endpoint_class)
-        end
-      end
-
-      # Routes incoming requests. It first asserts that the storage is existent
-      # and allowed, then the filesize isn't too large. Afterwards it proceeds
-      # with the file upload and returns the uploaded file as JSON.
-      class App < Roda
-        plugin :default_headers, "Content-Type"=>"application/json"
-        plugin :placeholder_string_matchers if Gem::Version.new(Roda::RodaVersion) >= Gem::Version.new("3.0.0")
-
-        route do |r|
-          r.on ":storage" do |storage_key|
-            @uploader = get_uploader(storage_key)
-
-            r.post ["upload", ":name"] do |name|
-              file = get_file
-              context = get_context(name)
-
-              uploaded_file = upload(file, context)
-
-              json uploaded_file
-            end
-
-            r.get "presign" do
-              location = get_presign_location
-              options = get_presign_options
-
-              presign_data = generate_presign(location, options)
-              response.headers["Cache-Control"] = "no-store"
-
-              json presign_data
-            end
-          end
-        end
-
-        private
-
-        attr_reader :uploader
-
-        # Instantiates the uploader, checking first if the storage is allowed.
-        def get_uploader(storage_key)
-          allow_storage!(storage_key)
-          shrine_class.new(storage_key.to_sym)
-        end
-
-        # Retrieves the context for the upload.
-        def get_context(name)
-          context = {action: :cache, phase: :cache}
-
-          if name != "upload"
-            Shrine.deprecation("The \"POST /:storage/:name\" route of the direct_upload plugin is deprecated, and it will be removed in Shrine 3. Use \"POST /:storage/upload\" instead.")
-            context[:name] = name
-          end
-
-          unless presign_storage?
-            context[:location] = request.params["key"]
-          end
-
-          context
-        end
-
-        # Uploads the file to the requested storage.
-        def upload(file, context)
-          uploader.upload(file, context)
-        end
-
-        # Generates a unique location, or calls `:presign_location`.
-        def get_presign_location
-          if presign_location
-            presign_location.call(request)
-          else
-            extension = request.params["extension"]
-            extension.prepend(".") if extension && !extension.start_with?(".")
-            uploader.send(:generate_uid, nil) + extension.to_s
-          end
-        end
-
-        # Returns dynamic options for generating the presign.
-        def get_presign_options
-          options = presign_options
-          options = options.call(request) if options.respond_to?(:call)
-          options || {}
-        end
-
-        # Generates the presign hash for the request.
-        def generate_presign(location, options)
-          if presign_storage?
-            generate_real_presign(location, options)
-          else
-            generate_fake_presign(location, options)
-          end
-        end
-
-        # Generates a presign by calling the storage.
-        def generate_real_presign(location, options)
-          signature = uploader.storage.presign(location, options)
-          {url: signature.url, fields: signature.fields}
-        end
-
-        # Generates a presign that points to the direct upload endpoint.
-        def generate_fake_presign(location, options)
-          url = request.url.sub(/presign[^\/]*$/, "upload")
-          {url: url, fields: {key: location}}
-        end
-
-        # Returns true if the storage supports presigns.
-        def presign_storage?
-          uploader.storage.respond_to?(:presign)
-        end
-
-        # Halts the request if storage is not allowed.
-        def allow_storage!(storage_key)
-          if !allowed_storages.map(&:to_s).include?(storage_key)
-            error! 403, "Storage #{storage_key.inspect} is not allowed."
-          end
-        end
-
-        # Returns the Rack file wrapped in an IO-like object. If "file" is
-        # missing or is too big, the request is halted.
-        def get_file
-          file = require_param!("file")
-          error! 400, "The \"file\" query parameter is not a file." if !(file.is_a?(Hash) && file.key?(:tempfile))
-          check_filesize!(file[:tempfile]) if max_size
-
-          RackFile::UploadedFile.new(file)
-        end
-
-        # If the file is too big, deletes the file and halts the request.
-        def check_filesize!(file)
-          if file.size > max_size
-            file.delete
-            megabytes = max_size.to_f / 1024 / 1024
-            error! 413, "The file is too big (maximum size is #{megabytes} MB)."
-          end
-        end
-
-        # Loudly requires the param.
-        def require_param!(name)
-          request.params.fetch(name)
-        rescue KeyError
-          error! 400, "Missing query parameter: #{name.inspect}"
-        end
-
-        # Halts the request with the error message.
-        def error!(status, message)
-          response.status = status
-          response.write({error: message}.to_json)
-          request.halt
-        end
-
-        def json(object)
-          object.to_json
-        end
-
-        def shrine_class
-          opts[:shrine_class]
-        end
-
-        def allowed_storages
-          shrine_class.opts[:direct_upload_allowed_storages]
-        end
-
-        def presign_options
-          shrine_class.opts[:direct_upload_presign_options]
-        end
-
-        def presign_location
-          shrine_class.opts[:direct_upload_presign_location]
-        end
-
-        def max_size
-          shrine_class.opts[:direct_upload_max_size]
-        end
-      end
-    end
-
-    register_plugin(:direct_upload, DirectUpload)
-  end
-end