shrine 2.2.0 → 2.3.0

data/lib/shrine/plugins/store_dimensions.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The store_dimensions plugin extracts and stores dimensions of the
+    # The `store_dimensions` plugin extracts and stores dimensions of the
     # uploaded image using the [fastimage] gem.
     #
     #     plugin :store_dimensions

data/lib/shrine/plugins/upload_options.rb

@@ -1,7 +1,7 @@
 class Shrine
   module Plugins
-    # The upload_options allows you to automatically pass additional upload
-    # options to storage on every upload:
+    # The `upload_options` plugin allows you to automatically pass additional
+    # upload options to storage on every upload:
     #
     #     plugin :upload_options, cache: {acl: "private"}
     #

data/lib/shrine/plugins/validation_helpers.rb

@@ -1,15 +1,14 @@
 class Shrine
   module Plugins
-    # The validation_helpers plugin provides helper methods for validating
+    # The `validation_helpers` plugin provides helper methods for validating
     # attached files.
     #
     #     class ImageUploader < Shrine
     #       plugin :validation_helpers
     #
     #       Attacher.validate do
-    #         if record.guest?
-    #           validate_max_size 5*1024*1024
-    #         end
+    #         validat_mime_type_inclusion %w[image/jpeg image/png image/gif]
+    #         validate_max_size 5*1024*1024 if record.guest?
     #       end
     #     end
     #
@@ -72,7 +71,7 @@ class Shrine
         end
 
         # Validates that the file is not wider than `max`. Requires the
-        # store_dimensions plugin.
+        # `store_dimensions` plugin.
         def validate_max_width(max, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:width)
           if get.width && get.width > max
@@ -81,7 +80,7 @@ class Shrine
         end
 
         # Validates that the file is not narrower than `min`. Requires the
-        # store_dimensions plugin.
+        # `store_dimensions` plugin.
         def validate_min_width(min, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:width)
           if get.width && get.width < min
@@ -90,7 +89,7 @@ class Shrine
         end
 
         # Validates that the file is not taller than `max`. Requires the
-        # store_dimensions plugin.
+        # `store_dimensions` plugin.
         def validate_max_height(max, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:height)
           if get.height && get.height > max
@@ -99,7 +98,7 @@ class Shrine
         end
 
         # Validates that the file is not shorter than `min`. Requires the
-        # store_dimensions plugin.
+        # `store_dimensions` plugin.
         def validate_min_height(min, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:height)
           if get.height && get.height < min

data/lib/shrine/plugins/versions.rb

@@ -1,6 +1,6 @@
 class Shrine
   module Plugins
-    # The versions plugin enables your uploader to deal with versions, by
+    # The `versions` plugin enables your uploader to deal with versions, by
     # allowing you to return a Hash of files when processing.
     #
     #     plugin :versions
@@ -19,16 +19,6 @@ class Shrine
     #       {large: size_700, medium: size_500, small: size_300}
     #     end
     #
-    # Note that if you want to keep the original file, you can forward it as is
-    # without explicitly downloading it (since `Shrine::UploadedFile` itself is
-    # an IO-like object), which might avoid downloading depending on the
-    # storage:
-    #
-    #     process(:store) do |io, context|
-    #       # processing thumbnail
-    #       {original: io, thumbnail: thumbnail}
-    #     end
-    #
     # Now when you access the stored attachment through the model, a hash of
     # uploaded files will be returned:
     #
@@ -51,28 +41,43 @@ class Shrine
     #     user.avatar[:medium].width #=> 500
     #     user.avatar[:small].width  #=> 300
     #
-    # You probably want to load the delete_raw plugin to automatically
+    # You probably want to load the `delete_raw` plugin to automatically
     # delete processed files after they have been uploaded.
     #
-    # The plugin also extends the `avatar_url` method to accept versions:
+    # ## Original file
     #
-    #     user.avatar_url(:medium)
+    # If you want to keep the original file, you can forward it as is without
+    # explicitly downloading it (since `Shrine::UploadedFile` itself is an
+    # IO-like object), which might avoid downloading depending on the storage:
     #
-    # This method plays nice when generating versions in a background job,
-    # since it will just point to the original cached file until the versions
-    # are done processing:
+    #     process(:store) do |io, context|
+    #       # processing thumbnail
+    #       {original: io, thumbnail: thumbnail}
+    #     end
+    #
+    # ## Fallbacks
     #
-    #     user.avatar #=> #<Shrine::UploadedFile>
-    #     user.avatar_url(:medium) #=> "http://example.com/original.jpg"
+    # The plugin also extends the `<attachmen>_url` method to accept versions,
+    # and adds automatic fallbacks:
     #
-    #     # the background job has finished generating versions
+    #     user.avatar_url(:medium)
+    #
+    #     # returns URL of that version if versions have been created,
+    #     # otherwise returns original URL if attachment exists,
+    #     # otherwise returns nil
     #
-    #     user.avatar_url(:medium) #=> "http://example.com/medium.jpg"
+    # This behaviour is convenient when using background jobs, as it allows you
+    # to gracefully degrade before the background job finishes.
     #
     # If you already have some versions processed in the foreground when a
-    # background job is kicked off, you can setup explicit URL fallbacks:
+    # background job is kicked off (with the `recache` plugin), the
+    # `<attachment>_url` method won't know which version to use as a fallback.
+    # In that case you can specify `:fallbacks` when loading the plugin:
     #
-    #     plugin :versions, fallbacks: {:thumb_2x => :thumb, :large_2x => :large}
+    #     plugin :versions, fallbacks: {
+    #       :thumb_2x => :thumb,
+    #       :large_2x => :large,
+    #     }
     #
     #     # ... (background job is kicked off)
     #
@@ -84,6 +89,8 @@ class Shrine
     #
     #     user.avatar_url(:medium, download: true)
     #
+    # ## Context
+    #
     # The `context` will now also include the version name, which you can use
     # when generating a location or a default URL:
     #
@@ -95,13 +102,7 @@ class Shrine
     #       "/images/defaults/#{context[:version]}.jpg"
     #     end
     #
-    # When deleting versions, any multi delete capabilities will be leveraged,
-    # so when using Storage::S3, deleting versions will issue only a single HTTP
-    # request. If you want to delete versions manually, you can use
-    # `Shrine#delete`:
-    #
-    #     versions.keys #=> [:small, :medium, :large]
-    #     ImageUploader.new(:storage).delete(versions) # deletes a hash of versions
+    # [image_processing]: https://github.com/janko-m/image_processing
     module Versions
       def self.load_dependencies(uploader, *)
         uploader.plugin :multi_delete

data/lib/shrine/storage/file_system.rb

@@ -51,10 +51,11 @@ class Shrine
     #
     # ## Permissions
     #
-    # If you want your files and folders to have certain permissions, you can
-    # pass the `:permissions` option:
+    # The storage sets the default UNIX permissions to 0644 for files and 0755
+    # for directories, but you can change that:
     #
-    #     Shrine::Storage::FileSystem.new("directory", permissions: 0755)
+    #     Shrine::Storage::FileSystem.new("directory", permissions: 0644)
+    #     Shrine::Storage::FileSystem.new("directory", directory_permissions: 0755)
     #
     # ## Heroku
     #
@@ -69,9 +70,9 @@ class Shrine
     # restarts. This also means that deploying the app can cancel someone's
     # uploading if you're using backgrounding. Also, by default you cannot
     # generate URLs to files in the "tmp" directory, but you can with the
-    # download_endpoint plugin.
+    # `download_endpoint` plugin.
     class FileSystem
-      attr_reader :directory, :prefix, :host, :permissions
+      attr_reader :directory, :prefix, :host, :permissions, :directory_permissions
 
       # Initializes a storage for uploading to the filesystem.
       #
@@ -84,14 +85,16 @@ class Shrine
       #    can use this option to set a CDN host (e.g. `//abc123.cloudfront.net`).
       #
       # :permissions
-      # :  The generated files and folders will have default UNIX permissions,
-      #    but if you want specific ones you can use this option (e.g. `0755`).
+      # :  Changes the UNIX permissions of created files (default is 0644).
+      #
+      # :directory_permissions
+      # :  Changes the UNIX permissions of created directories (default is 0755).
       #
       # :clean
       # :  By default empty folders inside the directory are automatically
       #    deleted, but if it happens that it causes too much load on the
       #    filesystem, you can set this option to `false`.
-      def initialize(directory, prefix: nil, host: nil, clean: true, permissions: nil)
+      def initialize(directory, prefix: nil, host: nil, clean: true, permissions: 0644, directory_permissions: 0755)
         if prefix
           @prefix = Pathname(relative(prefix))
           @directory = Pathname(directory).join(@prefix)
@@ -101,10 +104,11 @@ class Shrine
 
         @host = host
         @permissions = permissions
+        @directory_permissions = directory_permissions
         @clean = clean
 
         @directory.mkpath
-        @directory.chmod(permissions) if permissions
+        @directory.chmod(directory_permissions) if directory_permissions
       end
 
       # Copies the file into the given location.
@@ -118,7 +122,7 @@ class Shrine
         open(id) { |file| Down.copy_to_tempfile(id, file) }
       end
 
-      # Moves the file to the given location. This gets called by the "moving"
+      # Moves the file to the given location. This gets called by the `moving`
       # plugin.
       def move(io, id, shrine_metadata: {}, **upload_options)
         if io.respond_to?(:path)
@@ -173,7 +177,7 @@ class Shrine
         else
           directory.rmtree
           directory.mkpath
-          directory.chmod(permissions) if permissions
+          directory.chmod(directory_permissions) if directory_permissions
         end
       end
 
@@ -203,7 +207,7 @@ class Shrine
 
       # Creates all intermediate directories for that location.
       def path!(id)
-        path(id).dirname.mkpath
+        FileUtils.mkdir_p(path(id).dirname, mode: directory_permissions)
         path(id)
       end
 

data/lib/shrine/storage/s3.rb

@@ -4,8 +4,8 @@ require "uri"
 
 class Shrine
   module Storage
-    # The S3 storage handles uploads to Amazon S3 service, it depends on the
-    # [aws-sdk] gem:
+    # The S3 storage handles uploads to Amazon S3 service, using the [aws-sdk]
+    # gem:
     #
     #     gem "aws-sdk", "~> 2.1"
     #
@@ -56,6 +56,19 @@ class Shrine
     # Note that these aren't applied to presigns, since presigns are generated
     # using the storage directly.
     #
+    # ## URL options
+    #
+    # This storage supports various URL options that will be forwarded from
+    # uploaded file.
+    #
+    #     uploaded_file.url(public: true)   # public URL without signed parameters
+    #     uploaded_file.url(download: true) # forced download URL
+    #
+    # All other options are forwarded to the [aws-sdk] gem:
+    #
+    #     uploaded_file.url(expires_in: 15)
+    #     uploaded_file.urL(virtual_host: true)
+    #
     # ## CDN
     #
     # If you're using a CDN with S3 like Amazon CloudFront, you can specify
@@ -63,6 +76,27 @@ class Shrine
     #
     #     Shrine::Storage::S3.new(host: "http://abc123.cloudfront.net", **s3_options)
     #
+    # ## Presigns
+    #
+    # This storage can generate presigns for direct uploads to Amazon S3, and
+    # it accepts additional options which are passed to [aws-sdk]. There are
+    # three places in which you can specify presign options:
+    #
+    # * in `:upload_options` option on this storage
+    # * in `direct_upload` plugin through `:presign_options`
+    # * in `Storage::S3#presign` by forwarding options
+    #
+    # ## Large files
+    #
+    # The [aws-sdk] gem has the ability to automatically use multipart
+    # upload/copy for larger files, where the file is split into multiple chunks
+    # which are uploaded/copied in parallel.
+    #
+    # By default any files that are larger than 15MB will use this multipart
+    # upload/copy, but you change this threshold:
+    #
+    #     Shrine::Storage::S3.new(multipart_threshold: 30*1024*1024) # 30MB
+    #
     # ## Clearing cache
     #
     # If you're using S3 as a cache, you will probably want to periodically

data/lib/shrine/version.rb

@@ -5,7 +5,7 @@ class Shrine
 
   module VERSION
     MAJOR = 2
-    MINOR = 2
+    MINOR = 3
     TINY  = 0
     PRE   = nil
 

data/shrine.gemspec

@@ -6,15 +6,16 @@ Gem::Specification.new do |gem|
 
   gem.required_ruby_version = ">= 2.1"
 
-  gem.summary      = "Toolkit for handling file uploads in Ruby"
+  gem.summary      = "Toolkit for file attachments in Ruby applications"
   gem.description  = <<-END
-Shrine is a toolkit for handling file uploads in Ruby. It supports uploading,
-processing and deleting IO objects, backed by a storage adapter. It uses
-efficient streaming to minimize memory usage.
-
-Shrine comes with a high-level attachment interface for attaching uploaded
-files to database records, saving their location and metadata to a database
-column, and tying them to record's lifecycle.
+Shrine is a toolkit for file attachments in Ruby applications. It supports
+uploading, downloading, processing and deleting IO objects, backed by various
+storage engines. It uses efficient streaming for low memory usage.
+
+Shrine comes with a high-level interface for attaching uploaded files to
+database records, saving their location and metadata to a database column, and
+tying them to record's lifecycle. It natively supports background jobs and
+direct uploads for fully asynchronous user experience.
   END
 
   gem.homepage     = "https://github.com/janko-m/shrine"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-29 00:00:00.000000000 Z
+date: 2016-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -277,13 +277,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |
-  Shrine is a toolkit for handling file uploads in Ruby. It supports uploading,
-  processing and deleting IO objects, backed by a storage adapter. It uses
-  efficient streaming to minimize memory usage.
+  Shrine is a toolkit for file attachments in Ruby applications. It supports
+  uploading, downloading, processing and deleting IO objects, backed by various
+  storage engines. It uses efficient streaming for low memory usage.
 
-  Shrine comes with a high-level attachment interface for attaching uploaded
-  files to database records, saving their location and metadata to a database
-  column, and tying them to record's lifecycle.
+  Shrine comes with a high-level interface for attaching uploaded files to
+  database records, saving their location and metadata to a database column, and
+  tying them to record's lifecycle. It natively supports background jobs and
+  direct uploads for fully asynchronous user experience.
 email:
 - janko.marohnic@gmail.com
 executables: []
@@ -310,6 +311,7 @@ files:
 - lib/shrine/plugins/backgrounding.rb
 - lib/shrine/plugins/backup.rb
 - lib/shrine/plugins/cached_attachment_data.rb
+- lib/shrine/plugins/copy.rb
 - lib/shrine/plugins/data_uri.rb
 - lib/shrine/plugins/default_storage.rb
 - lib/shrine/plugins/default_url.rb
@@ -371,5 +373,5 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: Toolkit for handling file uploads in Ruby
+summary: Toolkit for file attachments in Ruby applications
 test_files: []