shrine 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 27f5213f9cac952b0947848a6f9b518ca5ed6705
-  data.tar.gz: d343abd428ddc64dec6d9a049509acdeebe90692
+  metadata.gz: b4039e8d8350766e0bbe1555e0039672f4224915
+  data.tar.gz: b8200b69674d031d15c82fd19e704eee55d049b9
 SHA512:
-  metadata.gz: f33bf01e38fa6e854467121d0d92f640491977d234a1201c7c4187503e889965ba797e54f3d05d561e8862bbe32c82edf2cbda6e63ab1557f222ce225613322a
-  data.tar.gz: 32351b7cb1fb3afd6bf31d206096fe034b038ed518950dbf82ca95cca8e4c718168ff4c50a5467c671e1d3a04ef7469e15c20ff61724edae416ebe31c7ffa0c3
+  metadata.gz: 0cf6ec31cb22d1396575720a5a8543f71875e9a5c9851ea1f8311aec34a5ef1dc1c83be64b32434dac3e825dd3b52c06bd9035eb15a02fe11572cbceb9584c45
+  data.tar.gz: 49ac2e4d1065b37733c82b7dacb8498db1784a2c7c2dadfb643b8d2348d9b8fea0ca84062dafa1dc7ce836ef142a101202b83abe2870003a7d803dd2230ace5c

data/README.md

@@ -2,8 +2,8 @@
 
 Shrine is a toolkit for file attachments in Ruby applications.
 
-If you're new, you're encouraged to read the [introductory blog post] which
-explains the motivation behind Shrine.
+If you're not sure why you should care, you're encouraged to read the
+[motivation behind creating Shrine][motivation].
 
 ## Resources
 
@@ -14,7 +14,8 @@ explains the motivation behind Shrine.
 
 ## Quick start
 
-Add Shrine to the Gemfile and write an initializer:
+Add Shrine to the Gemfile and write an initializer which sets up the storage and
+loads the ORM plugin:
 
 ```rb
 gem "shrine"
@@ -25,16 +26,17 @@ require "shrine"
 require "shrine/storage/file_system"
 
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
-  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"),
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"), # permanent
 }
 
 Shrine.plugin :sequel # :activerecord
 Shrine.plugin :cached_attachment_data # for forms
 ```
 
-Next write a migration to add a column which will hold attachment data, and run
-it:
+Next decide how you will name the attachment attribute on your model, and run a
+migration that adds an `<attachment>_data` text column, which Shrine will use
+to store all information about the attachment:
 
 ```rb
 Sequel.migration do                           # class AddImageDataToPhotos < ActiveRecord::Migration
@@ -45,7 +47,7 @@ end                                           # end
 ```
 
 Now you can create an uploader class for the type of files you want to upload,
-and make your model handle attachments:
+and add the attachment attribute to your model which will accept files:
 
 ```rb
 class ImageUploader < Shrine
@@ -59,8 +61,11 @@ class Photo < Sequel::Model # ActiveRecord::Base
 end
 ```
 
-This creates an `image` attachment attribute which accepts files. Let's now
-add the form fields needed for attaching files:
+Let's now add the form fields needed for attaching files. We need a file
+field for choosing files, and a hidden field for retaining the uploaded file
+in case of validation errors and [direct uploads]. Note that the file field
+needs to go *after* the hidden field, so that attaching a new file can always
+override whatever is in the hidden field.
 
 ```erb
 <form action="/photos" method="post" enctype="multipart/form-data">
@@ -75,17 +80,22 @@ add the form fields needed for attaching files:
 <% end %>
 ```
 
-Now assigning the request parameters in your router/controller will
-automatically handle the image attachment:
+Note the `enctype="multipart/form-data"` HTML attribute, which is required for
+submitting files through the form. The Rails form builder will automatically
+generate it for you when you add a file field.
+
+Now in your router/controller the attachment request parameter can be assigned
+to the model like any other attribute. Note that for non-Rails apps you will
+need to load the `rack_file` plugin which handles Rack's uploaded file hash.
 
 ```rb
 post "/photos" do
   Photo.create(params[:photo])
+  # ...
 end
 ```
 
-When a Photo is created with the image attached, you can display the image via
-its URL:
+Finally, you can use the URL of the attached file to display it:
 
 ```erb
 <img src="<%= @photo.image_url %>">
@@ -93,7 +103,7 @@ its URL:
 
 ## Attachment
 
-When we assign an IO-like object to the record, Shrine will upload it to the
+When we assign an IO object to the record, Shrine will upload it to the
 registered `:cache` storage, which acts as a temporary storage, and write the
 location, storage, and metadata of the uploaded file to a single
 `<attachment>_data` column:
@@ -112,13 +122,17 @@ The Shrine attachment module added the following methods to the `Photo` model:
 * `#image=` – caches the file and saves the result into `image_data`
 * `#image` – returns `Shrine::UploadedFile` instantiated from `image_data`
 * `#image_url` – calls `image.url` if attachment is present, otherwise returns nil
