action_auditor 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+spec/debug.log
+doc
+coverage

data/README.rdoc

@@ -0,0 +1,5 @@
+= ActionAuditor
+
+Allows you to write simple logs of your Rails actions.
+
+Copyright (c) 2009 Matt Powell, released under the MIT license

data/Rakefile

@@ -0,0 +1 @@
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/generators/action_auditor_migration/USAGE

@@ -0,0 +1,4 @@
+Description:
+  Generates a migration to create a database table to store
+  your application's audit trail.
+  

data/generators/action_auditor_migration/action_auditor_migration_generator.rb

@@ -0,0 +1,15 @@
+class ActionAuditorMigrationGenerator < Rails::Generator::Base
+  def initialize(runtime_args, runtime_options = {})
+    super
+  end
+  
+  def manifest
+    record do |m|
+      m.migration_template 'migration.rb', "db/migrate"
+    end
+  end
+  
+  def file_name
+    "create_action_auditor_table"
+  end
+end

data/generators/action_auditor_migration/templates/migration.rb

@@ -0,0 +1,16 @@
+class CreateActionAuditorTable < ActiveRecord::Migration
+  def self.up
+    create_table :logged_actions do |t|
+      t.belongs_to :scope, :polymorphic => true
+      t.text       :message
+      t.text       :parameters
+      t.timestamp  :created_at
+    end
+
+    add_index :logged_actions, [ :scope_type, :scope_id, :created_at ]
+  end
+  
+  def self.down
+    drop_table :logged_actions
+  end
+end

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/action_auditor.rb

@@ -0,0 +1,13 @@
+module ActionAuditor
+  def self.auditors
+    @@auditors ||= []
+  end
+  
+  def self.auditors=(auditors)
+    @@auditors = Array(auditors)
+  end
+  
+  def self.log(message, parameters = {})
+    auditors.each { |auditor| auditor.log(message, parameters) }
+  end
+end

data/lib/action_auditor/auditor/active_record.rb

@@ -0,0 +1,27 @@
+module ActionAuditor
+  module Auditor
+    class ActiveRecord < Base
+      class LoggedAction < ::ActiveRecord::Base
+        set_table_name "logged_actions"
+
+        serialize :parameters
+      end
+      
+      def clear!
+        LoggedAction.destroy_all
+      end
+      
+      def log(message, parameters = {})
+        LoggedAction.create :message => message, :parameters => parameters
+      end
+      
+      def size
+        LoggedAction.count
+      end
+      
+      def last
+        LoggedAction.last
+      end
+    end
+  end
+end

data/lib/action_auditor/auditor/base.rb

@@ -0,0 +1,7 @@
+module ActionAuditor
+  module Auditor
+    class Base
+
+    end
+  end
+end

data/lib/action_auditor/auditor/simple.rb

@@ -0,0 +1,33 @@
+module ActionAuditor
+  module Auditor
+    # The simplest possible implementation of an auditor.
+    # Simply maintains a list of [message, hash] pairs,
+    # with no persistence.
+    # This is mainly of use for testing.
+    class Simple < Base
+      class LoggedAction < Struct.new(:message, :parameters)
+        
+      end
+      
+      def initialize
+        @messages = []
+      end
+      
+      def clear!
+        @messages = []
+      end
+      
+      def log(message, parameters = {})
+        @messages << LoggedAction.new(message, parameters)
+      end
+      
+      def size
+        @messages.size
+      end
+      
+      def last
+        @messages.last
+      end
+    end
+  end
+end

data/lib/action_auditor/extensions/action_controller.rb

