shrine 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 685289a1b672f363582842cdb2109c4197f9e735
-  data.tar.gz: 37a64e5704dcc6125074dc2333ecf570ba5eaede
+  metadata.gz: d59731ea1e8a0376a6f8ad86e8d627250dec2f44
+  data.tar.gz: 14bd2696930a028e157cc1535995a5342958170b
 SHA512:
-  metadata.gz: 15150fb3c6d90f397c6e35f714b4eeed02d9c30ee8497fc9763f689b7e7732612e96a896c9d912cf04161a564e5196e73ba20f87df8d489d1562ffe4381dcf7b
-  data.tar.gz: eb4f056cf14cbacb40ee272008c08623e72767965b808d376f4880b83088a0bd57a20282ac7eb05138aea6dc6c0eae9d3c75c16b8bb8faae940816ee1d079fdc
+  metadata.gz: a0ca4170b242be2e01fa6abdeb9ff0e3380e1271c0783099e738182e4d6f995ac7b8042884c52147052a751b6a7143eb16766879165c87f221ed6e84b7deb53a
+  data.tar.gz: 6aee5bb9a3a44f162c9d2da791c498c2d592a05aa3efc7bf058d38def80040af8856db96431eb558ed93538cc327f718874f59a376e3b55e11778189c87401be

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Janko Marohnić
+Copyright (c) 2015-2016 Janko Marohnić
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -18,7 +18,7 @@ explains the motivation behind Shrine.
 gem "shrine"
 ```
 
-Shrine has been tested on MRI 2.1, MRI 2.2, JRuby and Rubinius.
+Shrine has been tested on MRI 2.1, MRI 2.2, MRI 2.3, JRuby and Rubinius.
 
 ## Basics
 
@@ -47,8 +47,8 @@ First we add the storage we want to use to Shrine's registry. Storages are
 simple Ruby classes which perform the actual uploads. We instantiate a `Shrine`
 with the storage name, and when we call `#upload` Shrine does the following:
 
-* generates a unique location for the file
 * extracts metadata from the file
+* generates a unique location for the file
 * uploads the file using the underlying storage
 * closes the file
 * returns a `Shrine::UploadedFile` with relevant data
@@ -78,8 +78,8 @@ To read about the metadata that is stored with the uploaded file, see the
 ## Attachment
 
 In web applications, instead of managing files directly, we rather want to
-treat them as "attachments" to recod tie them to their lifecycle. In Shrine we
-do this by generating and including "attachment" modules.
+treat them as "attachments" to records and tie them to their lifecycle. In
+Shrine we do this by generating and including "attachment" modules.
 
 Firstly we need to assign the special `:cache` and `:store` storages:
 
@@ -245,7 +245,8 @@ assigned and saved, an "upload" actually happens two times. First the file is
 "uploaded" to cache on assignment, and then the cached file is reuploaded to
 store on save. You could theoretically do processing in both phases, depending
 on your preferences (although it's generally not recommended to process on
-caching).
+caching, because it happens before file validations; use the `recache` plugin
+instead).
 
 Ok, now how do we do the actual processing? Well, Shrine actually doesn't ship
 with any file processing functionality, because that is a generic problem that
@@ -477,9 +478,11 @@ end
 
 Note that there should always be a random component in the location, otherwise
 dirty tracking won't be detected properly (you can use `Shrine#generate_uid`).
+Also note that you can access the extracted metadata here through
+`context[:metadata]`.
 
-When using `Shrine` directly you can bypass `#generate_location` by passing in
-`:location`
+When using the uploader directly, it's possible to bypass `#generate_location`
+by passing in `:location`:
 
 ```rb
 file = File.open("avatar.jpg")
@@ -527,7 +530,7 @@ and for FileSystem you can put something like this in your Rake task:
 
 ```rb
 file_system = Shrine.storages[:cache]
-file_system.clear!(older_than: 1.week.ago) # adjust the time
+file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
 ```
 
 ## Background jobs
@@ -569,7 +572,7 @@ libraries are:
 * **User experience** – After starting the background job, Shrine will save the
   record with the cached attachment so that it can be immediately shown to the
   user. With other file upload libraries users cannot see the file until the
-  background job has finished, which is really lame.
+  background job has finished.
 * **Simplicity** – Instead of writing the workers for you, Shrine allows you
   to use your own workers in a very simple way. Also, no extra columns are
   required.

data/doc/carrierwave.md

@@ -1,24 +1,24 @@
 # Shrine for CarrierWave Users
 
-This guide is aimed at helping CarrierWave users transition to Shrine. We will
-first generally mention what are the key differences. Afterwards there is an
-extensive reference of CarrierWave's interface and what is the equivalent in
-Shrine.
+This guide is aimed at helping CarrierWave users transition to Shrine. First it
+explains some key differences in the design between the two libraries.
+Afterwards it explains how you can transition an existing app that uses
+CarrierWave to Shrine. It then finishes off with an extensive reference of
+CarrierWave's interface and what is the equivalent in Shrine.
 
 ## Uploaders
 
-Shrine has a concept of uploaders similar to CarrierWave's, but instead of
-inheriting from `CarrierWave::Uploader::Base`, you inherit from `Shrine`
-directly:
+Shrine has a concept of uploaders similar to CarrierWave's, which allows you to
+have different uploading logic for different types of files:
 
 ```rb
 class ImageUploader < Shrine
