shrine 0.9.0 → 1.0.0

data/lib/shrine/plugins/versions.rb

@@ -1,16 +1,21 @@
 class Shrine
   module Plugins
     # The versions plugin enables your uploader to deal with versions. To
-    # generate versions, you simply return a hash of versions in `Shrine#process`:
+    # generate versions, you simply return a hash of versions in `Shrine#process`.
+    # Here is an example of processing image thumbnails using the
+    # [image_processing] gem:
+    #
+    #     require "image_processing/mini_magick"
     #
     #     class ImageUploader < Shrine
+    #       include ImageProcessing::MiniMagick
     #       plugin :versions, names: [:large, :medium, :small]
     #
     #       def process(io, context)
     #         if context[:phase] == :store
-    #           size_700 = process_to_limit!(io.download, 700, 700)
-    #           size_500 = process_to_limit!(size_700,    500, 500)
-    #           size_300 = process_to_limit!(size_500,    300, 300)
+    #           size_700 = resize_to_limit(io.download, 700, 700)
+    #           size_500 = resize_to_limit(size_700,    500, 500)
+    #           size_300 = resize_to_limit(size_500,    300, 300)
     #
     #           {large: size_700, medium: size_500, small: size_300}
     #         end
@@ -20,13 +25,19 @@ class Shrine
     # Now when you access the attachment through the model, a hash of uploaded
     # files will be returned:
     #
+    #     JSON.parse(user.avatar_data) #=>
+    #     # {
+    #     #   "large"  => {"id" => "lg043.jpg", "storage" => "store", "metadata" => {...}},
+    #     #   "medium" => {"id" => "kd9fk.jpg", "storage" => "store", "metadata" => {...}},
+    #     #   "small"  => {"id" => "932fl.jpg", "storage" => "store", "metadata" => {...}},
+    #     # }
+    #
     #     user.avatar #=>
     #     # {
-    #     #   large:  #<Shrine::UploadedFile>,
-    #     #   medium: #<Shrine::UploadedFile>,
-    #     #   small:  #<Shrine::UploadedFile>,
+    #     #   :large =>  #<Shrine::UploadedFile @data={"id"=>"lg043.jpg", ...}>,
+    #     #   :medium => #<Shrine::UploadedFile @data={"id"=>"kd9fk.jpg", ...}>,
+    #     #   :small =>  #<Shrine::UploadedFile @data={"id"=>"932fl.jpg", ...}>,
     #     # }
-    #     user.avatar.class #=> Hash
     #
     #     # With the store_dimensions plugin
     #     user.avatar[:large].width  #=> 700
@@ -64,7 +75,11 @@ class Shrine
     #
     # When deleting versions, any multi delete capabilities will be leveraged,
     # so when usingStorage::S3, deleting versions will issue only a single HTTP
-    # request.
+    # 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
     module Versions
       def self.load_dependencies(uploader, *)
         uploader.plugin :multi_delete
@@ -86,21 +101,19 @@ class Shrine
 
         # Asserts that the hash doesn't contain any unknown versions.
         def versions!(hash)
-          hash.select do |name, version|
-            version?(name) or raise Error, "unknown version: #{name.inspect}"
-          end
+          hash.select { |name, _| version?(name) or raise Error, "unknown version: #{name.inspect}" }
         end
 
         # Filters the hash to contain only the registered versions.
         def versions(hash)
-          hash.select { |name, version| version?(name) }
+          hash.select { |name, _| version?(name) }
         end
 
         # Converts a hash of data into a hash of versions.
         def uploaded_file(object, &block)
           if object.is_a?(Hash) && !object.key?("storage")
             versions(object).inject({}) do |result, (name, data)|
-              result.update(name.to_sym => super(data, &block))
+              result.update(name.to_sym => uploaded_file(data, &block))
             end
           else
             super
@@ -112,7 +125,7 @@ class Shrine
         # Checks whether all versions are uploaded by this uploader.
         def uploaded?(uploaded_file)
           if (hash = uploaded_file).is_a?(Hash)
-            hash.all? { |name, version| super(version) }
+            hash.all? { |name, version| uploaded?(version) }
           else
             super
           end
@@ -127,7 +140,7 @@ class Shrine
         def _store(io, context)
           if (hash = io).is_a?(Hash)
             self.class.versions!(hash).inject({}) do |result, (name, version)|
-              result.update(name => super(version, version: name, **context))
+              result.update(name => _store(version, version: name, **context))
             end
           else
             super
@@ -138,7 +151,7 @@ class Shrine
         # capabilities.
         def _delete(uploaded_file, context)
           if (versions = uploaded_file).is_a?(Hash)
-            super(versions.values, context)
+            _delete(versions.values, context)
             versions
           else
             super

