saviour 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c2fca8190280a50014041a2989e1faa1ab76940
-  data.tar.gz: 49c26d990899a05d0b10ce48196c26429a0e8bff
+  metadata.gz: 8673c1ddde4f8e16189bfd2d54ea7ad239155679
+  data.tar.gz: 8a97558346780d9105a5b2145fcdc3a038ae3bc6
 SHA512:
-  metadata.gz: 06fa6cba605bc2d7f44043bd979189cf3b8ddeb27faee2dd14f7c77c6361910c5abe0de610562cdd5d21c56e41e636a8aefc5a1fe40a879a1e46c3175e3d08c3
-  data.tar.gz: 0075fc54313974fe0d8ca044ad9b749bc92368ad1053d2844b60bd8e518d2d4f311d596423fbe0598e7a94e77b6a0f22e207efd99b754bbff77108f6d4d2f831
+  metadata.gz: 541052bdedf19b045140c57fa154d9f40007f56bd4fd4cd63895d99a2f577d24e4e10e39e876c597c1bc38fbd462797dcc59173d3b5f36d89aaa06e91c2cf52c
+  data.tar.gz: beea334842a6e686c7df91b933ed55a70298fb00818a950381c2d015bc138ff90ff7deff9b7d74f0a4c150a8069600800f5afc5ff002d77b92e3e1cb0fde2380

data/.gitignore

