shrine 3.0.0.beta3 → 3.0.0.rc

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad93860597c6a720f0159063d8cbb95a6aa0e93ea89947803342500f1193eb64
-  data.tar.gz: 79801e74ecd993986099f0f4679fcb37c2b778157c4df5bf6bb80064f2338a44
+  metadata.gz: 99f93b258aea07a618b1f35bf08f6b8394dea5d0c6301ed2f96cc72ec12371a4
+  data.tar.gz: ac05d107593d54ce6260d5159c8484f03c24ea0e9df4026b615f79fd5bc04a92
 SHA512:
-  metadata.gz: 12337c687f57272f9af85b8b8831de448fea258e25e6b7191b95131a60e705374807a87efb7c5e4e7c3db0c6f11a8c3dc87dfe21255d24785e908a93cc94be7e
-  data.tar.gz: 04561d887c0612ed193c31c470fcdd9ca5ed466794923ceecf979f78049ec3c9c46cf0161776121c72419bcc5f77babfc565ceaf6892a06a547bd93f9c1cccce
+  metadata.gz: 640d3a4f07816d7f4a20d385ac1249cd5cdbc46f320a6b8d377338b4ceaa724f5ce1e84782391fd2af6be1419aecd61474a36f03bcffb41c6600f6d999b0be0f
+  data.tar.gz: fa93fe25894f9a1125a852e438ca5ecd20518e206418d464afbcf59d8576959e373a3084ff133ef2c8aff062e1a4ba93d64841e19cc14fdc256f87d8871dcb4c

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.0.0.rc (2019-09-28)
+
+* `core` – Add `Storage#delete_prefixed` method for deleting all files in specified directory (@jrochkind)
+
+* `linter` – Return `true` in `Storage::Linter#call` so that it can be used with `assert` (@jrochkind)
+
+* `linter` – Allow `Storage::Linter` to accept a key that will be used for testing nonexistent file (@janko)
+
+* `core` – Infer file extension from `filename` metadata (@janko)
+
+* `pretty_location` – Add `:class_underscore` option for underscoring class name (@Uysim)
+
+* Update `down` dependency to `~> 5.0` (@janko)
+
 ## 3.0.0.beta3 (2019-09-25)
 
 * `multi_cache` – Add new plugin for whitelisting additional temporary storages (@janko, @jrochkind)

data/README.md

