shrine 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 583eed751bfa6c1ae0ad5d9495509091563a8c02
-  data.tar.gz: 9c82a62a10a45df20f3f4d9422066beb705cfa39
+  metadata.gz: 11b0d1c76734507b02ec22fb1ae1aef8a8c704e7
+  data.tar.gz: 397c1df52d016428395879fbc8bfba4c0dbb7db7
 SHA512:
-  metadata.gz: 68e093c6b118b379383305bfede12fd5710342c82c6b66040661be744d6995a723147f3b426b0d8afc03009c35d3b21a529232822e9232d2c25531d831fd973b
-  data.tar.gz: 41fabbd7fa515c3eb992bbbf5205fd924d502c64ec6f430d053ef135512e2476797435a5a4642fd066ea9bd8ba0b375455317a6bc54aaabcf24b557841b98de1
+  metadata.gz: ad5a997b948d19f19fd636502886fe1398deda24be00d5028aabaaabe17c99dd5251c50a4da976c0a7bd1025f9edec0243b2d8dbf67b5115605e3f74c30f7903
+  data.tar.gz: fa8e72de26ecafcbf0be585f25c495072b7502d50c018449a0071171de11e4501df43b75a074cb70968219ad9eb4259138669e86f58e9a2280f7f67b80b33a12

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:
+Here's a basic example showing how the file upload works in Shrine:
 
 ```rb
 require "shrine"
@@ -45,12 +45,13 @@ uploaded_file.data #=>
 
 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 `Shrine#upload` the following happens:
+with the storage name, and when we call `#upload` Shrine does the following:
 
-* a unique location is generated for the file
-* metadata is extracted from the file
-* the underlying storage is called to store the file
-* a `Shrine::UploadedFile` is returned with these data
+* generates a unique location for the file
+* extracts metadata from the file
+* uploads the file using the underlying storage
+* closes the file
+* returns a `Shrine::UploadedFile` with relevant data
 
 The argument to `Shrine#upload` needs to be an IO-like object. So, `File`,
 `Tempfile` and `StringIO` are all valid arguments. But the object doesn't have
@@ -80,8 +81,8 @@ uploaded_file.delete
 ## Attachment
 
 In web applications, instead of managing files directly, we rather want to
-treat them as "attachments" to models and to tie them to the lifecycle of
-records. In Shrine we do this by generating and including "attachment" modules.
+treat them as "attachments" to recod 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:
 
@@ -89,13 +90,14 @@ Firstly we need to assign the special `:cache` and `:store` storages:
 require "shrine/storage/file_system"
 
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/cache"),
-  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/store"),
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"),
 }
 ```
 
-Next we should create an uploader specific to the type of files we're
-uploading:
+These storages will by default be used for caching and storing attachments, but
+you can use additional storages with the `default_storage` plugin. Next we
+should create an uploader specific to the type of files we're uploading:
 
 ```rb
 class ImageUploader < Shrine
@@ -118,7 +120,7 @@ Now our model has gained special methods for attaching avatars:
 
 ```rb
 user = User.new
-user.avatar = File.open("avatar.jpg") # uploads the file to `:cache`
+user.avatar = File.open("avatar.jpg") # uploads the file to cache
 user.avatar      #=> #<Shrine::UploadedFile>
 user.avatar_url  #=> "/uploads/9260ea09d8effd.jpg"
 user.avatar_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
@@ -145,17 +147,35 @@ 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.
 
+This is how you would typically create the form for a `@user`:
+
+```erb
+<form action="/users" method="post" enctype="multipart/form-data">
+  <input name="user[avatar]" type="hidden" value="<%= @user.avatar_data %>">
+  <input name="user[avatar]" type="file">
+</form>
+```
+
+The "file" field is for file upload, while the "hidden" field is to make the
+file persist in case of validation errors, and for direct uploads. This code
+works because `#avatar=` also accepts already cached files via their JSON
+representation:
+
+```rb
+user.avatar = '{"id":"9jsdf02kd", "storage":"cache", "metadata": {...}}'
+```
+
 ### ORM
 
 Your models probably won't be POROs, so Shrine ships with plugins for