-  # ...
+  # uploading logic
 end
 ```
 
 While in CarrierWave you choose a storages for uploaders directly, in Shrine
-you first register storages globally (under a symbol name), and then you
+you first register storages globally (under a symbol name), and then you can
 instantiate uploaders with a specific storage.
 
 ```rb
@@ -35,15 +35,15 @@ store_uploader = Shrine.new(:store)
 ```
 
 CarrierWave uses symbols for referencing storages (`:file`, `:fog`, ...), but
-in Shrine you instantiate storages directly. This makes storages much more
-flexible, because this way they can have their own options that are specific to
-them.
+in Shrine storages are simple Ruby classes which you can instantiate directly.
+This makes storages much more flexible, because this way they can have their
+own options that are specific to them.
 
 ### Processing
 
-In Shrine processing is done instance-level in the `#process` method. To
-generate versions, you simply return a hash, and also load the `versions`
-plugin to make your uploader recognize versions:
+In Shrine processing is done instance-level in the `#process` method, and can
+be specified for each phase. You can return a single processed file or a hash of
+versions (with the `versions` plugin):
 
 ```rb
 require "image_processing/mini_magick" # part of the "image_processing" gem
@@ -73,7 +73,7 @@ Shrine.plugin :activerecord # If you're using ActiveRecord
 ```
 
 Instead of giving you class methods for "mounting" uploaders, in Shrine you
-generate "attachment modules" which you include in your models:
+generate attachment modules which you simply include in your models:
 
 ```rb
 class User < Sequel::Model
@@ -82,8 +82,8 @@ end
 ```
 
 You models are required to have the `<attachment>_data` column, in the above
-case `avatar_data`. It contains the storage and location of the file, as well
-as additional metadata.
+case `avatar_data`. Shrine stores storage, location, and additional metadata of
+the uploaded file to that column.
 
 ### Multiple uploads
 
@@ -94,6 +94,99 @@ you're using, and it's analogous to how you would implement adding items to any
 dynamic one-to-many relationship. Take a look at the [example app] which
 demonstrates how easy it is to implement multiple uploads.
 
+## Migrating from CarrierWave
+
+You have an existing app using CarrierWave and you want to transfer it to
+Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
+we need to create the `image_data` column for Shrine:
+
+```rb
+add_column :photos, :image_data, :text
+```
+
+Afterwards we need to make new uploads write to the `image_data` column. This
+can be done by including the below module to all models that have CarrierWave
+attachments:
+
+```rb
+require "fastimage"
+
+module CarrierwaveShrineSynchronization
+  def self.included(model)
+    model.before_save do
+      self.class.uploaders.each_key do |name|
+        write_shrine_data(name) if changes.key?(name)
+      end
+    end
+  end
+
+  def write_shrine_data(name)
+    uploader = send(name)
+
+    if read_attribute(name).present?
+      data = uploader_to_shrine_data(uploader)
+
+      if uploader.versions.any?
+        data = {original: data}
+        uploader.versions.each do |name, version|
+          data[name] = uploader_to_shrine_data(version)
+        end
+      end
+
+      write_attribute(:"#{name}_data", data.to_json)
+    else
+      write_attribute(:"#{name}_data", nil)
+    end
+  end
+
+  private
+
+  # If you'll be using `:prefix` on your Shrine storage, make sure to
+  # subtract it from the path assigned as `:id`.
+  def uploader_to_shrine_data(uploader)
+    path = uploader.store_path(read_attribute(uploader.mounted_as))
+
+    size   = uploader.file.size if changes.key?(uploader.mounted_as)
+    size ||= FastImage.new(uploader.url).content_length
+    size ||= File.size(File.join(uploader.root, path))
+    filename = File.basename(path)
+    mime_type = MIME::Types.type_for(path).first.to_s.presence
+
+    {
+      storage: :store,
+      id: path,
+      metadata: {
+        size: size,
+        filename: filename,
+        mime_type: mime_type,
+      },
+    }
+  end
+end
+```
+```rb
+class Photo < ActiveRecord::Base
+  mount_uploader :image, ImageUploader
+  include CarrierwaveShrineSynchronization # needs to be after `mount_uploader`
+end
+```
+
+After you deploy this code, the `image_data` column should now be successfully
+synchronized with new attachments.  Next step is to run a script which writes
+all existing CarrierWave attachments to `image_data`:
+
+```rb
+Photo.find_each do |photo|
+  Photo.uploaders.each_key { |name| photo.write_shrine_data(name) }
+  photo.save!
+end
+```
+
+Now you should be able to rewrite your application so that it uses Shrine
+instead of CarrierWave, using equivalent Shrine storages. For help with
+translating the code from CarrierWave to Shrine, you can consult the reference
+below.
+
 ## CarrierWave to Shrine direct mapping
 
 ### `CarrierWave::Uploader::Base`
