mole 0.0.1

data/lib/mole.rb

@@ -0,0 +1,175 @@
+# $Id$
+
+# Equivalent to a header guard in C/C++
+# Used to prevent the class/module from being loaded more than once
+unless defined? Mole
+  require 'activerecord'
+  module Mole                 
+    # :stopdoc:
+    LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+    PATH    = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+    
+    # :startdoc:  
+    # The MOle can be ran in a couple of modes: Transient and Persistent         
+    # Transient mode will log the output to the specified log file
+    # Persistent mode will log the mole output to your db      
+    # The default is :transient
+    def self.run_modes #:nodoc:
+      [:transient, :persistent]
+    end
+  
+    # MOle Default settings 
+    def self.defaults #:nodoc:
+      @defaults ||= { 
+        :moleable         => false, 
+        :application      => "Default", 
+        :perf_threshold   => 5,          
+        :mode             => :transient,  
+        :emole_from       => "MOleBeatch",  
+        :mole_config      => nil,
+        :emole_recipients => [],
+      
+        # logging options
+        :log_file           => $stdout,
+        :log_level          => :info,
+        :email_alerts_to    => "MOleBeatch",
+        :email_alert_level  => :error }      
+    end                               
+                                     
+    # Reset the configuration to what it would be when the class is parsed
+    # this is needed mainly for running specs.  This resets the class to the
+    # state it was before initialize is called.  initialize MUST be called
+    # after reset_configuration! is invoked
+    def self.reset_configuration! #:nodoc:
+      @logger.clear_appenders if @logger
+      @logger = nil
+      @config = nil
+    end
+            
+    # Initialize the MOle 
+    # Valid options are
+    # <tt>moleable</tt>::         specify if this application is moleable.
+    #                             Defaults to false.
+    # <tt>application</tt>::      the name of the application to be moled.
+    # <tt>perf_threshold</tt>::   the performance threshold over which a Mole condition will be issued.
+    #                             Defaults to 5 seconds
+    # <tt>mode</tt>::             the MOle logging mole. The mole can either log information to a db via
+    #                             the :persistent option or to a log file via the :transient flag.
+    #                             Defaults to transient
+    # <tt>emole_from</tt>::       the EMole originator when sending eMOle alerts.
+    # <tt>emole_recipients</tt>:: a collection of EMOle recipients
+    # <tt>mole_config</tt>::      the location of the MOle configuration file where the interceptors will
+    #                             be defined.
+    # <tt>log_file</tt>::         The log file to be used to log MOle interceptions
+    # <tt>log_level</tt>::        logging level ie :info, :debug, :error, :warn...
+    # <tt>email_alerts_to</tt>::  log level email alert recipients.
+    # <tt>email_alert_level</tt>:: specifies which log level will trigger email alerts to be sent   
+    def self.initialize( opts={} ) 
+      @config = defaults.merge( opts )    
+      @config[:email_alerts_to] = @config[:emole_recipients] if @config[:emole_recipients] and !@config[:emole_recipients].empty?
+      # dump                       
+      # Add the mode to the ruby lib path...
+      $: << libpath
+      Mole.require_all_libs_relative_to __FILE__    
+                                   
+      raise "Unable to find the MOle configuration file #{conf_file}" if conf_file and !File.exists? conf_file
+      load conf_file if conf_file and moleable?
+    end
+      
+    # Fetch the MOle configuration file
+    def self.conf_file #:nodoc:
+      config[:mole_config]
+    end
+                 
+    # EMole alert sender             
+    def self.emole_from #:nodoc:
+      config[:emole_from]
+    end
+                        
+    # EMole alert recipients
+    def self.emole_recipients  #:nodoc:
+      config[:emole_recipients]
+    end
+             
+    # Fetch the MOle configuration
+    def self.config  #:nodoc:
+      @config
+    end
+  
+    # Debug                        
+    def self.dump #:nodoc:
+      puts "" 
+      puts "Mole Configuration Landscape"    
+      config.keys.sort{ |a,b| a.to_s <=> b.to_s }.each do |k| 
+        key   = k.to_s.rjust(20)
+        value = config[k].to_s.rjust(97,".")
+        puts "#{key} : #{value}"
+      end
+    end
+
+    # get a hold of a logger.  This is the global logger for sentiment.
+    def self.logger #:nodoc:   
+      @logger ||= ::Mole::Logger.new( { :log_file          => config[:log_file], 
+                                        :logger_name       => "MOle",
+                                        :log_level         => config[:log_level],
+                                        :email_alerts_to   => config[:email_alerts_to],
+                                        :email_alert_level => config[:email_alert_level],
+                                        :additive          => false } )
+    end
+            
+    # The name of the MOled application
+    def self.application #:nodoc:
+      config[:application]
+    end                
+                          
+    # Is this application is MOleable
+    def self.moleable? #:nodoc:
+      config[:moleable]
+    end                
+                                         
+    # Returns the MOle perf threshold. If any MOled features takes longer
+    # than this time to complete, then an alarm will be triggered...
+    def self.perf_threshold #:nodoc:
+      config[:perf_threshold]
+    end
+        
+    # Enable to toggle between different log modes ie :persistent/:transient
+    def self.switch_mode( mode )
+      config[:mode] = mode
+    end
+                      
+    # Check if the MOle is running in persistent mode
+    def self.persistent?
+      config[:mode] == :persistent
+    end
+  
+    # Returns the library path for the module. If any arguments are given,
+    # they will be joined to the end of the libray path using
+    # <tt>File.join</tt>.
+    #
+    def self.libpath( *args ) #:nodoc:
+      args.empty? ? LIBPATH : ::File.join(LIBPATH, *args)
+    end
+
+    # Returns the lpath for the module. If any arguments are given,
+    # they will be joined to the end of the path using
+    # <tt>File.join</tt>.
+    #
+    def self.path( *args ) #:nodoc:
+      args.empty? ? PATH : ::File.join(PATH, *args)
+    end
+
+    # Utility method used to rquire all files ending in .rb that lie in the
+    # directory below this file that has the same name as the filename passed
+    # in. Optionally, a specific _directory_ name can be passed in such that
+    # the _filename_ does not have to be equivalent to the directory.
+    #
+    def self.require_all_libs_relative_to( fname, dir = nil ) #:nodoc:
+      dir ||= ::File.basename(fname, '.*')
+      search_me = ::File.expand_path(
+          ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+      Dir.glob(search_me).sort.each {|rb| require rb}
+    end
+  end
+end

data/spec/data/blee.rb

@@ -0,0 +1,53 @@
+require 'mole/module'
+
+class Blee  
+  def self.blee_static
+  end
+  
+  def crap_out
+  end       
+    
+  def crap_out_too
+  end
+  
+  def blee_no_args                 
+    # puts ">>> Blee_No_Args"
+  end             
+  
+  def blee_args( i, p )
+    # puts ">>> Blee_Args #{i} -- #{p}"
+  end
+  
+  def blee_args_ret( p )
+    "Hello #{p}"
+  end  
+           
+  def blee_raise
+    raise "Blee exception"
+  end
+
+  def blee_raise_too
+    raise "Blee exception"
+  end
+          
+  def blee_slow
+    sleep( 1 )
+  end
+
+  def blee_slow_too
+    sleep( 1 )
+  end
+  
+  private
+  
+  def blee_private( arg )
+    arg
+  end
+    
+  protected
+  
+  def blee_protected( arg )
+    arg
+  end
+    
+end       

data/spec/db/migrate_spec.rb

@@ -0,0 +1,19 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper" )
+
+describe Mole::Db::Migrate do     
+  before( :all ) do        
+    ::Mole.reset_configuration!
+    ::Mole.initialize( :moleable => true )
+    @config = ::File.expand_path( ::File.join(::File.dirname(__FILE__), %w[.. .. config database.yml] ) )
+  end
+                                 
+  it "migrates down correctly" do
+    mgt = Mole::Db::Migrate.new( OpenStruct.new( :direction => :down, :configuration => @config, :environment => 'test' ) )
+    mgt.apply
+  end
+
+  it "migrates up correctly" do
+    mgt = Mole::Db::Migrate.new( OpenStruct.new( :direction => :up, :configuration => @config, :environment => 'test' ) )
+    mgt.apply
+  end  
+end

data/spec/emole_spec.rb

@@ -0,0 +1,43 @@
+require File.join(File.dirname(__FILE__), "spec_helper" )
+                   
+require 'action_mailer'
+ActionMailer::Base.delivery_method       = :sendmail
+ActionMailer::Base.raise_delivery_errors = true                                       
+
+# TODO Figure out how to auto check email was sent                       
+describe Mole::EMole do                                      
+  before( :each ) do      
+    ::Mole.reset_configuration!
+    ::Mole.initialize( :moleable         => true, 
+                     :emole_from       => "MOleBeatch@liquidrail.com", 
+                     :emole_recipients => ['fernand@liquidrail.com'] )
+  end
+  
+  it "should send out a correct perf alert" do
+    Mole::EMole.deliver_perf_alerts(
+      self, 
+      "fernand", 
+      :feature      => "test", 
+      :elapsed_time => 10 )
+  end
+
+  it "should send out a correct feature alert" do
+    Mole::EMole.deliver_feature_alerts( 
+      self,
+      "fernand", 
+      :feature      => "test", 
+      :fred         => "blee" )
+  end
+
+  it "should send out a correct exception alert" do
+    begin
+      raise "Something craped out"
+    rescue => boom
+      Mole::EMole.deliver_exception_alerts( 
+        self,
+        "fernand", 
+        :feature    => "test", 
+        :boom       => boom )
+    end
+  end  
+end

data/spec/logger_spec.rb

@@ -0,0 +1,56 @@
+require File.join(File.dirname(__FILE__), "spec_helper" )
+
+require 'stringio'          
+require File.join(File.dirname(__FILE__), %w[.. lib mole logger] )
+
+describe Mole::Logger do
+  it "raises an error if the email addresses passed in is empty" do
+    lambda { Mole::Logger.new( { :email_alerts_to => [] } ) }.should raise_error( Mole::Logger::ConfigurationError )
+  end
+
+  it "configures an email appender if :email_alerts is set" do
+    l = Mole::Logger.new( { :logger_name => "Test2", :email_alerts_to => "fernand@invalid.address", :email_alert_level => :off })
+    l.email_appender.should_not == nil
+  end
+
+  it "does not configure an email appender if :email_alerts is not set" do
+    l = Mole::Logger.new( { :logger_name => "Test3" })
+    lambda { l.email_appender }.should raise_error( Mole::Logger::ConfigurationError )
+  end
+
+  it "raises an error if an invalid object is passed in for the :log_file" do
+    lambda { l = Mole::Logger.new( { :log_file => Object.new } ) }.should raise_error( Mole::Logger::ConfigurationError )
+  end
+
+  it "logs to an IO stream if given" do
+    io = StringIO.new
+    l  = Mole::Logger.new( { :log_file => io, :logger_name => "Test4"  })
+    l.info "This is a test io message"
+    io.string.split("\n").should have(1).item
+    io.string.should =~ /This is a test io message/
+    io.string.should =~ /INFO/
+  end
+
+  it "logs to a file if given a file name to log to" do
+    log_file = "/tmp/mole_logger_test.log"   
+    FileUtils.rm( log_file ) if File.exists?( log_file )
+    l = Mole::Logger.new({ :log_file => log_file, :logger_name => "Test5" })
+    l.info "This is a test log file message"
+
+    log_lines = IO.readlines(log_file)
+                          
+    log_lines.should have(1).items
+    log_lines.first.should =~ /This is a test log file message/
+    log_lines.first.should =~ /INFO/
+  end
+
+  it "creates a logger from another logger" do
+    io = StringIO.new
+    l  = Mole::Logger.new( { :log_file => io, :logger_name => ::Mole})
+    child_l = l.for(Mole)
+    
+    child_l.info "This is a child log message"
+    io.string.should =~ /This is a child log message/
+    io.string.should =~ /INFO/
+  end
+end

data/spec/models/mole_feature_spec.rb

@@ -0,0 +1,37 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper" )
+                
+describe MoleFeature do                         
+  before( :each ) do                                                                    
+    ::Mole.reset_configuration!
+    ::Mole.initialize( :mode => :persistent, :log_level => :debug, :moleable => true )
+  end
+                      
+  it "should find or create known features correctly" do
+    %w[ all performance exception].each do |f|
+      feature = MoleFeature.send( "find_#{f}_feature".to_sym, ::Mole.application )
+      feature.should_not           be_nil    
+      feature.name.downcase.should == f
+    end
+  end     
+  
+  it "should create a new feature" do
+    feature = MoleFeature.find_feature( "Fred", ::Mole.application, self.class.name )
+    feature.should_not     be_nil
+    feature.name.should    == "Fred"
+    feature.context.should == self.class.name
+  end  
+  
+  it "should not create a feature with no name" do
+    feature = MoleFeature.find_feature( "", ::Mole.application, self.class.name )
+    feature.should be_nil
+  end    
+  
+  it "should find all features for a given application correctly" do
+    %w[ all performance exception].each do |f|
+      MoleFeature.send( "find_#{f}_feature".to_sym, ::Mole.application )
+    end                                                                              
+    MoleFeature.find_feature( "Fred", ::Mole.application, self.class.name )
+    features = MoleFeature.find_features( ::Mole.application )
+    features.should have(4).mole_features
+  end
+end

data/spec/models/mole_log_spec.rb

@@ -0,0 +1,73 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper" )
+           
+describe MoleLog do                           
+  before( :each ) do    
+    ::Mole.reset_configuration!
+    ::Mole.initialize( :mode => :persistent, :log_level => :info, :moleable => true )
+  end
+                      
+  it "should log unchecked exceptions correctly" do   
+     begin
+       raise "Something crapped out"
+     rescue => boom
+       MoleLog.check_it( self, 100, :blee => "Hello", :duh => "World", :boom => boom )
+     end
+     except_feature = MoleFeature.find_exception_feature( ::Mole.application )
+     except_feature.should_not be_nil     
+     
+     log = MoleLog.find( :all, :conditions => ['mole_feature_id = ?', except_feature.id] )     
+     log.should_not           be_nil
+     log.should               have(1).mole_log     
+     log.first.user_id.should == 100
+  end
+      
+  it "should log perf exception correctly" do
+     MoleLog.perf_it( self, 100, :blee => "Hello", :duh => "World" )
+     perf_feature = MoleFeature.find_performance_feature( ::Mole.application )
+     perf_feature.should_not be_nil     
+     
+     log = MoleLog.find( :all, :conditions => ['mole_feature_id = ?', perf_feature.id] )     
+     log.should_not           be_nil
+     log.should               have(1).mole_log     
+     log.first.user_id.should == 100
+  end
+
+  it "should mole a feature correctly" do
+     MoleLog.mole_it( "Test", "fred", 100, :blee => "Hello", :duh => "World" )
+     feature = MoleFeature.find_feature( "fred", ::Mole.application, "Test".class.name )
+     feature.should_not be_nil     
+     
+     log = MoleLog.find( :all, :conditions => ['mole_feature_id = ?', feature.id] )     
+     log.should_not           be_nil
+     log.should               have(1).mole_log     
+     log.first.user_id.should == 100
+  end
+
+  it "should log request info correctly" do
+     ctrl = Moled::Controller.new
+     MoleLog.mole_it( ctrl, "fred", 100, :blee => "Hello", :duh => "World" )
+     feature = MoleFeature.find_feature( "fred", ::Mole.application, ctrl.class.name )
+     feature.should_not be_nil     
+     
+     log = MoleLog.find( :all, :conditions => ['mole_feature_id = ?', feature.id] )     
+     log.should_not           be_nil
+     log.should               have(1).mole_log     
+     log.first.user_id.should == 100                 
+     log.first.ip_address.should    == "1.1.1.1"
+     log.first.browser_type.should  == "GodZilla"
+  end   
+                   
+  module Moled
+    class Controller
+      class Request
+        def env
+          {'REMOTE_ADDR' => "1.1.1.1", 'HTTP_USER_AGENT' => 'GodZilla' }
+        end
+      end
+    
+      def request
+        Request.new
+      end
+    end
+   end
+end

data/spec/module_spec.rb

@@ -0,0 +1,171 @@
+require File.join(File.dirname(__FILE__), "spec_helper" )
+
+
+describe Module do     
+  before( :all ) do
+    ::Mole.initialize( :perf_threshold => 1 )
+    require File.join( File.dirname(__FILE__),  %w[data blee] )                          
+  end
+                    
+  before( :each ) do
+    @blee = Blee.new    
+    CallStackChecker.reset                                                                   
+  end                    
+
+  it "should trap mole before handler exceptions" do
+    Blee.mole_before( :feature => :crap_out ) { |context, feature, *args| 
+      raise "Before - Something did crap out"
+      CallStackChecker.called
+    }              
+    @blee.crap_out                      
+    CallStackChecker.should_not be_called
+  end
+
+  it "should trap mole after handler exceptions" do
+    Blee.mole_after( :feature => :crap_out ) { |context, feature, *args| 
+      raise "After - Something did crap out"
+      CallStackChecker.called
+    }              
+    @blee.crap_out                      
+    CallStackChecker.should_not be_called
+  end
+
+  it "should trap mole handler exceptions" do
+    Blee.mole_unchecked( :features => [:blee_raise_too] ) { |context, feature, *args| 
+      raise "Unchecked - Something did crap out"
+      CallStackChecker.called
+    }                           
+    @blee.blee_raise_too rescue nil                    
+    CallStackChecker.should_not be_called
+  end
+
+  it "should trap a perf handler exception" do
+    Blee.mole_perf( :features => [:blee_slow_too] ) do |context, feature, elapsed_time, args, block|
+      raise "Perf - Something did crap out"      
+      CallStackChecker.called
+    end         
+    @blee.blee_slow_too
+    CallStackChecker.should_not be_called    
+  end 
+  
+  it "should trap mole handler exceptions" do
+    Blee.mole_before( :feature => :crap_out ) { |context, feature, *args| 
+      raise "Something did crap out"
+      CallStackChecker.called
+    }              
+    @blee.crap_out                      
+    CallStackChecker.should_not be_called
+  end
+  
+  it "should correctly setup a before call" do
+    Blee.mole_before( :feature => :blee_no_args ) { |context, feature, *args| 
+      context.class.should == Blee
+      feature.should       == "blee_no_args"
+      args.should          have(0).items
+      CallStackChecker.called
+    }              
+    @blee.blee_no_args                         
+    CallStackChecker.should be_called
+  end
+  
+  it "should correctly setup an after call" do
+    Blee.mole_after( :feature => :blee_no_args ) { |context, feature, *args| 
+      context.class.should == Blee
+      feature.should       == "blee_no_args"
+      args.should          have(0).items      
+      CallStackChecker.called
+    }              
+    @blee.blee_no_args                         
+    CallStackChecker.should be_called
+  end
+  
+  it "should correctly trap an exception" do
+    Blee.mole_unchecked( :features => [:blee_raise] ) do |context, feature, boom, args, block|  
+      context.class.should == Blee
+      feature.should       == "blee_raise"
+      boom.to_s.should     == "Blee exception"
+      CallStackChecker.called
+    end         
+    @blee.blee_raise rescue nil                          
+    CallStackChecker.should be_called    
+  end     
+  
+  it "should not trap a before call" do     
+    @blee.blee_args( "Hello", "World" )
+    CallStackChecker.should_not be_called
+  end  
+  
+  it "should correctly trap the before call arguments" do
+    Blee.mole_before( :feature => :blee_args ) { |context, feature, *args| 
+      context.class.should == Blee
+      feature.should       == "blee_args"      
+      args.should          have(2).items
+      args[0].should       == "Hello"
+      args[1].should       == "World"
+      CallStackChecker.called
+    }              
+    @blee.blee_args( "Hello", "World" )                         
+    CallStackChecker.should be_called    
+  end    
+  
+  it "should correctly trap the after call arguments" do
+    Blee.mole_after( :feature => :blee_args ) { |context, feature, *args| 
+      context.class.should == Blee
+      feature.should       == "blee_args"            
+      args.size.should     == 2
+      args[0].should       == "Hello"
+      args[1].should       == "World"
+      CallStackChecker.called
+    }              
+    @blee.blee_args( "Hello", "World" )                         
+    CallStackChecker.should be_called    
+  end    
+  
+  it "should correctly trap a slow call" do
+    Blee.mole_perf( :features => [:blee_slow] ) do |context, feature, elapsed_time, args, block|
+      context.class.should == Blee
+      feature.should       == "blee_slow"      
+      elapsed_time.should  > 1      
+      CallStackChecker.called
+    end         
+    @blee.blee_slow rescue nil
+    CallStackChecker.should be_called    
+  end 
+  
+  it "should trap a private method correctly" do  
+    Blee.mole_after( :feature => :blee_private ) { |context, feature, *args| 
+      context.class.should == Blee
+      feature.should       == "blee_private"            
+      args.size.should     == 1
+      args[0].should       == "Hello"
+      CallStackChecker.called
+    }              
+    @blee.send( :blee_private, "Hello" )
+    CallStackChecker.should be_called        
+  end
+  
+  it "should trap a protected method correctly" do
+    Blee.mole_after( :feature => :blee_protected ) { |context, feature, *args| 
+      context.class.should == Blee
+      feature.should       == "blee_protected"            
+      args.size.should     == 1
+      args[0].should       == "Hello"
+      CallStackChecker.called
+    }              
+    @blee.send( :blee_protected, "Hello" )
+    CallStackChecker.should be_called        
+  end      
+                 
+  it "should mole a static method correctly" do
+    pending do
+      Blee.mole_after( :feature => :blee_static ) { |context, feature, *args| 
+        context.class.should == Blee
+        feature.should       == "blee_static"            
+        args.size.should     == 0
+        CallStackChecker.called
+      }              
+      Blee.blee_static
+      CallStackChecker.should be_called            
+    end
+  end
+end

data/spec/mole_spec.rb

@@ -0,0 +1,38 @@
+require File.join(File.dirname(__FILE__), "spec_helper" )
+
+describe Mole do     
+  before( :all ) do        
+    ::Mole.reset_configuration!
+    ::Mole.initialize( :moleable => true )
+    @root = ::File.expand_path( ::File.join(::File.dirname(__FILE__), ".." ) )
+  end
+                                 
+  it "is versioned" do
+    ::Mole::Version.version.should =~ /\d+\.\d+\.\d+/
+  end
+  
+  it "should have the right defaults" do
+    Mole.should                be_moleable
+    Mole.logger.should_not     be_nil
+    Mole.perf_threshold.should == 5
+    Mole.should_not            be_persistent  
+    Mole.application.should    == "Default"
+  end         
+  
+  it "generates a correct path relative to root" do
+    Mole.path( "mole.rb" ).should == ::File.join(@root, "mole.rb" )
+  end
+  
+  it "generates a correct path relative to lib" do
+    Mole.libpath(%w[ mole db_mole.rb]).should == ::File.join(@root, "lib", "mole", "db_mole.rb")
+  end       
+  
+  it "should define the correct run modes" do
+    Mole.run_modes.should == [:transient,:persistent]
+  end       
+  
+  it "should dump config info to console" do
+    Mole.dump
+  end
+  
+end