-* `#image_attacher` - instance of `Shrine::Attacher` which handles attaching
+* `#image_attacher` – returns instance of `Shrine::Attacher` which handles attaching
 
 In addition to assigning new files, you can also assign already cached files
 using their JSON representation:
 
 ```rb
-photo.image = '{"storage":"cache","id":"9260ea09d8effd.jpg","metadata":{...}}'
+photo.image = '{
+  "storage": "cache",
+  "id": "9260ea09d8effd.jpg",
+  "metadata": { ... }
+}'
 ```
 
 This allows Shrine to retain uploaded files in case of validation errors, and
@@ -161,6 +175,29 @@ class Movie < Sequel::Model
 end
 ```
 
+### Attacher
+
+The model attachment interface under-the-hood just delegates to a
+`Shrine::Attacher` object. If whether you don't want to add additional methods
+to your model, prefer explicitness over callbacks, or use Shrine with custom
+models, you can use `Shrine::Attacher` directly:
+
+```rb
+attacher = ImageUploader::Attacher.new(photo, :image) # equivalent to `photo.image_attacher`
+
+attacher.cache #=> #<ImageUploader @storage_key=:cache>
+attacher.store #=> #<ImageUploader @storage_key=:store>
+
+attacher.assign(file) # equivalent to `photo.image = file`
+attacher.get          # equivalent to `photo.image`
+attacher.url          # equivalent to `photo.image_url`
+
+attacher.finalize     # promotes cached file to store, deletes old attachment (after save callback)
+attacher.destroy      # deletes attachment (after destory callback)
+```
+
+See [Using Attacher] guide for more details.
+
 ### Multiple files
 
 Sometimes we want to allow users to upload multiple files at once. This can be
@@ -179,11 +216,14 @@ into nested association attributes in the controller.
 ## Uploader
 
 "Uploaders" are subclasses of `Shrine`, and this is where we define all our
-attachment logic. Uploaders act as a wrappers around a storage, delegating all
-service-specific logic to the storage. They don't know anything about models
-and are stateless; they are only in charge of uploading, processing and
-deleting files.
+attachment logic. Uploader objects act as a wrappers around a storage; they
+don't know anything about models, and are stateless.
 
+```rb
+class DocumentUploader < Shrine
+  # document uploading logic
+end
+```
 ```rb
 uploader = DocumentUploader.new(:store)
 uploaded_file = uploader.upload(File.open("resume.pdf"))
@@ -191,6 +231,14 @@ uploaded_file #=> #<Shrine::UploadedFile>
 uploaded_file.to_json #=> '{"storage":"store","id":"0sdfllasfi842.pdf","metadata":{...}}'
 ```
 
+The `Shrine#upload` method does the following:
+
+* calls processing
+* extracts metadata
+* generates unique location
+* uploads file(s) (this is where the storage is called)
+* closes uploaded file(s)
+
 Shrine requires the input for uploading to be an IO-like object. So, `File`,
 `Tempfile` and `StringIO` instances are all valid inputs. The object doesn't
 have to be an actual IO, it's enough that it responds to: `#read(*args)`,
@@ -205,7 +253,7 @@ uploaded_file.url      #=> "uploads/938kjsdf932.mp4"
 uploaded_file.metadata #=> {...}
 uploaded_file.download #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20151004-74201-1t2jacf.mp4>
 uploaded_file.exists?  #=> true
-uploaded_file.open { |io| ... }
+uploaded_file.open { |io| io.read }
 uploaded_file.delete
 # ...
 ```
@@ -224,8 +272,8 @@ and any additional features are available via plugins. This way you can choose
 exactly what and how much Shrine does for you. See the [website] for a complete
 list of plugins.
 
-The plugin system respects inheritance, so you can choose which plugins will
-be applied to which uploaders:
+The plugin system respects inheritance, so you can choose to load a plugin
+globally or only for a specific uploader.
 
 ```rb
 Shrine.plugin :logging # enables logging for all uploaders
@@ -274,8 +322,8 @@ class ImageUploader < Shrine
 end
 ```
 
-Since here `io` is a cached `Shrine::UploadedFile`, we need to download it to
-a `File`, which is what image_processing recognizes.
+Here the `io` is a cached `Shrine::UploadedFile`, so we need to download it to
+a `File`, since this is what image_processing gem recognizes.
 
 ### Versions
 
@@ -305,11 +353,11 @@ class ImageUploader < Shrine
 end
 ```
 
