auditor 1.0.0 → 2.0.0

data/.gitignore

@@ -0,0 +1,8 @@
+coverage
+rdoc
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+tmp/*
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in auditor.gemspec
+gemspec

data/README.rdoc

@@ -37,28 +37,24 @@ Auditor needs to know who the current user is, but with no standard for doing so
 
 Auditor works very similarly to Joshua Clayton's acts_as_auditable plugin. There are two audit calls in the example below. The first declares that create and update actions should be audited for the EditablePage model and the string returned by the passed block should be included as a custom message. The second audit call simply changes the custom message when auditing destroy (aka delete) actions.
 
-  class EditablePage < ActiveRecord::Base
-    include Auditor::ModelAudit
-    
-    has_many :tags
-    
-    audit(:create, :update) { |model, user| "Editable page modified by #{user.display_name}" }
-    audit(:destroy) { |model, user| "#{user.display_name} deleted editable page #{model.id}" }
+  class Page < ActiveRecord::Base
+    audit(:create, :update) { |model, user| "Page modified by #{user.display_name}" }
+    audit(:destroy) { |model, user| "#{user.display_name} deleted page #{model.id}" }
   end
 
 All audit data is stored in a table named Audits, which is automatically created for you when you run the migration included with the plugin. However, there's a lot more recorded than just the custom message, including:
 
 * auditable_id - the primary key of the table belonging to the audited model object
 * auditable_type - the class type of the audited model object
-* auditable_version - the version number of the audited model object (if versioning is tracked)
 * user_id - the primary key of the table belonging to the user being audited
 * user_type - the class type of the model object representing users in your application
 * action - a string indicating the action that was audited (create, update, destroy, or find)
-* message - the custom message returned by any block passed to the audit call
-* edits - a YAML string containing the before and after state of any model attributes that changed
+* audited_changes - a YAML string containing the before and after state of any model attributes that changed
+* comment - the custom message returned by any block passed to the audit call
+* version - an auditor-internal revision number for the audited model
 * created_at - the date and time the audit record was recorded
 
-The edits column automatically serializes the before and after state of any model attributes that change during the action. If there are only a few attributes you want to audit or a couple that you want to prevent from being audited, you can specify that in the audit call. For example
+The audited_changes column automatically serializes the changes of any model attributes modified during the action. If there are only a few attributes you want to audit or a couple that you want to prevent from being audited, you can specify that in the audit call. For example
 
   # Prevent SSN and passwords from being saved in the audit table
   audit(:create, :destroy, :except => [:ssn, :password])
@@ -66,4 +62,55 @@ The edits column automatically serializes the before and after state of any mode
   # Only audit edits to the title column when destroying/deleting
   audit(:destroy, :only => :title)
 
+= Make Auditing Important
+
+There's an alternate form of specifying your audit requirements that will cause the create, find, update, or destroy to fail if for some reason the audit record cannot be saved to the database. Instead of calling audit, call audit! instead.
+
+  class Page < ActiveRecord::Base
+    audit!(:create, :update) { |model, user| "Page modified by #{user.display_name}" }
+    audit!(:destroy) { |model, user| "#{user.display_name} deleted page #{model.id}" }
+  end
+
+= Auditable Versioning
+
+Since auditor will keep a "diff" of all the changes applied to a model object, you can retrieve the state of any audited model object's attributes at any point in time. For this to work, you have to specify auditing for all actions that modify the table, which is create, update, and destroy. Assuming those attributes have been declared with a call to audit or audit!, the following shows you how to use the revisions.
+
+  p = Page.create(:title => "Revision 1")
+  p.audits.last.attribute_snapshot
+  > {:title => "Revision 1"}
+  time = Time.now
+  p.author = "Jeff"
+  p.save
+  p.audits.last.attribute_snapshot
+  > {:title => "Revision 1", :author => "Jeff"}
+  p.attributes_at(time)
+  > {:title => "Revision 1"}
+
+= Integration
+There may be some instances where you need to perform an action on your model object without Auditor recording the action. In those cases you can include the Auditor::Status module for help.
+
+  class PagesController < ApplicationController
+    include Auditor::Status
+
+    def update
+      page = Page.find(params[:id])
+        without_auditing { page.update_attributes(params[:page]) } # Auditor is disabled for the entire block
+      end
+    end
+  end
+
+You can also force Auditor to audit any actions within a block as a specified user.
+
+  class PagesController < ApplicationController
+    include Auditor::Status
+
+    def update
+      page = Page.find(params[:id])
+        # Auditor will attribute update to 'another user'
+        audit_as(another_user) { page.update_attributes(params[:page]) }
+      end
+    end
+  end
+
+
 Copyright (c) 2011 Near Infinity Corporation, released under the MIT license

data/Rakefile

@@ -0,0 +1,33 @@
+$:.unshift File.expand_path("../lib", __FILE__)
+
+require 'rake'
+require 'rake/rdoctask'
+require 'rspec/core/rake_task'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+desc 'Default: run specs'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = %w(-fs --color)
+end
+
+desc "Run specs with RCov"
+RSpec::Core::RakeTask.new(:rcov) do |t|
+  t.rspec_opts = %w(-fs --color)
+  t.rcov = true
+  t.rcov_opts = %w(--exclude "spec/*,gems/*")
+end
+
+desc 'Generate documentation for the gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Auditor'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/auditor.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "auditor/version"
+
+Gem::Specification.new do |s|
+  s.name        = "auditor"
+  s.version     = Auditor::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jeff Kunkle"]
+  s.homepage    = "http://github.com/nearinfinity/auditor"
+  s.summary     = %q{Rails 3 plugin for auditing access to your ActiveRecord model objects}
+  s.description = %q{Auditor allows you to declaratively specify what CRUD operations should be audited and save the audit data to the database.}
+  s.license     = "MIT"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency('rspec', '2.5.0')
+  s.add_development_dependency('sqlite3-ruby', '1.3.3')
+  s.add_development_dependency('activerecord', '> 3.0.0')
+end

data/init.rb

@@ -0,0 +1 @@
+require 'auditor'

data/lib/auditor.rb

@@ -1,9 +1,21 @@
 require 'auditor/audit'
-require 'auditor/integration'
-require 'auditor/model_audit'
-require 'auditor/user'
-require 'auditor/version'
+require 'auditor/auditable'
 
 module Auditor
   class Error < StandardError; end
 end
+
+ActiveRecord::Base.send :include, Auditor::Auditable
+
+if defined?(ActionController) and defined?(ActionController::Base)
+
+  require 'auditor/user'
+
+  ActionController::Base.class_eval do
+    before_filter do
+      Auditor::User.current_user = self.current_user if self.respond_to?(:current_user)
+    end
+  end
+
+end
+

data/lib/auditor/audit.rb

@@ -1,6 +1,53 @@
 require 'active_record'
+require 'auditor/config'
 
 class Audit < ActiveRecord::Base
-  validates_presence_of :auditable_id, :auditable_type, :user_id, :user_type, :action
-  serialize :edits
+  belongs_to :auditable, :polymorphic => true
+  belongs_to :user, :polymorphic => true
+
+  before_create :set_version_number
+  before_create :set_user
+
+  serialize :audited_changes
+
+  default_scope order(:version, :created_at)
+  scope :modifying, lambda { where('action in (?)', Auditor::Config.modifying_actions) }
+  scope :trail, lambda { |audit|
+    where('auditable_id = ? and auditable_type = ? and version <= ?',
+    audit.auditable_id, audit.auditable_type, audit.version) 
+  }
+
+  def attribute_snapshot
+    attributes = {}.with_indifferent_access
+    self.class.modifying.trail(self).each do |predecessor|
+      attributes.merge!(predecessor.new_attributes)
+    end
+    attributes
+  end
+
+protected
+
+  # Returns a hash of the changed attributes with the new values
+  def new_attributes
+    (audited_changes || {}).inject({}.with_indifferent_access) do |attrs,(attr,values)|
+      attrs[attr] = values.is_a?(Array) ? values.last : values
+      attrs
+    end
+  end
+
+private
+
+  def set_version_number
+    max = self.class.where(
+      :auditable_id => auditable_id,
+      :auditable_type => auditable_type
+    ).maximum(:version) || 0
+
+    self.version = Auditor::Config.modifying_actions.include?(self.action.to_sym) ? max + 1 : max
+  end
+
+  def set_user
+    self.user = Auditor::User.current_user if self.user_id.nil?
+  end
+
 end

data/lib/auditor/auditable.rb

@@ -0,0 +1,44 @@
+require 'auditor/status'
+require 'auditor/config'
+require 'auditor/recorder'
+
+module Auditor
+  module Auditable
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def audit(*args, &blk)
+        unless self.included_modules.include?(Auditor::Auditable::InstanceMethods)
+          include InstanceMethods
+          include Auditor::Status unless self.included_modules.include?(Auditor::Status)
+          has_many :audits, :as => :auditable
+        end
+
+        config = Auditor::Config.new(*args)
+        config.actions.each do |action|
+          send "after_#{action}", Auditor::Recorder.new(config.options, &blk)
+        end
+      end
+
+      def audit!(*args, &blk)
+        if args.last.kind_of?(Hash)
+          args.last[:fail_on_error] = true
+        else
+          args << { :fail_on_error => true }
+        end
+
+        audit(*args, &blk)
+      end
+    end
+
+    module InstanceMethods
+      def attributes_at(date_or_time)
+        audits.where('created_at <= ?', date_or_time).last.attribute_snapshot
+      end
+    end
+
+  end
+end

data/lib/auditor/config.rb

@@ -0,0 +1,38 @@
+module Auditor
+  class Config
+    attr_reader :actions
+    attr_reader :options
+
+    def self.valid_actions
+      @valid_actions ||= [:create, :find, :update, :destroy]
+    end
+
+    def self.modifying_actions
+      @modifying_actions ||= [:create, :update, :destroy]
+    end
+
+    def initialize(*args)
+      @options = (args.pop if args.last.kind_of?(Hash)) || {}
+      normalize_options(@options)
+
+      @actions = args.map(&:to_sym)
+      validate_actions(@actions)
+    end
+
+  private
+
+    def normalize_options(options)
+      options.each_pair { |k, v| options[k.to_sym] = options.delete(k) unless k.kind_of? Symbol }
+      options[:only] ||= []
+      options[:except] ||= []
+      options[:only] = Array(options[:only]).map(&:to_s)
+      options[:except] = Array(options[:except]).map(&:to_s)
+    end
+
+    def validate_actions(actions)
+      raise Auditor::Error.new "at least one action in #{Config.valid_actions.inspect} must be specified" if actions.empty?
+      raise Auditor::Error.new "#{Config.valid_actions.inspect} are the only valid actions" unless actions.all? { |a| Config.valid_actions.include?(a.to_sym) }
+    end
+
+  end
+end

data/lib/auditor/recorder.rb

@@ -1,44 +1,45 @@
-require 'auditor/user'
+require 'auditor/status'
 
 module Auditor
   class Recorder
-    
-    def initialize(action, model, options, &blk)
-      @action, @model, @options, @blk = action.to_sym, model, options, blk
+    include Status
+
+    def initialize(options, &blk)
+      @options = options
+      @blk = blk
     end
-      
-    def audit_before
-      @audit = Audit.new(:edits => prepare_edits(@model.changes, @options))
+
+    [:create, :find, :update, :destroy].each do |action|
+      define_method("after_#{action}") do |model|
+        audit(model, action)
+      end
     end
 
-    def audit_after
-      @audit ||= Audit.new
-      
-      @audit.attributes = {
-        :auditable_id => @model.id,
-        :auditable_type => @model.class.to_s,
-        :user_id => user.id,
-        :user_type => user.class.to_s,
-        :action => @action.to_s
-      }
-      
-      @audit.auditable_version = @model.version if @model.respond_to? :version
-      @audit.message = @blk.call(@model, user) if @blk
-
-      @audit.save  
+  private
+
+    def audit(model, action)
+      return nil if auditing_disabled?
+      user = Auditor::User.current_user
+
+      audit = Audit.new
+      audit.auditable = model
+      audit.audited_changes = prepare_changes(model.changes) if changes_available?(action)
+      audit.action = action
+      audit.comment = @blk.call(model, user) if @blk
+
+      @options[:fail_on_error] ? audit.save! : audit.save
     end
-    
-    private
-      def user
-        Auditor::User.current_user
-      end
-      
-      def prepare_edits(changes, options)
-        chg = changes.dup
-        chg = chg.delete_if { |key, value| options[:except].include? key } unless options[:except].empty?
-        chg = chg.delete_if { |key, value| !options[:only].include? key } unless options[:only].empty?
-        chg.empty? ? nil : chg
-      end
-    
+
+    def prepare_changes(changes)
+      chg = changes.dup
+      chg = chg.delete_if { |key, value| @options[:except].include?(key) } unless @options[:except].empty?
+      chg = chg.delete_if { |key, value| !@options[:only].include?(key) } unless @options[:only].empty?
+      chg.empty? ? nil : chg
+    end
+
+    def changes_available?(action)
+      [:create, :update].include?(action)
+    end
+
   end
-end
+end

data/lib/auditor/spec_helpers.rb

@@ -1,19 +1,19 @@
 module Auditor
   module SpecHelpers
-    include Auditor::Integration
-    
+    include Auditor::Status
+
     def self.included(base)
       base.class_eval do
         before(:each) do
-          disable_auditor
+          disable_auditing
         end
-      
+
         after(:each) do
-          enable_auditor
+          enable_auditing
         end
       end
     end
-  
+
   end
 end
 

data/lib/auditor/status.rb

@@ -0,0 +1,60 @@
+module Auditor
+  module Status
+
+    def auditing_disabled?
+      Thread.current[:auditor_disabled] == true
+    end
+
+    def auditing_enabled?
+      Thread.current[:auditor_disabled] == false
+    end
+
+    def disable_auditing
+      Thread.current[:auditor_disabled] = true
+    end
+
+    def enable_auditing
+      Thread.current[:auditor_disabled] = false
+    end
+
+    def without_auditing
+      previously_disabled = auditing_disabled?
+
+      begin
+        disable_auditing
+        result = yield if block_given?
+      ensure
+        enable_auditing unless previously_disabled
+      end
+
+      result
+    end
+
+    def with_auditing
+      previously_disabled = auditing_disabled?
+
+      begin
+        enable_auditing
+        result = yield if block_given?
+      ensure
+        disable_auditing if previously_disabled
+      end
+
+      result
+    end
+
+    def audit_as(user)
+      previous_user = Audit::User.current_user
+
+      begin
+        Audit::User.current_user = user
+        result = yield if block_given?
+      ensure
+        Audit::User.current_user = previous_user
+      end
+
+      result
+    end
+
+  end
+end