@@ -18,4 +18,5 @@ tmp
 spec/support/test_data_dir/*
 .idea
 .rbenv-gemsets
-*.gemfile.lock
+*.gemfile.lock
+.DS_Store

data/.travis.yml

@@ -1,23 +1,14 @@
 language: ruby
+sudo: false
+cache: bundler
 rvm:
-  - 2.0.0
   - 2.1.8
   - 2.2.4
   - 2.3.0
 
-gemfile:
-  - gemfiles/4.0.gemfile
-  - gemfiles/4.1.gemfile
-  - gemfiles/4.2.gemfile
-  - gemfiles/5.0.gemfile
-
 addons:
   code_climate:
     repo_token: abb288da5fac3efc45be30ffb37085314b9189ddccedf2cc68282777477e21c5
 
-matrix:
-  exclude:
-    - rvm: 2.0.0
-      gemfile: gemfiles/5.0.gemfile
-    - rvm: 2.1.8
-      gemfile: gemfiles/5.0.gemfile
+after_success:
+  - bundle exec codeclimate-test-reporter

data/DECOMPOSE.md

@@ -0,0 +1,66 @@
+- New saviour-ar gem will provide what's currently in saviour gem
+- saviour gem will be data-storage independent. It will provide a way to manage files with processors, but without a
+lifecycle attached to a database-model. It will provide a more low level api.
+- saviour-ar will provide the specific integration with active record.
+
+
+# Saviour agnostic gem API
+
+
+First, you'll need to define what files can be saved in what objects (any Ruby class). You can do that by including the `Saviour::BasicModel` module, example:
+
+```
+class MyObject
+  include Saviour::BasicModel
+
+  attach_file :image, ImageUploader
+  attach_file :scheme, FileUploader
+end
+```
+
+Now, you can assign and work with the files associated to instances of MyObject with the following api:
+
+```
+# New file
+
+a = MyObject.new
+a.image = File.open('/path/image.jpg')
+a.image.assign File.open('newfile.jpg')
+a.image.changed? # => true
+saved_path = a.image.write # => persists file in the storage and returns the path in which the file has been saved
+
+b = MyObject.new
+b.image.set_path!(saved_path) # => Link this image to the persisted image from before
+b.image.exists? # => true
+b.image.read # -> return bytes
+b.image.delete # -> delete
+b.image.exists? # => false
+
+# ...
+```
+
+If you want to work directly managing the files associated to those objects, you can use the `Saviour::File` public API directly.
+
+However, Saviour is designed to work with models that are saved in some kind of persistent storage, like a database of some sort. This is why Saviour also provides a generic `LifeCycle` service which you can use to simulate the persistence lifecycle of the object. You can then use:
+
+```
+a = MyObject.new image: File.open('image.jpg')
+
+Saviour::LifeCycle.new(a).save!
+Saviour::LifeCycle.new(a).delete!
+```
+
+`save!` will have the effect of saving all the attachments associated with the object, and `delete!` will have the effect of removing all the files associated with this object from the file storage defined.
+
+Using LifeCycle you consider the object as a whole, while working with individual files you have more control, but you always operate with individual files.
+
+The feature of versions, for example, only applies when you use the LifeCycle approach, since, by definition, a version is automatically constructed from the original file while this one is saved, and this involved operating in two or more attachments at the same time over an specific object. Since in Saviour versions can be managed exactly like regular attachments, such behavior don't apply when you work with File instances directly.
+
+
+# Saviour API for developers
+
+If you want to develop a new gem to integrate Saviour with another persistence technology, you need to do two things.
+
+1) Write a class with the api #read, #write and #persisted? and give it to Savior, so he knows how to work with the persistence layer.
+2) Write a new module for the final users to include in their models, providing the expected hooks so that the usage of the `LifeCycle` is automatic and transparent.
+

data/Gemfile

@@ -4,3 +4,4 @@ source 'https://rubygems.org'
 gemspec
 
 gem "codeclimate-test-reporter", group: :test, require: nil
+gem "simplecov", group: :test, require: nil

data/README.md

@@ -56,12 +56,14 @@ to an ActiveRecord object) and processings. See the following example of a model
 
 ```
 class Post < ActiveRecord::Base
-  # The posts table must have an `image` String column.
+  include Saviour::Model
+
+  # 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}" }
+  store_dir { "/default/path/#{model.id}/#{attached_as}" }
 
   process :resize, width: 500, height: 500
 
@@ -281,7 +283,7 @@ and UrlSource.
 
 ### StringSource
 
-This is just a wrapper class that gives no additional behaviour except for implementing the required API. Use it as:
+This is just a wrapper class that gives no additional behavior except for implementing the required API. Use it as:
 
 ```
 foo = Saviour::StringSource.new("my raw contents", "filename.jpg")
@@ -310,7 +312,7 @@ example:
 
 ```
 class ExampleUploader < Saviour::BaseUploader
-  store_dir! { "/default/path/#{model.id}" }
+  store_dir { "/default/path/#{model.id}" }
 
   process :resize, width: 50, height: 50
 
@@ -324,7 +326,7 @@ class ExampleUploader < Saviour::BaseUploader
   end
 
   version(:thumb) do
-    store_dir! { "/default/path/#{model.id}/versions" }
+    store_dir { "/default/path/#{model.id}/versions" }
     process :resize, with: 10, height: 10
   end
 
@@ -431,6 +433,7 @@ Example of validations:
 
 ```
 class Post < ActiveRecord::Base
+  include Saviour::Model
   attach_file :image, PostImageUploader
 
   attach_validation(:image) do |contents, filename|
@@ -447,6 +450,7 @@ Validations can also be declared passing a method name instead of a block, like
 
 ```
 class Post < ActiveRecord::Base
+  include Saviour::Model
   attach_file :image, PostImageUploader
   attach_validation :image, :check_size
 
@@ -481,8 +485,8 @@ 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:
+A common use case is to create a processor to include a digest of the file in the filename, in order to automatically
+expire caches. The implementation is left for the user, but a simple example of such processor is this:
 
 ```
   def digest_filename(contents, filename, opts = {})
@@ -497,8 +501,35 @@ for the user, but a simple example of such processor is this:
   end
 ```
 
-### Getting metadata from the file
 ### How to recreate versions
+
+Recreating a version based on the master file can be easily done by just assigning the master file to the version and
+saving the model. You just need a little bit more code in order to preserve the current version filename, for example,
+if that's something you want.
+
+An example service that can do that is the following:
+
+```
+class SaviourRecreateVersionsService
+  def initialize(model)
+    @model = model
+  end
+
+  def recreate!(attached_as, *versions)
+    base = @model.send(attached_as).read
+
+    versions.each do |version|
+      current_filename = @model.send(attached_as, version).filename
+      @model.send(attached_as, version).assign(Saviour::StringSource.new(base, current_filename))
+    end
+
+    @model.save!
+  end
+end
+```
+
+### Getting metadata from the file
+
 ### Caching across redisplays in normal forms
 ### Introspection (Class.attached_files)
 ### Processing in background

data/lib/saviour/attribute_name_calculator.rb

@@ -0,0 +1,15 @@
+module Saviour
+  class AttributeNameCalculator
+    def initialize(attached_as, version = nil)
+      @attached_as, @version = attached_as, version
+    end
+
+    def name
+      if @version
+        "#{@attached_as}_#{@version}"
+      else
+        @attached_as.to_s
+      end
+    end
+  end
+end

data/lib/saviour/base_integrator.rb

@@ -0,0 +1,53 @@
+module Saviour
+  class BaseIntegrator
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def file_instantiator_hook(model, file_instance, attach_as, version)
+      # noop
+    end
+
+    def attach_file_hook(klass, attach_as, uploader_klass)
+      # noop
+    end
+
+    def setup!
+      raise "You cannot include Saviour twice in the same class" if @klass.respond_to?(:attached_files)
+
+      @klass.send :extend, ClassAttribute
+      @klass.class_attribute :attached_files
+      @klass.attached_files = {}
+
+      a = self
+      b = @klass
+
+      @klass.define_singleton_method "attach_file" do |attach_as, uploader_klass|
+        a.attach_file_hook(self, attach_as, uploader_klass)
+
+        versions = uploader_klass.versions || []
+        b.attached_files[attach_as] ||= []
+        b.attached_files[attach_as] += versions
+
+        b.class_eval do
+          define_method(attach_as) do |version = nil|
+            instance_variable_get("@__uploader_#{version}_#{attach_as}") || begin
+              new_file = ::Saviour::File.new(uploader_klass, self, attach_as, version)
+              a.file_instantiator_hook(self, new_file, attach_as, version)
+
+              instance_variable_set("@__uploader_#{version}_#{attach_as}", new_file)
+            end
+          end
+
+          define_method("#{attach_as}=") do |value|
+            send(attach_as).assign(value)
+          end
+
+          define_method("#{attach_as}_changed?") do
+            send(attach_as).changed?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/saviour/basic_model.rb

@@ -0,0 +1,7 @@
+module Saviour
+  module BasicModel
+    def self.included(klass)
+      BaseIntegrator.new(klass).setup!
+    end
+  end
+end

data/lib/saviour/config.rb

@@ -17,7 +17,6 @@ module Saviour
         Thread.current["Saviour::Config"][:processing_enabled] = value
       end
 
-
       def storage
         Thread.current["Saviour::Config"] ||= {}
         Thread.current["Saviour::Config"][:storage] || Thread.main["Saviour::Config"][:storage] || NotImplemented.new

data/lib/saviour/file.rb

@@ -2,47 +2,32 @@ require 'securerandom'
 
 module Saviour
   class File
-    class SourceFilenameExtractor
-      def initialize(source)
-        @source = source
-      end
-
-      def detected_filename
-        original_filename || path_filename
-      end
-
-      def original_filename
-        @source.respond_to?(:original_filename) && @source.original_filename.present? && @source.original_filename
-      end
-
-      def path_filename
-        @source.respond_to?(:path) && @source.path.present? && ::File.basename(@source.path)
-      end
-    end
-
+    attr_reader :persisted_path
 
     def initialize(uploader_klass, model, attached_as, version = nil)
       @uploader_klass, @model, @attached_as = uploader_klass, model, attached_as
       @version = version
-
-      @persisted = !!persisted_path
       @source_was = @source = nil
     end
 
+    def set_path!(path)
+      @persisted_path = path
+    end
+
     def exists?
-      persisted? && Config.storage.exists?(persisted_path)
+      persisted? && Config.storage.exists?(@persisted_path)
     end
 
     def read
-      persisted? && exists? && Config.storage.read(persisted_path)
+      persisted? && exists? && Config.storage.read(@persisted_path)
     end
 
     def delete
-      persisted? && exists? && Config.storage.delete(persisted_path)
+      persisted? && exists? && Config.storage.delete(@persisted_path)
     end
 
     def public_url
-      persisted? && Config.storage.public_url(persisted_path)
+      persisted? && Config.storage.public_url(@persisted_path)
     end
 
     alias_method :url, :public_url
@@ -52,13 +37,13 @@ module Saviour
 
       @source_data = nil
       @source = object
-      @persisted = !object
+      @persisted_path = nil if object
 
       object
     end
 
     def persisted?
-      @persisted
+      !!@persisted_path
     end
 
     def changed?
@@ -66,7 +51,7 @@ module Saviour
     end
 
     def filename
-      persisted? && ::File.basename(persisted_path)
+      ::File.basename(@persisted_path) if persisted?
     end
 
     def with_copy
@@ -96,7 +81,7 @@ module Saviour
 
       path = uploader.write(source_data, filename_to_be_assigned)
       @source_was = @source
-      @persisted = true
+      @persisted_path = path
       path
     end
 
@@ -114,11 +99,5 @@ module Saviour
     def uploader
       @uploader ||= @uploader_klass.new(version: @version, data: {model: @model, attached_as: @attached_as})
     end
-
-    def persisted_path
-      if @model.persisted? || @model.destroyed?
-        @model.read_attribute(ColumnNamer.new(@attached_as, @version).name)
-      end
-    end
   end
 end

data/lib/saviour/life_cycle.rb

@@ -0,0 +1,57 @@
+module Saviour
+  class LifeCycle
+    def initialize(model, persistence_klass = nil)
+      raise "Please provide an object compatible with Saviour." unless model.class.respond_to?(:attached_files)
+
+      @persistence_klass = persistence_klass
+      @model = model
+    end
+
+    def delete!
+      attached_files.each do |column, versions|
+        (versions + [nil]).each { |version| @model.send(column, version).delete if @model.send(column, version).exists? }
+      end
+    end
+
+    def save!
+      attached_files.each do |column, versions|
+        base_file_changed = @model.send(column).changed?
+        original_content = @model.send(column).source_data if base_file_changed
+
+        versions.each do |version|
+          if @model.send(column, version).changed?
+            upload_file(column, version)
+          elsif base_file_changed
+            @model.send(column, version).assign(StringSource.new(original_content, default_version_filename(column, version)))
+            upload_file(column, version)
+          end
+        end
+
+        upload_file(column, nil) if base_file_changed
+      end
+    end
+
+
+    private
+
+    def default_version_filename(column, version)
+      filename = @model.send(column).filename_to_be_assigned
+      "#{::File.basename(filename, ".*")}_#{version}#{::File.extname(filename)}"
+    end
+
+    def upload_file(column, version)
+      name = AttributeNameCalculator.new(column, version).name
+      persistence_layer = @persistence_klass.new(@model) if @persistence_klass
+      current_path = persistence_layer.read(name) if persistence_layer
+
+      Config.storage.delete(current_path) if current_path
+
+      new_path = @model.send(column, version).write
+      persistence_layer.write(name, new_path) if persistence_layer
+    end
+
+    def attached_files
+      @model.class.attached_files || {}
+    end
+  end
+end

data/lib/saviour/source_filename_extractor.rb

@@ -0,0 +1,21 @@
+module Saviour
+  class SourceFilenameExtractor
+    def initialize(source)
+      @source = source
+    end
+
+    def detected_filename
+      original_filename || path_filename
+    end
+
+    def original_filename
+      value = @source.original_filename if @source.respond_to?(:original_filename)
+      value if !value.nil? && value != ''
+    end
+
+    def path_filename
+      value = @source.path if @source.respond_to?(:path)
+      ::File.basename(value) if !value.nil? && value != ''
+    end
+  end
+end

data/lib/saviour/url_source.rb

@@ -24,7 +24,7 @@ module Saviour
     private
 
     def resolve(uri, max_redirects = MAX_REDIRECTS)
-      raise RuntimeError, "Max number of allowed redirects reached (#{MAX_REDIRECTS}) when resolving #{@uri}" if max_redirects == 0
+      raise RuntimeError, "Max number of allowed redirects reached (#{MAX_REDIRECTS}) when resolving #{uri}" if max_redirects == 0
 
       response = Net::HTTP.get_response(uri)
 

data/lib/saviour/utils/class_attribute.rb

@@ -0,0 +1,26 @@
+# Port and simplification of ActiveSupport class attribute
+module Saviour
+  module ClassAttribute
+    def class_attribute(*attrs)
+      attrs.each do |name|
+        singleton_class.instance_eval do
+          undef_method(name) if method_defined?(name)
+        end
+
+        define_singleton_method(name) { nil }
+
+        singleton_class.instance_eval do
+          undef_method("#{name}=") if method_defined?("#{name}=")
+        end
+
+        define_singleton_method("#{name}=") do |val|
+          singleton_class.class_eval do
+            undef_method(name) if method_defined?(name)
+            define_method(name) { val }
+          end
+          val
+        end
+      end
+    end
+  end
+end

data/lib/saviour/version.rb

@@ -1,3 +1,3 @@
 module Saviour
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end