shrine 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11b0d1c76734507b02ec22fb1ae1aef8a8c704e7
-  data.tar.gz: 397c1df52d016428395879fbc8bfba4c0dbb7db7
+  metadata.gz: 685289a1b672f363582842cdb2109c4197f9e735
+  data.tar.gz: 37a64e5704dcc6125074dc2333ecf570ba5eaede
 SHA512:
-  metadata.gz: ad5a997b948d19f19fd636502886fe1398deda24be00d5028aabaaabe17c99dd5251c50a4da976c0a7bd1025f9edec0243b2d8dbf67b5115605e3f74c30f7903
-  data.tar.gz: fa8e72de26ecafcbf0be585f25c495072b7502d50c018449a0071171de11e4501df43b75a074cb70968219ad9eb4259138669e86f58e9a2280f7f67b80b33a12
+  metadata.gz: 15150fb3c6d90f397c6e35f714b4eeed02d9c30ee8497fc9763f689b7e7732612e96a896c9d912cf04161a564e5196e73ba20f87df8d489d1562ffe4381dcf7b
+  data.tar.gz: eb4f056cf14cbacb40ee272008c08623e72767965b808d376f4880b83088a0bd57a20282ac7eb05138aea6dc6c0eae9d3c75c16b8bb8faae940816ee1d079fdc

data/README.md

@@ -22,7 +22,7 @@ Shrine has been tested on MRI 2.1, MRI 2.2, JRuby and Rubinius.
 
 ## Basics
 
-Here's a basic example showing how the file upload works in Shrine:
+Here's a basic example showing how file upload works in Shrine:
 
 ```rb
 require "shrine"
@@ -32,13 +32,13 @@ Shrine.storages[:file_system] = Shrine::Storage::FileSystem.new("uploads")
 
 uploader = Shrine.new(:file_system)
 
-uploaded_file = uploader.upload(File.open("avatar.jpg"))
+uploaded_file = uploader.upload(File.open("movie.mp4"))
 uploaded_file      #=> #<Shrine::UploadedFile>
-uploaded_file.url  #=> "/uploads/9260ea09d8effd.jpg"
+uploaded_file.url  #=> "/uploads/9260ea09d8effd.mp4"
 uploaded_file.data #=>
 # {
 #   "storage"  => "file_system",
-#   "id"       => "9260ea09d8effd.jpg",
+#   "id"       => "9260ea09d8effd.mp4",
 #   "metadata" => {...},
 # }
 ```
@@ -59,24 +59,21 @@ to be an actual IO, it's enough that it responds to these 5 methods:
 `#read(*args)`, `#size`, `#eof?`, `#rewind` and `#close`.
 `ActionDispatch::Http::UploadedFile` is one such object.
 
-The returned `Shrine::UploadedFile` represents the file that has been uploaded,
-and we can do a lot with it:
+The returned object is a [`Shrine::UploadedFile`], which represents the file
+that was uploaded, and we can do a lot with it:
 
 ```rb
-uploaded_file.url      #=> "/uploads/938kjsdf932.jpg"
+uploaded_file.url      #=> "/uploads/938kjsdf932.mp4"
 uploaded_file.read     #=> "..."
 uploaded_file.exists?  #=> true
-uploaded_file.download #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20151004-74201-1t2jacf>
+uploaded_file.download #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20151004-74201-1t2jacf.mp4>
 uploaded_file.metadata #=> {...}
+uploaded_file.delete
+# ...
 ```
 
 To read about the metadata that is stored with the uploaded file, see the