@@ -107,7 +200,6 @@ plugin:
 ```rb
 Shrine.storages[:foo] = Shrine::Storage::Foo.new(*args)
 ```
-
 ```rb
 class ImageUploader
   plugin :default_storage, store: :foo

data/doc/changing_location.md

@@ -4,26 +4,12 @@ You have a production app with already uploaded attachments. However, you've
 realized that the existing store folder structure for attachments isn't working
 for you.
 
-The first step is to change the location, either by using the `pretty_location`
-plugin:
+The first step is to change the location (by overriding `#generate_location` or
+with the pretty_location plugin), and deploy that change. Attachments on old
+locations will still continue to work properly.
 
-```rb
-Shrine.plugin :pretty_location
-```
-
-Or by overriding `#generate_location`:
-
-```rb
-class MyUploader < Shrine
-  def generate_location(io, context)
-    "#{context[:record].class}/#{context[:record].id}/#{io.original_filename}"
-  end
-end
-```
-
-After you've deployed this change, all existing attachments on old locations
-will continue to work properly. The next step is to run a script that will
-move those to new locations. The easiest way to do that is to reupload them:
+The next step is to run a script that will move those to new locations. The
+easiest way to do that is to reupload them, and afterwards delete them:
 
 ```rb
 Shrine.plugin :migration_helpers # before the model is loaded

data/doc/creating_storages.md

@@ -69,10 +69,31 @@ def upload(io, id, metadata = {})
 end
 ```
 
+## Updating
+
+If your storage supports updating data of existing files (e.g. some metadata),
+the convention is to create an `#update` method:
+
+```rb
+class Shrine
+  module Storage
+    class MyStorage
+      # ...
+
+      def update(id, options = {})
+        # update data of the file
+      end
+
+      # ...
+    end
+  end
+end
+```
+
 ## Streaming
 
 If your storage can stream files by yielding chunks, you can add an additional
-`#stream` method:
+`#stream` method (used by the `download_endpoint` plugin):
 
 ```rb
 class Shrine

data/doc/direct_s3.md

@@ -39,7 +39,7 @@ Shrine's JSON representation of an uploaded file looks like this:
   "id": "349234854924394", # requied
   "storage": "cache", # required
   "metadata": {
-    "size": 45461, # required
+    "size": 45461, # optional
     "filename": "foo.jpg", # optional
     "mime_type": "image/jpeg", # optional
   }
@@ -141,10 +141,8 @@ include the object key as a query param:
 <%
   cached_file = {
     storage: "cache",
-    id: params[:key][/cache\/(.+)/, 1], # we have to remove the prefix part,
-    metadata: {
-      size: Shrine.storages[:cache].bucket.object(params[:key]).size,
-    }
+    id: params[:key][/cache\/(.+)/, 1], # we have to remove the prefix part
+    metadata: {},
   }
 %>
 

data/doc/paperclip.md

@@ -103,10 +103,9 @@ class User < Sequel::Model
 end
 ```
 
-Unlike in Paperclip which requires you to have `<attachment>_file_name`,
-`<attachment>_file_size`, `<attachment>_content_type` and
-`<attachment>_updated_at` columns, in Shrine you only need to have an
-`<attachment>_data` text column, and all information will be stored there.
+Unlike in Paperclip which requires you to have 4 `<attachment>_*` columns, in
+Shrine you only need to have an `<attachment>_data` text column, and all
+information will be stored there (in the above case `avatar_data`).
 
 The attachments use `:store` for storing the files, and `:cache` for caching.
 The latter is something Paperclip doesn't do, but caching before storing is
