saviour 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 58fead9b2cc6702062727d40824f65b016445a6d
+  data.tar.gz: 5a6a218dae027315fce70761c2b39035cd243bcb
+SHA512:
+  metadata.gz: 58f13bfb42bb55782bcade9e8fefb67e5d697eb614cd181cca89eaa6443b3166dbbd73d70a53ce24af864de2d9d5f918c8dd48a13f1eb1a96fd821d1d8267a95
+  data.tar.gz: c1d3737b8414cae6610d4c33232514aa74e99b1a5e948b887f2aa32de0b9bd5629b644478e269726053901590e16452af717486fcdb95f4d6bc1fb43ff393495

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec/support/test_data_dir/*
+.idea
+.rbenv-gemsets

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+
+addons:
+  code_climate:
+    repo_token: abb288da5fac3efc45be30ffb37085314b9189ddccedf2cc68282777477e21c5

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in saviour.gemspec
+gemspec
+
+gem "codeclimate-test-reporter", group: :test, require: nil

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Roger Campos
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,491 @@
+[![Build Status](https://travis-ci.org/rogercampos/saviour.svg?branch=master)](https://travis-ci.org/rogercampos/saviour)
+[![Code Climate](https://codeclimate.com/github/rogercampos/saviour/badges/gpa.svg)](https://codeclimate.com/github/rogercampos/saviour)
+[![Test Coverage](https://codeclimate.com/github/rogercampos/saviour/badges/coverage.svg)](https://codeclimate.com/github/rogercampos/saviour/coverage)
+
+# Saviour
+
+This is a small library that handles file uploads and nothing more. It integrates with ActiveRecord and manages file
+storage following the active record instance lifecycle.
+
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Intro](#intro)
+- [Basic usage example](#basic-usage-example)
+- [File API](#file-api)
+- [Storage abstraction](#storage-abstraction)
+  - [public_url](#public_url)
+  - [LocalStorage](#localstorage)
+  - [S3Storage](#s3storage)
+- [Source abstraction](#source-abstraction)
+  - [StringSource](#stringsource)
+  - [UrlSource](#urlsource)
+- [Uploader classes and Processors](#uploader-classes-and-processors)
+  - [store_dir](#store_dir)
+  - [Accessing model and attached_as](#accessing-model-and-attached_as)
+  - [Processors](#processors)
+- [Versions](#versions)
+- [Validations](#validations)
+- [Active Record Lifecycle integration](#active-record-lifecycle-integration)
+- [FAQ](#faq)
+  - [Digested filename](#digested-filename)
+  - [Getting metadata from the file](#getting-metadata-from-the-file)
+  - [How to recreate versions](#how-to-recreate-versions)
+  - [Caching across redisplays in normal forms](#caching-across-redisplays-in-normal-forms)
+  - [Introspection (Class.attached_files)](#introspection-classattached_files)
+  - [Processing in background](#processing-in-background)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
+## Intro
+
+The goal of this library is to be as minimal as possible, including as less features and code the better. This library's
+responsibility is to handle the storage of a file related to an ActiveRecord object, persisting the file on save and
+deleting it on destroy. Therefore, there is no code included to handle images, integration with rails views or any
+other related feature. There is however a FAQ section later on in this README that can help you implement those things
+using Saviour and your own code.
+
+
+## Basic usage example
+
+This library is inspired api-wise by carrierwave, sharing the same way of declaring "attachments" (file storages related
+to an ActiveRecord object) and processings. See the following example of a model including a file:
+
+```
+class Post < ActiveRecord::Base
+  # The posts table must have an `image` String column.
+  attach_file :image, PostImageUploader
+end
+
+class PostImageUploader < Saviour::BaseUploader
+  store_dir! { "/default/path/#{model.id}/#{attached_as}" }
+
+  process :resize, width: 500, height: 500
+
+  version(:thumb) do
+    process :resize, width: 100, height: 100
+  end
+
+  def resize(contents, filename, opts)
+    width = opts[:width]
+    height = opts[:height]
+
+    # modify contents in memory here
+    contents = user_implementation_of_resize(contents, width, height)
+
+    [contents, filename]
+  end
+end
+```
+
+In this example we have posts that have an image. That image will be stored in a path like `/default/path/<id>/image`
+and also a resize operation will be performed before persisting the file.
+
+There's one version declared with the name `thumb` that will be created by resizing the file to 100x100. The version
+filename will be by default `<original_filename>_thumb` but it can be changed if you want.
+
+Filenames (both for the original image and for the versions) can be changed in a processor just by returning a different
+second argument.
+
+Here the resize manipulation is done in-memory, but there're also a way to handle manipulations done at the file level if
+you need to use external binaries like imagemagick, image optimization tools (pngquant, jpegotim, etc...) or others.
+
+
+## File API
+
+`Saviour::File` is the type of object you'll get when accessing the attribute over which a file is attached in the
+ActiveRecord object. The public api you can use on those objects is:
+
+- assign
+- exists?
+- read
+- write
+- delete
+- public_url
+- url
+- changed?
+- filename
+- with_copy
+- blank?
+
+Use `assign` to assign a file to be stored. You can use any object that responds to `read`. See below the section
+about Sources abstraction for further info.
+
+`exists?`, `read`, `write`, `delete` and `public_url` are delegated to the storage, with the exception of `write` that
+is channeled with the uploader first to handle processings. `url` is just an alias for `public_url`.
+
+`changed?` indicates if the file has changed, in memory, regarding it's initial value. It's equivalent to the `changed?`
+method that ActiveRecord implements on database columns.
+
+`filename` is the filename of the currently stored file. Only works for files that have been already stored, not assigned.
+
+`blank?` indicates if the file is present either in the persistence layer or in memory. It provides api-compatibility with
+default rails validations like `validates_presence_of`.
+
+`with_copy` is a helper method that will read the persisted file, create a copy using a `Tempfile` and call the block
+passed to the method with that Tempfile. Will clean afterwards.
+
+As mentioned before, you can access a `File` object via the name of the attached_as, from the previous example you could do:
+
+```
+post = Post.find(123)
+post.image # => <Saviour::File>
+```
+
+You can also get the `File` instance of version by using an argument matching the version name:
+
+```
+post = Post.find(123)
+post.image # => <Saviour::File>
+post.image(:thumb) # => <Saviour::File>
+```
+
+Finally, a couple of convenient methods are also added to the ActiveRecord object that just delegate to the `File` object:
+
+```
+post = Post.find(123)
+post.image = File.open("/my/image.jpg") # This is equivalent to post.image.assign(File.open(...))
+post.image_changed? # This is equivalent to post.image.changed?
+```
+
+## Storage abstraction
+
+Storages are classes responsible for handling the persistence layer with the underlying persistence provider, whatever
+that is. Storages are considered public API and anyone can write a new one. Included in the Library there are two of them,
+LocalStorage and S3Storage. To be an Storage, a class must implement the following api:
+
+```
+def write(contents, path)
+end
+
+def read(path)
+end
+
+def exists?(path)
+end
+
+def delete(path)
+end
+```
+
+The convention here is that a file consist of a raw content and a path representing its location within the underlying
+persistence layer.
+
+You must configure Saviour by providing the storage to use:
+
+```
+Saviour::Config.storage = MyStorageImplementation.new
+```
+
+The provided storage object will be used for all the lifespan of the running application, for all the file uploads
+handled by Saviour.
+
+
+### public_url
+
+Storages can optionally also implement this method, in order to provide a public URL to the stored file without going
+through the application code.
+
+For example, if you're storing files in a machine with a webserver, you may want this method to convert from a local
+path to an external URL, adding the domain and protocol parts. As an ilustrative example:
+
+```
+def public_url(path)
+  "http://mydomain.com/files/#{path}"
+end
+```
+
+
+### LocalStorage
+
+You can use this storage to store files in the local machine running the code. Example:
+
+```
+Saviour::Config.storage = Saviour::LocalStorage.new(
+  local_prefix: "/var/www/app_name/current/files",
+  public_url_prefix: "http://mydomain.com/uploads"
+)
+```
+
+The `local_prefix` option is mandatory, and defines the base prefix under which the storage will store files in the
+machine. You need to configure this accordingly to your use case and deployment strategies, for example, for rails
+and capistrano with default settings you'll need to set it to `Rails.root.join("public/system")`.
+
+The `public_url_prefix` is optional and should represent the public endpoint from which you'll serve the assets.
+Same as before, you'll need to configure this accordingly to your deployment specifics.
+You can also assign a Proc instead of a String to dynamically manage this (for multiple asset hosts for example).
+
+This storage will take care of removing empty folders after removing files.
+
+This storage includes a feature of overwrite protection, raising an exception if an attempt is made of writing something
+on a path that already exists. This behaviour in enabled by default, but you can turn it off by passing an additional
+argument when instantiating the storage: `overwrite_protection: false`.
+
+
+### S3Storage
+
+An storage implementation using `Fog::AWS` to talk with Amazon S3. Example:
+
+```
+Saviour::Config.storage = Saviour::S3Storage.new(
+  bucket: "my-bucket-name",
+  aws_access_key_id: "stub",
+  aws_secret_access_key: "stub"
+)
+```
+
+All passed options except for `bucket` will be directly forwarded to the initialization of `Fog::Storage.new(opts)`,
+so please refer to Fog/AWS [source](https://github.com/fog/fog-aws/blob/master/lib/fog/aws/storage.rb) for extra options.
+
+The `public_url` method just delegates to the Fog implementation, which will provide the default path to the file,
+for example `https://fake-bucket.s3.amazonaws.com/dest/file.txt`. Custom domains can be configured directly in Fog via
+the `host` option, as well as `region`, etc.
+
+The `exists?` method uses a head request to verify existence, so it doesn't actually download the file.
+
+All files will be created as public.
+
+This storage includes a feature of overwrite protection, raising an exception if an attempt is made of writing something
+on a path that already exists. This behaviour in enabled by default, but you can turn it off by passing an additional
+argument when instantiating the storage: `overwrite_protection: false`.
+
+
+## Source abstraction
+
+As mentioned before, you can use `File#assign` with any object that responds to `read`. This is already the case for `::File`,
+`Tempfile` or `IO`. Since a file requires also a filename, however, in those cases a random filename will be assigned
+(you can always set the filename using a processor later on).
+
+Additionally, if the object responds to `#original_filename` then that will be used as a filename instead of generating
+a random one.
+
+You can create your own classes implementing this API to extend functionality. This library includes two of them: StringSource
+and UrlSource.
+
+
+### StringSource
+
+This is just a wrapper class that gives no additional behaviour except for implementing the required API. Use it as:
+
+```
+foo = Saviour::StringSource.new("my raw contents", "filename.jpg")
+post = Post.find(123)
+post.image = foo
+```
+
+### UrlSource
+
+This class implements the source abstraction from a URL. The `read` method will download the given URL and use those
+contents. The filename will be guessed as well from the URL. Redirects will be followed (max 10) and connection retried
+3 times before raising an exception. Example:
+
+```
+foo = Saviour::UrlSource.new("http://server.com/path/image.jpg")
+post = Post.find(123)
+post.image = foo
+```
+
+
+## Uploader classes and Processors
+
+Uploaders are the classes responsible for managing what happens when a file is uploaded into an storage. Use them to define
+the path that will be used to store the file, additional processings that you want to run and versions. See a complete
+example:
+
+```
+class ExampleUploader < Saviour::BaseUploader
+  store_dir! { "/default/path/#{model.id}" }
+
+  process :resize, width: 50, height: 50
+
+  process_with_file do |local_file, filename|
+    `mogrify -resize 40x40 #{local_file.path}`
+    [local_file, filename]
+  end
+
+  process do |contents, filename|
+    [contents, "new-#{filename}"]
+  end
+
+  version(:thumb) do
+    store_dir! { "/default/path/#{model.id}/versions" }
+    process :resize, with: 10, height: 10
+  end
+
+  version(:just_a_copy)
+
+  def resize(contents, filename, opts)
+    # User RMagick to modify contents in memory here
+    [contents, filename]
+  end
+end
+```
+
+### store_dir
+
+Use `store_dir` to indicate the default directory under which the file will be stored. You can also use it under a
+`version` to change the default directory for that specific version.
+
+
+### Accessing model and attached_as
+
+Both `store_dir` and `process` / `process_with_file` declarations can be expressed passing a block or passing a symbol
+representing a method. In both cases, you can directly access there a method called `model` and a method called
+`attached_as`, representing the original model and the name under which the file is attached to the model.
+
+Use this to get info form the model to compose the store_dir, for example, or even to create a processor that
+extracts information from the file and passes this info back to the model to store it in additional db columns.
+
+### Processors
+
+Processors are the methods (or blocks) that will modify either the file contents or the filename before actually
+upload the file into the storage. You can declare them via the `process` or the `process_with_file` method.
+
+They work as a stack, chaining the response from the previous one as input for the next one, and are executed in the
+same order you declare them. Each processor will receive the raw contents and the filename, and must return an array
+with two values, the new contents and the new filename.
+
+As described in the example before, processors can be declared in two ways:
+
+- As a symbol or a string, it will be interpreted as a method that will be called in the current uploader.
+  You can optionally set an extra Hash of options that will be forwarded to the method, so it becomes easier to reuse processors.
+
+- As a Proc, for inline use cases.
+
+By default processors work with the full raw contents of the file, and that's what you will get and must return when
+using the `process` method. However, since there are use cases for which is more convenient to have a File object
+instead of the raw contents, you can also use the `process_with_file` method, which will give you a Tempfile object,
+and from which you must return a File object as well.
+
+You can combine both and Saviour will take care of synchronization, however take into account that every time you
+switch from one to another there will be a penalty for having to either read or write from/to disk.
+Internally Saviour works with raw contents, so even if you only use `process_with_file`, there will be a penalty at the
+beginning and at the end, for writing and reading to and from a file.
+
+When using `process_with_file`, the last file instance you return from your last processor defined as
+`process_with_file` will be automatically deleted by Saviour. Be aware of this if you return
+some File instance different than the one you received pointing to a file.
+
+Finally, processors can be disabled entirely via a configuration parameter. Example:
+
+```
+Saviour::Config.processing_enabled = false
+Saviour::Config.processing_enabled = true
+```
+
+You can use this when running tests, for example, or if you want processors to not execute for some reason. The flag can be
+changed in real time.
+
+
+## Versions
+
+Versions in Saviour are treated just like an additional attachment. They require you an additional database column to
+persist the file path, and this means you can work with them completely independently of the main file. They can be
+assigned, deleted, etc... independently. You just need to work with the versioned `Saviour::File` instance instead of the main
+one, so for example when assigning a file you'll need to do `object.file(:thumb).assign(my_file)`.
+
+You must create an additional database String column for each version, with the following convention:
+
+`<attached_as>_<version_name>`
+
+The only feature versions gives you is following their main file: A version will be assigned automatically if you assign the
+main file, and all versions will be deleted when deleting the main file.
+
+In case of conflict, the versioned assignation will be preserved. For example, if you assign both the main file and the version,
+both of them will be respected and the main file will not propagate to the version in this case.
+
+Defined processors in the Uploader will execute when assigning a version directly. Validations will also execute when assigning
+a version directly (see validation section for details).
+
+When you open a `version` block within an uploader, you can declare some processors (or change the store dir) only for
+that version. Note that all processors will be executed for every version that exists, plus one time for the base file.
+There are no optimizations done, if your uploader declares one processors first, and from there you open 2 versions,
+the first processors will be executed 3 times.
+
+
+## Validations
+
+You can declare validations on your model to implement specific checkings over the contents or the filename of an attachment.
+
+Take note that validations are executed over the contents given as they are, before any processing. For example you can
+have a validation declaring "max file size is 1Mb", assign a file right below the limit, but then process it in a way that
+increases its size. You'll be left with a file bigger than 1Mb.
+
+Example of validations:
+
+```
+class Post < ActiveRecord::Base
+  attach_file :image, PostImageUploader
+
+  attach_validation(:image) do |contents, filename|
+    errors.add(:image, "must be smaller than 10Mb") if contents.bytesize >= 10.megabytes
+    errors.add(:image, "must be a jpeg file") if File.extname(filename) != ".jpg" # naive, don't copy paste
+  end
+end
+```
+
+Validations will always receive the raw contents of the file. If you need to work with a `File` object you'll need to implement
+the necessary conversions.
+
+Validations can also be declared passing a method name instead of a block, like this:
+
+```
+class Post < ActiveRecord::Base
+  attach_file :image, PostImageUploader
+  attach_validation :image, :check_size
+
+  private
+
+  def check_size(contents, filename)
+    errors.add(:image, "must be smaller than 10Mb") if contents.bytesize >= 10.megabytes
+  end
+end
+```
+
+To improve reusability, validation blocks or methods will also receive a third argument (only if declared in your
+implementation). This third argument is a hash containing `attached_as` and `version` of the validating file.
+
+
+## Active Record Lifecycle integration
+
+On `after_save` Saviour will upload the changed files attached to the current model, executing the processors as needed.
+
+On `after_destroy` Saviour will delete all the attached files and versions.
+
+On `validate` Saviour will execute the validations defined.
+
+When validations are defined, the assigned source will be readed only once. On validation time, it will be readed, passed
+to the validation blocks and cached. If the model is valid, the upload will happen from those cached contents. If there
+are no validations, the source will be readed only on upload time, after validating the model.
+
+
+## FAQ
+
+This is a compilation of common questions or features regarding file uploads.
+
+### Digested filename
+
+A common use case is to create a processor to include a digest of the file in the filename. The implementation is left
+for the user, but a simple example of such processor is this:
+
+```
+  def digest_filename(contents, filename, opts = {})
+    separator = opts.fetch(:separator, "-")
+
+    digest = ::Digest::MD5.hexdigest(contents)
+    extension = ::File.extname(filename)
+
+    new_filename = "#{[::File.basename(filename, ".*"), digest].join(separator)}#{extension}"
+
+    [contents, new_filename]
+  end
+```
+
+### Getting metadata from the file
+### How to recreate versions
+### Caching across redisplays in normal forms
+### Introspection (Class.attached_files)
+### Processing in background