-Sequel and ActiveRecord ORMs. Shrine uses the "\<attachment\>\_data" column
+Sequel and ActiveRecord ORMs. Shrine uses the `<attachment>_data` column
 for storing attachments, so you'll need to add it in a migration:
 
 ```rb
-add_column :users, :avatar_data, :text # or a "jsonb" column if you need querying
+add_column :users, :avatar_data, :text # or a JSON column
 ```
 ```rb
-Shrine.plugin :sequel
+Shrine.plugin :sequel # or :activerecord
 ```
 ```rb
 class User < Sequel::Model
@@ -175,30 +195,17 @@ user.destroy
 user.avatar.exists? #=> false
 ```
 
-This is how you would typically create the form for a `@user`:
-
-```erb
-<form action="/users" method="post" enctype="multipart/form-data">
-  <input name="user[avatar]" type="hidden" value="<%= @user.avatar_data %>">
-  <input name="user[avatar]" type="file">
-</form>
-```
-
-The "file" field is for file upload, while the "hidden" field is to make the
-file persist in case of validation errors, and for direct uploads.
-
 ## Direct uploads
 
-Shrine comes with a `direct_upload` plugin which provides an endpoint
-(implemented in [Roda]) that can be used for AJAX 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):
 
 ```rb
 Shrine.plugin :direct_upload # Provides a Roda endpoint
 ```
 ```rb
 Rails.application.routes.draw do
-  # adds `POST /attachments/images/:storage/:name`
-  mount ImageUploader.direct_endpoint => "/attachments/images"
+  mount ImageUploader::UploadEndpoint => "/attachments/images"
 end
 ```
 ```rb
@@ -214,21 +221,9 @@ end
 }
 ```
 
-There are many great JavaScript libraries for AJAX file uploads, for example
-this is how we could hook up [jQuery-File-Upload] to our endpoint:
-
-```js
-$('[type="file"]').fileupload({
-  url: '/attachments/images/cache/avatar',
-  paramName: 'file',
-  done: function(e, data) { $(this).prev().value(data.result) }
-});
-```
-
-This is an oversimplified implementation without any UX, it's just to show you
-how easy it is. The `direct_upload` plugin also provides a route for direct S3
-uploads, see the [example app] for how you can do multiple uploads directly to
-S3.
+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
 
@@ -248,8 +243,8 @@ end
 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.
+"uploaded" to cache on assignment, and then the cached file is reuploaded to
+store on save.
 
 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
@@ -271,8 +266,8 @@ end
 ```
 
 Notice that we needed to call `io.download`. This is because the original file
-was already stored to `:cache`, and now this cached file is being uploaded to
-`:store`. The cached file is an instance of `Shrine::UploadedFile`, but for
+was already stored to cache, and now this cached file is being uploaded to
+store. The cached file is an instance of `Shrine::UploadedFile`, but for
 processing we need to work with actual files, so we first need to download it.
 
 In general, processing works in a way that if `#process` returns a file, Shrine
@@ -456,20 +451,6 @@ class ImageUploader < Shrine
 end
 ```
 
-## Default URL
-
-When attachment is missing, `user.avatar_url` by default returns nil. This
-because it internally calls `Shrine#default_url`, which returns nil unless
-overriden. For custom default URLs simply override the method:
-
-```rb
-class ImageUploader < Shrine
-  def default_url(context)
-    "/images/fallback/#{context[:name]}.png"
-  end
-end
-```
-
 ## Locations
 
 By default files will all be put in the same folder. If you want that each
@@ -489,73 +470,75 @@ If you want to generate your own locations, simply override
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, context)
-    # your custom logic
+    "#{context[:record].class}/#{context[:record].id}/#{io.original_filename}"
   end
 end
 ```
 
-Note that in this case should be careful to make the locations unique,
-otherwise dirty tracking won't be detected properly (you can use
-`Shrine#generate_uid`).
+Note that in this case should make your locations unique, 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`
 
 ```rb
 file = File.open("avatar.jpg")
