shrine 2.13.0 → 2.14.0

data/lib/shrine/plugins/sequel.rb

@@ -70,33 +70,36 @@ class Shrine
 
           return unless model < ::Sequel::Model
 
-          opts = shrine_class.opts
+          name = attachment_name
 
-          module_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:sequel_validations]
-            def validate
-              super
-              #{@name}_attacher.errors.each do |message|
-                errors.add(:#{@name}, *message)
+          if shrine_class.opts[:sequel_validations]
+            define_method :validate do
+              super()
+              send(:"#{name}_attacher").errors.each do |message|
+                errors.add(name, *message)
               end
             end
-          RUBY
+          end
 
-          module_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:sequel_callbacks]
-            def before_save
-              super
-              #{@name}_attacher.save if #{@name}_attacher.changed?
+          if shrine_class.opts[:sequel_callbacks]
+            define_method :before_save do
+              super()
+              attacher = send(:"#{name}_attacher")
+              attacher.save if attacher.changed?
             end
 
-            def after_save
-              super
-              db.after_commit{#{@name}_attacher.finalize} if #{@name}_attacher.changed?
+            define_method :after_save do
+              super()
+              attacher = send(:"#{name}_attacher")
+              db.after_commit { attacher.finalize } if attacher.changed?
             end
 
-            def after_destroy
-              super
-              db.after_commit{#{@name}_attacher.destroy} if #{@name}_attacher.read
+            define_method :after_destroy do
+              super()
+              attacher = send(:"#{name}_attacher")
+              db.after_commit { attacher.destroy } if attacher.read
             end
-          RUBY
+          end
         end
       end
 

data/lib/shrine/plugins/tempfile.rb

@@ -0,0 +1,68 @@
+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
+          else
+            super
+          end
+        end
+      end
+
+      module FileMethods
+        def tempfile
+          raise Error, "uploaded file must be opened" unless @io
+
+          @tempfile ||= download
+          @tempfile.rewind
+          @tempfile
+        end
+
+        def close
+          super
+
+          @tempfile.close! if @tempfile
+          @tempfile = nil
+        end
+      end
+    end
+
+    register_plugin(:tempfile, Tempfile)
+  end
+end

data/lib/shrine/plugins/upload_endpoint.rb

@@ -135,14 +135,15 @@ class Shrine
         # Additional options can be given to override the options given on
         # plugin initialization.
         def upload_endpoint(storage_key, **options)
-          App.new({
+          App.new(
             shrine_class:   self,
             storage_key:    storage_key,
             max_size:       opts[:upload_endpoint_max_size],
             upload_context: opts[:upload_endpoint_upload_context],
             upload:         opts[:upload_endpoint_upload],
             rack_response:  opts[:upload_endpoint_rack_response],
-          }.merge(options))
+            **options
+          )
         end
       end
 

data/lib/shrine/plugins/upload_options.rb

@@ -5,32 +5,33 @@ class Shrine
     # The `upload_options` plugin allows you to automatically pass additional
     # upload options to storage on every upload:
     #
-    #     plugin :upload_options, cache: {acl: "private"}
+    #     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"}
+    #         { acl: "public-read" }
     #       else
-    #         {acl: "private"}
+    #         { 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"})
+    #     uploader.upload(file, upload_options: { acl: "public-read" })
     module UploadOptions
       def self.configure(uploader, options = {})
-        uploader.opts[:upload_options] = (uploader.opts[:upload_options] || {}).merge(options)
+        uploader.opts[:upload_options] ||= {}
+        uploader.opts[:upload_options].merge!(options)
       end
 
       module InstanceMethods
         def put(io, context)
           upload_options = get_upload_options(io, context)
-          context = {upload_options: upload_options}.merge(context)
+          context = { upload_options: upload_options }.merge(context)
           super
         end
 

data/lib/shrine/plugins/validation_helpers.rb

@@ -40,7 +40,8 @@ class Shrine
     # For a complete list of all validation helpers, see AttacherMethods.
     module ValidationHelpers
       def self.configure(uploader, opts = {})
-        uploader.opts[:validation_default_messages] = (uploader.opts[:validation_default_messages] || {}).merge(opts[:default_messages] || {})
+        uploader.opts[:validation_default_messages] ||= {}
+        uploader.opts[:validation_default_messages].merge!(opts[:default_messages] || {})
       end
 
       DEFAULT_MESSAGES = {

data/lib/shrine/storage/file_system.rb

@@ -8,6 +8,8 @@ class Shrine
     # The FileSystem storage handles uploads to the filesystem, and it is
     # most commonly initialized with a "base" folder and a "prefix":
     #
+    #     require "shrine/storage/file_system"
+    #
     #     storage = Shrine::Storage::FileSystem.new("public", prefix: "uploads")
     #     storage.url("image.jpg") #=> "/uploads/image.jpg"
     #
@@ -153,8 +155,8 @@ class Shrine
 
       # Opens the file on the given location in read mode. Accepts additional
       # `File.open` arguments.
-      def open(id, *args, &block)
-        path(id).open("rb", *args, &block)
+      def open(id, **options, &block)
+        path(id).open(binmode: true, **options, &block)
       end
 
       # Returns true if the file exists on the filesystem.
@@ -186,16 +188,15 @@ class Shrine
       # time.
       def clear!(older_than: nil)
         if older_than
-          directory.find do |path|
+          # add trailing slash to make it work with symlinks
+          Pathname("#{directory}/").find do |path|
             if path.file? && path.mtime < older_than
               path.delete
               clean(path) if clean?
             end
           end
         else
-          directory.rmtree
-          directory.mkpath
-          directory.chmod(directory_permissions) if directory_permissions
+          directory.children.each(&:rmtree)
         end
       end
 
@@ -205,17 +206,9 @@ class Shrine
       end
 
       # Catches the deprecated `#download` method.
-      def method_missing(name, *args)
-        if name == :download
-          begin
-            Shrine.deprecation("Shrine::Storage::FileSystem#download is deprecated and will be removed in Shrine 3.")
-            tempfile = Tempfile.new(["shrine-filesystem", File.extname(args[0])], binmode: true)
-            open(*args) { |file| IO.copy_stream(file, tempfile) }
-            tempfile.tap(&:open)
-          rescue
-            tempfile.close! if tempfile
-            raise
-          end
+      def method_missing(name, *args, &block)
+        case name
+        when :download then deprecated_download(*args, &block)
         else
           super
         end
@@ -254,6 +247,16 @@ class Shrine
       def relative(path)
         path.sub(%r{^/}, "")
       end
+
+      def deprecated_download(id, **options)
+        Shrine.deprecation("Shrine::Storage::FileSystem#download is deprecated and will be removed in Shrine 3.")
+        tempfile = Tempfile.new(["shrine-filesystem", File.extname(id)], binmode: true)
+        open(id, **options) { |file| IO.copy_stream(file, tempfile) }
+        tempfile.tap(&:open)
+      rescue
+        tempfile.close! if tempfile
+        raise
+      end
     end
   end
 end

data/lib/shrine/storage/linter.rb

@@ -38,7 +38,6 @@ class Shrine
       def call(io_factory = default_io_factory)
         storage.upload(io_factory.call, id = "foo".dup, {})
 
-        lint_download(id) if storage.respond_to?(:download)
         lint_open(id)
         lint_exists(id)
         lint_url(id)
@@ -59,12 +58,6 @@ class Shrine
         end
       end
 
-      def lint_download(id)
-        downloaded = storage.download(id)
-        error :download, "doesn't return a Tempfile" if !downloaded.is_a?(Tempfile)
-        error :download, "returns an empty IO object" if downloaded.read.empty?
-      end
-
       def lint_open(id)
         opened = storage.open(id)
         error :open, "doesn't return a valid IO object" if !io?(opened)

data/lib/shrine/storage/s3.rb

@@ -17,6 +17,8 @@ rescue LoadError => exception
 end
 
 require "down/chunked_io"
+require "content_disposition"
+
 require "uri"
 require "cgi"
 require "tempfile"
@@ -30,6 +32,8 @@ class Shrine
     #
     # It can be initialized by providing the bucket name and credentials:
     #
+    #     require "shrine/storage/s3"
+    #
     #     s3 = Shrine::Storage::S3.new(
     #       bucket: "my-app", # required
     #       access_key_id: "abc",
@@ -153,24 +157,24 @@ class Shrine
     #     # or
     #     Shrine::Storage::S3.new(signer: -> (url, **options) { signer.signed_url(url, **options) })
     #
-    # ## Accelerate endpoint
+    # ## Presigns
     #
-    # To use Amazon S3's [Transfer Acceleration] feature, you can change the
-    # `:endpoint` of the underlying client to the accelerate endpoint, and this
-    # will be applied both to regular and presigned uploads, as well as
-    # download URLs.
+    # The `#presign` method can be used for generating paramters for direct
+    # uploads to Amazon S3:
     #
-    #     Shrine::Storage::S3.new(endpoint: "https://s3-accelerate.amazonaws.com")
+    #     s3.presign("/path/to/file") #=>
+    #     # {
+    #     #   url: "https://my-bucket.s3.amazonaws.com/...",
+    #     #   fields: { ... },  # blank for PUT presigns
+    #     #   headers: { ... }, # blank for POST presigns
+    #     #   method: "post",
+    #     # }
     #
-    # ## Presigns
-    #
-    # This storage can generate presigns for direct uploads to Amazon S3, and
-    # it accepts additional options which are passed to aws-sdk-s3. There are
-    # three places in which you can specify presign options:
+    # Additional presign options can be given in three places:
     #
+    # * in `Storage::S3#presign` by forwarding options
     # * in `:upload_options` option on this storage
     # * in `presign_endpoint` plugin through `:presign_options`
-    # * in `Storage::S3#presign` by forwarding options
     #
     # ## Large files
     #
@@ -194,6 +198,55 @@ class Shrine
     #       { thread_count: 5 }
     #     end
     #
+    # ## Encryption
+    #
+    # The easiest way to use server-side encryption for uploaded S3 objects is
+    # to configure default encryption for your S3 bucket. Alternatively, you
+    # can pass server-side encryption parameters to the API calls.
+    #
+    # The `#upload` method accepts `:sse_*` options:
+    #
+    #     s3.upload(io, "key", sse_customer_algorithm: "AES256",
+    #                          sse_customer_key:       "secret_key",
+    #                          sse_customer_key_md5:   "secret_key_md5",
+    #                          ssekms_key_id:          "key_id")
+    #
+    # The `#presign` method accepts `:server_side_encryption_*` options for
+    # POST presigns, and the same `:sse_*` options as above for PUT presigns.
+    #
+    #     s3.presign("key", server_side_encryption_customer_algorithm: "AES256",
+    #                       server_side_encryption_customer_key:       "secret_key",
+    #                       server_side_encryption_aws_kms_key_id:     "key_id")
+    #
+    # When downloading encrypted S3 objects, the same server-side encryption
+    # parameters need to be passed in.
+    #
+    #     s3.download("key", sse_customer_algorithm: "AES256",
+    #                        sse_customer_key:       "secret_key",
+    #                        sse_customer_key_md5:   "secret_key_md5")
+    #
+    #     s3.open("key", sse_customer_algorithm: "AES256",
+    #                    sse_customer_key:       "secret_key",
+    #                    sse_customer_key_md5:   "secret_key_md5")
+    #
+    # If you want to use client-side encryption instead, you can instantiate
+    # the storage with an `Aws::S3::Encryption::Client` instance.
+    #
+    #     client = Aws::S3::Encryption::Client.new(
+    #       kms_key_id: "alias/my-key"
+    #     )
+    #
+    #     Shrine::Storage::S3(client: client, bucket: "my-bucket")
+    #
+    # ## Accelerate endpoint
+    #
+    # To use Amazon S3's [Transfer Acceleration] feature, you can change the
+    # `:endpoint` of the underlying client to the accelerate endpoint, and this
+    # will be applied both to regular and presigned uploads, as well as
+    # download URLs.
+    #
+    #     Shrine::Storage::S3.new(endpoint: "https://s3-accelerate.amazonaws.com")
+    #
     # ## Clearing cache
     #
     # If you're using S3 as a cache, you will probably want to periodically
@@ -205,6 +258,14 @@ class Shrine
     #     # deletes all objects that were uploaded more than 7 days ago
     #     s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 }
     #
+    # ## Request Rate and Performance Guidelines
+    #
+    # Amazon S3 automatically scales to high request rates. For example, your
+    # application can achieve at least 3,500 PUT/POST/DELETE and 5,500 GET
+    # requests per second per prefix in a bucket (a prefix is a top-level
+    # "directory" in the bucket). If your app needs to support higher request
+    # rates to S3 than that, you can scale exponentially by using more prefixes.
+    #
     # [uploading]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#put-instance_method
     # [copying]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#copy_from-instance_method
     # [presigning]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
@@ -214,8 +275,6 @@ class Shrine
     # [serve private content via CloudFront]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PrivateContent.html
     # [`Aws::CloudFront::UrlSigner`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/CloudFront/UrlSigner.html
     class S3
-      MIN_PART_SIZE = 5 * 1024 * 1024 # 5MB
-
       attr_reader :client, :bucket, :prefix, :host, :upload_options, :signer, :public
 
       # Initializes a storage for uploading to S3. All options are forwarded to
@@ -224,6 +283,12 @@ class Shrine
       # :bucket
       # : (Required). Name of the S3 bucket.
       #
+      # :client
+      # : By default an `Aws::S3::Client` instance is created internally from
+      #   additional options, but you can use this option to provide your own
+      #   client. This can be an `Aws::S3::Client` or an
+      #   `Aws::S3::Encryption::Client` object.
+      #
       # :prefix
       # : "Directory" inside the bucket to store files into.
       #
@@ -249,9 +314,10 @@ class Shrine
       # [`Aws::S3::Bucket#presigned_post`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
       # [`Aws::S3::Client#initialize`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#initialize-instance_method
       # [configuring AWS SDK]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html
-      def initialize(bucket:, prefix: nil, host: nil, upload_options: {}, multipart_threshold: {}, signer: nil, public: nil, **s3_options)
+      def initialize(bucket:, client: nil, prefix: nil, host: nil, upload_options: {}, multipart_threshold: {}, signer: nil, public: nil, **s3_options)
+        raise ArgumentError, "the :bucket option is nil" unless bucket
+
         Shrine.deprecation("The :host option to Shrine::Storage::S3#initialize is deprecated and will be removed in Shrine 3. Pass :host to S3#url instead, you can also use default_url_options plugin.") if host
-        resource = Aws::S3::Resource.new(**s3_options)
 
         if multipart_threshold.is_a?(Integer)
           Shrine.deprecation("Accepting the :multipart_threshold S3 option as an integer is deprecated, use a hash with :upload and :copy keys instead, e.g. {upload: 15*1024*1024, copy: 150*1024*1024}")
@@ -259,8 +325,8 @@ class Shrine
         end
         multipart_threshold = { upload: 15*1024*1024, copy: 100*1024*1024 }.merge(multipart_threshold)
 
-        @bucket = resource.bucket(bucket) or fail(ArgumentError, "the :bucket option was nil")
-        @client = resource.client
+        @client = client || Aws::S3::Client.new(**s3_options)
+        @bucket = Aws::S3::Bucket.new(name: bucket, client: @client)
         @prefix = prefix
         @host = host
         @upload_options = upload_options
@@ -287,7 +353,7 @@ class Shrine
 
         options = {}
         options[:content_type] = content_type if content_type
-        options[:content_disposition] = "inline; filename=\"#{filename}\"" if filename
+        options[:content_disposition] = ContentDisposition.inline(filename) if filename
         options[:acl] = "public-read" if public
 
         options.merge!(@upload_options)
@@ -303,22 +369,6 @@ class Shrine
         end
       end
 
-      # Downloads the file from S3 and returns a `Tempfile`. The download will
-      # be automatically retried up to 3 times. Any additional options are
-      # forwarded to [`Aws::S3::Object#get`].
-      #
-      # [`Aws::S3::Object#get`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#get-instance_method
-      def download(id, **options)
-        tempfile = Tempfile.new(["shrine-s3", File.extname(id)], binmode: true)
-        (object = object(id)).get(response_target: tempfile, **options)
-        tempfile.singleton_class.instance_eval { attr_accessor :content_type }
-        tempfile.content_type = object.content_type
-        tempfile.tap(&:open)
-      rescue
-        tempfile.close! if tempfile
-        raise
-      end
-
       # Returns a `Down::ChunkedIO` object that downloads S3 object content
       # on-demand. By default, read content will be cached onto disk so that
       # it can be rewinded, but if you don't need that you can pass
@@ -329,13 +379,15 @@ class Shrine
       # [`Aws::S3::Object#get`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#get-instance_method
       def open(id, rewindable: true, **options)
         object = object(id)
-        io = Down::ChunkedIO.new(
+
+        load_data(object, **options)
+
+        Down::ChunkedIO.new(
           chunks:     object.enum_for(:get, **options),
           rewindable: rewindable,
+          size:       object.content_length,
           data:       { object: object },
         )
-        io.size = object.content_length
-        io
       end
 
       # Returns true file exists on S3.
@@ -383,11 +435,24 @@ class Shrine
         url
       end
 
-      # Returns URL, params and headers for direct uploads. By default it
-      # generates data for a POST request, calling [`Aws::S3::Object#presigned_post`].
-      # You can also specify `method: :put` to generate data for a PUT request,
-      # using [`Aws::S3::Object#presigned_url`]. Any additional options are
-      # forwarded to the underlying AWS SDK method.
+      # Returns URL, params, headers, and verb for direct uploads.
+      #
+      #     s3.presign("key") #=>
+      #     # {
+      #     #   url: "https://my-bucket.s3.amazonaws.com/...",
+      #     #   fields: { ... },  # blank for PUT presigns
+      #     #   headers: { ... }, # blank for POST presigns
+      #     #   method: "post",
+      #     # }
+      #
+      # By default it calls [`Aws::S3::Object#presigned_post`] which generates
+      # data for a POST request, but you can also specify `method: :put` for
+      # PUT uploads which calls [`Aws::S3::Object#presigned_url`].
+      #
+      #     s3.presign("key", method: :post) # for POST upload (default)
+      #     s3.presign("key", method: :put)  # for PUT upload
+      #
+      # Any additional options are forwarded to the underlying AWS SDK method.
       #
       # [`Aws::S3::Object#presigned_post`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
       # [`Aws::S3::Object#presigned_url`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_url-instance_method
@@ -447,12 +512,11 @@ class Shrine
         bucket.object([*prefix, id].join("/"))
       end
 
-      # Catches the deprecated `#stream` method.
-      def method_missing(name, *args)
-        if name == :stream
-          Shrine.deprecation("Shrine::Storage::S3#stream is deprecated over calling #each_chunk on S3#open.")
-          object = object(*args)
-          object.get { |chunk| yield chunk, object.content_length }
+      # Catches the deprecated `#download` and `#stream` methods.
+      def method_missing(name, *args, &block)
+        case name
+        when :stream   then deprecated_stream(*args, &block)
+        when :download then deprecated_download(*args, &block)
         else
           super
         end
@@ -501,6 +565,23 @@ class Shrine
         bytes_uploaded
       end
 
+      # Aws::S3::Object#load doesn't support passing options to #head_object,
+      # so we call #head_object ourselves and assign the response data
+      def load_data(object, **options)
+        # filter out #get_object options that are not valid #head_object options
+        options = options.select do |key, value|
+          client.config.api.operation(:head_object).input.shape.member?(key)
+        end
+
+        response = client.head_object(
+          bucket: bucket.name,
+          key: object.key,
+          **options
+        )
+
+        object.instance_variable_set(:@data, response.data)
+      end
+
       def extract_path(io)
         if io.respond_to?(:path)
           io.path
@@ -530,9 +611,37 @@ class Shrine
       # should automatically URI-decode filenames when downloading.
       def encode_content_disposition(content_disposition)
         content_disposition.sub(/(?<=filename=").+(?=")/) do |filename|
-          CGI.escape(filename).gsub("+", " ")
+          if filename =~ /[^[:ascii:]]/
+            Shrine.deprecation("Shrine::Storage::S3 will not escape characters in the filename for Content-Disposition header in Shrine 3. Use the content_disposition gem, for example `ContentDisposition.format(disposition: 'inline', filename: '...')`.")
+            CGI.escape(filename).gsub("+", " ")
+          else
+            filename
+          end
         end
       end
+
+      def deprecated_stream(id)
+        Shrine.deprecation("Shrine::Storage::S3#stream is deprecated over calling #each_chunk on S3#open.")
+        object = object(id)
+        object.get { |chunk| yield chunk, object.content_length }
+      end
+
+      def deprecated_download(id, **options)
+        Shrine.deprecation("Shrine::Storage::S3#download is deprecated over S3#open.")
+
+        tempfile = Tempfile.new(["shrine-s3", File.extname(id)], binmode: true)
+        data = object(id).get(response_target: tempfile, **options)
+        tempfile.content_type = data.content_type
+        tempfile.tap(&:open)
+      rescue
+        tempfile.close! if tempfile
+        raise
+      end
+
+      # Tempfile with #content_type accessor which represents downloaded files.
+      class Tempfile < ::Tempfile
+        attr_accessor :content_type
+      end
     end
   end
 end