shrine 2.14.0 → 2.15.0

data/lib/shrine/plugins/signature.rb

@@ -2,43 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `signature` plugin provides the ability to calculate a hash from file
-    # content. This hash can be used as a checksum or just as a unique
-    # signature for the uploaded file.
-    #
-    #     Shrine.plugin :signature
-    #
-    # The plugin adds a `#calculate_signature` instance and class method to the
-    # uploader. The method accepts an IO object and a hashing algorithm, and
-    # returns the calculated hash.
-    #
-    #     Shrine.calculate_signature(io, :md5)
-    #     #=> "9a0364b9e99bb480dd25e1f0284c8555"
-    #
-    # You can then use the `add_metadata` plugin to add a new metadata field
-    # with the calculated hash.
-    #
-    #     plugin :add_metadata
-    #
-    #     add_metadata :md5 do |io, context|
-    #       calculate_signature(io, :md5)
-    #     end
-    #
-    # This will generate a hash for each uploaded file, but if you want to
-    # generate one only for the original file, you can add a conditional:
-    #
-    #     add_metadata :md5 do |io, context|
-    #       calculate_signature(io, :md5) if context[:action] == :cache
-    #     end
-    #
-    # The following hashing algorithms are supported: SHA1, SHA256, SHA384,
-    # SHA512, MD5, and CRC32.
-    #
-    # You can also choose which format will the calculated hash be encoded in:
-    #
-    #     Shrine.calculate_signature(io, :sha256, format: :base64)
-    #
-    # The supported encoding formats are `hex` (default), `base64`, and `none`.
     module Signature
       module ClassMethods
         # Calculates `algorithm` hash of the contents of the IO object, and

data/lib/shrine/plugins/store_dimensions.rb

@@ -2,69 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `store_dimensions` plugin extracts dimensions of uploaded images and
-    # stores them into the metadata hash (by default it uses the [fastimage]
-    # gem).
-    #
-    #     plugin :store_dimensions
-    #
-    # The dimensions are stored as "width" and "height" metadata values on the
-    # Shrine::UploadedFile object. For convenience the plugin also adds
-    # `#width`, `#height` and `#dimensions` reader methods.
-    #
-    #     image = uploader.upload(file)
-    #
-    #     image.metadata["width"]  #=> 300
-    #     image.metadata["height"] #=> 500
-    #     # or
-    #     image.width  #=> 300
-    #     image.height #=> 500
-    #     # or
-    #     image.dimensions #=> [300, 500]
-    #
-    # By default the [fastimage] gem is used to extract dimensions. You can
-    # choose a different built-in analyzer via the `:analyzer` option:
-    #
-    #     plugin :store_dimensions, analyzer: :mini_magick
-    #
-    # The following analyzers are supported:
-    #
-    # :fastimage
-    # : (Default). Uses the [fastimage] gem to extract dimensions from any IO
-    #   object.
-    #
-    # :mini_magick
-    # : Uses the [mini_magick] gem to extract dimensions from File objects. If
-    #   non-file IO object is given it will be temporarily downloaded to disk.
-    #
-    # :ruby_vips
-    # : Uses the [ruby-vips] gem to extract dimensions from File objects. If
-    #   non-file IO object is given it will be temporarily downloaded to disk.
-    #
-    # You can also create your own custom dimensions analyzer, where you can
-    # reuse any of the built-in analyzers. The analyzer is a lambda that
-    # accepts an IO object and returns width and height as a two-element array,
-    # or `nil` if dimensions could not be extracted.
-    #
-    #     plugin :store_dimensions, analyzer: -> (io, analyzers) do
-    #       dimensions   = analyzers[:fastimage].call(io)   # try extracting dimensions with FastImage
-    #       dimensions ||= analyzers[:mini_magick].call(io) # otherwise fall back to MiniMagick
-    #       dimensions
-    #     end
-    #
-    # You can use methods for extracting the dimensions directly:
-    #
-    #     # or YourUploader.extract_dimensions(io)
-    #     Shrine.extract_dimensions(io) # calls the defined analyzer
-    #     #=> [300, 400]
-    #
-    #     # or YourUploader.dimensions_analyzers
-    #     Shrine.dimensions_analyzers[:fastimage].call(io) # calls a built-in analyzer
-    #     #=> [300, 400]
-    #
-    # [fastimage]: https://github.com/sdsykes/fastimage
-    # [mini_magick]: https://github.com/minimagick/minimagick
-    # [ruby-vips]: https://github.com/libvips/ruby-vips
     module StoreDimensions
       def self.configure(uploader, opts = {})
         uploader.opts[:dimensions_analyzer] = opts.fetch(:analyzer, uploader.opts.fetch(:dimensions_analyzer, :fastimage))

