changeling 0.0.7 → 0.1.0

data/README.md

@@ -5,6 +5,8 @@
 [travis-home]: http://travis-ci.org/
 [brew-home]: http://mxcl.github.com/homebrew/
 [elasticsearch-home]: http://www.elasticsearch.org
+[sidekiq-home]: https://github.com/mperham/sidekiq
+[resque-home]: https://github.com/defunkt/resque
 
 A flexible and lightweight object change tracking system.
 
@@ -38,7 +40,7 @@ $ brew install elasticsearch
 ```
 
 ## Usage
-
+### Models
 Include the Trackling module for any class you want to keep track of:
 
 ```ruby
@@ -49,35 +51,40 @@ class Post
 end
 ```
 
-If you want to keep track of the user who made the changes:
+### Controllers
+If you are using a Rails app, and have the notion of a "user"", you may want to track of which user made which changes.
+Unfortunately models don't understand the concept of the currently signed in user. We'll have to leverage the controller to tack on this information.
 
 ```ruby
 # Doesn't have to be ApplicationController, perhaps you only want it in controllers for certain resources.
 class ApplicationController < ActionController::Base
     include Changeling::Blameling
-    
+
     # Changeling assumes your user is current_user, but if not, override the changeling_blame_user method like so:
     def changeling_blame_user
         current_account
     end
-    
+
     # Controller logic here...
 end
 ```
 
-That's it! Including the module(s) will silently keep track of any changes made to objects of this class.
-For example:
+### Asynchronous Tracking
+Sometimes in high production load, you don't want another gem clogging up your resource pipeline, slowing down performance and potentially causing downtime.
+Changeling has built-in Asynchronous support so you don't have to go and write your own callbacks and queues!
+Changeling is compatible with [Sidekiq][sidekiq-home] and [Resque][resque-home].
+When your object is saved, a job is placed in the 'changeling' queue.
 
 ```ruby
-@post = Post.first
-@post.title
-=> 'Old Title'
-@post.title = 'New Title'
-@post.save
+class Post
+  # include Changeling::Trackling
+  include Changeling::Async::Trackling
+  
+  # Model logic here...
+end
 ```
 
-This code will save a history that represents that the title for this post has been changed.
-
+### Accessing Changeling's history
 If you wish to see what has been logged, include the Probeling module:
 
 ```ruby
@@ -93,37 +100,40 @@ With Probeling, you can check out the changes that have been made! They're store
 You can access the up to the last 10 changes simply by calling
 
 ```ruby
-@post.history
+# Alias for this method: @post.history
+@post.loglings
 ```
 
-You can access a different number of records by passing in a number to the .history method:
+You can access a different number of records by passing in a number to the .loglings method:
 
 ```ruby
 # Will automatically handle if there are less than the number of histories requested.
-@post.history(50)
+@post.loglings(50)
 ```
 
 Access all of an objects history:
 
 ```ruby
-@post.all_history
+# Alias for this method: @post.all_history
+@post.all_loglings
 ```
 
 Access all of an objects history where a specific field was changed:
 
 ```ruby
-@post.history_for_field(:title)
+# Alias for this method: @post.history_for_field(field)
+@post.loglings_for_field(:title)
 # Or if you prefer stringified fields:
-@post.history_for_field('title')
+@post.loglings_for_field('title')
 
 # You can also pass in a number to limit your results
-@post.history_for_field(:title, 10)
+@post.loglings_for_field(:title, 10)
 ```
 