-Being able to define processing on instance-level like this provides a lot of
-flexibility. For example, you can choose to process files in a certain order
-for maximum performance, and you can also add parallelization. It is
-recommended to load the `delete_raw` plugin for automatically deleting processed
-files after uploading.
+By defining processing on instance-level Shrine gives you a lot of flexibility.
+You could choose the processing order which yields the best performance, even
+add parallelization, and when processing logic gets complex you could extract
+everything into a PORO class. It is recommended to load the `delete_raw` plugin
+so that processed files are automatically deleted after uploading.
 
 Each version will be saved to the attachment column, and the attachment getter
 will simply return a Hash of `Shrine::UploadedFile` objects:
@@ -356,6 +404,41 @@ class VideoUploader < Shrine
 end
 ```
 
+### Triggering processing
+
+Whenever a file is uploaded by the attacher, an additional `:action` parameter
+is added to the context, which holds a symbol name describing what the file was
+uploaded for. For example, for caching files `action: :cache` will be sent, for
+promoting `action: :store`, while for backing up attacher sends `action:
+:backup`.
+
+The argument to the `process` declaration is the name of that action. When
+uploading via the uploader, you can add `:action` option with the value of the
+processing block you want performed before uploading.
+
+```rb
+uploader = ImageUploader.new(:store)
+uploader.upload(file, action: :store) # performs processing defined under ":store"
+```
+
+You can also define and call processing for a custom action:
+
+```rb
+class ImageUploader < Shrine
+  process(:my_action) { |io, context| special_processing(io) }
+end
+```
+```rb
+uploader.upload(file, action: :my_action)
+```
+
+Finally, you can also call defined processing directly, without uploading the
+results, using `Shrine#process`.
+
+```rb
+uploader.process(file, action: :my_action) # returns processed files without uploading
+```
+
 ## Context
 
 You may have noticed the `context` variable floating around as the second
@@ -371,57 +454,24 @@ to uploaded file, and can contain useful information depending on the situation:
 The `context` is useful for doing conditional processing, validation,
 generating location etc, and it is also used by some plugins internally.
 
-## Validation
-
-Validations are registered inside a `Attacher.validate` block, and you can load
-the `validation_helpers` plugin to get some convenient file validation methods:
-
 ```rb
 class VideoUploader < Shrine
-  plugin :validation_helpers
-
-  Attacher.validate do
-    validate_max_size 50*1024*1024, message: "is too large (max is 50 MB)"
-    validate_mime_type_inclusion ["video/mp4"]
-  end
-end
-```
-
-```rb
-trailer = Trailer.new
-trailer.video = File.open("matrix.mp4")
-trailer.valid? #=> false
-trailer.errors.to_hash #=> {video: ["is too large (max is 50 MB)"]}
-```
-
-You can also do custom validations:
-
-```rb
-class VideoUploader < Shrine
-  Attacher.validate do
-    errors << "is longer than 5 minutes" if get.duration > 300
+  process(:store) do |io, context|
+    trim_video(io, 300) if context[:record].guest?
   end
 end
 ```
 
-The `Attacher.validate` block is executed in context of a `Shrine::Attacher`
-instance:
+The context is just a hash that is passed to the uploader methods. If you're
+using the uploader directly, you can pass the context directly:
 
 ```rb
-class VideoUploader < Shrine
-  Attacher.validate do
-    self   #=> #<Shrine::Attacher>
-
-    get    #=> #<Shrine::UploadedFile>
-    record # the model instance
-    errors # array of error messages for this file
-  end
-end
+uploader.upload(file, {foo: "bar"}) # passing context hash directly
 ```
 
 ## Metadata
 
-Shrine automatically extracts and stores general file metadata:
+Shrine automatically extracts and stores available file metadata:
 
 ```rb
 photo = Photo.create(image: image)
@@ -480,6 +530,54 @@ photo.image.metadata["exif"]
 photo.image.exif
 ```
 
+## Validation
+
+Validations are registered inside a `Attacher.validate` block, and you can load
+the `validation_helpers` plugin to get some convenient file validation methods:
+
+```rb
+class VideoUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 50*1024*1024, message: "is too large (max is 50 MB)"
+    validate_mime_type_inclusion ["video/mp4"]
+  end
+end
+```
+
+```rb
+trailer = Trailer.new
+trailer.video = File.open("matrix.mp4")
+trailer.valid? #=> false
+trailer.errors.to_hash #=> {video: ["is too large (max is 50 MB)"]}
+```
+
+You can also do custom validations:
+
+```rb
+class VideoUploader < Shrine
+  Attacher.validate do
+    errors << "is longer than 5 minutes" if get.duration > 300
+  end
+end
+```
+
+The `Attacher.validate` block is executed in context of a `Shrine::Attacher`
+instance:
+
+```rb
+class VideoUploader < Shrine
+  Attacher.validate do
+    self   #=> #<Shrine::Attacher>
+
+    get    #=> #<Shrine::UploadedFile>
+    record # the model instance
+    errors # array of error messages for this file
+  end
+end
+```
+
 ## Locations
 
 Before Shrine uploads a file, it generates a random location for it. By