data/lib/shrine/plugins/tempfile.rb

@@ -1,44 +1,13 @@
 class Shrine
   module Plugins
-    # The `tempfile` plugin makes it easier to reuse a single copy of an
-    # uploaded file on disk.
-    #
-    #     Shrine.plugin :tempfile
-    #
-    # The plugin provides the `UploadedFile#tempfile` method, which when called
-    # on an open uploaded file will return a copy of its content on disk. The
-    # first time the method is called the file content will cached into a
-    # temporary file and returned. On any subsequent method calls the cached
-    # temporary file will be returned directly. The temporary file is deleted
-    # when the uploaded file is closed.
-    #
-    #     uploaded_file.open do
-    #       # ...
-    #       uploaded_file.tempfile #=> #<Tempfile:...> (file is cached)
-    #       # ...
-    #       uploaded_file.tempfile #=> #<Tempfile:...> (cache is returned)
-    #       # ...
-    #     end # tempfile is deleted
-    #
-    #     # OR
-    #
-    #     uploaded_file.open
-    #     # ...
-    #     uploaded_file.tempfile #=> #<Tempfile:...> (file is cached)
-    #     # ...
-    #     uploaded_file.tempfile #=> #<Tempfile:...> (cache is returned)
-    #     # ...
-    #     uploaded_file.close # tempfile is deleted
-    #
-    # This plugin also modifies `Shrine.with_file` to call
-    # `UploadedFile#tempfile` when the given IO object is an open
-    # `UploadedFile`. Since `Shrine.with_file` is typically called on the
-    # `Shrine` class directly, it's recommended to load this plugin globally.
     module Tempfile
       module ClassMethods
         def with_file(io)
           if io.is_a?(UploadedFile) && io.opened?
-            yield io.tempfile
+            # open a new file descriptor for thread safety
+            File.open(io.tempfile.path, binmode: true) do |file|
+              yield file
+            end
           else
             super
           end

data/lib/shrine/plugins/upload_endpoint.rb

@@ -7,113 +7,6 @@ require "digest"
 
 class Shrine
   module Plugins