data/lib/shrine/storage/file_system.rb

@@ -5,29 +5,74 @@ require "pathname"
 
 class Shrine
   module Storage
+    # The FileSystem storage handles uploads to the filesystem, and it is
+    # most commonly initialized with a "base" folder and a "subdirectory":
+    #
+    #     storage = Shrine::Storage::FileSystem.new("public", subdirectory: "uploads")
+    #     storage.url("image.jpg") #=> "/uploads/image.jpg"
+    #
+    # This storage will upload all files to "public/uploads", and the URLs
+    # of the uploaded files will start with "/uploads/*". This way you can
+    # use FileSystem for both cache and store, one having subdirectory
+    # "uploads/cache" and other "uploads/store".
+    #
+    # You can also initialize the storage just with the "base" directory, and
+    # then the FileSystem storage will generate absolute URLs to files:
+    #
+    #     storage = Shrine::Storage::FileSystem.new(Dir.tmpdir)
+    #     storage.url("image.jpg") #=> "/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/image.jpg"
+    #
+    # ## CDN
+    #
+    # It's generally a good idea to serve your files via a CDN, so an
+    # additional `:host` option can be provided:
+    #
+    #     storage = Shrine::Storage::FileSystem.new("public",
+    #       subdirectory: "uploads", host: "//abc123.cloudfront.net")
+    #     storage.url("image.jpg") #=> "//abc123.cloudfront.net/uploads/image.jpg"
+    #
+    # The `:host` option can also be used wihout `:subdirectory`, and is
+    # useful if you for example have files located on another server:
+    #
+    #     storage = Shrine::Storage::FileSystem.new("files", host: "943.23.43.1")
+    #     storage.url("image.jpg") #=> "943.23.43.1/files/image.jpg"
+    #
+    # ## Clearing cache
+    #
+    # If you're using FileSystem as cache, you will probably want to
+    # periodically delete old files which aren't used anymore. You can put
+    # the following in a periodic Rake task:
+    #
+    #     file_system = Shrine.storages[:cache]
+    #     file_system.clear!(older_than: 1.week.ago) # adjust the time
+    #
+    # ## Permissions
+    #
+    # If you want your files and folders to have certain permissions, you can
+    # pass the `:permissions` option:
+    #
+    #     Shrine::Storage::FileSystem.new("directory", permissions: 0755)
     class FileSystem
       attr_reader :directory, :subdirectory, :host, :permissions
 
-      # The `directory` is the root directory where uploaded files will be
-      # stored. In web applications this is typically the "public/" directory,
-      # to make the files available via URL.
+      # Initializes a storage for uploading to the filesystem.
       #
-      # If `:subdirectory` is given, #url will return a URL relative to
-      # `directory` (and include `:subdirectory`). So, `FileSystem.new('public',
-      # subdirectory: 'uploads')` will upload files to "public/uploads", and
-      # URLs will be "/uploads/*".
+      # :subdirectory
+      # :  The directory relative to `directory` to which files will be stored,
+      #    and it is included in the URL.
       #
-      # In applications it's common to serve files over CDN, so an additional
-      # `:host` option can be provided. This option can also be used without
-      # `:subdirectory`, if for example files are located on another server
-      # which requires an IP address.
+      # :host
+      # :  URLs will by default be relative if `:subdirectory` is set, and you
+      #    can use this option to set a CDN host (e.g. `//abc123.cloudfront.net`).
       #
-      # By default FileSystem will clean empty directories when files get
-      # deleted. However, if this puts too much load on the filesystem, it can
-      # be disabled with `clean: false`.
+      # :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`).
       #
-      # Optional folder and file permissions can be set through the
-      # `:permissions` option.
+      # :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, subdirectory: nil, host: nil, clean: true, permissions: nil)
         if subdirectory
           @subdirectory = Pathname(relative(subdirectory))
@@ -131,7 +176,7 @@ class Shrine
 
       # Returns the full path to the file.
       def path(id)
-        directory.join(relative(id))
+        directory.join(id.gsub("/", File::SEPARATOR))
       end
 
       # Cleans all empty subdirectories up the hierarchy.

data/lib/shrine/storage/linter.rb

@@ -47,9 +47,7 @@ class Shrine
           end
         end
 
-        begin
-          Shrine.io!(storage.open("foo.jpg"))
-        rescue Shrine::InvalidFile => error
+        if !io?(storage.open("foo.jpg"))
           error! "#open doesn't return a valid IO object"
         end
 
@@ -75,6 +73,13 @@ class Shrine
 
       private
 
+      def io?(object)
+        missing_methods = IO_METHODS.reject do |m, a|
+          object.respond_to?(m) && [a.count, -1].include?(object.method(m).arity)
+        end
+        missing_methods.empty?
+      end
+
       def error!(message)
         @errors << message
       end