@@ -0,0 +1,107 @@
+module ActionAuditor
+  module Extensions
+    module ActionController
+      module ClassMethods
+        # Set up an audit trail for the next action defined.
+        # This is similar to +desc+ in a Rake task: you call it
+        # immediately before the action.
+        #
+        # == Simple messages
+        # This will log "hello, world" each time someone
+        # visits the +index+ page.
+        #     class PostsController < ApplicationController
+        #       audit "hello, world"
+        #       def index
+        #       end
+        #     end
+        #
+        # == Blocks
+        # If you need to interpolate any information at runtime,
+        # you'll need to use a block:
+        #     class PostsController < ApplicationController
+        #       audit { "#{current_user} stopped by" }
+        #       def index
+        #       end
+        #     end
+        # ...otherwise the string will get evaluated when the
+        # controller class is defined.
+        #
+        # == Parameters
+        # If you need to save any information besides a message,
+        # you can write a block that returns [+message+, +params+],
+        # where +params+ is a hash of objects:
+        #     class PostsController < ApplicationController
+        #       audit {[
+        #         "{{user}} created {{post}}",
+        #         { :user => current_user, :post => @post }
+        #       ]}
+        #       def create
+        #         @post = Post.create(params[:post])
+        #       end
+        #     end
+        # Notice that you can interpolate these parameters
+        # within your log message.
+        #
+        # It's up to the individual auditors how your parameters
+        # are saved — and, indeed, whether they're saved at all.
+        # An ActiveRecord implementation might serialize the
+        # objects, or just their IDs, while a text-only auditor
+        # might discard them completely. You should not rely on
+        # having access to these parameters later on, unless
+        # you know how and where they are saved.
+        def audit(*args, &block)
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          block_or_message = block_given? ? block : args.shift
+          @pending_auditor = [ args, options, block_or_message ]
+        end
+        
+        def method_added_with_auditing(name) #:nodoc:
+          method_added_without_auditing(name)
+          if @pending_auditor
+            auditors[name.to_sym] = @pending_auditor
+            @pending_auditor = nil
+          end
+        end
+      end
+      
+      # Filter method called after each action.
+      # Checks if there's any auditing set up for this
+      # action, then logs relevant information using
+      # any active auditors.
+      def audit_last_action
+        if auditor = self.class.auditors[action_name.to_sym]
+          args, options, block_or_message = auditor
+          parameters = {}
+          
+          log_message, parameters = case block_or_message
+          when String then [ block_or_message, {} ]
+          when Proc
+            values = Array(instance_eval(&block_or_message))
+            values << {} if values.size < 2
+            values[0,2]
+          end
+          
+          log_message.gsub!(/\{\{(\w+)\}\}/) { parameters[$1.to_sym].to_s }
+          
+          ActionAuditor.log(log_message, parameters)
+        end
+      end
+      protected :audit_last_action
+      
+      def self.included(receiver) #:nodoc:
+        receiver.extend ClassMethods
+        
+        receiver.class_eval do
+          class_inheritable_accessor :auditors
+          self.auditors = {}
+          
+          class << receiver
+            alias_method_chain :method_added, :auditing
+          end
+          
+          after_filter :audit_last_action
+        end
+      end
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1,3 @@
+# require "action_auditor"
+
+ActionController::Base.send :include, ActionAuditor::Extensions::ActionController

data/spec/action_auditor_spec.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/spec_helper'

data/spec/controllers/controller_integration_spec.rb