@@ -179,6 +178,120 @@ class ImageUploader < Shrine
 end
 ```
 
+## Migrating from Paperclip
+
+You have an existing app using Paperclip and you want to transfer it to Shrine.
+First we need to make new uploads write to the `<attachment>_data` column.
+Let's assume we have a `Photo` model with the "image" attachment:
+
+```rb
+add_column :photos, :image_data, :text
+```
+
+Afterwards we need to make new uploads write to the `image_data` column. This
+can be done by including the below module to all models that have Paperclip
+attachments:
+
+```rb
+require "fastimage"
+
+module PaperclipShrineSynchronization
+  def self.included(model)
+    model.before_save do
+      Paperclip::AttachmentRegistry.each_definition do |klass, name, options|
+        write_shrine_data(name) if changes.key?(:"#{name}_file_name") && klass == self.class
+      end
+    end
+  end
+
+  def write_shrine_data(name)
+    attachment = send(name)
+
+    if attachment.size.present?
+      data = attachment_to_shrine_data(attachment)
+
+      if attachment.styles.any?
+        data = {original: data}
+        attachment.styles.each do |name, style|
+          data[name] = style_to_shrine_data(style)
+        end
+      end
+
+      write_attribute(:"#{name}_data", data.to_json)
+    else
+      write_attribute(:"#{name}_data", nil)
+    end
+  end
+
+  private
+
+  # If you'll be using a `:prefix` on your Shrine storage, or you're storing
+  # files on the filesystem, make sure to subtract the appropriate part
+  # from the path assigned to `:id`.
+  def attachment_to_shrine_data(attachment)
+    {
+      storage: :store,
+      id: attachment.path,
+      metadata: {
+        size: attachment.size,
+        filename: attachment.original_filename,
+        content_type: attachment.content_type,
+      },
+    }
+  end
+
+  # If you'll be using a `:prefix` on your Shrine storage, or you're storing
+  # files on the filesystem, make sure to subtract the appropriate part
+  # from the path assigned to `:id`.
+  def style_to_shrine_data(style)
+    attachment = style.attachment
+    path = attachment.path(style.name)
+    url = attachment.url(style.name)
+    file = attachment.instance_variable_get("@queued_for_write")[style.name]
+
+    size   = file.size if file
+    size ||= FastImage.new(url).content_length
+    size ||= File.size(path)
+    filename = File.basename(path)
+    mime_type = MIME::Types.type_for(path).first.to_s.presence
+
+    {
+      storage: :store,
+      id: path,
+      metadata: {
+        size: size,
+        filename: filename,
+        mime_type: mime_type,
+      }
+    }
+  end
+end
+```
+```rb
+class Photo < ActiveRecord::Base
+  has_attached_file :image
+  include PaperclipShrineSynchronization # needs to be after `has_attached_file`
+end
+```
+
+After you deploy this code, the `image_data` column should now be successfully
+synchronized with new attachments.  Next step is to run a script which writes
+all existing CarrierWave attachments to `image_data`:
+
+```rb
+Photo.find_each do |photo|
+  Paperclip::AttachmentRegistry.each_definition do |klass, name, options|
+    photo.write_shrine_data(name) if klass == Photo
+  end
+  photo.save!
+end
+```
+
+Now you should be able to rewrite your application so that it uses Shrine
+instead of Paperclip, using equivalent Shrine storages. For help with
+translating the code from Paperclip to Shrine, you can consult the reference
+below.
+
 ## Paperclip to Shrine direct mapping
 
 ### `has_attached_file`

data/doc/refile.md

@@ -188,6 +188,67 @@ Shrine doesn't have a built-in solution for accepting multiple uploads, but
 it's actually very easy to do manually, see the [example app] on how you can do
 multiple uploads directly to S3.
 
+## Migrating from Refile
+
+You have an existing app using Refile and you want to transfer it to
+Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
+we need to create the `image_data` column for Shrine:
+
+```rb
+add_column :photos, :image_data, :text
+```
+
+Afterwards we need to make new uploads write to the `image_data` column. This
+can be done by including the below module to all models that have Refile
+attachments:
+
+```rb
+module RefileShrineSynchronization
+  def write_shrine_data(name)
+    if read_attribute("#{name}_id").present?
+      data = {
+        storage: :store,
+        id: send("#{name}_id"),
+        metadata: {
+          size: (send("#{name}_size") if respond_to?("#{name}_size")),
+          filename: (send("#{name}_filename") if respond_to?("#{name}_filename")),
+          mime_type: (send("#{name}_content_type") if respond_to?("#{name}_content_type")),
+        }
+      }
+
+      write_attribute(:"#{name}_data", data.to_json)
+    else
+      write_attribute(:"#{name}_data", nil)
+    end
+  end
+end
+```
+```rb
+class Photo < ActiveRecord::Base
+  attachment :image
+  include RefileShrineSynchronization
+
+  before_save do
+    write_shrine_data(:image) if changes.key?(:image_id)
+  end
+end
+```
+
+After you deploy this code, the `image_data` column should now be successfully
+synchronized with new attachments.  Next step is to run a script which writes
+all existing Refile attachments to `image_data`:
+
+```rb
+Photo.find_each do |photo|
+  photo.write_shrine_data(:image)
+  photo.save!
+end
+```
+
+Now you should be able to rewrite your application so that it uses Shrine
+instead of Refile, using equivalent Shrine storages. For help with translating
+the code from Refile to Shrine, you can consult the reference below.
+
 ## Refile to Shrine direct mapping
 
 ### `Refile`

data/lib/shrine.rb

@@ -258,10 +258,11 @@ class Shrine
         # Generates a unique location for the uploaded file, and preserves an
         # optional extension.
         def generate_location(io, context = {})
-          extension = File.extname(extract_filename(io).to_s)
+          extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
+          extension ||= File.extname(extract_filename(io).to_s)
           basename  = generate_uid(io)
 
-          basename + extension
+          basename + extension.to_s
         end
 
         # Extracts filename, size and MIME type from the file, which is later
@@ -310,15 +311,15 @@ class Shrine
         # the metadata, stores the file, and returns a Shrine::UploadedFile.
         def _store(io, context)
           _enforce_io(io)
-          context[:location] ||= get_location(io, context)
-          context[:metadata] ||= get_metadata(io, context)
+          metadata = get_metadata(io, context)
+          location = get_location(io, context.merge(metadata: metadata))
 
-          put(io, context)
+          put(io, context.merge(location: location, metadata: metadata))
 
           self.class::UploadedFile.new(
-            "id"       => context[:location],
+            "id"       => location,
             "storage"  => storage_key.to_s,
-            "metadata" => context[:metadata],
+            "metadata" => metadata,
           )
         end
 
@@ -352,7 +353,7 @@ class Shrine
         # Retrieves the location for the given io and context. First it looks
         # for the `:location` option, otherwise it calls #generate_location.
         def get_location(io, context)
-          generate_location(io, context)
+          context[:location] || generate_location(io, context)
         end
 
         # Copies the metadata over from an UploadedFile or calls
@@ -527,7 +528,7 @@ class Shrine
         # stored file.
         def promote(cached_file)
           stored_file = store!(cached_file, phase: :store)
-          (result = swap(stored_file)) or delete!(stored_file, phase: :stored)
+          result = swap(stored_file) or delete!(stored_file, phase: :stored)
           result
         end
 
@@ -562,6 +563,7 @@ class Shrine
           instance_exec(&validate_block) if validate_block && get
         end
 
+        # Delegates to `Shrine.uploaded_file`.
         def uploaded_file(*args, &block)
           shrine_class.uploaded_file(*args, &block)
         end
@@ -585,7 +587,7 @@ class Shrine
           uploaded_file && cache.uploaded?(uploaded_file)
         end
 
-        # Alias to #update, overriden in ORM plugins.
+        # Calls #update, overriden in ORM plugins.
         def swap(uploaded_file)
           update(uploaded_file)
           uploaded_file
@@ -642,7 +644,7 @@ class Shrine
         # The context that's sent to Shrine on upload and delete. It holds the
         # record and the name of the attachment.
         def context
-          @context ||= {name: name, record: record}
+          {name: name, record: record}
         end
       end
 
@@ -659,46 +661,50 @@ class Shrine
       end
 
       module FileMethods
-        # The ID of the uploaded file, which holds the location of the actual
-        # file on the storage
-        attr_reader :id
-
-        # The storage key as a string.
-        attr_reader :storage_key
-
-        # A hash of metadata, returned from `Shrine#extract_metadata`.
-        attr_reader :metadata
-
         # The entire data hash which identifies this uploaded file.
         attr_reader :data
 
         def initialize(data)