@@ -34,6 +34,7 @@ If you're curious how it compares to other file attachment libraries, see the [A
   - [IO abstraction](#io-abstraction)
 * [Uploaded file](#uploaded-file)
 * [Attachment](#attachment)
+  - [Temporary storage](#temporary-storage)
 * [Attacher](#attacher)
 * [Plugin system](#plugin-system)
 * [Metadata](#metadata)
@@ -421,6 +422,20 @@ photo.update(image: new_file) # changes the attachment and deletes previous
 photo.update(image: nil)      # removes the attachment and deletes previous
 ```
 
+### Temporary storage
+
+Shrine uses temporary storage to enable retaining uploaded files across form
+redisplays and for [direct uploads](#direct-uploads), but you can disable this
+behaviour and have files go straight to permanent storage:
+
+```rb
+Shrine.plugin :model, cache: false
+```
+```rb
+photo.image = File.open("waterfall.jpg")
+photo.image.storage_key #=> :store
+```
+
 ## Attacher
 
 The model attachment attributes and callbacks added by `Shrine::Attachment`
@@ -848,12 +863,21 @@ choice][Backgrounding Libraries]:
 
 ```rb
 Shrine.plugin :backgrounding
-Shrine::Attacher.promote_block { PromoteJob.perform_later(self.class, record, name, file_data) }
-Shrine::Attacher.destroy_block { DestroyJob.perform_later(self.class, data) }
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
 ```
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record.id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.atomic_promote
   rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
@@ -862,8 +886,12 @@ class PromoteJob < ActiveJob::Base
 end
 ```
 ```rb
-class DestroyJob < ActiveJob::Base
+class DestroyJob
+  include Sidekiq::Worker
+
   def perform(attacher_class, data)
+    attacher_class = Object.const_get(attacher_class)
+
     attacher = attacher_class.from_data(data)
     attacher.destroy
   end

data/doc/advantages.md

@@ -310,12 +310,17 @@ library][backgrounding libraries].
 
 ```rb
 Shrine::Attacher.promote_block do
-  PromoteJob.perform_later(self.class, record, name, file_data)
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
 end
 ```
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.create_derivatives # perform processing
     attacher.atomic_promote

data/doc/changing_derivatives.md

@@ -288,17 +288,23 @@ Photo.find_each do |photo|
 
   next unless attacher.stored?
 
-  MakeChangeJob.perform_later(
-    attacher.class,
-    attacher.record,
+  MakeChangeJob.perform_async(
+    attacher.class.name,
+    attacher.record.class.name,
+    attacher.record.id,
     attacher.name,
     attacher.file_data,
   )
 end
 ```
 ```rb
-class MakeChangeJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class MakeChangeJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     # ... make our change ...
   end

data/doc/changing_location.md

@@ -76,17 +76,23 @@ Photo.find_each do |photo|
 
   next unless attacher.stored? # move only attachments uploaded to permanent storage
 
-  MoveFilesJob.perform_later(
-    attacher.class,
-    attacher.record,
+  MoveFilesJob.perform_async(
+    attacher.class.name,
+    attacher.record.class.name,
+    attacher.record.id,
     attacher.name,
     attacher.file_data,
   )
 end
 ```
 ```rb
-class MoveFilesJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class MoveFilesJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher     = attacher_class.retrieve(model: record, name: name, file: file_data)
     old_attacher = attacher.dup
 

data/doc/creating_storages.md

@@ -206,15 +206,24 @@ The storage can support additional options to customize how the presign will be
 generated, those can be forwarded via the `:presign_options` option on the
 `presign_endpoint` plugin.
 
-## Clear
+## Delete Prefixed and Clear
 
-While this method is not used by Shrine, it is good to give users the
-possibility to delete all files in a storage, and the conventional name for
-this method is `#clear!`.
+There are two methods that are not currently used by shrine, but which it's good
+for storages to provide to allow client code to delete files from storage. If
+storages provide these conventional methods, then clients can delete files using
+consistent API for any storage.
+
+`#clear!` deletes all files from storage, and `#delete_prefixed` will delete all
+files in a given directory/prefix/path. While not strictly required for shrine storage
+service functionality, storages should usually implement if possible.
 
 ```rb
 class MyStorage
   # ...
+  def delete_prefixed(prefix_path)
+    # deletes all files under the supplied argument prefix
+  end
+
   def clear!
     # deletes all files in the storage
   end

data/doc/direct_s3.md

@@ -310,7 +310,7 @@ Shrine.plugin :backgrounding
 
 Shrine::Attacher.promote_block do
   # tells a Sidekiq worker to perform in 3 seconds
-  PromoteJob.perform_in(3, self.class, record.class, record.id, name, file_data)
+  PromoteJob.perform_in(3, self.class.name, record.class.name, record.id, name, file_data)
 end
 ```
 

data/doc/metadata.md

@@ -255,11 +255,19 @@ plugin uses internally):
 ```rb
 Shrine.plugin :refresh_metadata # allow re-extracting metadata
 Shrine.plugin :backgrounding
-Shrine::Attacher.promote_block { PromoteJob.perform_later(self.class, record, name, file_data) }
+
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
 ```
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.refresh_metadata!
     attacher.atomic_promote
@@ -270,16 +278,22 @@ end
 You can also extract metadata in the background separately from promotion:
 
 ```rb
-MetadataJob.perform_later(
-  attacher.class,
-  attacher.record,
+MetadataJob.perform_async(
+  attacher.class.name,
+  attacher.record.class.name,
+  attacher.record.id,
   attacher.name,
   attacher.file_data,
 )
 ```
 ```rb
-class MetadataJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class MetadataJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.refresh_metadata!
     attacher.atomic_persist
@@ -308,9 +322,14 @@ class MyUploader < Shrine
 end
 ```
 ```rb
-class MetadataJob < ActiveJob::Base
-  def perform(record, name, file_data)
-    attacher = Shrine::Attacher.retrieve(model: record, name: name, file: file_data)
+class MetadataJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.refresh_metadata!(background: true)
     attacher.atomic_persist
   end
@@ -324,9 +343,14 @@ promotion, you can wrap both in an `UploadedFile#open` block to make
 sure the file content is retrieved from the storage only once.
 
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(record, name, file_data)
-    attacher = Shrine::Attacher.retrieve(model: record, name: name, file: file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
 
     attacher.file.open do
       attacher.refresh_metadata!

data/doc/plugins/backgrounding.md

@@ -15,12 +15,21 @@ jobs:
 
 ```rb
 # register backgrounding blocks for all uploaders
-Shrine::Attacher.promote_block { PromoteJob.perform_later(self.class, record, name, file_data) }
-Shrine::Attacher.destroy_block { DestroyJob.perform_later(self.class, data) }
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
 ```
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.atomic_promote
   rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
@@ -29,8 +38,12 @@ class PromoteJob < ActiveJob::Base
 end
 ```
 ```rb
-class DestroyJob < ActiveJob::Base
+class DestroyJob
+  include Sidekiq::Worker
+
   def perform(attacher_class, data)
+    attacher_class = Object.const_get(attacher_class)
+
     attacher = attacher_class.from_data(data)
     attacher.destroy
   end
@@ -43,8 +56,12 @@ backgrounding blocks only for a specific uploader:
 ```rb
 class MyUploader < Shrine
   # register backgrounding blocks only for this uploader
-  Attacher.promote_block { PromoteJob.perform_later(self.class, record, name, file_data) }
-  Attacher.destroy_block { DestroyJob.perform_later(self.class, data) }
+  Attacher.promote_block do
+    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+  end
+  Attacher.destroy_block do
+    DestroyJob.perform_async(self.class.name, data)
+  end
 end
 ```
 
@@ -101,17 +118,18 @@ also use the explicit version by declaring an attacher argument:
 
 ```rb
 Shrine::Attacher.promote_block do |attacher|
-  PromoteJob.perform_later(
-    attacher.class,
-    attacher.record,
+  PromoteJob.perform_async(
+    attacher.class.name,
+    attacher.record.class.name,
+    attacher.record.id,
     attacher.name,
     attacher.file_data,
   )
 end
 
 Shrine::Attacher.destroy_block do |attacher|
-  DestroyJob.perform_later(
-    attacher.class,
+  DestroyJob.perform_async(
+    attacher.class.name,
     attacher.data,
   )
 end
@@ -122,9 +140,10 @@ flexibility:
 
 ```rb
 photo.image_attacher.promote_block do |attacher|
-  PromoteJob.perform_later(
-    attacher.class,
-    attacher.record,
+  PromoteJob.perform_async(
+    attacher.class.name,
+    attacher.record.class.name,
+    attacher.record.id,
     attacher.name,
     attacher.file_data,
     current_user.id, # pass arguments known at the controller level
@@ -135,42 +154,6 @@ photo.image = file
 photo.save # executes the promote block above
 ```
 
-## Other backgrounding libraries
-
-If you're not using Active Job for backgrounding, you might need to retrieve
-records and resolve constants from job arguments manually:
-
-```rb
-# register backgrounding blocks for all uploaders
-Shrine::Attacher.promote_block { PromoteJob.perform_async(self.class, record.class, record.id, name, file_data) }
-Shrine::Attacher.destroy_block { DestroyJob.perform_async(self.class, data) }
-```
-```rb
-class PromoteJob
-  include Sidekiq::Worker
-
-  def perform(attacher_class, record_class, record_id, name, file_data)
-    attacher_class = Object.const_get(attacher_class)
-    record         = Object.const_get(record_class).find(record_id) # if using Active Record
-
-    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
-    attacher.atomic_promote
-  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-  end
-end
-
-class DestroyJob
-  include Sidekiq::Worker
-
-  def perform(attacher_class, data)
-    attacher_class = Object.const_get(attacher_class)
-
-    attacher = attacher_class.from_data(data)
-    attacher.destroy
-  end
-end
-```
-
 [backgrounding]: /lib/shrine/plugins/backgrounding.rb
 [derivatives]: /doc/plugins/derivatives.md#readme
 [atomic_helpers]: /doc/plugins/atomic_helpers.md#readme

data/doc/plugins/mirroring.md

@@ -49,24 +49,32 @@ You can have mirroring performed in a background job:
 
 ```rb
 Shrine.mirror_upload_block do |file|
-  MirrorUploadJob.perform_later(file.shrine_class, file.data)
+  MirrorUploadJob.perform_async(file.shrine_class.name, file.data)
 end
 
 Shrine.mirror_delete_block do |file|
-  MirrorDeleteJob.perform_later(file.shrine_class, file.data)
+  MirrorDeleteJob.perform_async(file.shrine_class.name, file.data)
 end
 ```
 ```rb
-class MirrorUploadJob < ActiveJob::Base
+class MirrorUploadJob
+  include Sidekiq::Worker
+
   def perform(shrine_class, file_data)
+    shrine_class = Object.const_get(shrine_class)
+
     file = shrine_class.uploaded_file(file_data)
     file.mirror_upload
   end
 end
 ```
 ```rb
-class MirrorDeleteJob < ActiveJob::Base
+class MirrorDeleteJob
+  include Sidekiq::Worker
+
   def perform(shrine_class, file_data)
+    shrine_class = Object.const_get(shrine_class)
+
     file = shrine_class.uploaded_file(file_data)
     file.mirror_delete
   end

data/doc/plugins/pretty_location.md

@@ -40,6 +40,17 @@ plugin :pretty_location, identifier: :email
 # "user/foo@bar.com/profile_picture/493g82jf23.jpg"
 ```
 
+By default, the class name will be only downcased. We can also have the class
+name underscored with the `:class_underscore` option:
+
+```ruby
+plugin :pretty_location
+# "blogpost/aa357797-5845-451b-8662-08eecdc9f762/image/493g82jf23.jpg"
+
+plugin :pretty_location, class_underscore: :true
+# "blog_post/aa357797-5845-451b-8662-08eecdc9f762/image/493g82jf23.jpg"
+```
+
 For a more custom identifier logic, you can overwrite the method
 `#generate_location` and call `#pretty_location` with the identifier you have
 calculated.

data/doc/processing.md

@@ -82,11 +82,18 @@ promotion:
 
 ```rb
 Shrine.plugin :backgrounding
-Shrine::Attacher.promote_block { PromoteJob.perform_later(self.class, record, name, file_data) }
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
 ```
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.create_derivatives # calls derivatives processor
     attacher.atomic_promote
@@ -102,16 +109,22 @@ Derivatives don't need to be created as part of the attachment flow, you can
 create them at any point after promotion:
 
 ```rb
-DerivativesJob.perform_later(
-  attacher.class,
-  attacher.record,
+DerivativesJob.perform_async(
+  attacher.class.name,
+  attacher.record.class.name,
+  attacher.record.id,
   attacher.name,
   attacher.file_data,
 )
 ```
 ```rb
-class DerivativesJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class DerivativesJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.create_derivatives # calls derivatives processor
     attacher.atomic_persist
@@ -144,9 +157,10 @@ end
 ```
 ```rb
 ImageUploader::THUMBNAILS.each_key do |derivative_name|
-  DerivativeJob.perform_later(
-    attacher.class,
-    attacher.record,
+  DerivativeJob.perform_async(
+    attacher.class.name,
+    attacher.record.class.name,
+    attacher.record.id,
     attacher.name,
     attacher.file_data,
     derivative_name,
@@ -154,8 +168,13 @@ ImageUploader::THUMBNAILS.each_key do |derivative_name|
 end
 ```
 ```rb
-class DerivativeJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data, derivative_name)
+class DerivativeJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data, derivative_name)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.create_derivatives(name: derivative_name)
     attacher.atomic_persist do |reloaded_attacher|

data/doc/release_notes/3.0.0.md

@@ -135,22 +135,35 @@ how to upgrade.
 
   ```rb
   Shrine.plugin :backgrounding
-  Shrine::Attacher.promote_block { PromoteJob.promote_later(self.class, record, name, file_data) }
-  Shrine::Attacher.destroy_block { DestroyJob.promote_later(self.class, data) }
+  Shrine::Attacher.promote_block do
+    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+  end
+  Shrine::Attacher.destroy_block do
+    DestroyJob.perform_async(self.class.name, data)
+  end
   ```
   ```rb
-  class PromoteJob < ActiveJob::Base
-    def perform(attacher_class, record, name, file_data)
+  class PromoteJob
+    include Sidekiq::Worker
+
+    def perform(attacher_class, record_class, record.id, name, file_data)
+      attacher_class = Object.const_get(attacher_class)
+      record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
       attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
-      attacher.atomic_promote # promote if attachment hasn't changed
+      attacher.atomic_promote
     rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-      # attachment has changed or record has been deleted, nothing to do
+      # attachment has changed or the record has been deleted, nothing to do
     end
   end
   ```
   ```rb
-  class DestroyJob < ActiveJob::Base
+  class DestroyJob
+    include Sidekiq::Worker
+
     def perform(attacher_class, data)
+      attacher_class = Object.const_get(attacher_class)
+
       attacher = attacher_class.from_data(data)
       attacher.destroy
     end
@@ -170,9 +183,10 @@ how to upgrade.
   photo = Photo.new(photo_params)
 
   photo.image_attacher.promote_block do |attacher|
-    PromoteJob.perform_later(
-      attacher.class,
-      attacher.record,
+    PromoteJob.perform_async(
+      attacher.class.name,
+      attacher.record.class.name,
+      attacher.record.id,
       attacher.name,
       attacher.file_data,
       current_user.id, # <== parameters from the controller
@@ -196,16 +210,22 @@ how to upgrade.
   implement metadata extraction in the background in a concurrency-safe way:
 
   ```rb
-  MetadataJob.perform_later(
-    attacher.class,
-    attacher.record,
+  MetadataJob.perform_async(
+    attacher.class.name,
+    attacher.record.class.name,
+    attacher.record.id,
     attacher.name,
     attacher.file_data,
   )
   ```
   ```rb
-  class MetadataJob < ActiveJob::Base
-    def perform(attacher_class, record, name, file_data)
+  class MetadataJob
+    include Sidekiq::Worker
+
+    def perform(attacher_class, record_class, record_id, name, file_data)
+      attacher_class = Object.const_get(attacher_class)
+      record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
       attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
       attacher.refresh_metadata! # extract metadata
       attacher.atomic_persist    # persist if attachment hasn't changed
@@ -215,7 +235,7 @@ how to upgrade.
   end
   ```
 
-## Other features
+## Other new plugins
 
 * The new [`mirroring`][mirroring] plugin has been added for replicating
   uploads and deletes to other storages.
@@ -272,6 +292,8 @@ how to upgrade.
   photo.image.storage_key #=> :store (permanent storage)
   ```
 
+## Other features
+
 * New `Shrine.download_response` method has been added to the
   `download_endpoint` plugin for generating file response from the controller.
 
@@ -314,10 +336,11 @@ how to upgrade.
   ```rb
   class Photo
     include ImageUploader::Attachment(:image)
-
-    image_attacher #=> #<ImageUploader::Attacher ...>
   end
   ```
+  ```rb
+  Photo.image_attacher #=> #<ImageUploader::Attacher ...>
+  ```
 
 * The attachment data serializer is now configurable (by default `JSON`
   standard library is used):
@@ -382,6 +405,17 @@ how to upgrade.
 
 ## Other Improvements
 
+### Core improvements
+
+* Shrine now works again with MRI 2.3.
+
+* The memory storage from the [shrine-memory] gem has been merged into core.
+
+  ```rb
+  # Gemfile
+  gem "shrine-memory" # this can be removed
+  ```
+
 * The `Attacher#assign` method now accepts cached file data as a Hash.
 
   ```rb
@@ -396,15 +430,36 @@ how to upgrade.
 
 * The temporary storage doesn't need to be defined anymore if it's not used.
 
-* The memory storage from the [shrine-memory] gem has been merged into core.
+* Any changes to `Shrine.storages` will now be applied to existing `Shrine` and
+  `Attacher` instances.
+
+* When copying the S3 object to another location, any specified upload options
+  will now be applied.
+
+* Deprecation of passing unknown options to `FileSystem#open` has been
+  reverted. This allows users to continue using `FileSystem` storage in tests
+  as a mock storage.
+
+* The `Shrine#upload` method now infers file extension from `filename` metadata,
+  making possible to use `filename` to specify file extension.
 
   ```rb
-  # Gemfile
-  gem "shrine-memory" # this can be removed
+  file = uploader.upload(StringIO.new("some text"), metadata: { "filename" => "file.txt" })
+  file.id #=> "2a2467ee6acbc5cb.txt"
   ```
 
-* When copying the S3 object to another location, any specified upload options
-  will now be applied.
+* The `Shrine.opts` hash is now deep-copied on subclassing. This allows plugins
+  to freely mutate hashes and arrays in `Shrine.opts`, knowing they won't be
+  shared across subclasses.
+
+* The `down` dependency has been updated to `~> 5.0`.
+
+### Plugin improvements
+
+* The `activerecord` plugin now works with Active Record 3.
+
+* Callback code from `activerecord` and `sequel` plugin has been moved into
+  attacher methods, allowing the user to override them.
 
 * The `url_options` plugin now allows you to override URL options by deleting
   them.
@@ -448,6 +503,9 @@ how to upgrade.
 * The `Derivation#upload` method from `derivation_endpoint` plugin now accepts
   any IO-like object.
 
+* The `derivation_endpoint` plugin doesn't re-open `File` objects returned in
+  derivation block anymore.
+
 * The `instrumentation` plugin now instruments `UploadedFile#open` calls as a
   new `open.shrine` event. `UploadedFile#download` is still instrumented as
   `download.shrine`.
@@ -462,29 +520,19 @@ how to upgrade.
 * Any options passed to `Attacher#attach_cached` are now forwarded to metadata
   extraction when `restore_cached_data` plugin is loaded.
 
-* Deprecation of passing unknown options to `FileSystem#open` has been
-  reverted. This allows users to continue using `FileSystem` storage in tests
-  as a mock storage.
-
-* The `activerecord` plugin now works with Active Record 3.
-
-* Shrine now works again with MRI 2.3.
-
 * The `infer_extension` plugin now works correctly with `pretty_location`
   plugin when `pretty_location` was loaded after `infer_extension`.
 
-* The `derivation_endpoint` plugin doesn't re-open `File` objects returned in
-  derivation block anymore.
-
-* Any changes to `Shrine.storages` will now be applied to existing `Shrine` and
-  `Attacher` instances.
+* The `pretty_location` plugin now accepts `:class_underscore` option for
+  underscoring class names.
 
-* Callback code from `activerecord` and `sequel` plugin has been moved into
-  attacher methods, allowing the user to override them.
+  ```rb
+  plugin :pretty_location
+  # "blogpost/aa357797-5845-451b-8662-08eecdc9f762/image/493g82jf23.jpg"
 
-* The `Shrine.opts` hash is now deep-copied on subclassing. This allows plugins
-  to freely mutate hashes and arrays in `Shrine.opts`, knowing they won't be
-  shared across subclasses.
+  plugin :pretty_location, class_underscore: :true
+  # "blog_post/aa357797-5845-451b-8662-08eecdc9f762/image/493g82jf23.jpg"
+  ```
 
 ## Backwards compatibility
 
@@ -636,8 +684,7 @@ how to upgrade.
 
 ### S3 API
 
-* The support for `aws-sdk` 2.x and `aws-sdk-s3` lower than 1.14 has been
-  removed.
+* The support for `aws-sdk` 2.x and `aws-sdk-s3` < 1.14 has been removed.
 
 * `S3#open` now raises `Shrine::FileNotFound` exception when S3 object doesn't
   exist on the bucket.

data/doc/storage/file_system.md

@@ -74,6 +74,15 @@ You can retrieve path to the file using `#path`:
 storage.path("image.jpg") #=> #<Pathname:public/image.jpg>
 ```
 
+## Deleting prefixed
+
+If you want to delete all files in some directory, you can use
+`FileSystem#delete_prefixed`:
+
+```rb
+storage.delete_prefixed("some_directory") # deletes all files in "some_directory/"
+```
+
 ## Clearing cache
 
 If you're using FileSystem as cache, you will probably want to periodically

data/doc/storage/s3.md

@@ -259,6 +259,15 @@ To use Amazon S3's [Transfer Acceleration] feature, set
 Shrine::Storage::S3.new(use_accelerate_endpoint: true, **other_options)
 ```
 
+## Deleting prefixed
+
+If you want to delete all objects in some prefix, you can use
+`S3#delete_prefixed`:
+
+```rb
+s3.delete_prefixed("some_prefix") # deletes all objects in "some_prefix/"
+```
+
 ## Clearing cache
 
 If you're using S3 as a cache, you will probably want to periodically delete

data/doc/upgrading_to_3.md

@@ -161,12 +161,21 @@ The `backgrounding` plugin has been rewritten in Shrine 3.0 and has a new API.
 
 ```rb
 Shrine.plugin :backgrounding
-Shrine::Attacher.promote_block { PromoteJob.perform_later(self.class, record, name, file_data) }
-Shrine::Attacher.destroy_block { DestroyJob.perform_later(self.class, data) }
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
 ```
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.atomic_promote
   rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
@@ -175,8 +184,12 @@ class PromoteJob < ActiveJob::Base
 end
 ```
 ```rb
-class DestroyJob < ActiveJob::Base
+class DestroyJob
+  include Sidekiq::Worker
+
   def perform(attacher_class, data)
+    attacher_class = Object.const_get(attacher_class)
+
     attacher = attacher_class.from_data(data)
     attacher.destroy
   end
@@ -191,16 +204,21 @@ both argument formats, and then switch to the new one once the jobs with old
 format have been drained.
 
 ```rb
-class PromoteJob < ActiveJob::Base
+class PromoteJob
+  include Sidekiq::Worker
+
   def perform(*args)
     if args.one?
       file_data, (record_class, record_id), name, shrine_class =
         args.first.values_at("attachment", "record", "name", "shrine_class")
 
-      record         = Object.const_get(record_class).find(record_id)
+      record         = Object.const_get(record_class).find(record_id) # if using Active Record
       attacher_class = Object.const_get(shrine_class)::Attacher
     else
-      attacher_class, record, name, file_data = args
+      attacher_class, record_class, record_id, name, file_data = args
+
+      attacher_class = Object.const_get(attacher_class)
+      record         = Object.const_get(record_class).find(record_id) # if using Active Record
     end
 
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
@@ -211,7 +229,9 @@ class PromoteJob < ActiveJob::Base
 and
 ```
 ```rb
-class DestroyJob < ActiveJob::Base
+class DestroyJob
+  include Sidekiq::Worker
+
   def perform(*args)
     if args.one?
       data, shrine_class = args.first.values_at("attachment", "shrine_class")
@@ -220,6 +240,8 @@ class DestroyJob < ActiveJob::Base
       attacher_class = Object.const_get(shrine_class)::Attacher
     else
       attacher_class, data = args
+
+      attacher_class = Object.const_get(attacher_class)
     end
 
     attacher = attacher_class.from_data(data)
@@ -393,8 +415,13 @@ If you're using the `backgrounding` plugin, you can trigger derivatives
 creation in the `PromoteJob` instead of the controller:
 
 ```rb
-class PromoteJob < ActiveJob::Base
-  def perform(attacher_class, record, name, file_data)
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record.id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
     attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
     attacher.create_derivatives # call derivatives processor
     attacher.atomic_promote

data/lib/shrine.rb

@@ -273,7 +273,7 @@ class Shrine
     # Generates a basic location for an uploaded file
     def basic_location(io, metadata:)
       extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
-      extension ||= File.extname(extract_filename(io).to_s).downcase
+      extension ||= File.extname(metadata["filename"].to_s).downcase
       basename    = generate_uid(io)
 
       basename + extension

data/lib/shrine/plugins/pretty_location.rb

@@ -34,9 +34,17 @@ class Shrine
           record.public_send(opts[:pretty_location][:identifier])
         end
 
+        def transform_class_name(class_name)
+          if opts[:pretty_location][:class_underscore]
+            class_name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+          else
+            class_name.downcase
+          end
+        end
+
         def record_namespace(record)
           class_name = record.class.name or return
-          parts      = class_name.downcase.split("::")
+          parts      = transform_class_name(class_name).split("::")
 
           if separator = opts[:pretty_location][:namespace]
             parts.join(separator)

data/lib/shrine/plugins/remote_url.rb

@@ -66,12 +66,12 @@ class Shrine
 
         def download_remote_url(url, options)
           opts[:remote_url][:downloader].call(url, options)
-        rescue Down::NotFound
-          fail DownloadError, "remote file not found"
         rescue Down::TooLarge
           fail DownloadError, "remote file too large"
+        rescue Down::Error
+          fail DownloadError, "remote file not found"
         rescue DownloadError
-          fail
+          fail # re-raise
         end
 
         # Sends a `remote_url.shrine` event for instrumentation plugin.

data/lib/shrine/storage/file_system.rb

@@ -70,6 +70,16 @@ class Shrine
         path(id).exist?
       end
 
+      # If #prefix is not present, returns a path composed of #directory and
+      # the given `id`. If #prefix is present, it excludes the #directory part
+      # from the returned path (e.g. #directory can be set to "public" folder).
+      # Both cases accept a `:host` value which will be prefixed to the
+      # generated path.
+      def url(id, host: nil, **options)
+        path = (prefix ? relative_path(id) : path(id)).to_s
+        host ? host + path : path
+      end
+
       # Delets the file, and by default deletes the containing directory if
       # it's empty.
       def delete(id)
@@ -79,14 +89,11 @@ class Shrine
       rescue Errno::ENOENT
       end
 
-      # If #prefix is not present, returns a path composed of #directory and
-      # the given `id`. If #prefix is present, it excludes the #directory part
-      # from the returned path (e.g. #directory can be set to "public" folder).
-      # Both cases accept a `:host` value which will be prefixed to the
-      # generated path.
-      def url(id, host: nil, **options)
-        path = (prefix ? relative_path(id) : path(id)).to_s
-        host ? host + path : path
+      # Deletes the specified directory on the filesystem.
+      #
+      #    file_system.delete_prefixed("somekey/derivatives")
+      def delete_prefixed(delete_prefix)
+        FileUtils.rm_rf directory.join(delete_prefix)
       end
 
       # Deletes all files from the #directory. If a block is passed in, deletes

data/lib/shrine/storage/linter.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "shrine"
 
 require "forwardable"
@@ -30,19 +28,32 @@ class Shrine
         new(*args).call
       end
 
-      def initialize(storage, action: :error)
-        @storage = storage
-        @action  = action
+      def initialize(storage, action: :error, nonexisting: "nonexisting")
+        @storage     = storage
+        @action      = action
+        @nonexisting = nonexisting
       end
 
       def call(io_factory = default_io_factory)
-        storage.upload(io_factory.call, id = "foo".dup, {})
+        storage.upload(io_factory.call, id = "foo", {})
 
         lint_open(id)
         lint_exists(id)
         lint_url(id)
         lint_delete(id)
 
+        if storage.respond_to?(:delete_prefixed)
+          storage.upload(io_factory.call, id1 = "a/a/a")
+          storage.upload(io_factory.call, id2 = "a/a/b")
+          storage.upload(io_factory.call, id3 = "a/aaa/a")
+
+          lint_delete_prefixed(prefix: "a/a",
+                               expect_deleted: [id1, id2],
+                               expect_remaining: [id3])
+
+          storage.delete(id3)
+        end
+
         if storage.respond_to?(:clear!)
           storage.upload(io_factory.call, id = "quux".dup)
           lint_clear(id)
@@ -51,6 +62,8 @@ class Shrine
         if storage.respond_to?(:presign)
           lint_presign(id)
         end
+
+        true
       end
 
       def lint_open(id)
@@ -60,7 +73,7 @@ class Shrine
         opened.close
 
         begin
-          storage.open("nonexisting", {})
+          storage.open(@nonexisting, {})
           error :open, "should raise an exception on nonexisting file"
         rescue Shrine::FileNotFound
         rescue => exception
@@ -100,6 +113,20 @@ class Shrine
         error :presign, "result should include :url key" unless data.to_h.key?(:url)
       end
 
+      def lint_delete_prefixed(prefix:, expect_deleted:, expect_remaining:)
+        storage.delete_prefixed(prefix)
+
+        expect_deleted.each do |key|
+          next unless storage.exists?(key)
+          error :delete_prefixed, "#{key} still #exists? after #clear_prefix('a/a/')"
+        end
+
+        expect_remaining.each do |key|
+          next if storage.exists?(key)
+          error :delete_prefixed, "#{key} doesn't #exists? but should after #clear_prefix('a/a/')"
+        end
+      end
+
       private
 
       attr_reader :storage

data/lib/shrine/storage/memory.rb

@@ -26,12 +26,16 @@ class Shrine
         store.key?(id)
       end
 
+      def url(id, *)
+        "memory://#{id}"
+      end
+
       def delete(id)
         store.delete(id)
       end
 
-      def url(id, *)
-        "memory://#{id}"
+      def delete_prefixed(delete_prefix)
+        store.delete_if { |k, _v| k.start_with?(delete_prefix + "/") }
       end
 
       def clear!

data/lib/shrine/storage/s3.rb

@@ -205,6 +205,16 @@ class Shrine
         object(id).delete
       end
 
+      # Deletes objects at keys starting with the specified prefix.
+      #
+      #    s3.delete_prefixed("somekey/derivatives")
+      def delete_prefixed(delete_prefix)
+        # We need to make sure to combine with storage prefix, and
+        # that it ends in '/' cause S3 can be squirrely about matching interior.
+        absolute_prefix = [*prefix, delete_prefix + "/"].join("/")
+        bucket.objects(prefix: absolute_prefix).batch_delete!
+      end
+
       # If block is given, deletes all objects from the storage for which the
       # block evaluates to true. Otherwise deletes all objects from the storage.
       #

data/lib/shrine/version.rb

@@ -9,7 +9,7 @@ class Shrine
     MAJOR = 3
     MINOR = 0
     TINY  = 0
-    PRE   = "beta3"
+    PRE   = "rc"
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
   end

data/shrine.gemspec

@@ -33,7 +33,7 @@ direct uploads for fully asynchronous user experience.
   gem.files        = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*.rb", "shrine.gemspec", "doc/**/*.md"]
   gem.require_path = "lib"
 
-  gem.add_dependency "down", "~> 4.1"
+  gem.add_dependency "down", "~> 5.0"
   gem.add_dependency "content_disposition", "~> 1.0"
 
   # general testing helpers

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 3.0.0.beta3
+  version: 3.0.0.rc
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-25 00:00:00.000000000 Z
+date: 2019-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: content_disposition
   requirement: !ruby/object:Gem::Requirement