data/lib/shrine/storage/s3.rb

@@ -1,27 +1,64 @@
 require "aws-sdk"
 require "down"
+require "uri"
 
 class Shrine
   module Storage
+    # The S3 storage handles uploads to Amazon S3 service, and it is
+    # initialized with the following 4 required options:
+    #
+    #     Shrine::Storage::S3.new(
+    #       access_key_id: "xyz",
+    #       secret_access_key: "abc",
+    #       region: "eu-west-1",
+    #       bucket: "my-app",
+    #     )
+    #
+    # ## Prefix
+    #
+    # The `:prefix` option can be specified for uploading all files inside
+    # a specific S3 prefix (folder), which is useful when using S3 for both
+    # cache and store:
+    #
+    #     Shrine::Storage::S3.new(prefix: "cache", **s3_options)
+    #     Shrine::Storage::S3.new(prefix: "store", **s3_options)
+    #
+    # ## CDN
+    #
+    # If you're using a CDN with S3 like Amazon CloudFront, you can specify
+    # the `:host` option to have all your URLs use the CDN host:
+    #
+    #     Shrine::Storage::S3.new(host: "//abc123.cloudfront.net", **s3_options)
+    #
+    # ## Clearing cache
+    #
+    # If you're using S3 as a cache, you will probably want to periodically
+    # delete old files which aren't used anymore. S3 has a built-in way to do
+    # this, read [this article](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html)
+    # for instructions.
     class S3
-      attr_reader :prefix, :bucket, :s3
+      attr_reader :prefix, :bucket, :s3, :host
 
-      # Example:
+      # Initializes a storage for uploading to S3.
       #
-      #     Shrine::Storage::S3.new(
-      #       access_key_id: "xyz",
-      #       secret_access_key: "abc",
-      #       region: "eu-west-1"
-      #       bucket: "my-app",
-      #       prefix: "cache",
-      #     )
+      # :access_key_id
+      # :secret_access_key
+      # :region
+      # :bucket
+      # :   Credentials required by the `aws-sdk` gem.
       #
-      # The above storage will store file into the "my-app" bucket in the
-      # "cache" directory.
-      def initialize(bucket:, prefix: nil, **s3_options)
+      # :prefix
+      # :   "Folder" name inside the bucket to store files into.
+      #
+      # :host
+      # :   This option is used for setting CDNs, e.g. it can be set to `//abc123.cloudfront.net`.
+      #
+      # All other options are forwarded to [`Aws::S3::Client#initialize`](http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html#initialize-instance_method).
+      def initialize(bucket:, prefix: nil, host: nil, **s3_options)
         @prefix = prefix
-        @s3 = Aws::S3::Resource.new(s3_options)
+        @s3 = Aws::S3::Resource.new(**s3_options)
         @bucket = @s3.bucket(bucket)
+        @host = host
       end
 
       # If the file is an UploadedFile from S3, issues a COPY command, otherwise
@@ -68,20 +105,47 @@ class Shrine
       # This is called when multiple files are being deleted at once. Issues
       # a single MULTI DELETE command.
       def multi_delete(ids)
-        bucket.delete_objects(delete: {objects: ids.map { |id| {key: id} }})
+        objects = ids.map { |id| {key: object(id).key} }
+        bucket.delete_objects(delete: {objects: objects})
       end
 
-      # Returns the presigned URL to the file. If `download: true` is passed,
-      # returns a forced download link.
-      def url(id, download: nil, **options)
-        options[:response_content_disposition] = "attachment" if download
-        object(id).presigned_url(:get, **options)
+      # Returns the presigned URL to the file.
+      #
+      # :download
+      # :  If set to `true`, creates a "forced download" link, which means that
+      #    the browser will never display the file and always ask the user to
+      #    download it.
+      #
+      # :public
+      # :  Creates an unsigned version of the URL (requires setting appropriate
+      #    permissions on the S3 bucket).
+      #
+      # options
+      # :  All other optione are forwarded to 
+      # If `download: true` is passed,
+      # returns a forced download link. If `public: true` is passed, it returns
+      # an unsigned S3 URL. All other options are forwarded to
+      # [`Aws::S3::Object#presigned_url`], so take a look there for the
+      # complete list of additional options.
+      #
+      # [`Aws::S3::Object#presigned_url`]: http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Object.html#presigned_url-instance_method
+      def url(id, download: nil, public: nil, **options)
+        if host.nil?
+          options[:response_content_disposition] = "attachment" if download
+          if public.nil?
+            object(id).presigned_url(:get, **options)
+          else
+            object(id).public_url(**options)
+          end
+        else
+          URI.join(host, object(id).key).to_s
+        end
       end
 
       # Deletes all files from the storage (requires confirmation).
       def clear!(confirm = nil)
         raise Shrine::Confirm unless confirm == :confirm