-          @data        = data
-          @id          = data.fetch("id")
-          @storage_key = data.fetch("storage")
-          @metadata    = data.fetch("metadata")
-
+          @data = data
+          @data["metadata"] ||= {}
           storage # ensure storage exists
         end
 
+        # The ID of the uploaded file, which holds the location of the actual
+        # file on the storage
+        def id
+          @data.fetch("id")
+        end
+
+        # The storage key as a string.
+        def storage_key
+          @data.fetch("storage")
+        end
+
+        # A hash of metadata.
+        def metadata
+          @data.fetch("metadata")
+        end
+
         # The filename that was extracted from the original file.
         def original_filename
-          metadata.fetch("filename")
+          metadata["filename"]
         end
 
-        # The extension derived from `#original_filename`.
+        # The extension derived from #id if present, otherwise from
+        # #original_filename.
         def extension
           File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
         end
 
         # The filesize of the original file.
         def size
-          Integer(metadata.fetch("size"))
+          Integer(metadata["size"]) if metadata["size"]
         end
 
         # The MIME type of the original file.
         def mime_type
-          metadata.fetch("mime_type")
+          metadata["mime_type"]
         end
         alias content_type mime_type
 
@@ -717,8 +723,10 @@ class Shrine
         # Part of Shrine::UploadedFile's complying to the IO interface.  It
         # delegates to the internally downloaded file.
         def close
-          io.close
-          io.delete if io.class.name == "Tempfile"
+          if @io
+            io.close
+            io.delete if io.class.name == "Tempfile"
+          end
         end
 
         # Part of Shrine::UploadedFile's complying to the IO interface.  It
@@ -783,12 +791,12 @@ class Shrine
 
         # The instance of `Shrine` with the corresponding storage.
         def uploader
-          @uploader ||= shrine_class.new(storage_key)
+          shrine_class.new(storage_key)
         end
 
         # The storage class this file was uploaded to.
         def storage
-          uploader.storage
+          shrine_class.find_storage(storage_key)
         end
 
         # Returns the Shrine class related to this uploaded file.

data/lib/shrine/plugins/activerecord.rb

@@ -28,9 +28,9 @@ class Shrine
     # If you want to put some parts of this lifecycle into a background job, see
     # the backgrounding plugin.
     #
-    # Additionally, any Shrine validation errors will added to ActiveRecord's
-    # errors upon validation. Note that if you want to validate presence of the
-    # attachment, you can do it directly on the model.
+    # Additionally, any Shrine validation errors will be added to
+    # ActiveRecord's errors upon validation. If you want to validate presence
+    # of the attachment, you can do it directly on the model.
     #
     #     class User < ActiveRecord::Base
     #       include ImageUploader[:avatar]
@@ -80,7 +80,7 @@ class Shrine
             break if record.send("#{name}_data") != record.reload.send("#{name}_data")
             super
           end
-        rescue ActiveRecord::RecordNotFound
+        rescue ::ActiveRecord::RecordNotFound
         end
 
         # We save the record after updating, raising any validation errors.

data/lib/shrine/plugins/backup.rb