-Properties of Loglings (history objects):
+### Logling Properties (history objects):
 
 ```ruby
-log = @post.history.first
+log = @post.loglings.first
 
 log.klass # class of the object that the Logling is tracking.
 => Post

data/Rakefile

@@ -2,6 +2,20 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+Dir.glob('benchmarks/*.rake').each { |r| import r }
+
+desc "Run all benchmarks."
+task :benchmark, :count, :fields do |t, args|
+  args.with_defaults(:count => 1000, :fields => 20)
+
+  Rake::Task["benchmark_setup"].invoke
+  Rake::Task["benchmark_tire"].reenable
+  Rake::Task["benchmark_tire"].invoke
+  puts "====================================================================\n\n"
+  Rake::Task["benchmark_changeling"].reenable
+  Rake::Task["benchmark_changeling"].invoke
+end
+
 RSpec::Core::RakeTask.new("spec") do |spec|
   spec.pattern = "spec/**/*_spec.rb"
 end
@@ -12,3 +26,36 @@ RSpec::Core::RakeTask.new('spec:progress') do |spec|
 end
 
 task :default => :spec
+
+
+# Helper methods
+def generate_loglings(count, fields)
+  hashes = generate_logling_hashes(count, fields)
+
+  loglings = []
+
+  hashes.each { |hash| loglings << Changeling::Models::Logling.new(hash) }
+
+  loglings
+end
+
+def generate_logling_hashes(count, fields)
+  hashes = []
+  count.times do
+    hash = {}
+
+    hash['klass'] = "Object"
+    hash['oid'] = BSON::ObjectId.new.to_s
+    hash['modified_by'] = BSON::ObjectId.new.to_s
+    hash['modified_at'] = Time.now.to_s
+    hash['modifications'] = {}
+    fields.times do |time|
+      hash['modifications']["name_of_field_#{time}"] = ["value_of_field_before_#{time}", "value_of_field_after_#{time}"]
+    end
+    hash['modifications'] = hash['modifications'].to_json
+
+    hashes << hash
+  end
+
+  hashes
+end

data/benchmarks/benchmark_setup.rake

@@ -0,0 +1,16 @@
+task :benchmark_setup do
+  Rake::Task["install"].invoke
+
+  begin
+    require 'changeling'
+    require 'bson'
+  rescue LoadError
+    require 'rubygems'
+    require 'changeling'
+    require 'bson'
+  end
+
+  # Setup Tire stuff for benchmarks.
+  Tire::Model::Search.index_prefix "changeling_benchmark"
+  Changeling::Models::Logling.tire.index.delete
+end

data/benchmarks/changeling_benchmark.rake

@@ -0,0 +1,34 @@
+desc "Benchmark Changeling processing times, from after_save hook through the final Tire index update."
+task :benchmark_changeling, :count, :fields do |t, args|
+  args.with_defaults(:count => 1000, :fields => 20)
+  count = args[:count].to_i
+  fields = args[:fields].to_i
+
+  Rake::Task["benchmark_setup"].invoke
+
+  puts "Benchmarking Changeling: #{count} object(s) with #{fields} fields each.".upcase
+  puts "Generating objects. This may take a minute..."
+
+  hashes = generate_logling_hashes(count, fields)
+  loglings = []
+
+  puts "Done generating objects. Proceeding to benchmark..."
+
+  Benchmark.bmbm do |bm|
+    bm.report('Creation of Logling Index') do
+      Changeling::Models::Logling.tire.create_elasticsearch_index
+    end
+
+    bm.report("Initializing Loglings") do
+      hashes.each { |hash| Changeling::Models::Logling.new(hash) }
+    end
+
+    bm.report('Creating Loglings') do
+      hashes.each { |hash| Changeling::Models::Logling.create(hash) }
+    end
+
+    bm.report('Deletion of Logling Index') do
+      Changeling::Models::Logling.tire.index.delete
+    end
+  end
+end

data/benchmarks/tire_benchmark.rake

@@ -0,0 +1,29 @@
+desc "Benchmark Tire indexing times alone when objects are already created."
+task :benchmark_tire, :count, :fields do |t, args|
+  args.with_defaults(:count => 1000, :fields => 20)
+  count = args[:count].to_i
+  fields = args[:fields].to_i
+
+  Rake::Task["benchmark_setup"].invoke
+
+  puts "Benchmarking Tire: #{count} Logling(s) with #{fields} fields each.".upcase
+  puts "Generating loglings. This may take a minute..."
+
+  loglings = generate_loglings(count, fields)
+
+  puts "Done generating loglings. Proceeding to benchmark..."
+
+  Benchmark.bmbm do |bm|
+    bm.report('Creation of Logling Index') do
+      Changeling::Models::Logling.tire.create_elasticsearch_index
+    end
+
+    bm.report('Inserting Loglings into Index') do
+      loglings.each { |logling| logling.update_index }
+    end
+
+    bm.report('Deletion of Logling Index') do
+      Changeling::Models::Logling.tire.index.delete
+    end
+  end
+end

data/changeling.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |gem|
   gem.version       = Changeling::VERSION
 
   # Dependencies
-  gem.add_dependency "tire", "~> 0.5.4"
+  gem.add_dependency "tire", "~> 0.5.3"
   gem.add_dependency "activemodel"
 
   # Development Dependencies
@@ -37,4 +37,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "database_cleaner"
   gem.add_development_dependency "sqlite3"
   gem.add_development_dependency "rails"
+  gem.add_development_dependency "sidekiq"
+  gem.add_development_dependency "resque"
 end

data/lib/changeling.rb

@@ -17,6 +17,16 @@ module Changeling
     autoload :Search, 'changeling/support/search'
   end
 
+  module Async
+    autoload :Trackling, 'changeling/async/trackling'
+    autoload :SidekiqWorker, 'changeling/async/sidekiq_worker'
+    autoload :ResqueWorker, 'changeling/async/resque_worker'
+  end
+
+  module Exceptions
+    autoload :AsyncGemRequired, 'changeling/exceptions/async_gem_required'
+  end
+
   def self.blame_user
     self.changeling_store[:blame_user]
   end

data/lib/changeling/async/resque_worker.rb

@@ -0,0 +1,11 @@
+module Changeling
+  module Async
+    class ResqueWorker
+      @queue = :changeling
+
+      def self.perform(json)
+        Changeling::Models::Logling.create(JSON.parse(json))
+      end
+    end
+  end
+end

data/lib/changeling/async/sidekiq_worker.rb

@@ -0,0 +1,16 @@
+module Changeling
+  module Async
+    class SidekiqWorker
+      # If Sidekiq is not installed, we'll throw an error when trying to access Changeling::Async::Trackling
+      begin
+        include Sidekiq::Worker
+        sidekiq_options :queue => :changeling
+      rescue
+      end
+
+      def perform(json)
+        Changeling::Models::Logling.create(JSON.parse(json))
+      end
+    end
+  end
+end

data/lib/changeling/async/trackling.rb

@@ -0,0 +1,27 @@
+module Changeling
+  module Async
+    module Trackling
+      def self.included(base)
+        base.after_update :async_save_logling
+      end
+
+      def async_save_logling
+        unless defined?(Sidekiq) || defined?(Resque)
+          raise Changeling::Exceptions::AsyncGemRequired
+        end
+
+        if self.changes && !self.changes.empty?
+          logling = Changeling::Models::Logling.new(self)
+
+          if defined?(Sidekiq)
+            Changeling::Async::SidekiqWorker.perform_async(logling.to_indexed_json)
+          elsif defined?(Resque)
+            Resque.enqueue(Changeling::Async::ResqueWorker, logling.to_indexed_json)
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/changeling/exceptions/async_gem_required.rb

@@ -0,0 +1,9 @@
+module Changeling
+  module Exceptions
+    class AsyncGemRequired < StandardError
+      def to_s
+        "Changeling's asynchronous features require either the Sidekiq (https://github.com/mperham/sidekiq) or Resque (https://github.com/defunkt/resque) background job processing gems. Please install either one and try again."
+      end
+    end
+  end
+end

data/lib/changeling/probeling.rb

@@ -1,15 +1,18 @@
 module Changeling
   module Probeling
-    def all_history
+    def all_loglings
       Changeling::Models::Logling.records_for(self)
     end
+    alias_method :all_history, :all_loglings
 
-    def history(records = 10)
+    def loglings(records = 10)
       Changeling::Models::Logling.records_for(self, records.to_i)
     end
+    alias_method :history, :loglings
 
-    def history_for_field(field_name, records = nil)
+    def loglings_for_field(field_name, records = nil)
       Changeling::Models::Logling.records_for(self, records ? records.to_i : nil, field_name.to_s)
     end
+    alias_method :history_for_field, :loglings_for_field
   end
 end

data/lib/changeling/trackling.rb

@@ -8,6 +8,8 @@ module Changeling
       if self.changes && !self.changes.empty?
         logling = Changeling::Models::Logling.create(self)
       end
+
+      true
     end
   end
 end

data/lib/changeling/version.rb

@@ -1,3 +1,3 @@
 module Changeling
-  VERSION = "0.0.7"
+  VERSION = "0.1.0"
 end

data/spec/controllers/blameling_integration_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+describe RailsApp, "Testing Blameling Integration" do
+  context "Controller without Blameling" do
+    controller(RailsApp::BlogPostsController) do
+      extend(RSpec::Rails::ControllerExampleGroup::BypassRescue)
+    end
+
+    before(:each) do
+      # Request needs to be setup to avoid path setting error
+      @request = ActionController::TestRequest.new
+    end
+
+    it "should not set current_user" do
+      Thread.new {
+        post :create
+        # Look in application.rb for the User class and it's id method.
+        BlogPost.last.all_loglings.last.modified_by.should == nil
+      }.join
+    end
+  end
+
+  context "Controller with Blameling" do
+    controller(RailsApp::BlamelingController) do
+      extend(RSpec::Rails::ControllerExampleGroup::BypassRescue)
+    end
+
+    before(:each) do
+      # Request needs to be setup to avoid path setting error
+      @request = ActionController::TestRequest.new
+    end
+
+    it "should set current_user" do
+      Thread.new {
+        post :create
+        # Look in application.rb for the User class and it's id method.
+        BlogPost.last.all_loglings.last.modified_by.should == 33
+      }.join
+    end
+  end
+
+  context "Controller with undefined current_user method" do
+    controller(RailsApp::NoCurrentUserController) do
+      extend(RSpec::Rails::ControllerExampleGroup::BypassRescue)
+    end
+
+    before(:each) do
+      # Request needs to be setup to avoid path setting error
+      @request = ActionController::TestRequest.new
+    end
+
+    it "should not set current_user, nor should it error out" do
+      Thread.new {
+        post :create
+        # Look in application.rb for the User class and it's id method.
+        BlogPost.last.all_loglings.last.modified_by.should == nil
+      }.join
+    end
+  end
+
+  context "Controller with a different overridden 'changeling_blame_user' method" do
+    controller(RailsApp::CurrentAccountController) do
+      extend(RSpec::Rails::ControllerExampleGroup::BypassRescue)
+    end
+
+    before(:each) do
+      # Request needs to be setup to avoid path setting error
+      @request = ActionController::TestRequest.new
+    end
+
+    it "should not set current_user if current_user is not defined" do
+      Thread.new {
+        post :create
+        # Look in application.rb for the User class and it's id method.
+        BlogPost.last.all_loglings.last.modified_by.should == 88
+      }.join
+    end
+  end
+end