simple_audit 0.1.0 → 0.1.1

data/README.markdown

@@ -0,0 +1,127 @@
+# simple_audit
+
+Simple auditing solution for ActiveRecord models. Provides an easy way of creating audit logs for complex model associations.
+Instead of storing audits for all data aggregated by the audited model, you can specify a serializable representation of the model.
+    
+  * a helper method is provided to easily display the audit log
+  * the Audit object provides a #delta method which computes the differences between two audits
+
+In a nutshell:
+
+    class Booking < ActiveRecord::Base
+      simple_audit do |record|
+        # data to be audited
+        {
+            :price => record.price,
+            :period => record.period, 
+            ...
+        }
+      end
+    end
+    
+    # in your view
+    <%= render_audits(@booking) %>
+
+# Why ?
+
+simple_audit is intended as a straightforward auditing solution for complex model associations. 
+In a normalized data structure (which is usually the case when using SQL), a core business model will aggregate data from several associated entities.
+More often than not in such cases, only the core model is of interest from an auditing point of view. 
+
+So instead of auditing every entity separately, with simple_audit you decide for each audited model what data needs to be audited. 
+This data will be serialized on every model update and the available helper methods will render a clear audit trail.
+
+![Screenshot of helper result](http://github.com/gtarnovan/simple_audit/raw/master/screenshot.png)
+
+# Installation & Configuration
+
+## Rails 2.3.x
+
+### Gem
+
+    # in your config/environment.rb    
+    config.gem 'simple_audit'
+        
+    # then install if you don't already have it
+    rake gems:install
+
+### Plugin
+  
+    ./script/plugin install http://github.com/gtarnovan/simple_audit
+
+### Post installation
+    # generate & run migration
+    ./script/generate simple_audit_migration
+    rake db:migrate
+
+## Rails 3
+    # in your Gemfile
+    gem 'simple_audit'
+    
+    # then install
+    bundle install
+
+### Post installation
+    # generate & run migration
+    rails generate simple_audit:migration
+    rake db:migrate
+
+# Usage
+
+Audit ActiveRecord models. Somewhere in your (backend) views show the audit logs.
+    
+    # in your model
+    # app/models/booking.rb
+    
+    class Booking < ActiveRecord::Base
+        simple_audit
+        ...
+    end
+    
+    # in your view
+    # app/views/bookings/booking.html.erb
+    
+    ...
+    <%= render_audits(@booking) %>
+    ...     
+
+# Assumptions and limitations
+
+  * Your user model is called User and the current user User.current
+    See [sentient_user](http://github.com/bokmann/sentient_user) for more information.
+
+    
+## Customize auditing
+
+By default after each save, all model's attributes are saved in the audits table.
+You can customize the data which is saved by supplying a block which will return all relevant data for the audited model.
+
+    # app/models/booking.rb
+    
+    class Booking < ActiveRecord::Base
+        simple_audit do |record|
+          {
+            :state  => record.state, 
+            :price  => record.price.format,
+            :period => record.period.to_s,
+            :housing_units => record.housing_units.collect(&:name).join('; '),
+            ...
+            }
+        end
+        ...
+    end
+    
+You can also customize the attribute of the User model which will be stored in the audit.
+
+    # default is :name
+    simple_audit :username_method => :email
+    
+## Rendering audit trail
+
+A helper method for displaying a list of audits is provided. It will render a decorated list of the provided audits;
+only the differences between revisions will be shown, thus making the audit information easily readable.
+
+![Screenshot of helper result](http://github.com/gtarnovan/simple_audit/raw/master/screenshot.png)
+    
+
+Copyright (c) 2010 [Gabriel Târnovan, Cubus Arts](http://cubus.ro "Cubus Arts"), released under the MIT license

data/Rakefile

@@ -45,7 +45,7 @@ begin
     gemspec.email = ["gabriel.tarnovan@cubus.ro", "mihai.tarnovan@cubus.ro"]
     gemspec.homepage = "http://github.com/gtarnovan/simple_audit"
     gemspec.authors = ["Gabriel Tarnovan", "Mihai Tarnovan"]
-    gemspec.version = "0.1.0"
+    gemspec.version = "0.1.1"
     gemspec.files = gem_files
     gemspec.test_files = test_files
     

data/TODO

@@ -2,11 +2,16 @@
 * support for ActiveModel
 * ORM agnosticism
 
-# Funtionality
+# Functionality
 * provide some sort of UUID for audited models that identify these independently from the database provided ID.
   in case of deletion and creation of a new entity with the same UUID, the audit trails of both entities could be bound.
   e.g. for an invoice the UUID could be its number/series combination. when someone deletes an invoice and creates a new one
   with the same UUID, the audit trail of both instances should be bound, such that the deletion event is visible during the audit (i.e. in the view helper)
 
+* recent activity page
+
+# Testing
+* test helper  
+
 # Minor
 * provide a sample css file for audit trail rendering

data/lib/simple_audit.rb

@@ -6,7 +6,7 @@ require 'simple_audit/audit'
 require 'simple_audit/helper'
 
 if defined?(ActiveRecord::Base)
-  ActiveRecord::Base.send :include, SimpleAudit
+  ActiveRecord::Base.send :include, SimpleAudit::Model
 end
 
 if defined?(ActionView::Base)

data/lib/simple_audit/audit.rb

@@ -17,7 +17,7 @@ module SimpleAudit #:nodoc:
     
       return self.change_log if other_audit.nil?
     
-      returning({}) do |d|
+      {}.tap do |d|
         
         # first for keys present only in this audit
         (self.change_log.keys - other_audit.change_log.keys).each do |k|

data/lib/simple_audit/helper.rb

@@ -14,7 +14,7 @@ module SimpleAudit #:nodoc:
           content_tag(:div, audit.username, :class => "user") + 
           content_tag(:div, l(audit.created_at), :class => "timestamp") + 
           content_tag(:div, :class => 'changes') do
-            if older_audit.present?
+            changes = if older_audit.present?
               audit.delta(older_audit).collect do |k, v| 
                 "\n" + 
                 audited_model.class.human_attribute_name(k) +
@@ -24,7 +24,8 @@ module SimpleAudit #:nodoc:
               end
             else
               audit.change_log.reject{|k, v| v.blank?}.collect {|k, v| "\n#{audited_model.class.human_attribute_name(k)}: #{v}"}
-            end    
+            end
+            changes.join    
           end        
         end
       end

data/lib/simple_audit/simple_audit.rb

@@ -7,67 +7,69 @@
 #
 # See SimpleAudit::ClassMethods#simple_audit for configuration options
 
-module SimpleAudit 
-  def self.included(base) #:nodoc:
-    base.send :extend, ClassMethods
-  end
+module SimpleAudit
+
+  module Model
+    def self.included(base) #:nodoc:
+      base.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+
+      # == Configuration options
+      #
+      # * <tt>username_method => symbol</tt> - Call this method on the current user to get the name
+      #
+      # With no block, all the attributes of the audited model will be logged.
+      #
+      #    class Booking
+      #      # this is equivalent to passing no block
+      #      simple_audit do |audited_record|
+      #        audited_record.attributes
+      #      end
+      #    end
+      #
+      # If a block is given, the data returned by the block will be saved in the audit's change log.
+      #
+      #    class Booking
+      #      has_many :housing_units
+      #      simple_audit do |audited_record|
+      #        {
+      #          :some_relevant_attribute => audited_record.some_relevant_attribute,
+      #          :human_readable_serialization_of_aggregated_models => audited_record.housing_units.collect(&:to_s),
+      #          ...
+      #        }
+      #      end
+      #    end
+      #
+
+      def simple_audit(options = {}, &block)
+        class_eval do
 
-  module ClassMethods
-  
-    # == Configuration options
-    # 
-    # * <tt>username_method => symbol</tt> - Call this method on the current user to get the name
-    # 
-    # With no block, all the attributes of the audited model will be logged.
-    #
-    #    class Booking
-    #      # this is equivalent to passing no block
-    #      simple_audit do |audited_record|
-    #        audited_record.attributes
-    #      end
-    #    end
-    #
-    # If a block is given, the data returned by the block will be saved in the audit's change log.
-    #
-    #    class Booking
-    #      has_many :housing_units
-    #      simple_audit do |audited_record|
-    #        {
-    #          :some_relevant_attribute => audited_record.some_relevant_attribute,
-    #          :human_readable_serialization_of_aggregated_models => audited_record.housing_units.collect(&:to_s),
-    #          ...
-    #        }
-    #      end
-    #    end
-    #
+          write_inheritable_attribute :username_method, (options[:username_method] || :name).to_sym
+          class_inheritable_reader :username_method
 
-    def simple_audit(options = {}, &block)
-      class_eval do 
-        
-        write_inheritable_attribute :username_method, (options[:username_method] || :name).to_sym
-        class_inheritable_reader :username_method
-        
-        audit_changes_proc = block_given? ? block.to_proc : Proc.new {|record| record.attributes}
-        write_inheritable_attribute :audit_changes, audit_changes_proc
-        class_inheritable_reader :audit_changes
+          audit_changes_proc = block_given? ? block.to_proc : Proc.new {|record| record.attributes}
+          write_inheritable_attribute :audit_changes, audit_changes_proc
+          class_inheritable_reader :audit_changes
 
-        has_many :audits, :as => :auditable, :class_name => '::SimpleAudit::Audit'
-        
-        after_create {|record| record.class.audit(record, :create)}
-        after_update {|record| record.class.audit(record, :update)}
-            
+          has_many :audits, :as => :auditable, :class_name => '::SimpleAudit::Audit'
+
+          after_create {|record| record.class.audit(record, :create)}
+          after_update {|record| record.class.audit(record, :update)}
+
+        end
+      end
+
+      def audit(record, action = :update, user = nil) #:nodoc:
+        user ||= User.current if User.respond_to?(:current)
+        record.audits.create(:user => user,
+          :username => user.try(self.username_method),
+          :action => action.to_s,
+          :change_log => self.audit_changes.call(record)
+        )
       end
     end
     
-    def audit(record, action = :update, user = nil) #:nodoc:
-      user ||= User.current if User.respond_to?(:current)
-      record.audits.create(:user => user, 
-        :username => user.try(self.username_method), 
-        :action => action.to_s, 
-        :change_log => self.audit_changes.call(record)
-      )
-    end
-  
   end
-  
 end

data/rails-magazine-article.markdown

@@ -0,0 +1,112 @@
+# Auditing in Rails
+
+Auditing is a broad term, but when talking about web applications it usually refers to keeping track of who did what, and when. Auditing changes in models is a common requirement for web applications. For Rails there are several solutions which provide this functionality. We'll be looking at two of the best solutions available - acts_as_audit and paper_trail - and introduce simple_audit, a straightforward approach focusing on human readable audit trails.
+
+## Implementing Auditing with Rails
+
+Implementing an auditing solution for ActiveRecord models is pretty straightforward due to the many interception points ActiveRecord provides in the lifecycle of a record with callbacks, observers and cache sweepers. Every change to a record can thus easily be tracked and stored in the database.
+
+<pre>
+class AuditObserver < ActiveRecord::Observer
+    observe :person, :account
+
+    def after_update(record)
+      AuditTrail.new(record, "UPDATED")          
+    end
+end 
+</pre>
+
+As you can see, the problem with using observers is that the user who performed the update is not accessible. Sweepers don't have this problem, as they can access the session through the controller, but they will only track changes originating in controller actions. To work around this problem when employing observers/callbacks, many solutions use Thread.local to store the currently logged user, making the data globally available.
+
+There are two main approaches for storing the audited records' changes:
+
+* one additional audit table for each audited model; audit tables will have the same structure as the audited tables
+* a single audit table for all audited models; tracked changes are stored in a serialized form 
+
+Using the first approach allows one to issue database queries directly on the audited attributes of a model; this can not be done efficiently with a serialized form used by the second approach.
+
+The second approach is used more widely due its flexibility:
+
+* any number of models can be audited
+* changes to the attributes of the audited models don't require any updates to the audits table or to the already audited changes
+* database backups / exports can be managed easier
+* smaller footprint - only the changed attributes can be stored, not the entire record
+
+Versioning solutions are very similar to auditing solutions; core functionality is basically the same. This is why versioning systems are sometimes also employed for the auditing system of an application or vice versa. See [vestal_versions](http://github.com/laserlemon/vestal_versions) for a solid versioning solution.
+
+When relying on ActiveRecord's hooks in the lifecycle of a record to perform auditing, one should keep in mind that some operations will not trigger callbacks and will have to be audited separately. Such operations include direct queries to the database, methods that don't instantiate the records like ActiveRecord#delete_all, #update_all, updating counter caches on associations, etc.
+
+## Available Auditing Solutions for Rails
+
+[acts_as_audit](http://github.com/collectiveidea/acts_as_audited) is an established solution for auditing in Rails, having been around since Rails 1.2. It stores each change to a model's attributes in an audit table. The initial value is also stored, making each audit entry self-contained. One can specify which attributes should be audited; the _current_user_ method of the controller is used to get the acting user. A list of versions is available for each audited records.
+
+[paper_trail](http://github.com/airblade/paper_trail) is a good solution for both auditing and versioning your models. Besides the functionality provided by acts_as_audited, it allows you to store arbitrary controller-level information  (e.g. remote IP, user agent, etc) and also arbitrary model-level metadata with each version. Metadata fields must have their respective columns in the audits table; this allows audits to be quickly filtered using SQL rather then deserializing all data and then filtering it. 
+
+## Keeping it simple: simple_audit
+
+[simple_audit](http://github.com/gtarnovan/simple_audit) is an auditing solution for Rails primarily intended to be used when the human readable representation of the changes is the main reason for implementing the audit. It handles everything from storing record changes to displaying a human readable audit trail.
+
+Many applications need auditing just to show to a privileged user details about actions performed on the database records. Versioning, storing all changed attributes - especially database internal data like record ids - are not as important as displaying a human readable activity feed in a form that is easy to interpret.
+
+simple_audit encourages the developer to generate a readable representation of the relevant attributes of a model. This is especially helpful when tracking changes on the parent of a complex aggregation or on a composite record (see [aggregation vs composition](http://en.wikipedia.org/wiki/Object_composition#Aggregation) ). 
+Tracking changes on all records in the database is required in certain situations, but it gets complicated if one has to rebuild an aggregation of several audited records just to display a readable audit log.
+
+Let's look at an example:
+
+<pre>
+    class Person < ActiveRecord::Base
+      belongs_to :booking
+      has_one :address
+    end
+    
+    class Room < ActiveRecord::Base
+      has_many :room_bookings
+      has_many :bookings, :through => :room_bookings
+    end
+    
+    class RoomBooking < ActiveRecord::Base
+      belongs_to :room
+      belongs_to :booking
+    end
+    
+    class Booking < ActiveRecord::Base
+      has_one :person
+      has_many :room_bookings
+      has_many :rooms, :through => :room_bookings
+            
+      simple_audit do |booking|
+        # this is a human readable representation of the relevant attributes
+        {
+            :person => "#{booking.person.full_name} #{booking.address.to_s}",
+            :housing_units  => booking.rooms.collect(&:name).join('; '), 
+            :arrival => booking.arrival,
+            ...
+            # other relevant data
+        }
+      end
+      
+    end
+</pre>
+
+The audit trail generated by the supplied view helper will look like this:
+
+![Screenshot of helper result](http://github.com/gtarnovan/simple_audit/raw/master/screenshot.png)
+
+In this context, changes made to booking records are central to the application domain. RoomBooking and Person records are relevant only in the context of a booking, therefore auditing them separately would make little sense and would require recomposing data from several audit entries just to show a single change in a booking.
+
+simple_audit works on Rails 2.3.x and Rails 3.
+
+### Future developments of simple_audit
+
+Support for other ORMs is planned to be implemented until end of november. This will include support for DataMapper and MongoDB.
+
+Another planned development is auditing controller actions. Not every action results in a change to the database, but even such actions are sometimes worth tracking (e.g. login & logout, searches, sending email, etc). 
+<br />
+Tracking database updates and controller actions would cover most auditing needs for web applications.
+
+Integration of [Aquarium](http://aquarium.rubyforge.org/) AOP library to enable auditing of any relevant method call will also be investigated.
+
+
+
+
+

data/simple_audit.gemspec

@@ -5,22 +5,24 @@
 
 Gem::Specification.new do |s|
   s.name = %q{simple_audit}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Gabriel Tarnovan", "Mihai Tarnovan"]
-  s.date = %q{2010-09-29}
+  s.date = %q{2010-11-09}
   s.description = %q{      Provides a straightforward way for auditing changes on active record models, especially for composite entities. 
       Also provides helper methods for easily rendering an audit trail in Ruby on Rails views.
 }
   s.email = ["gabriel.tarnovan@cubus.ro", "mihai.tarnovan@cubus.ro"]
   s.extra_rdoc_files = [
     "LICENSE",
+     "README.markdown",
      "TODO"
   ]
   s.files = [
     "CHANGELOG",
      "LICENSE",
+     "README.markdown",
      "Rakefile",
      "TODO",
      "generators/simple_audit_migration/USAGE",
@@ -32,6 +34,7 @@ Gem::Specification.new do |s|
      "lib/simple_audit/audit.rb",
      "lib/simple_audit/helper.rb",
      "lib/simple_audit/simple_audit.rb",
+     "rails-magazine-article.markdown",
      "rails/init.rb",
      "screenshot.png",
      "simple_audit.gemspec",
@@ -44,7 +47,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{simple_audit}
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{Simple auditing solution for ActiveRecord models}
   s.test_files = [
     "test/fixtures",
@@ -59,7 +62,7 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
     else
     end
   else

data/test/test_helper.rb

@@ -1,7 +1,6 @@
 require 'rubygems'
 require 'test/unit'
-require 'active_support'
-require 'active_support/test_case'
+require 'active_support/all'
 require 'active_record'
 require 'active_record/fixtures'
 require 'action_controller'

data/test/unit/simple_audit_test.rb

@@ -62,5 +62,5 @@ class SimpleAuditTest < ActiveSupport::TestCase
     address = Address.create
     assert_equal User.new.full_name, address.audits.last.username
   end
- 
+   
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: simple_audit
 version: !ruby/object:Gem::Version 
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Gabriel Tarnovan
@@ -15,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-29 00:00:00 +03:00
+date: 2010-11-09 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -29,10 +30,12 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
+- README.markdown
 - TODO
 files: 
 - CHANGELOG
 - LICENSE
+- README.markdown
 - Rakefile
 - TODO
 - generators/simple_audit_migration/USAGE
@@ -44,6 +47,7 @@ files:
 - lib/simple_audit/audit.rb
 - lib/simple_audit/helper.rb
 - lib/simple_audit/simple_audit.rb
+- rails-magazine-article.markdown
 - rails/init.rb
 - screenshot.png
 - simple_audit.gemspec
@@ -61,23 +65,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: simple_audit
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Simple auditing solution for ActiveRecord models