@@ -30,20 +30,25 @@ class Shrine
 
       module AttacherMethods
         def backup_file(uploaded_file)
-          uploaded_file(uploaded_file) { |f| f.data["storage"] = backup_storage.to_s }
-          uploaded_file(uploaded_file.to_json)
+          uploaded_file(uploaded_file.to_json) do |file|
+            file.data["storage"] = backup_storage.to_s
+          end
         end
 
         private
 
         # Back up the stored file and return it.
         def store!(io, phase:)
-          super.tap { |stored_file| store_backup!(stored_file) }
+          stored_file = super
+          store_backup!(stored_file)
+          stored_file
         end
 
         # Delete the backed up file unless `:delete` was set to false.
         def delete!(uploaded_file, phase:)
-          super.tap { |deleted_file| delete_backup!(deleted_file) if backup_delete? }
+          deleted_file = super
+          delete_backup!(deleted_file) if backup_delete?
+          deleted_file
         end
 
         # Upload the stored file to the backup storage.

data/lib/shrine/plugins/data_uri.rb

@@ -74,7 +74,7 @@ class Shrine
           else
             message = shrine_class.opts[:data_uri_error_message]
             message = message.call(uri) if message.respond_to?(:call)
-            errors << message
+            errors.replace [message]
             @data_uri = uri
           end
         end

data/lib/shrine/plugins/default_url.rb

@@ -23,7 +23,7 @@ class Shrine
         private
 
         def default_url(**options)
-          default_url_block.call(options.merge(context))
+          default_url_block.call(context.merge(options){|k,old,new|old})
         end
 
         def default_url_block

data/lib/shrine/plugins/determine_mime_type.rb

@@ -107,13 +107,16 @@ class Shrine
         # Uses the ruby-filemagic gem to magically extract the MIME type.
         def _extract_mime_type_with_filemagic(io)
           filemagic = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
-          data = io.read(MAGIC_NUMBER); io.rewind
+          data = io.read(MAGIC_NUMBER)
+          io.rewind
           filemagic.buffer(data)
         end
 
         # Uses the mimemagic gem to extract the MIME type.
         def _extract_mime_type_with_mimemagic(io)
-          MimeMagic.by_magic(io).type
+          result = MimeMagic.by_magic(io).type
+          io.rewind
+          result
         end
 
         # Uses the mime-types gem to determine MIME type from file extension.

data/lib/shrine/plugins/direct_upload.rb

@@ -55,9 +55,9 @@ class Shrine
     #
     #     plugin :direct_upload, presign: true
     #
-    # This will disable the default `POST /:storage/:name` route (for security
-    # reasons), and enable `GET /:storage/presign`. The response for that
-    # request looks something like this:
+    # This will add `GET /:storage/presign`, and disable the default `POST
+    # /:storage/:name` (for security reasons) The response for that request
+    # looks something like this:
     #
     #     {
     #       "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",

data/lib/shrine/plugins/keep_location.rb

@@ -1,3 +1,6 @@
+warn "The keep_location Shrine plugin is deprecated and will be removed in Shrine 2. " \
+     "You can easily implement the same behaviour in Shrine#generate_location."
+
 class Shrine
   module Plugins
     # The keep_location plugin allows you to preserve locations when
@@ -22,7 +25,7 @@ class Shrine
         private
 
         def get_location(io, context)
-          if io.is_a?(UploadedFile) && keep_location?(io)
+          if !context[:location] && io.is_a?(UploadedFile) && keep_location?(io)
             io.id
           else
             super

data/lib/shrine/plugins/migration_helpers.rb

@@ -5,6 +5,8 @@ class Shrine
     #
     #     plugin :migration_helpers
     #
+    # ## `<attachment>_cache` and `<attachment>_store`
+    #
     # If your attachment's name is "avatar", the model will get `#avatar_cache`
     # and `#avatar_store` methods.
     #
@@ -12,6 +14,16 @@ class Shrine
     #     user.avatar_cache #=> #<Shrine @storage_key=:cache @storage=#<Shrine::Storage::FileSystem @directory=public/uploads>>
     #     user.avatar_store #=> #<Shrine @storage_key=:store @storage=#<Shrine::Storage::S3:0x007fb8343397c8 @bucket=#<Aws::S3::Bucket name="foo">>>
     #
+    # ## `<attachment>_cached?` and `<attachment>_stored?`
+    #
+    # You can use these methods to check whether attachment exists and is
+    # cached/stored:
+    #
+    #     user.avatar_cached? # user.avatar && user.avatar_cache.uploaded?(user.avatar)
+    #     user.avatar_stored? # user.avatar && user.avatar_store.uploaded?(user.avatar)
+    #
+    # ## `update_<attachment>`
+    #
     # The model will also get `#update_avatar` method, which can be used when
     # doing attachment migrations. It will update the record's attachment with
     # the result of the passed in block.
@@ -41,6 +53,14 @@ class Shrine
             def #{name}_store
               #{name}_attacher.store
             end
+
+            def #{name}_cached?
+              #{name}_attacher.cached?
+            end
+
+            def #{name}_stored?
+              #{name}_attacher.stored?
+            end
           RUBY
         end
       end