-Shrine.new(:store).upload(file, location: "a/specific/location.jpg")
+Shrine.new(:store).upload(file, location: "some/specific/location.jpg")
 ```
 
-## Amazon S3
+## Storage
 
-So far in the examples we've only used the FileSystem storage. However, Shrine
-also ships with S3 storage (which internally uses the [aws-sdk] gem).
+Other than [FileSystem], Shrine also ships with [S3] storage:
 
-```
+```rb
 gem "aws-sdk", "~> 2.1"
 ```
-
-It's typically good to use FileSystem for `:cache`, and S3 for `:store`:
-
 ```rb
-require "shrine"
-require "shrine/storage/file_system"
 require "shrine/storage/s3"
 
-s3_options = {
+Shrine.storages[:store] = Shrine::Storage::S3.new(
   access_key_id:     "<ACCESS_KEY_ID>",      # "xyz"
   secret_access_key: "<SECRET_ACCESS_KEY>",  # "abc"
   region:            "<REGION>",             # "eu-west-1"
   bucket:            "<BUCKET>",             # "my-app"
-}
-
-Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads"),
-  store: Shrine::Storage::S3.new(s3_options),
-}
+)
 ```
 
 ```rb
 user = User.new(avatar: File.open(:avatar))
 user.avatar.url #=> "/uploads/j4k343ui12ls9.jpg"
 user.save
-user.avatar.url #=> "https://s3-sa-east-1.amazonaws.com/my-bucket/0943sf8gfk13.jpg"
+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
-execute an S3 COPY command if possible, which avoids reuploading the file.
-Also, the `versions` plugin takes advantage of S3's MULTI DELETE capabilities,
-so versions are deleted with a single HTTP request.
+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
+`versions` plugin takes advantage of S3's MULTI DELETE capabilities, so
+versions are deleted with a single HTTP request.
+
+See the full documentation for [FileSystem] and [S3] storages. There are also
+many other Shrine storages available, see the [Plugins & Storages] section.
+
+### Clearing cache
+
+You will want to periodically clean your cache storage. Amazon S3 provides [a
+built-in solution](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html),
+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
+```
 
 ## Background jobs
 
-Unlike other uploading libraries, Shrine embraces that putting phases of file
-upload into background jobs is essential for scaling and good user experience,
-so it ships with `background_helpers` plugin which makes backgrounding really
-easy:
+Shrine is the first uploading library designed from day one to be used with
+background jobs. Backgrounding parts of file upload is essential for scaling
+and good user experience, and Shrine provides a `backgrounding` plugin which
+makes it really easy to plug in your backgrounding library:
 
 ```rb
-Shrine.plugin :background_helpers
+Shrine.plugin :backgrounding
 Shrine::Attacher.promote { |data| UploadJob.perform_async(data) }
 Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
 ```
@@ -580,61 +563,27 @@ The above puts all promoting (moving to store) and deleting of files into a
 background Sidekiq job. Obviously instead of Sidekiq you can just as well use
 any other backgrounding library.
 