-    # The `upload_endpoint` plugin provides a Rack endpoint which accepts file
-    # uploads and forwards them to specified storage. On the client side it's
-    # recommended to use [Uppy] for asynchronous uploads.
-    #
-    #     plugin :upload_endpoint
-    #
-    # The plugin adds a `Shrine.upload_endpoint` method which, given a storage
-    # identifier, returns a Rack application that accepts multipart POST
-    # requests, and uploads received files to the specified storage. You can
-    # run this Rack application inside your app:
-    #
-    #     # config.ru (Rack)
-    #     map "/images/upload" do
-    #       run ImageUploader.upload_endpoint(:cache)
-    #     end
-    #
-    #     # OR
-    #
-    #     # config/routes.rb (Rails)
-    #     Rails.application.routes.draw do
-    #       mount ImageUploader.upload_endpoint(:cache) => "/images/upload"
-    #     end
-    #
-    # Asynchronous upload is typically meant to replace the caching phase in
-    # the default synchronous workflow, so we want the uploads to go to
-    # temporary (`:cache`) storage.
-    #
-    # The above will create a `POST /images/upload` endpoint, which uploads the
-    # file received in the `file` param using `ImageUploader`, and returns a
-    # JSON representation of the uploaded file.
-    #
-    #     # POST /images/upload
-    #     {
-    #       "id": "43kewit94.jpg",
-    #       "storage": "cache",
-    #       "metadata": {
-    #         "size": 384393,
-    #         "filename": "nature.jpg",
-    #         "mime_type": "image/jpeg"
-    #       }
-    #     }
-    #
-    # This JSON string can now be assigned to an attachment attribute instead
-    # of a raw file. In a form it can be written to a hidden attachment field,
-    # and then it can be assigned as the attachment.
-    #
-    # ## Limiting filesize
-    #
-    # It's good practice to limit the accepted filesize of uploaded files. You
-    # can do that with the `:max_size` option:
-    #
-    #     plugin :upload_endpoint, max_size: 20*1024*1024 # 20 MB
-    #
-    # If the uploaded file is larger than the specified value, a `413 Payload
-    # Too Large` response will be returned.
-    #
-    # ## Checksum
-    #
-    # If you want the upload endpoint to verify the integrity of the uploaded
-    # file, you can include the `Content-MD5` header in the request filled with
-    # the base64-encoded MD5 hash of the file that was calculated prior to the
-    # upload, and the endpoint will automatically use it to verify the uploaded
-    # data.
-    #
-    # If the checksums don't match, a `460 Checksum Mismatch` response is
-    # returned.
-    #
-    # ## Context
-    #
-    # The upload context will *not* contain `:record` and `:name` values, as
-    # the upload happens independently of a database record. The endpoint will
-    # send the following upload context:
-    #
-    # * `:action` - holds the value `:upload`
-    # * `:request` - holds an instance of `Rack::Request`
-    #
-    # You can update the upload context via `:upload_context`:
-    #
-    #     plugin :upload_endpoint, upload_context: -> (request) do
-    #       { location: "my-location" }
-    #     end
-    #
-    # ## Upload
-    #
-    # You can also customize the upload itself via the `:upload` option:
-    #
-    #     plugin :upload_endpoint, upload: -> (io, context, request) do
-    #       Shrine.new(:cache).upload(io, context)
-    #     end
-    #
-    # ## Response
-    #
-    # The response returned by the endpoint can be customized via the
-    # `:rack_response` option:
-    #
-    #     plugin :upload_endpoint, rack_response: -> (uploaded_file, request) do
-    #       body = { data: uploaded_file.data, url: uploaded_file.url }.to_json
-    #       [201, { "Content-Type" => "application/json" }, [body]]
-    #     end
-    #
-    # ## Ad-hoc options
-    #
-    # You can override any of the options above when creating the endpoint:
-    #
-    #     Shrine.upload_endpoint(:cache, max_size: 20*1024*1024)
-    #
-    # [Uppy]: https://uppy.io
     module UploadEndpoint
       def self.load_dependencies(uploader, opts = {})
         uploader.plugin :rack_file
@@ -237,7 +130,7 @@ class Shrine
           if @rack_response
             @rack_response.call(object, request)
           else
-            [200, {"Content-Type" => CONTENT_TYPE_JSON}, [object.to_json]]
+            [200, { "Content-Type" => CONTENT_TYPE_JSON }, [object.to_json]]
           end
         end
 
@@ -251,7 +144,7 @@ class Shrine
 
         # Used for early returning an error response.
         def error!(status, message)
-          throw :halt, [status, {"Content-Type" => CONTENT_TYPE_TEXT}, [message]]
+          throw :halt, [status, { "Content-Type" => CONTENT_TYPE_TEXT }, [message]]
         end
 
         # Returns the uploader around the specified storage.

data/lib/shrine/plugins/upload_options.rb

@@ -2,26 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `upload_options` plugin allows you to automatically pass additional
-    # upload options to storage on every upload:
-    #
-    #     plugin :upload_options, cache: { acl: "private" }
-    #
-    # Keys are names of the registered storages, and values are either hashes
-    # or blocks.
-    #
-    #     plugin :upload_options, store: ->(io, context) do
-    #       if [:original, :thumb].include?(context[:version])
-    #         { acl: "public-read" }
-    #       else
-    #         { acl: "private" }
-    #       end
-    #     end
-    #
-    # If you're uploading the file directly, you can also pass `:upload_options`
-    # to the uploader.
-    #
-    #     uploader.upload(file, upload_options: { acl: "public-read" })
     module UploadOptions
       def self.configure(uploader, options = {})
         uploader.opts[:upload_options] ||= {}