@@ -53,6 +73,18 @@ class Shrine
           new_attachment = block.call(get)
           swap(new_attachment)
         end
+
+        # Returns true if the attachment is present and is uploaded by the
+        # temporary storage.
+        def cached?
+          get && cache.uploaded?(get)
+        end
+
+        # Returns true if the attachment is present and is uploaded by the
+        # permanent storage.
+        def stored?
+          get && store.uploaded?(get)
+        end
       end
     end
 

data/lib/shrine/plugins/moving.rb

@@ -17,12 +17,12 @@ class Shrine
     #
     #     plugin :moving, storages: [:cache, :store]
     #
-    # What exactly means "moving"? Usually this means that the file which is
-    # being uploaded will be deleted afterwards. However, if both the file
-    # being uploaded and the destination are on the filesystem, a `mv` command
-    # will be executed instead. Some other storages may implement moving as
-    # well, usually if also both the cache and store are using the same
-    # storage.
+    # What exactly means "moving"? If both the file being uploaded and the
+    # destination are on the filesystem, a `mv` command will be executed
+    # (making the transfer instantaneous). Some other storages may implement
+    # moving as well, usually only for files which are on the same storage.
+    # If moving isn't implemented by the storage, the file will be simply
+    # deleted after upload.
     module Moving
       def self.configure(uploader, storages:)
         uploader.opts[:move_files_to_storages] = storages

data/lib/shrine/plugins/multi_delete.rb

@@ -24,7 +24,7 @@ class Shrine
             if storage.respond_to?(:multi_delete)
               storage.multi_delete(uploaded_file.map(&:id))
             else
-              uploaded_file.map { |file| _delete(file, context) }
+              uploaded_file.each { |file| _delete(file, context) }
             end
           else
             super

data/lib/shrine/plugins/pretty_location.rb

@@ -11,11 +11,28 @@ class Shrine
     #
     #     "user/564/avatar/thumb-493g82jf23.jpg"
     #     # :model/:id/:attachment/:version-:uid.:extension
+    #
+    # By default if a record class is inside a namespace, only the "inner"
+    # class name is used in the location. If you want to include the namespace,
+    # you can pass in the `:namespace` option with the desired separator as the
+    # value:
+    #
+    #     plugin :pretty_location, namespace: "_"
+    #     # "blog_user/.../493g82jf23.jpg"
+    #
+    #     plugin :pretty_location, namespace: "/"
+    #     # "blog/user/.../493g82jf23.jpg"
     module PrettyLocation
+      def self.configure(uploader, namespace: nil)
+        uploader.opts[:pretty_location_namespace] = namespace
+      end
+
       module InstanceMethods
         def generate_location(io, context)
-          type = context[:record].class.name.downcase if context[:record] && context[:record].class.name
-          id   = context[:record].id if context[:record].respond_to?(:id)
+          if context[:record]
+            type = class_location(context[:record].class) if context[:record].class.name
+            id   = context[:record].id if context[:record].respond_to?(:id)
+          end
           name = context[:name]
 
           dirname, slash, basename = super.rpartition("/")
@@ -30,6 +47,15 @@ class Shrine
         def generate_uid(io)
           SecureRandom.hex(5)
         end
+
+        def class_location(klass)
+          parts = klass.name.downcase.split("::")
+          if separator = opts[:pretty_location_namespace]
+            parts.join(separator)
+          else
+            parts.last
+          end
+        end
       end
     end
 

data/lib/shrine/plugins/remote_url.rb

@@ -29,34 +29,38 @@ class Shrine
     #
     #     plugin :remote_url, max_size: nil
     #
-    # If download fails, either because the remote file wasn't found, was too
-    # large, or the request redirected, an error will be added to the
-    # attachment. You can change the default error message:
-    #
-    #     plugin :remote_url, error_message: "download failed"
-    #     plugin :remote_url, error_message: ->(url) { I18n.t("errors.download_failed") }
-    #
     # Finally, if for some reason the way the file is downloaded doesn't suit
     # your needs, you can provide a custom downloader:
     #
-    #     plugin :remote_url, downloader: ->(url) do
+    #     plugin :remote_url, downloader: ->(url, max_size:) do
     #       request = RestClient::Request.new(method: :get, url: url, raw_response: true)
     #       response = request.execute
     #       response.file
     #     end
+    #
+    # If download errors, the error is rescued and a validation error is added
+    # equal to the error message. You can change the default error message:
+    #
+    #     plugin :remote_url, error_message: "download failed"
+    #     plugin :remote_url, error_message: ->(url) { I18n.t("errors.download_failed") }
+    #
+    # If you need the error instance for generating the error message, passing
+    # the `:include_error` option will additionally yield the error to the
+    # block:
+    #
+    #     plugin :remote_url, include_error: true, error_message: ->(url, error) { "..." }
     module RemoteUrl
-      DEFAULT_ERROR_MESSAGE = "file was not found or was too large"
-
       def self.load_dependencies(uploader, downloader: :open_uri, **)
         case downloader
         when :open_uri then require "down"
         end
       end
 