@@ -568,11 +666,22 @@ uploader = MyUploader.new(:store)
 uploader.upload(file, upload_options: {acl: "private"})
 ```
 
+### Clearing cache
+
+From time to time you'll want to clean your temporary storage from old files.
+Amazon S3 provides [a built-in solution][s3 lifecycle], and for FileSystem you
+can put something like this in your Rake task:
+
+```rb
+file_system = Shrine.storages[:cache]
+file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+```
+
 ## Direct uploads
 
-Shrine comes with a `direct_upload` plugin for asynchronous uploads to your
-app or an external service. It provides a [Roda] endpoint which you can mount
-in your app:
+Shrine comes with a `direct_upload` plugin for asynchronous uploads to your app
+or an external service like Amazon S3. It provides a [Roda] endpoint which you
+can mount in your app:
 
 ```rb
 gem "roda"
@@ -589,7 +698,7 @@ end
 This endpoint provides the following routes:
 
 * `POST /images/cache/upload` - for direct uploads to your app
-* `GET /images/cache/presign` - for direct uploads to external service
+* `GET /images/cache/presign` - for direct uploads to external service (e.g. Amazon S3)
 
 These routes can be used to asynchronously start caching the file the moment
 the user selects it, using JavaScript file upload libraries like
@@ -647,17 +756,6 @@ libraries are:
 * **Safety** – All of Shrine's code has been designed to take delayed storing
   into account, and concurrent requests are handled well.
 
-## Clearing cache
-
-From time to time you'll want to clean your temporary storage from old files.
-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: Time.now - 7*24*60*60) # delete files older than 1 week
-```
-
 ## On-the-fly processing
 
 Shrine allows you to define processing that will be performed on upload.
@@ -669,9 +767,26 @@ generic image servers.
 Shrine has integrations for many commercial on-the-fly processing services,
 including [Cloudinary], [Imgix] and [Uploadcare].
 
-If you don't want to use a commercial service, [Attache] is a great open-source
-image server. There isn't a Shrine integration written for it yet, but it
-should be fairly easy to write one.
+If you don't want to use a commercial service, [Attache] and [Dragonfly] are
+great open-source image servers. For Attache a Shrine integration is in
+progress, while for Dragonfly it is not needed.
+
+## Chunked & Resumable uploads
+
+When you're accepting large file uploads, you normally want to split it into
+multiple chunks. This way if an upload fails, it is just for one chunk and can
+be retried, while the previous chunks remain uploaded.
+
+[Tus][tus] is an open protocol for resumable file uploads, which enables the
+client and the server to achieve reliable file uploads, even on unstable
+networks, with the possibility to resume the upload even after the browser is
+closed or the device shut down. You can use a client library like
+[tus-js-client] to upload the file to [tus-ruby-server], and attach the
+uploaded file to a record using [shrine-url]. See [shrine-tus-demo] for an
+example integration.
+
+Another option might be to do chunked uploads directly to your storage service,
+if the storage service supports it (e.g. Amazon S3 or Google Cloud Storage).
 
 ## Inspiration
 
@@ -704,7 +819,7 @@ 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
 [ships with over 35 plugins]: http://shrinerb.com#plugins
-[introductory blog post]: http://twin.github.io/introducing-shrine/
+[motivation]: https://twin.github.io/better-file-uploads-with-shrine-motivation/
 [FileSystem]: http://shrinerb.com/rdoc/classes/Shrine/Storage/FileSystem.html
 [S3]: http://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html
 [External]: http://shrinerb.com#external
@@ -721,3 +836,11 @@ The gem is available as open source under the terms of the [MIT License].
 [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [website]: http://shrinerb.com
 [backgrounding libraries]: https://github.com/janko-m/shrine/wiki/Backgrounding-libraries
+[tus]: http://tus.io
+[tus-ruby-server]: https://github.com/janko-m/tus-ruby-server
+[tus-js-client]: https://github.com/tus/tus-js-client
+[shrine-tus-demo]: https://github.com/janko-m/shrine-tus-demo
+[shrine-url]: https://github.com/janko-m/shrine-url
+[s3 lifecycle]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html
+[Dragonfly]: http://markevans.github.io/dragonfly/
+[Using Attacher]: http://shrinerb.com/rdoc/files/doc/attacher_md.html