data/lib/shrine/plugins/validation_helpers.rb

@@ -2,42 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `validation_helpers` plugin provides helper methods for validating
-    # attached files.
-    #
-    #     plugin :validation_helpers
-    #
-    #     Attacher.validate do
-    #       validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
-    #       validate_max_size 5*1024*1024 if record.guest?
-    #     end
-    #
-    # The validation methods are instance-level, the `Attacher.validate` block
-    # is evaluated in context of an instance of `Shrine::Attacher`, so you can
-    # easily do conditional validation.
-    #
-    # The validation methods return whether the validation succeeded, allowing
-    # you to do conditional validation.
-    #
-    #     if validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
-    #       validate_max_width 2000
-    #       validate_max_height 2000
-    #     end
-    #
-    # If you would like to change default validation error messages, you can
-    # pass in the `:default_messages` option to the plugin:
-    #
-    #     plugin :validation_helpers, default_messages: {
-    #       max_size: ->(max) { I18n.t("errors.file.max_size", max: max) },
-    #       mime_type_inclusion: ->(whitelist) { I18n.t("errors.file.mime_type_inclusion", whitelist: whitelist) },
-    #     }
-    #
-    # If you would like to change the error message inline, you can pass the
-    # `:message` option to any validation method:
-    #
-    #     validate_mime_type_inclusion %w[image/jpeg image/png image/gif], message: "must be JPEG, PNG or GIF"
-    #
-    # For a complete list of all validation helpers, see AttacherMethods.
     module ValidationHelpers
       def self.configure(uploader, opts = {})
         uploader.opts[:validation_default_messages] ||= {}

data/lib/shrine/plugins/versions.rb

@@ -2,162 +2,6 @@
 
 class Shrine
   module Plugins