@@ -0,0 +1,116 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+class Thing
+  attr_accessor :attributes
+  
+  def initialize(attributes = {})
+    self.attributes = attributes
+  end
+  
+  def to_s
+    "Thing(#{attributes.collect { |k, v| "#{k}:#{v}" }.join(", ")})"
+  end
+  
+  def self.clear!
+    @things = []
+  end
+  
+  def self.create(params = {})
+    returning new(params) do |thing|
+      @things << thing
+    end
+  end
+  
+  def self.last
+    @things.last
+  end
+end
+
+class TestController < ActionController::Base
+  audit "Someone looked at something"
+  def simple
+    
+  end
+  
+  def unlogged
+    
+  end
+  
+  audit { "Message from #{current_user}" }
+  def substituted
+    
+  end
+  
+  audit { [ "{{user}} created {{thing}}", { :user => current_user, :thing => @thing } ] }
+  def complex
+    @thing = Thing.create :colour => :red
+  end
+  
+protected
+  def current_user
+    "Matt"
+  end
+end
+
+describe TestController do
+  [
+    ActionAuditor::Auditor::Simple.new,
+    ActionAuditor::Auditor::ActiveRecord.new
+  ].each do |auditor|
+    describe "with #{auditor.class.name.demodulize} auditing" do
+      before :each do
+        ActionAuditor.auditors = auditor
+        Thing.clear!
+        auditor.clear!
+      end
+      
+      it "should allow auditing" do
+        controller.class.should respond_to(:audit)
+      end
+      
+      it "should log visits to '/index" do
+        lambda {
+          get :simple
+        }.should change(auditor, :size).by(1)
+      end
+      
+      it "should provide a message on visits to /simple" do
+        get :simple
+        auditor.last.message.should == "Someone looked at something"
+      end
+      
+      it "should not log visits to /unlogged" do
+        lambda {
+          get :unlogged
+        }.should_not change(auditor, :size)
+      end
+      
+      it "should log visits to /substituted" do
+        lambda {
+          get :substituted
+        }.should change(auditor, :size).by(1)
+      end
+
+      it "should keep a correct log of visits to /substituted" do
+        get :substituted
+        auditor.last.message.should == "Message from Matt"
+        auditor.last.parameters.should be_empty
+      end
+
+      it "should log visits to /complex" do
+        lambda {
+          get :complex
+        }.should change(auditor, :size).by(1)
+      end
+
+      it "should keep a correct log of visits to /complex" do
+        get :complex
+        log = auditor.last
+        log.message.should == "Matt created Thing(colour:red)"
+        log.parameters[:user].should == "Matt"
+        log.parameters[:thing].should be_a(Thing)
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+begin
+  require File.dirname(__FILE__) + '/../../../../spec/spec_helper'
+rescue LoadError
+  puts "You need to install rspec in your base app"
+  exit
+end
+
+plugin_spec_dir = File.dirname(__FILE__)
+ActiveRecord::Base.logger = Logger.new(plugin_spec_dir + "/debug.log")
+

data/tasks/rdoc.rake

@@ -0,0 +1,17 @@
+begin
+  require 'hanna/rdoctask'
+rescue
+  require 'rake/rdoctask'
+end
+
+desc 'Generate RDoc documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.include('README.rdoc').
+    include('lib/**/*.rb')
+
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "ActionAuditor documentation"
+
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--webcvs=http://github.com/fauxparse/action_auditor/'
+end

data/tasks/spec.rake

@@ -0,0 +1,45 @@
+# Don't load rspec if running "rake gems:*"
+unless ARGV.any? {|a| a =~ /^gems/}
+
+begin
+  require 'spec/rake/spectask'
+rescue MissingSourceFile
+  module Spec
+    module Rake
+      class SpecTask
+        def initialize(name)
+          task name do
+            raise <<-MSG
+
+#{"*" * 80}
+*  You are trying to run an rspec rake task defined in
+*  #{__FILE__},
+*  but rspec cannot be found.
+#{"*" * 80}
+MSG
+          end
+        end
+      end
+    end
+  end
+end
+
+task :default => :spec
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+namespace :spec do
+  desc "Run all specs in spec directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = ['--text-report --rails --exclude "spec/*,application_controller.rb,application_helper.rb"']
+  end
+end
+
+end

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: action_auditor
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Matt Powell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-27 00:00:00 +13:00
+default_executable: 
+dependencies: []
+
+description: Keep an audit trail of actions in your application
+email: fauxparse@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- README.rdoc
+- Rakefile
+- VERSION
+- generators/action_auditor_migration/USAGE
+- generators/action_auditor_migration/action_auditor_migration_generator.rb
+- generators/action_auditor_migration/templates/migration.rb
+- install.rb
+- lib/action_auditor.rb
+- lib/action_auditor/auditor/active_record.rb
+- lib/action_auditor/auditor/base.rb
+- lib/action_auditor/auditor/simple.rb
+- lib/action_auditor/extensions/action_controller.rb
+- rails/init.rb
+- spec/action_auditor_spec.rb
+- spec/controllers/controller_integration_spec.rb
+- spec/spec_helper.rb
+- tasks/rdoc.rake
+- tasks/spec.rake
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/fauxparse/action_auditor
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Keep an audit trail of actions in your application
+test_files: 
+- spec/action_auditor_spec.rb
+- spec/controllers/controller_integration_spec.rb
+- spec/spec_helper.rb