-      def self.configure(uploader, downloader: :open_uri, error_message: nil, max_size:)
+      def self.configure(uploader, downloader: :open_uri, max_size:, error_message: nil, include_error: false)
         uploader.opts[:remote_url_downloader] = downloader
-        uploader.opts[:remote_url_error_message] = error_message || DEFAULT_ERROR_MESSAGE
         uploader.opts[:remote_url_max_size] = max_size
+        uploader.opts[:remote_url_error_message] = error_message
+        uploader.opts[:remote_url_include_error] = include_error
       end
 
       module AttachmentMethods
@@ -82,12 +86,17 @@ class Shrine
         def remote_url=(url)
           return if url == ""
 
-          if downloaded_file = download(url)
+          begin
+            downloaded_file = download(url)
+          rescue => error
+            download_error = error
+          end
+
+          if downloaded_file
             assign(downloaded_file)
           else
-            message = shrine_class.opts[:remote_url_error_message]
-            message = message.call(url) if message.respond_to?(:call)
-            errors << message
+            message = download_error_message(url, download_error)
+            errors.replace [message]
             @remote_url = url
           end
         end
@@ -117,7 +126,19 @@ class Shrine
         # the download simply failed.
         def download_with_open_uri(url, max_size:)
           Down.download(url, max_size: max_size)
-        rescue Down::Error
+        end
+
+        def download_error_message(url, error)
+          if message = shrine_class.opts[:remote_url_error_message]
+            args = [url]
+            args << error if shrine_class.opts[:remote_url_include_error]
+            message = message.call(*args) if message.respond_to?(:call)
+          else
+            message = "download failed"
+            message = "#{message}: #{error.message}" if error
+          end
+
+          message
         end
       end
     end

data/lib/shrine/plugins/sequel.rb

@@ -78,7 +78,7 @@ class Shrine
             break if record.send("#{name}_data") != record.reload.send("#{name}_data")
             super
           end
-        rescue Sequel::Error
+        rescue ::Sequel::Error
         end
 
         # We save the record after updating, raising any validation errors.

data/lib/shrine/plugins/store_dimensions.rb

@@ -62,7 +62,9 @@ class Shrine
         private
 
         def _extract_dimensions_with_fastimage(io)
-          FastImage.size(io)
+          result = FastImage.size(io)
+          io.rewind # https://github.com/sdsykes/fastimage/pull/66
+          result
         end
       end
 

data/lib/shrine/plugins/versions.rb

@@ -154,7 +154,6 @@ class Shrine
         def _delete(uploaded_file, context)
           if (versions = uploaded_file).is_a?(Hash)
             _delete(versions.values, context)
-            versions
           else
             super
           end

data/lib/shrine/storage/s3.rb

@@ -40,8 +40,8 @@ class Shrine
     # These options will be passed to aws-sdk's methods for [uploading],
     # [copying] and [presigning].
     #
-    # You can also forward additional upload options per upload with the
-    # `upload_options` plugin:
+    # You can also generate upload options per upload with the `upload_options`
+    # plugin:
     #
     #     class MyUploader < Shrine
     #       plugin :upload_options, store: ->(io, context) do
@@ -53,6 +53,9 @@ class Shrine
     #       end
     #     end
     #
+    # Note that these aren't applied to presigns, since presigns are generated
+    # using the storage directly.
+    #
     # ## CDN
     #
     # If you're using a CDN with S3 like Amazon CloudFront, you can specify
@@ -217,7 +220,7 @@ class Shrine
 
       # This is used to check whether an S3 file is copyable.
       def access_key_id
-        @s3.client.config.credentials.access_key_id
+        @s3.client.config.credentials.credentials.access_key_id
       end
 
       private
@@ -242,7 +245,7 @@ class Shrine
 
       # Amazon requires multipart copy from S3 objects larger than 5 GB.
       def large?(io)
-        io.size >= 5*1024*1024*1024 # 5GB
+        io.size && io.size >= 5*1024*1024*1024 # 5GB
       end
     end
   end

data/lib/shrine/version.rb

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

data/shrine.gemspec

@@ -16,13 +16,12 @@ 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.5"
+  gem.add_dependency "down", ">= 2.0.1"
 
   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"
-  gem.add_development_dependency "vcr", "~> 2.9"
   gem.add_development_dependency "webmock"
   gem.add_development_dependency "rack-test_app"
   gem.add_development_dependency "dotenv"
@@ -39,7 +38,7 @@ Gem::Specification.new do |gem|
   end
 
   gem.add_development_dependency "sequel"
-  gem.add_development_dependency "activerecord"
+  gem.add_development_dependency "activerecord", "~> 4.2"
 
   if RUBY_ENGINE == "jruby"
     gem.add_development_dependency "activerecord-jdbcsqlite3-adapter"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-26 00:00:00.000000000 Z
+date: 2016-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.5
+        version: 2.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.5
+        version: 2.0.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -80,20 +80,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.9'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -252,16 +238,16 @@ dependencies:
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.2'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -358,9 +344,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Toolkit for file uploads in Ruby
 test_files: []
-has_rdoc: