shrine 0.9.0 → 1.0.0

data/doc/direct_s3.md

@@ -23,7 +23,7 @@ upfront the fields necessary for direct S3 uploads using
 object, which has `#url` and `#fields`, which you could use like this:
 
 ```erb
-<% presign = Shrine.storages[:cache].presign(SecureRandom.hex.to_s) %>
+<% presign = Shrine.storages[:cache].presign(SecureRandom.hex) %>
 
 <form action="<%= presign.url %>" method="post" enctype="multipart/form-data">
   <input type="file" name="file">
@@ -33,6 +33,16 @@ object, which has `#url` and `#fields`, which you could use like this:
 </form>
 ```
 
+You can also pass additional options to `#presign`:
+
+```rb
+Shrine.storages[:cache].presign(SecureRandom.hex,
+  content_length_range: 0..(5*1024*1024), # Limit of 5 MB
+  success_action_redirect: webhook_url,   # Tell S3 where to redirect
+  # ...
+)
+```
+
 ## Dynamic upload
 
 If the frontend is separate from the backend, or you want to do multiple file
@@ -64,6 +74,15 @@ You can use this data in a similar way as with static upload. See
 the [example app] for how multiple file upload to S3 can be done using
 [jQuery-File-Upload].
 
+If you want to pass additional options to `Storage::S3#presign`, you can pass
+a block to `:presign`:
+
+```rb
+plugin :direct_upload, presign: ->(request) do # yields a Roda request object
+  {success_action_redirect: "http://example.com/webhook"}
+end
+```
+
 ## File hash
 
 Once you've uploaded the file to S3, you need to create the representation of

data/doc/paperclip.md

@@ -0,0 +1,308 @@
+# Shrine for Paperclip Users
+
+This guide is aimed at helping Paperclip users transition to Shrine. We will
+first generally mention what are the key differences. Afterwards there is a
+complete reference of Paperclip's interface and what is the equivalent in
+Shrine.
+
+## Uploaders
+
+While in Paperclip you write your uploading logic as a list of options inside
+your models, in Shrine you instead have "uploader" classes where you put all
+your uploading logic.
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_mime_type_inclusion [/^image/]
+  end
+
+  def process(io, context)
+    # processing
+  end
+
+  def default_url(context)
+    # default URL
+  end
+end
+```
+
+Unlike Paperclip, in Shrine you can use these uploaders directly if you have
+to do some lower-level logic. First you need to register storages, and then
+you can instantiate uploaders with a specific storage:
+
+```rb
+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"),
+}
+```
+```rb
+uploader = Shrine.new(:cache)
+uploaded_file = uploader.upload(File.open("nature.jpg"))
+uploaded_file.path #=> "/uploads/cache/s9ffdkfd02kd.jpg"
+uploaded_file.original_filename #=> "nature.jpg"
+```
+
+### Processing
+
+In Shrine you do processing inside the uploader's `#process` method, and unlike
+Paperclip, the processing is done on instance-level, so you have maximum
+flexibility. In Shrine you generate versions by simply returning a hash, and
+also loading the `versions` plugin to make your uploader recognize versions:
+
+```rb
+require "image_processing/mini_magick" # part of the "image_processing" gem
+
+class ImageUploader < Shrine
+  include ImageProcessing::MiniMagick
+  plugin :versions, names: [:original, :thumb]
+
+  def process(io, context)
+    if context[:phase] == :store
+      thumb = resize_to_limit(io.download, 300, 300)
+      {original: io, thumb: thumb}
+    end
+  end
+end
+```
+
+#### Regenerating versions
+
+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. But I wrote
+a "[Regenerating versions]" guide that should give you useful guidelines.
+
+### Logging
+
+In Paperclip you enable logging by setting `Paperclip.options[:log] = true`.
+Shrine also provides logging with the `logging` plugin:
+
+```rb
+Shrine.plugin :logging
+```
+
+## Attachments
+
+The uploaders can then integrate with models by generating attachment modules
+which are included into the models. Shrine ships with plugins for Sequel and
+ActiveRecord ORMs, so you first have to load the one for your ORM:
+
+```rb
+Shrine.plugin :sequel       # If you're using Sequel
+Shrine.plugin :activerecord # If you're using ActiveRecord
+```
+
+Now you use your uploaders to generate "attachment modules", which you can then
+include in your models:
+
+```rb
+class User < Sequel::Model
+  include ImageUploader[:avatar] # adds `avatar`, `avatar=` and `avatar_url` methods
+end
+```
+
+Unlike in Paperclip which requires you to have `<attachment>_file_name`,
+`<attachment>_file_size`, `<attachment>_content_type` and
+`<attachment>_updated_at` columns, in Shrine you only need to have an
+`<attachment>_data` text column, and all information will be stored there.
+
+The attachments use `:store` for storing the files, and `:cache` for caching.
+The latter is something Paperclip doesn't do, but caching before storing is
+really great because the file then persists on validation errors, and also in
+backgrounding you can show the users the cached version before the file is
+finished storing.
+
+### Validations
+
+In Shrine validations are done inside uploader classes, and validation methods
+are provided by the `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 5*1024*1024
+    validate_mime_type_inclusion [/^image/]
+  end
+end
+```
+
+For presence validation you should use the one provided by your ORM:
+
+```rb
+class User < Sequel::Model
+  include ImageUploader[:avatar]
+
+  def validate
+    validates_presence [:avatar]
+  end
+end
+```
+
+#### MIME type spoofing
+
+By default Shrine will extract the MIME type from the `Content-Type` header of
+the uploaded file, which is solely determined from the file extension, so it's
+prone to spoofing. Shrine provides the `determine_mime_type` plugin which
+determines the MIME type from the file *contents* instead:
+
+```rb
+Shrine.plugin :determine_mime_type
+```
+
+By default the UNIX [file] utility is used, but you can choose other analyzers.
+Unlike Paperclip, you won't get any errors if the MIME type is "spoofed",
+instead it's better if you simply validate allowed MIME types.
+
+### Hooks/Callbacks
+
+Shrine's `hooks` plugin provides callbacks for Shrine, so to get Paperclip's
+`(before|after)_post_process`, you can override `#before_process` and
+`#after_process` methods:
+
+```rb
+class ImageUploader < Shrine
+  plugin :hooks
+
+  def before_process(io, context)
+    # ...
+    super
+  end
+
+  def after_process(io, context)
+    super
+    # ...
+  end
+end
+```
+
+## Paperclip to Shrine direct mapping
+
+### `has_attached_file`
+
+As mentioned above, Shrine's equivalent of `has_attached_file` is including
+an attachment module:
+
+```rb
+class User < Sequel::Model
+  include ImageUploader[:avatar] # adds `avatar`, `avatar=` and `avatar_url` methods
+end
+```
+
+Now we'll list all options that `has_attached_file` accepts, and explain
+Shrine's equivalents:
+
+#### `:storage`
+
+In Shrine attachments will automatically use `:cache` and `:store` storages
+which you have to register:
+
+```rb
+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"),
+}
+```
+
+You can change that for a specific uploader with the `default_storage` plugin.
+
+#### `:styles`, `:processors`, `:convert_options`
+
+As explained in the "Processing" section, processing is done by overriding the
+`Shrine#process` method.
+
+#### `:default_url`
+
+In Shrine you achieve default URLs by defining the instance method on the
+uploader:
+
+```rb
+class ImageUploader < Shrine
+  def default_url(context)
+    "/placeholders/missing-image.png"
+  end
+end
+```
+
+#### `:preserve_files`
+
+Shrine provides a `keep_files` plugin which allows you to keep files that would
+otherwise be deleted:
+
+```rb
+Shrine.plugin :keep_files, destroyed: true
+```
+
+#### `:path`, `:url`, `:interpolator`, `:url_generator`
+
+Shrine by default stores your files in the same directory, but you can also
+load the `pretty_location` plugin for nice folder structure:
+
+```rb
+Shrine.plugin :pretty_location
+```
+
+Alternatively, if you want to generate locations yourself you can override the
+`#generate_location` method:
+
+```rb
+class ImageUploader < Shrine
+  def generate_location(io, context)
+    # ...
+  end
+end
+```
+
+#### `:validate_media_type`
+
+Shrine has this functionality in the `determine_mime_type` plugin.
+
+### `Paperclip::Attachment`
+
+This section explains the equivalent of Paperclip attachment's methods, in
+Shrine this is an instance of `Shrine::UploadedFile`.
+
+#### `#url`, `#styles`
+
+If you're generating versions in Shrine, the attachment will be a hash of
+uploaded files:
+
+```rb
+user.avatar.class #=> Hash
+user.avatar #=>
+# {
+#   small:  #<Shrine::UploadedFile>,
+#   medium: #<Shrine::UploadedFile>,
+#   large:  #<Shrine::UploadedFile>,
+# }
+
+user.avatar[:small].url #=> "..."
+# or
+user.avatar_url(:small) #=> "..."
+```
+
+#### `#path`
+
+Shrine doesn't have this because storages are abstract and this would be
+specific to the filesystem, but the closest is probably `#id`:
+
+```rb
+user.avatar.id #=> "users/342/avatar/398543qjfdsf.jpg"
+```
+
+#### `#reprocess!`
+
+Shrine doesn't have an equivalent to this, but there is a "[Regenerating
+versions]" that should give you some useful guidelines.
+
+[file]: http://linux.die.net/man/1/file
+[Regenerating versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html

data/doc/regenerating_versions.md

@@ -3,36 +3,101 @@
 While your app is serving uploads in production, you may realize that you want
 to change how your attachment's versions are generated. This means that, in
 addition to changing you processing code, you also need to reprocess the
-existing attachments. Depending on the magnitude and the nature of the change,
-you can take different steps on doing that.
+existing attachments. This guide is aimed to help doing this migration with
+zero downtime and no unused files left in the main storage.
 
 ## Regenerating a specific version
 
-The simplest scenario is where you need to regenerate a specific version. After
-you change your processing code, this is how you would regenerate a specific
-version (in Sequel):
+The simplest scenario is where you need to regenerate an existing version.
+First you need to change and deploy your updated processing code, and
+afterwards you can run a script like this on your production database:
 
 ```rb
 Shrine.plugin :migration_helpers
 
 User.paged_each do |user|
   user.update_avatar do |avatar|
-    file = some_processing(avatar[:thumb].download)
-    avatar.merge(thumb: avatar[:thumb].replace(file))
+    thumb = some_processing(avatar[:original].download)
+    avatar.merge(thumb: avatar[:thumb].replace(thumb))
   end
 end
 ```
 
-In a similar way you would add a new version or remove an existing one.
+### Adding a new version
+
+When adding a new version to a production app, first add it to the list and
+update your processing code to generate it, and deploy it:
+
+```rb
+class ImageUploader < Shrine
+  plugin :versions, names: [:small, :medium, :new] # we add the ":new" version
+
+  def process(io, context)
+    case context[:phase]
+    when :store
+      # ...
+      new = some_processing(io.download, *args)
+      {small: small, medium: medium, new: new} # we generate the ":new" version
+    end
+  end
+end
+```
+
+After you've deployed this change, you should run a script that will generate
+the new version for all existing records:
+
+```rb
+Shrine.plugin :migration_helpers
+
+User.paged_each do |user|
+  user.update_avatar do |avatar|
+    unless new = avatar[:new]
+      file = some_processing(avatar[:original].download, *args)
+      new = user.avatar_store.upload(file)
+    end
+    avatar.merge(new: new)
+  end
+end
+```
+
+After you've run this script on your production database, all records should
+have the new version, and now you should be able to safely update your app to
+use it.
+
+### Removing a version
+
+Before removing a version, you first need to update your processing to not
+generate it (but keep the version name in the list), as well as update your app
+not to use the new version, and deploy that code. After you've done that, you
+can run a script which removes that version:
+
+```rb
+Shrine.plugin :migration_helpers
+
+User.paged_each do |user|
+  user.update_avatar do |avatar|
+    old_version = avatar.delete(:old_version)
+    old_version.delete if old_version
+    avatar
+  end
+end
+```
+
+After the script has finished, you should be able to safely remove the version
+name from the list.
 
 ## Regenerating all versions
 
 If you made a lot of changes to versions, it might make sense to simply
-regenerate all versions. You would typically use a "base" version to regenerate
-the other versions from:
+regenerate all versions. After you've deployed the change in processing, you
+can run a script which updates existing records:
 
 ```rb
+Shrine.plugin :migration_helpers
+
 User.paged_each do |user|
-  user.update(avatar: user.avatar[:original])
+  if user.avatar && user.avatar_store.uploaded?(user.avatar)
+    user.update(avatar: user.avatar[:original])
+  end
 end
 ```