-### Seamless user experience
-
-In combination with direct upload for caching, this provides a completely
-seamless user experience. First the user ansynchronosuly caches the file and
-hopefully sees a nice progress bar. After this is finishes and user submits the
-form, promoting will be kicked off into a background job, and the record will
-be saved with the cached file If your cache is public (e.g. in the "public"
-folder), the end user will immediately see their uploaded file, because the URL
-will point to the cached version.
-
-In the meanwhile, what `#promote` does is it uploads the cached file `:store`,
-and writes the stored file to the column. When the record gets saved, the URL
-will switch from filesystem to S3, but the user won't even notice that
-something happened, because they will still see the same file.
-
-### Generality
-
-This solution is completely agnostic about what kind of attachment it is
-uploading/deleting, and for which model. This means that all attachments can
-use this same worker. Also, there is no need for any extra columns.
-
-### Safety
-
-It is possible that the user changes their mind and reuploads a new file before
-the background job finished promoting. With a naive implementation, this means
-that after uploading a new file, there can happen a brief moment where the user
-sees the old file again, which can be upsetting.
-
-Shrine handles this gracefully. After `#promote` uploads the cached file to
-`:store`, it checks if the cached file still matches the file in the record
-column. If the files are different, that means the user uploaded a new
-attachment, and Shrine won't do the replacement. Additionally, this job is
-idempotent, meaning it can be safely repeated in case of failure.
-
-## Clearing cache
-
-Your `:cache` storage will grow over time, so you'll want to periodically clean
-it. If you're using FileSystem as your `:cache`, you can put this in a
-scheduled job:
-
-```rb
-file_system = Shrine.storages[:cache]
-file_system.clear!(older_than: 1.week.ago) # adjust the time
-```
-
-If your `:cache` is S3, Amazon provides settings for automatic cache clearing,
-see [this article](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html).
+The main advantages of Shrine's backgrounding support over other file upload
+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.
+* **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.
+* **Generality** – The above solution will automatically work for all uploaders,
+  types of files and models.
+* **Safety** – All of Shrine's code has been designed to take delayed storing
+  into account, so concurrency issues should be nonexistent.
 
 ## Plugins
 
-Shrine comes with a small core which provides only the essential functionality.
-However, it comes with a lot of additional features which can be loaded via
-plugins. This way you can choose exactly how much Shrine does for you. Shrine
-itself [ships with over 25 plugins], most of them I haven't managed to cover
-here.
+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.
 
 The plugin system respects inheritance, so you can choose which plugins will
 be applied to which uploaders:
@@ -670,5 +619,8 @@ The gem is available as open source under the terms of the [MIT License].
 [plugin system]: http://twin.github.io/the-plugin-system-of-sequel-and-roda/
 [MIT License]: http://opensource.org/licenses/MIT
 [example app]: https://github.com/janko-m/shrine-example
-[ships with over 25 plugins]: http://shrinerb.com#plugins
+[ships with over 35 plugins]: http://shrinerb.com#plugins
 [introductory blog post]: http://twin.github.io/introducing-shrine/
+[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

data/doc/carrierwave.md

@@ -25,8 +25,8 @@ instantiate uploaders with a specific storage.
 require "shrine/storage/file_system"
 
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/cache"),
-  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/store"),
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"),
 }
 ```
 ```rb
@@ -105,12 +105,12 @@ for store. If you want to change that, you can use the `default_storage`
 plugin:
 
 ```rb
-Shrine.storages[:dropbox] = Shrine::Storage::Dropbox.new(*args)
+Shrine.storages[:foo] = Shrine::Storage::Foo.new(*args)
 ```
 
 ```rb
 class ImageUploader
-  plugin :default_storage, store: :dropbox
+  plugin :default_storage, store: :foo
 end
 ```
 
@@ -185,10 +185,7 @@ storages:
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, context)
-    case storage_key
-    when :cache then "..."
-    when :store then "..."
-    end
+    "#{context[:record].class}/#{context[:record].id}/#{io.original_filename}"
   end
 end
 ```
@@ -199,13 +196,12 @@ for automatically generating an organized folder structure.
 
 #### `#default_url`
 
-Similarly to CarrierWave, you also provide default URLs be overriding the
-method:
+For default URLs you can use the `default_url` plugin:
 
 ```rb
 class ImageUploader < Shrine
-  def default_url(context)
-    # ...
+  plugin :default_url do |context|
+    "/attachments/#{context[:name]}/default.jpg"
   end
 end
 ```
@@ -264,10 +260,10 @@ end
 
 #### `#recreate_versions!`
 
-Shrine doesn't provide an automatic mechanism for recreating versions, because
-that is very individual for different situations. For example, sometimes you want to
-regenerate all versions and sometimes just one. However, I wrote a guide
-"[Regenerating versions]" that should help you out with that.
+Shrine doesn't have a built-in way of regenerating versions, because that's
+very individual and depends on what versions you want regenerated, what ORM are
+you using, how many records there are in your database etc. The [Regenerating
+versions] guide provides some useful tips on this task.
 
 ### Models