-[metadata](#metadata) section. Once you're done with the file, you can delete
-it.
-
-```rb
-uploaded_file.delete
-```
+[metadata](#metadata) section.
 
 ## Attachment
 
@@ -101,7 +98,7 @@ should create an uploader specific to the type of files we're uploading:
 
 ```rb
 class ImageUploader < Shrine
-  # logic for uploading images
+  # your logic for uploading files
 end
 ```
 
@@ -110,9 +107,7 @@ Now if we assume that we have a "User" model, and we want our users to have an
 
 ```rb
 class User
-  attr_accessor :avatar_data
-
-  include ImageUploader[:avatar]
+  include ImageUploader[:avatar] # requires "avatar_data" attribute
 end
 ```
 
@@ -127,7 +122,7 @@ user.avatar_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"met
 ```
 
 The attachment module has added `#avatar`, `#avatar=` and `#avatar_url`
-methods to our User. This is what's happening:
+methods to our User, using regular module inclusion.
 
 ```rb
 Shrine[:avatar] #=> #<Shrine::Attachment(avatar)>
@@ -142,10 +137,9 @@ Shrine.attachment(:avatar)
 Shrine::Attachment.new(:document)
 ```
 
-The setter (`#avatar=`) caches the assigned file and writes it to the "data"
-column (`avatar_data`). The getter (`#avatar`) reads the "data" column and
-returns a `Shrine::UploadedFile`. The url method (`#avatar_url`) calls
-`avatar.url` if the attachment is present, otherwise returns nil.
+* `#avatar=` – caches the file and saves a JSON representation into `avatar_data`
+* `#avatar` – returns a `Shrine::UploadedFile` based on the data from `avatar_data`
+* `#avatar_url` – calls `avatar.url` if attachment is present, otherwise returns nil.
 
 This is how you would typically create the form for a `@user`:
 
@@ -195,10 +189,18 @@ user.destroy
 user.avatar.exists? #=> false
 ```
 
+*NOTE: The record will first be saved with the cached attachment, and afterwards
+(in an "after commit" hook) updated with the stored attachment. This is done so
+that processing/storing isn't performed inside a database transaction. If you're
+doing processing, there will be a bried period of time when the record will exist
+with an unprocessed attachment, so you may need to account for that.*
+
 ## Direct uploads
 
 Shrine comes with a `direct_upload` plugin which provides a [Roda] endpoint
-that can be used for AJAX uploads (using any JavaScript file upload library):
+that accepts file uploads. This allows you to asynchronously start caching the
+file the moment the user selects it (e.g. using the [jQuery-File-Upload] JS
+library), which gives a nice experience to the user.
 
 ```rb
 Shrine.plugin :direct_upload # Provides a Roda endpoint
@@ -208,21 +210,18 @@ Rails.application.routes.draw do
   mount ImageUploader::UploadEndpoint => "/attachments/images"
 end
 ```
-```rb
-# POST /attachments/images/cache/avatar
-{
-  "id": "43kewit94.jpg",
-  "storage": "cache",
-  "metadata": {
-    "size": 384393,
-    "filename": "nature.jpg",
-    "mime_type": "image/jpeg"
-  }
-}
+```js
+$('[type="file"]').fileupload({
+  url:       '/attachments/images/cache/avatar',
+  paramName: 'file',
+  add:       function(e, data) { /* Disable the submit button */ },
+  progress:  function(e, data) { /* Add a nice progress bar */ },
+  done:      function(e, data) { /* Fill in the hidden field with the result */ }
+});
 ```
 
-The plugin also provides a route that can be used for doing direct S3 uploads,
-see the documentation of the plugin for more details, as well as the [example
+The plugin also provides a route that can be used for doing direct S3 uploads.
+See the documentation of the plugin for more details, as well as the [example
 app] to see how easy it is to implement multiple uploads directly to S3.
 
 ## Processing
@@ -240,11 +239,13 @@ class ImageUploader < Shrine
 end
 ```
 
-The `io` is the file being uploaded, and `context` we'll leave for later.  You
+The `io` is the file being uploaded, and `context` we'll leave for later. You
 may be wondering why we need this conditional. Well, when an attachment is
 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.
+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).
 
 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
@@ -344,10 +345,9 @@ user.save                              # "store"
 ```
 
 The `:name` is the name of the attachment, in this case "avatar". The `:record`
-is the model instance, in this case instance of `User`. As for `:phase`, in web
-applications a file upload isn't an event that happens at once, it's a process
-that happens in *phases*. By default there are only 2 phases, "cache" and
-"store", other plugins add more of them.
+is the model instance, in this case instance of `User`. Lastly, the `:phase`;
+by default the two main phases of attaching are "cache" and "store", but some
+plugins add more of them, and there are different ones for deleting files.
 
 Context is really useful for doing conditional processing and validation, since
 we have access to the record and attachment name. In general the context is
@@ -403,11 +403,11 @@ end
 
 ### MIME type
 
-By default, "mime_type" is inherited from `#content_type` of the uploaded file.
-In case of Rails, this value is set from the `Content-Type` header, which the
-browser sets solely based on the extension of the uploaded file. This means
-that by default Shrine's "mime_type" is *not* guaranteed to hold the actual
-MIME type of the file.
+By default, "mime_type" is inherited from `#content_type` of the uploaded file,
+which holds the value of the "Content-Type" header added by the browser solely
+based on the extension of the uploaded file. This means that by default
+Shrine's "mime_type" is *not* guaranteed to hold the actual MIME type of the
+file.
 
 To help with that Shrine provides the `determine_mime_type` plugin, which by
 default uses the UNIX [file] utility to determine the actual MIME type:
@@ -470,13 +470,13 @@ If you want to generate your own locations, simply override
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, context)
-    "#{context[:record].class}/#{context[:record].id}/#{io.original_filename}"
+    "#{context[:record].class}/#{super}"
   end
 end
 ```
 
-Note that in this case should make your locations unique, otherwise dirty
-tracking won't be detected properly (you can use `Shrine#generate_uid`).
+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`).
 
 When using `Shrine` directly you can bypass `#generate_location` by passing in
 `:location`
@@ -511,8 +511,8 @@ user.save
 user.avatar.url #=> "https://my-bucket.s3-eu-west-1.amazonaws.com/0943sf8gfk13.jpg"
 ```
 
-If you're using S3 for both cache and store, saving the record will avoid
-reuploading the file by issuing an S3 COPY command instead.  Also, the
+If you're using S3 both for cache and store, saving the record will avoid
+reuploading the file by issuing an S3 COPY command instead. Also, the
 `versions` plugin takes advantage of S3's MULTI DELETE capabilities, so
 versions are deleted with a single HTTP request.
 
@@ -583,7 +583,7 @@ libraries are:
 Shrine comes with a small core which provides only the essential functionality,
 and all additional features are available via plugins. This way you can choose
 exactly how much Shrine does for you. Shrine itself [ships with over 35
-plugins], most of them I haven't managed to cover here.
+plugins], most of which I haven't managed to cover here.
 
 The plugin system respects inheritance, so you can choose which plugins will
 be applied to which uploaders:
@@ -607,7 +607,6 @@ system].
 
 The gem is available as open source under the terms of the [MIT License].
 
-[Contributor Covenant]: http://contributor-covenant.org
 [image_processing]: https://github.com/janko-m/image_processing
 [fastimage]: https://github.com/sdsykes/fastimage
 [file]: http://linux.die.net/man/1/file
@@ -624,3 +623,4 @@ The gem is available as open source under the terms of the [MIT License].
 [FileSystem]: http://shrinerb.com/rdoc/classes/Shrine/Storage/FileSystem.html
 [S3]: http://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html
 [Plugins & Storages]: http://shrinerb.com#external
+[`Shrine::UploadedFile`]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/Base/FileMethods.html

data/doc/changing_location.md

@@ -16,7 +16,7 @@ Or by overriding `#generate_location`:
 ```rb
 class MyUploader < Shrine
   def generate_location(io, context)
-    "#{context[:record].class}/#{context[:record.id]}/#{io.original_filename}"
+    "#{context[:record].class}/#{context[:record].id}/#{io.original_filename}"
   end
 end
 ```

data/doc/direct_s3.md

@@ -1,13 +1,18 @@
 # Direct Uploads to S3
 
-Probably the best way to do file uploads is to upload them directly to S3, and
-then upon saving the record when file is moved to a permanent place, put that
-and any additional file processing in the background. The goal of this guide
-is to provide instructions, as well as evaluate possible ways of doing this.
+Shrine gives you the ability to upload files directly to S3, which frees your
+server from accepting file uploads. If on saving the record you need to do some
+file processing, you can kick that into a background job using the
+`backgrounding` plugin. If you're not doing any processing and your permanent
+storage is also S3, saving the record will perform an S3 COPY request from
+cache to store, without any downloading and uploading (which is both fast and
+memory-efficient).
 
 ```rb
 require "shrine/storage/s3"
 
+s3_options = {access_key_id: "...", secret_access_key: "...", region: "..."}
+
 Shrine.storages = {
   cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
   store: Shrine::Storage::S3.new(prefix: "store", **s3_options),

data/doc/refile.md

@@ -306,7 +306,7 @@ class ImageUploader < Shrine
 
   Attacher.validate do
     validate_extension_inclusion [/jpe?g/, "png"]
-    validate_mime_type_inclusion [/image/jpeg/, "image/png"]
+    validate_mime_type_inclusion ["image/jpeg", "image/png"]
   end
 end
 ```

data/doc/regenerating_versions.md

@@ -129,19 +129,19 @@ Shrine.plugin :migration_helpers # before the model is loaded
 ```
 
 ```rb
-removed_versions = []
+old_versions = []
 
 User.paged_each do |user|
   user.update_avatar do |avatar|
     old_version = avatar.delete(:old_version)
-    removed_versions << old_version if old_version
+    old_versions << old_version if old_version
     avatar
   end
 end
 
-if removed_versions.any?
-  uploader = removed_versions.first.uploader
-  uploader.delete(removed_versions)
+if old_versions.any?
+  uploader = old_versions.first.uploader
+  uploader.delete(old_versions)
 end
 ```
 

data/lib/shrine.rb

@@ -282,7 +282,7 @@ class Shrine
 
         private
 
-        # Extracts the filename from the IO using smart heuristics.
+        # Extracts the filename from the IO using some basic heuristics.
         def extract_filename(io)
           if io.respond_to?(:original_filename)
             io.original_filename
@@ -291,7 +291,7 @@ class Shrine
           end
         end
 
-        # Extracts the MIME type from the IO using smart heuristics.
+        # Extracts the MIME type from the IO using some basic heuristics.
         def extract_mime_type(io)
           if io.respond_to?(:mime_type)
             io.mime_type
@@ -311,7 +311,7 @@ class Shrine
         def _store(io, context)
           _enforce_io(io)
           context[:location] ||= get_location(io, context)
-          context[:metadata] ||= extract_metadata(io, context)
+          context[:metadata] ||= get_metadata(io, context)
 
           put(io, context)
 
@@ -335,6 +335,7 @@ class Shrine
         # Does the actual uploading, calling `#upload` on the storage.
         def copy(io, context)
           storage.upload(io, context[:location], context[:metadata])
+        ensure
           io.close rescue nil
         end
 
@@ -354,6 +355,16 @@ class Shrine
           generate_location(io, context)
         end
 
+        # Copies the metadata over from an UploadedFile or calls
+        # #extract_metadata.
+        def get_metadata(io, context)
+          if io.is_a?(UploadedFile)
+            io.metadata.dup
+          else
+            extract_metadata(io, context)
+          end
+        end
+
         # Checks if the object is a valid IO by checking that it responds to
         # `#read`, `#eof?`, `#rewind`, `#size` and `#close`, otherwise raises
         # Shrine::InvalidFile.
@@ -512,16 +523,12 @@ class Shrine
           promote(get) if promote?(get)
         end
 
-        # Promotes a cached file to store, taking into account to check whether
-        # the attachment has changed in the meanwhile. Afterwards the cached
-        # file is deleted.
+        # Uploads the cached file to store, and updates the record with the
+        # stored file.
         def promote(cached_file)
           stored_file = store!(cached_file, phase: :store)
-          unless changed?(cached_file)
-            update(stored_file)
-          else
-            delete!(stored_file, phase: :stored)
-          end
+          (result = swap(stored_file)) or delete!(stored_file, phase: :stored)
+          result
         end
 
         # Deletes the attachment that was replaced, and is called after saving
@@ -549,7 +556,7 @@ class Shrine
           end
         end
 
-        # Runs the validations defined by `Shrine.validate`.
+        # Runs the validations defined by `Attacher.validate`.
         def validate
           errors.clear
           instance_exec(&validate_block) if validate_block && get
@@ -573,11 +580,17 @@ class Shrine
         end
 
         # Returns true if uploaded_file exists and is cached.  If it's true,
-        # #promote will be called.
+        # \#promote will be called.
         def promote?(uploaded_file)
           uploaded_file && cache.uploaded?(uploaded_file)
         end
 
+        # Alias to #update, overriden in ORM plugins.
+        def swap(uploaded_file)
+          update(uploaded_file)
+          uploaded_file
+        end
+
         # Sets and saves the uploaded file.
         def update(uploaded_file)
           _set(uploaded_file)
@@ -610,11 +623,6 @@ class Shrine
           shrine_class.opts[:validate]
         end
 
-        # Checks if the uploaded file matches the written one.
-        def changed?(uploaded_file)
-          get != uploaded_file
-        end
-
         # It dumps the UploadedFile to JSON and writes the result to the column.
         def _set(uploaded_file)
           write(uploaded_file ? uploaded_file.to_json : nil)

data/lib/shrine/plugins/activerecord.rb

@@ -66,27 +66,28 @@ class Shrine
       module AttacherClassMethods
         # Needed by the backgrounding plugin.
         def find_record(record_class, record_id)
-          record_class.find(record_id)
+          record_class.where(id: record_id).first
         end
       end
 
       module AttacherMethods
         private
 
+        # Updates the current attachment with the new one, unless the current
+        # attachment has changed.
+        def swap(uploaded_file)
+          record.class.transaction do
+            break if record.send("#{name}_data") != record.reload.send("#{name}_data")
+            super
+          end
+        rescue ActiveRecord::RecordNotFound
+        end
+
         # We save the record after updating, raising any validation errors.
         def update(uploaded_file)
           super
           record.save!
         end
-
-        # If we're in a transaction, then promoting is happening inline. If
-        # we're not, then this is happening in a background job. In that case
-        # when we're checking that the attachment changed during storing, we
-        # need to first reload the record to pick up new columns.
-        def changed?(uploaded_file)
-          record.reload
-          super
-        end
       end
     end
 

data/lib/shrine/plugins/backgrounding.rb

@@ -1,25 +1,18 @@
 class Shrine
   module Plugins
-    # The background_helpers plugin enables you to intercept phases of
-    # uploading and put them into background jobs. This doesn't require any
-    # additional columns.
-    #
-    #     plugin :backgrounding
-    #
-    # ## Promoting
-    #
-    # If you're doing processing, or your `:store` is something other than
-    # Storage::FileSystem, it's recommended to put promoting (moving to store)
-    # into a background job. This plugin allows you to do that by calling
-    # `Shrine::Attacher.promote`:
+    # The backgrounding plugin enables you to remove processing/storing/deleting
+    # of files from record's lifecycle, and put them into background jobs.
+    # This is generally useful if you're doing processing and/or your store is
+    # something other than Storage::FileSystem.
     #
+    #     Shrine.plugin :backgrounding
     #     Shrine::Attacher.promote { |data| UploadJob.perform_async(data) }
+    #     Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
     #
-    # When you call `Shrine::Attacher.promote` with a block, it will save the
-    # block and call it on every promotion. Then in your background job you can
-    # again call `Shrine::Attacher.promote` with the data, and internally it
-    # will resolve all necessary objects, do the promoting and update the
-    # record.
+    # The `data` variable is a serializable hash containing all context needed
+    # for promotion/deletion. You then just need to declare `UploadJob` and
+    # `DeleteJob`, and call `Shrine::Attacher.promote`/`Shrine::Attacher.delete`
+    # with the data hash:
     #
     #     class UploadJob
     #       include Sidekiq::Worker
@@ -29,22 +22,6 @@ class Shrine
     #       end
     #     end
     #
-    # Shrine automatically handles all concurrency issues, such as canceling
-    # promoting if the attachment has changed in the meanwhile.
-    #
-    # ## Deleting
-    #
-    # If your `:store` is something other than Storage::FileSystem, it's
-    # recommended to put deleting files into a background job. This plugin
-    # allows you to do that by calling `Shrine::Attacher.delete`:
-    #
-    #     Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
-    #
-    # When you call `Shrine::Attacher.delete` with a block, it will save the
-    # block and call it on every delete. Then in your background job you can
-    # again call `Shrine::Attacher.delete` with the data, and internally it
-    # will resolve all necessary objects, and delete the file.
-    #
     #     class DeleteJob
     #       include Sidekiq::Worker
     #
@@ -53,20 +30,26 @@ class Shrine
     #       end
     #     end
     #
-    # ## Conclusion
+    # Internally these methods will resolve all necessary objects, do the
+    # promotion/deletion, and in case of promotion update the record with the
+    # stored attachment. Concurrency issues, like record being deleted or
+    # attachment being changed, are handled automatically.
     #
     # The examples above used Sidekiq, but obviously you can just as well use
-    # any other backgrounding library. Also, if you want you can use
-    # backgrounding just for certain uploaders:
+    # any other backgrounding library. This setup will work globally for all
+    # uploaders.
     #
-    #     class ImageUploader < Shrine
-    #       Attacher.promote { |data| UploadJob.perform_async(data) }
-    #       Attacher.delete { |data| DeleteJob.perform_async(data) }
+    # Both methods return the record (if it exists and the action didn't
+    # abort), so you can use it to do additional actions:
+    #
+    #     def perform(data)
+    #       record = Shrine::Attacher.promote(data)
+    #       record.update(published: true) if record.is_a?(Post)
     #     end
     #
-    # If you would like to speed up your uploads and deletes, you can use the
-    # parallelize plugin, either as a replacement or an addition to
-    # background_helpers.
+    # If you're generating versions, and you want to process some versions in
+    # the foreground before kicking off a background job, you can use the
+    # `recache` plugin.
     module Backgrounding
       module AttacherClassMethods
         # If block is passed in, stores it to be called on promotion. Otherwise
@@ -77,13 +60,16 @@ class Shrine
           else
             record_class, record_id = data["record"]
             record_class = Object.const_get(record_class)
-            record = find_record(record_class, record_id)
+            record = find_record(record_class, record_id) or return
 
             name = data["attachment"]
             attacher = record.send("#{name}_attacher")
             cached_file = attacher.uploaded_file(data["uploaded_file"])
+            return if cached_file != record.send(name)
+
+            attacher.promote(cached_file) or return
 
-            attacher.promote(cached_file)
+            record
           end
         end
 
@@ -103,12 +89,15 @@ class Shrine
             context = {name: name.to_sym, record: record, phase: phase.to_sym}
 
             attacher.store.delete(uploaded_file, context)
+
+            record
           end
         end
       end
 
       module AttacherMethods
-        # Calls the promoting block with the data if it's been registered.
+        # Calls the promoting block (if registered) with a serializable data
+        # hash.
         def _promote
           if background_promote = shrine_class.opts[:backgrounding_promote]
             data = {
@@ -125,7 +114,8 @@ class Shrine
 
         private
 
-        # Calls the deleting block with the data if it's been registered.
+        # Calls the deleting block (if registered) with a serializable data
+        # hash.
         def delete!(uploaded_file, phase:)
           if background_delete = shrine_class.opts[:backgrounding_delete]
             data = {

data/lib/shrine/plugins/data_uri.rb

@@ -19,7 +19,7 @@ class Shrine
     #     user.avatar.size              #=> 43423
     #     user.avatar.original_filename #=> nil
     #
-    # If the data URI wasn't correctly parsed, an error message will added to
+    # If the data URI wasn't correctly parsed, an error message will be added to
     # the attachment column. You can change the default error message:
     #
     #     plugin :data_uri, error_message: "data URI was invalid"

data/lib/shrine/plugins/direct_upload.rb

@@ -18,10 +18,10 @@ class Shrine
     #
     # You should always mount a new endpoint for each uploader that you want to
     # enable direct uploads for. This now gives your Ruby application a `POST
-    # /attachments/images/:storage/:name` route, which accepts a `file` query
+    # /attachments/images/:storage/:name` route, which accepts a "file" query
     # parameter, and returns the uploaded file in JSON format:
     #
-    #     # POST /attachments/images/cache/avatar
+    #     # POST /attachments/images/cache/avatar (file upload)
     #     {
     #       "id": "43kewit94.jpg",
     #       "storage": "cache",
@@ -32,9 +32,9 @@ class Shrine
     #       }
     #     }
     #
-    # Once you've uploaded the file, you need to assign this JSON to the hidden
-    # attachment field in the form. There are many great JavaScript libraries
-    # for file uploads, most popular being [jQuery-File-Upload].
+    # Once you've uploaded the file, you need to assign the result to the
+    # hidden attachment field in the form. There are many great JavaScript
+    # libraries for file uploads, most popular being [jQuery-File-Upload].
     #
     # ## Limiting filesize
     #

data/lib/shrine/plugins/migration_helpers.rb

@@ -12,17 +12,18 @@ 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">>>
     #
-    # The model will also get `#update_avatar` method, which should be used
-    # when doing attachment migrations. It will update the record's attachment
-    # with the result of the passed in block.
+    # 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.
     #
     #     user.update_avatar do |avatar|
     #       user.avatar_store.upload(avatar) # saved to the record
     #     end
     #
     # This will get triggered _only_ if the attachment is not nil and is
-    # stored. The result can be anything that responds to `#to_json` and
-    # evaluates to uploaded files' data.
+    # stored, and will get saved only if the current attachment hasn't changed
+    # while executing the block. The result can be anything that responds to
+    # `#to_json` and evaluates to uploaded files' data.
     module MigrationHelpers
       module AttachmentMethods
         def initialize(name)
@@ -48,10 +49,9 @@ class Shrine
         # Updates the attachment with the result of the block. It will get
         # called only if the attachment exists and is stored.
         def update_stored(&block)
-          attachment = get
-          return if attachment.nil? || cache.uploaded?(attachment)
-          new_attachment = block.call(attachment)
-          update(new_attachment) unless changed?(attachment)
+          return if get.nil? || cache.uploaded?(get)
+          new_attachment = block.call(get)
+          swap(new_attachment)
         end
       end
     end

data/lib/shrine/plugins/remove_attachment.rb

@@ -16,7 +16,8 @@ class Shrine
     #     <% end %>
     #
     # Now when the checkbox is ticked and the form is submitted, the attached
-    # file will be removed.
+    # file will be removed. Note that the "remove_avatar" field needs to be
+    # declared somewhere after the hidden field.
     module RemoveAttachment
       module AttachmentMethods
         def initialize(name)
@@ -38,7 +39,7 @@ class Shrine
         # We remove the attachment if the value evaluates to true.
         def remove=(value)
           @remove = value
-          set(nil) if remove?
+          assign(nil) if remove?
         end
 
         def remove

data/lib/shrine/plugins/sequel.rb

@@ -14,10 +14,10 @@ class Shrine
     # * `after_commit` -- Promotes the attachment, deletes replaced ones.
     # * `after_destroy_commit` -- Deletes the attachment.
     #
-    # Note that if your tests are wrapped in transactions, the `after_commit`
-    # and `after_destroy_commit` callbacks won't get called, so in order to
-    # test uploading you should first disable these transactions for those
-    # tests.
+    # Note that if your tests are wrapped in transactions, for testing
+    # attachments you should set `Sequel::Model.use_transactions` to `false`,
+    # so that `after_commit` and `after_destroy_commit` callbacks get properly
+    # called.
     #
     # If you want to put some parts of this lifecycle into a background job, see
     # the backgrounding plugin.
@@ -64,28 +64,29 @@ class Shrine
       module AttacherClassMethods
         # Needed by the backgrounding plugin.
         def find_record(record_class, record_id)
-          record_class.with_pk!(record_id)
+          record_class.with_pk(record_id)
         end
       end
 
       module AttacherMethods
         private
 
+        # Updates the current attachment with the new one, unless the current
+        # attachment has changed.
+        def swap(uploaded_file)
+          record.db.transaction do
+            break if record.send("#{name}_data") != record.reload.send("#{name}_data")
+            super
+          end
+        rescue Sequel::Error
+        end
+
         # We save the record after updating, raising any validation errors.
         def update(uploaded_file)
           super
           record.save(raise_on_failure: true)
         end
 
-        # If we're in a transaction, then promoting is happening inline. If
-        # we're not, then this is happening in a background job. In that case
-        # when we're checking that the attachment changed during storing, we
-        # need to first reload the record to pick up new columns.
-        def changed?(uploaded_file)
-          record.reload
-          super
-        end
-
         # Support for Postgres JSON columns.
         def read
           value = super

data/lib/shrine/plugins/store_dimensions.rb

@@ -68,11 +68,11 @@ class Shrine
 
       module FileMethods
         def width
-          metadata["width"] && Integer(metadata["width"])
+          Integer(metadata["width"]) if metadata["width"]
         end
 
         def height
-          metadata["height"] && Integer(metadata["height"])
+          Integer(metadata["height"]) if metadata["height"]
         end
       end
     end

data/lib/shrine/plugins/validation_helpers.rb

@@ -28,7 +28,7 @@ class Shrine
     # If you would like to change the error message inline, you can pass the
     # `:message` option to any validation method:
     #
-    #     validate_mime_type_inclusion [/^image/], message: "is not an image"
+    #     validate_mime_type_inclusion [/\Aimage/], message: "is not an image"
     #
     # For a complete list of all validation helpers, see AttacherMethods.
     module ValidationHelpers
@@ -110,7 +110,7 @@ class Shrine
         # Validates that the MIME type is in the `whitelist`. The whitelist is
         # an array of strings or regexes.
         #
-        #     validate_mime_type_inclusion ["audio/mp3", /^video/]
+        #     validate_mime_type_inclusion ["audio/mp3", /\Avideo/]
         def validate_mime_type_inclusion(whitelist, message: nil)
           if whitelist.none? { |mime_type| regex(mime_type) =~ get.mime_type.to_s }
             errors << error_message(:mime_type_inclusion, message, whitelist)
@@ -120,7 +120,7 @@ class Shrine
         # Validates that the MIME type is not in the `blacklist`. The blacklist
         # is an array of strings or regexes.
         #
-        #     validate_mime_type_exclusion ["image/gif", /^audio/]
+        #     validate_mime_type_exclusion ["image/gif", /\Aaudio/]
         def validate_mime_type_exclusion(blacklist, message: nil)
           if blacklist.any? { |mime_type| regex(mime_type) =~ get.mime_type.to_s }
             errors << error_message(:mime_type_exclusion, message, blacklist)
@@ -130,7 +130,7 @@ class Shrine
         # Validates that the extension is in the `whitelist`. The whitelist
         # is an array of strings or regexes.
         #
-        #     validate_extension_inclusion [/jpe?g/]
+        #     validate_extension_inclusion [/\Ajpe?g\z/i]
         def validate_extension_inclusion(whitelist, message: nil)
           if whitelist.none? { |extension| regex(extension) =~ get.extension.to_s }
             errors << error_message(:extension_inclusion, message, whitelist)
@@ -140,7 +140,7 @@ class Shrine
         # Validates that the extension is not in the `blacklist`. The blacklist
         # is an array of strings or regexes.
         #
-        #     validate_extension_exclusion ["mov", /^mp*/]
+        #     validate_extension_exclusion ["mov", /\Amp/i]
         def validate_extension_exclusion(blacklist, message: nil)
           if blacklist.any? { |extension| regex(extension) =~ get.extension.to_s }
             errors << error_message(:extension_exclusion, message, blacklist)
@@ -150,8 +150,8 @@ class Shrine
         private
 
         # Converts a string to a regex.
-        def regex(string)
-          string.is_a?(Regexp) ? string : /^#{Regexp.escape(string)}$/
+        def regex(value)
+          value.is_a?(Regexp) ? value : /\A#{Regexp.escape(value)}\z/
         end
 
         # Returns the direct message if given, otherwise uses the default error

data/lib/shrine/plugins/versions.rb

@@ -171,7 +171,7 @@ class Shrine
               if file = get[version]
                 file.url(**options)
               else
-                default_url(options.merge(version: version))
+                default_url(**options, version: version)
               end
             else
               raise Error, "must call #{name}_url with the name of the version"
@@ -180,7 +180,7 @@ class Shrine
             if get || version.nil?
               super(**options)
             else
-              default_url(options.merge(version: version))
+              default_url(**options, version: version)
             end
           end
         end

data/lib/shrine/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-26 00:00:00.000000000 Z
+date: 2016-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down