-        @bucket.clear!
+        @bucket.object_versions(prefix: prefix).delete
       end
 
       # Returns a signature for direct uploads. Internally it calls

data/lib/shrine/version.rb

@@ -4,8 +4,8 @@ class Shrine
   end
 
   module VERSION
-    MAJOR = 0
-    MINOR = 9
+    MAJOR = 1
+    MINOR = 0
     TINY  = 0
     PRE   = nil
 

data/shrine.gemspec

@@ -16,8 +16,9 @@ Gem::Specification.new do |gem|
   gem.files        = Dir["README.md", "LICENSE.txt", "lib/**/*.rb", "shrine.gemspec", "doc/*.md"]
   gem.require_path = "lib"
 
-  gem.add_dependency "down", ">= 1.0.2"
+  gem.add_dependency "down", ">= 1.0.3"
 
+  gem.add_development_dependency "rake"
   gem.add_development_dependency "minitest", "~> 5.8"
   gem.add_development_dependency "minitest-hooks", "~> 1.3.0"
   gem.add_development_dependency "mocha"
@@ -27,20 +28,22 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "dotenv"
 
   gem.add_development_dependency "roda"
-  gem.add_development_dependency "ruby-filemagic", "~> 0.7" unless RUBY_ENGINE == "jruby"
   gem.add_development_dependency "mimemagic"
   gem.add_development_dependency "mime-types"
   gem.add_development_dependency "fastimage"
   gem.add_development_dependency "thread", "~> 0.2"
-  gem.add_development_dependency "aws-sdk", "~> 2.1"
-  gem.add_development_dependency "image_processing", ">= 0.2.4"
-  gem.add_development_dependency "mini_magick", ">= 4.3.5"
+  gem.add_development_dependency "aws-sdk", "~> 2.1.30"
+
+  unless RUBY_ENGINE == "jruby" || ENV["CI"]
+    gem.add_development_dependency "ruby-filemagic", "~> 0.7"
+  end
 
   gem.add_development_dependency "sequel"
   gem.add_development_dependency "activerecord"
-  unless RUBY_ENGINE == "jruby"
-    gem.add_development_dependency "sqlite3"
-  else
+
+  if RUBY_ENGINE == "jruby"
     gem.add_development_dependency "activerecord-jdbcsqlite3-adapter"
+  else
+    gem.add_development_dependency "sqlite3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-25 00:00:00.000000000 Z
+date: 2015-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -16,14 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 1.0.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 1.0.3
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -136,20 +150,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: ruby-filemagic
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: mimemagic
   requirement: !ruby/object:Gem::Requirement
@@ -212,42 +212,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.1.30
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
-- !ruby/object:Gem::Dependency
-  name: image_processing
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.4
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 2.1.30
 - !ruby/object:Gem::Dependency
-  name: mini_magick
+  name: ruby-filemagic
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.3.5
+        version: '0.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.3.5
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
@@ -299,10 +285,12 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- doc/carrierwave.md
 - doc/creating_plugins.md
 - doc/creating_storages.md
 - doc/direct_s3.md
 - doc/migrating_storage.md
+- doc/paperclip.md
 - doc/regenerating_versions.md
 - lib/shrine.rb
 - lib/shrine/plugins/activerecord.rb
@@ -310,7 +298,7 @@ files:
 - lib/shrine/plugins/cached_attachment_data.rb
 - lib/shrine/plugins/data_uri.rb
 - lib/shrine/plugins/default_storage.rb
-- lib/shrine/plugins/delete_invalid.rb
+- lib/shrine/plugins/default_url_options.rb
 - lib/shrine/plugins/determine_mime_type.rb
 - lib/shrine/plugins/direct_upload.rb
 - lib/shrine/plugins/dynamic_storage.rb
@@ -319,10 +307,13 @@ files:
 - lib/shrine/plugins/keep_files.rb
 - lib/shrine/plugins/logging.rb
 - lib/shrine/plugins/migration_helpers.rb
+- lib/shrine/plugins/module_include.rb
 - lib/shrine/plugins/moving.rb
 - lib/shrine/plugins/multi_delete.rb
 - lib/shrine/plugins/parallelize.rb
+- lib/shrine/plugins/parsed_json.rb
 - lib/shrine/plugins/pretty_location.rb
+- lib/shrine/plugins/rack_file.rb
 - lib/shrine/plugins/recache.rb
 - lib/shrine/plugins/remote_url.rb
 - lib/shrine/plugins/remove_attachment.rb