-    # The `versions` plugin enables your uploader to deal with versions, by
-    # allowing you to return a Hash of files when processing.
-    #
-    #     plugin :versions
-    #
-    # Here is an example of processing image thumbnails using the
-    # [image_processing] gem:
-    #
-    #     require "image_processing/mini_magick"
-    #
-    #     plugin :processing
-    #
-    #     process(:store) do |io, context|
-    #       versions = { original: io } # retain original
-    #
-    #       io.download do |original|
-    #         pipeline = ImageProcessing::MiniMagick.source(original)
-    #
-    #         versions[:large]  = pipeline.resize_to_limit!(800, 800)
-    #         versions[:medium] = pipeline.resize_to_limit!(500, 500)
-    #         versions[:small]  = pipeline.resize_to_limit!(300, 300)
-    #       end
-    #
-    #       versions # return the hash of processed files
-    #     end
-    #
-    # You probably want to load the `delete_raw` plugin to automatically
-    # delete processed files after they have been uploaded.
-    #
-    # Now when you access the stored attachment through the model, a hash of
-    # uploaded files will be returned:
-    #
-    #     user.avatar_data #=>
-    #     # '{
-    #     #   "original": {"id":"0gsdf.jpg", "storage":"store", "metadata":{...}},
-    #     #   "large": {"id":"lg043.jpg", "storage":"store", "metadata":{...}},
-    #     #   "medium": {"id":"kd9fk.jpg", "storage":"store", "metadata":{...}},
-    #     #   "small": {"id":"932fl.jpg", "storage":"store", "metadata":{...}}
-    #     # }'
-    #
-    #     user.avatar #=>
-    #     # {
-    #     #   :original => #<Shrine::UploadedFile @data={"id"=>"0gsdf.jpg", ...}>,
-    #     #   :large    => #<Shrine::UploadedFile @data={"id"=>"lg043.jpg", ...}>,
-    #     #   :medium   => #<Shrine::UploadedFile @data={"id"=>"kd9fk.jpg", ...}>,
-    #     #   :small    => #<Shrine::UploadedFile @data={"id"=>"932fl.jpg", ...}>,
-    #     # }
-    #
-    #     user.avatar[:medium]     #=> #<Shrine::UploadedFile>
-    #     user.avatar[:medium].url #=> "/uploads/store/lg043.jpg"
-    #
-    # The plugin also extends the `Attacher#url` to accept versions:
-    #
-    #     user.avatar_url(:large)
-    #     user.avatar_url(:small, download: true) # with URL options
-    #
-    # `Shrine.uploaded_file` will also instantiate a hash of
-    # `Shrine::UploadedFile` objects if given data with versions. If you want
-    # to apply a change to all files in an attachment, regardless of whether
-    # it consists of a single file or a hash of versions, you can pass a block
-    # to `Shrine.uploaded_file` and it will yield each file:
-    #
-    #     Shrine.uploaded_file(attachment_data) do |uploaded_file|
-    #       # ...
-    #     end
-    #
-    # ## Fallbacks
-    #
-    # If versions are processed in a background job, there will be a period
-    # where the user will browse the site before versions have finished
-    # processing. In this period `Attacher#url` will by default fall back to
-    # the original file.
-    #
-    #     user.avatar #=> #<Shrine::UploadedFile>
-    #     user.avatar_url(:large) # falls back to `user.avatar_url`
-    #
-    # This behaviour is convenient if you want to gracefully degrade to the
-    # cached file until the background job has finished processing. However, if
-    # you would rather provide your own default URLs for versions, you can
-    # disable this fallback:
-    #
-    #     plugin :versions, fallback_to_original: false
-    #
-    # If you already have some versions processed in the foreground after a
-    # background job is kicked off (with the `recache` plugin), you can have
-    # URLs for versions that are yet to be processed fall back to existing
-    # versions:
-    #
-    #     plugin :versions, fallbacks: {
-    #       :thumb_2x => :thumb,
-    #       :large_2x => :large,
-    #     }
-    #
-    #     # ... (background job is kicked off)
-    #
-    #     user.avatar_url(:thumb_2x) # returns :thumb URL until :thumb_2x becomes available
-    #     user.avatar_url(:large_2x) # returns :large URL until :large_2x becomes available
-    #
-    # ## Arrays
-    #
-    # In addition to Hashes, the plugin also supports Arrays of files. For
-    # example, you might want to split a PDf into pages:
-    #
-    #     process(:store) do |io, context|
-    #       versions = { pages: [] }
-    #
-    #       io.download do |pdf|
-    #         page_count = MiniMagick::Image.new(pdf.path).pages.count
-    #         pipeline   = ImageProcessing::MiniMagick.source(pdf).convert("jpg")
-    #
-    #         page_count.times do |page_number|
-    #           versions[:pages] << pipeline.loader(page: page_number).call
-    #         end
-    #       end
-    #
-    #       versions
-    #     end
-    #
-    # You can also combine Hashes and Arrays, there is no limit to the level of
-    # nesting.
-    #
-    # ## Original file
-    #
-    # It's recommended to always keep the original file after processing
-    # versions, which you can do by adding the yielded `Shrine::UploadedFile`
-    # object as one of the versions, by convention named `:original`:
-    #
-    #     process(:store) do |io, context|
-    #       # processing thumbnail
-    #       { original: io, thumbnail: thumbnail }
-    #     end
-    #
-    # If both temporary and permanent storage are Amazon S3, the cached original
-    # will simply be copied over to permanent storage (without any downloading
-    # and reuploading), so in these cases the performance impact of storing the
-    # original file in addition to processed versions is neglibible.
-    #
-    # ## Context
-    #
-    # The version name will be available via `:version` when generating
-    # location or a default URL.
-    #
-    #     def generate_location(io, context)
-    #       "uploads/#{context[:version]}-#{super}"
-    #     end
-    #
-    #     Attacher.default_url do |options|
-    #       "/images/defaults/#{options[:version]}.jpg"
-    #     end
-    #
-    # ## Re-create Versions
-    #
-    # If you want to re-create a single or all versions, refer to the [reprocessing versions] guide for details.
-    #
-    # [reprocessing versions]: https://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html
-    # [image_processing]: https://github.com/janko-m/image_processing
     module Versions
       def self.load_dependencies(uploader, *)
         uploader.plugin :default_url