bullet 4.0.0 → 4.13.1

data/README_for_rails2.textile

@@ -1,400 +0,0 @@
-h1. Bullet
-
-The Bullet plugin/gem is designed to help you increase your application's performance by reducing the number of queries it makes. It will watch your queries while you develop your application and notify you when you should add eager loading (N+1 queries), when you're using eager loading that isn't necessary and when you should use counter cache.
-
-Best practice is to use Bullet in development mode or custom mode (staging, profile, etc.). The last thing you want is your clients getting alerts about how lazy you are.
-
-The Bullet plugin/gem now supports rails 2.1, 2.2 and 2.3, tested in rails 2.1.2, 2.2.2 and 2.3.2.
-
-****************************************************************************
-
-h2. Change
-
-There is a large refactor from gem 1.4 to 1.5, so if you upgrade to 1.5 gem, please read the Configuration section again and rewrite your configuration.
-
-****************************************************************************
-
-h2. Contributors
-
-"https://github.com/flyerhzm/bullet/contributors":https://github.com/flyerhzm/bullet/contributors
-
-****************************************************************************
-
-h2. Install
-
-You can install it as a gem:
-<pre><code>
-sudo gem install bullet
-</code></pre>
-
-****************************************************************************
-
-h2. Configuration
-
-Bullet won't do ANYTHING unless you tell it to explicitly. Append to <code>config/environments/development.rb</code> initializer with the following code:
-<pre><code>
-config.after_initialize do
-  Bullet.enable = true
-  Bullet.alert = true
-  Bullet.bullet_logger = true
-  Bullet.console = true
-  Bullet.growl = true
-  Bullet.rails_logger = true
-  Bullet.disable_browser_cache = true
-  Bullet.xmpp = { :account => 'bullets_account@jabber.org',
-                  :password => 'bullets_password_for_jabber',
-                  :receiver => 'your_account@jabber.org',
-                  :show_online_status => true }
-end
-</code></pre>
-
-The notifier of bullet is a wrap of "uniform_notifier":https://github.com/flyerhzm/uniform_notifier
-
-The code above will enable all five of the Bullet notification systems:
-* <code>Bullet.enable</code>: enable Bullet plugin/gem, otherwise do nothing
-* <code>Bullet.alert</code>: pop up a JavaScript alert in the browser
-* <code>Bullet.bullet_logger</code>: log to the Bullet log file (RAILS_ROOT/log/bullet.log)
-* <code>Bullet.rails_logger</code>: add warnings directly to the Rails log
-* <code>Bullet.console</code>: log warnings to your browser's console.log (Safari/Webkit browsers or Firefox w/Firebug installed)
-* <code>Bullet.growl</code>: pop up Growl warnings if your system has Growl installed. Requires a little bit of configuration
-* <code>Bullet.disable_browser_cache</code>: disable browser cache which usually causes unexpected problems
-
-****************************************************************************
-
-h2. Log
-
-The Bullet log <code>log/bullet.log</code> will look something like this:
-
-* N+1 Query:
-<pre><code>
-2009-08-25 20:40:17[INFO] N+1 Query: PATH_INFO: /posts;    model: Post => associations: [comments]·
-Add to your finder: :include => [:comments]
-2009-08-25 20:40:17[INFO] N+1 Query: method call stack:·
-/Users/richard/Downloads/test/app/views/posts/index.html.erb:11:in `_run_erb_app47views47posts47index46html46erb'
-/Users/richard/Downloads/test/app/views/posts/index.html.erb:8:in `each'
-/Users/richard/Downloads/test/app/views/posts/index.html.erb:8:in `_run_erb_app47views47posts47index46html46erb'
-/Users/richard/Downloads/test/app/controllers/posts_controller.rb:7:in `index'
-</code></pre>
-
-The first two lines are notifications that N+1 queries have been encountered. The remaining lines are stack traces so you can find exactly where the queries were invoked in your code, and fix them.
-
-* Unused eager loading:
-<pre><code>
-2009-08-25 20:53:56[INFO] Unused eager loadings: PATH_INFO: /posts;    model: Post => associations: [comments]·
-Remove from your finder: :include => [:comments]
-</code></pre>
-
-These two lines are notifications that unused eager loadings have been encountered.
-
-* Need counter cache:
-<pre><code>
-2009-09-11 09:46:50[INFO] Need Counter Cache
-  Post => [:comments]
-</code></pre>
-
-****************************************************************************
-
-h2. Growl Support
-
-To get Growl support up-and-running for Bullet, follow the steps below:
-* Install the ruby-growl gem: <code>gem install ruby-growl</code>
-* Open the Growl preference pane in Systems Preferences
-* Click the "Network" tab
-* Make sure both "Listen for incoming notifications" and "Allow remote application registration" are checked. *Note*: If you set a password, you will need to set <code>Bullet.growl = { :password => 'growl password' }</code> in the config file.
-* Restart Growl ("General" tab -> Stop Growl -> Start Growl)
-* Boot up your application. Bullet will automatically send a Growl notification when Growl is turned on. If you do not see it when your application loads, make sure it is enabled in your initializer and double-check the steps above.
-
-****************************************************************************
-
-h2. Ruby 1.9 issue
-
-ruby-growl gem has an issue about md5 in ruby 1.9, if you use growl and ruby 1.9, check this gist http://gist.github.com/300184
-
-****************************************************************************
-
-h2. XMPP/Jabber Support
-
-To get XMPP support up-and-running for Bullet, follow the steps below:
-* Install the xmpp4r gem: <code>sudo gem install xmpp4r</code>
-* Make both the bullet and the receipient account add each other as contacts.
-  This will require you to manually log into both accounts, add each other
-  as contact and confirm each others contact request.
-* Boot up your application. Bullet will automatically send an XMPP notification when XMPP is turned on.
-
-****************************************************************************
-
-h2. Important
-
-If you encounter the following errors in development environment:
-
-<pre><code>
-You might have expected an instance of Array.
-The error occurred while evaluating nil.include?
-    /usr/lib/ruby/gems/1.8/gems/activerecord-2.3.2/lib/active_record/attribute_methods.rb:142:in `create_time_zone_conversion_attribute?'
-    /usr/lib/ruby/gems/1.8/gems/activerecord-2.3.2/lib/active_record/attribute_methods.rb:75:in `define_attribute_methods'
-    /usr/lib/ruby/gems/1.8/gems/activerecord-2.3.2/lib/active_record/attribute_methods.rb:71:in `each'
-    /usr/lib/ruby/gems/1.8/gems/activerecord-2.3.2/lib/active_record/attribute_methods.rb:71:in `define_attribute_methods'
-    /usr/lib/ruby/gems/1.8/gems/activerecord-2.3.2/lib/active_record/attribute_methods.rb:242:in `method_missing'
-</code></pre>
-
-Or any strange behavior of bullet plugin/gem, *please disable your browser's cache*.
-
-****************************************************************************
-
-h2. Advance
-
-The bullet plugin/gem use rack middleware for http request. If you want to bullet for without http server, such as job server. You can do like this:
-
-<pre><code>
-Bullet.start_request if Bullet.enable?
-# run job
-if Bullet.enable?
-  Bullet.growl_notification
-  Bullet.log_notification('JobServer: ')
-  Bullet.end_request
-end
-</code></pre>
-
-Or you want to use it in test mode
-
-<pre><code>
-before(:each)
-  Bullet.start_request if Bullet.enable?
-end
-
-after(:each)
-  if Bullet.enable?
-    Bullet.perform_out_of_channel_notifications
-    Bullet.end_request
-  end
-end
-</code></pre>
-
-Don't forget enabling bullet in test environment.
-
-****************************************************************************
-
-h2. Links
-
-* "http://weblog.rubyonrails.org/2009/10/22/community-highlights":http://weblog.rubyonrails.org/2009/10/22/community-highlights
-* "http://ruby5.envylabs.com/episodes/9-episode-8-september-8-2009":http://ruby5.envylabs.com/episodes/9-episode-8-september-8-2009
-* "http://railslab.newrelic.com/2009/10/23/episode-19-on-the-edge-part-1":http://railslab.newrelic.com/2009/10/23/episode-19-on-the-edge-part-1
-
-****************************************************************************
-
-h2. Step by step example
-
-Bullet is designed to function as you browse through your application in development. It will alert you whenever it encounters N+1 queries or unused eager loading.
-
-1. setup test environment
-
-<pre><code>
-$ rails test_bullet
-$ cd test_bullet
-$ script/generate scaffold post name:string
-$ script/generate scaffold comment name:string post_id:integer
-$ rake db:migrate
-</code></pre>
-
-2. change <code>app/model/post.rb</code> and <code>app/model/comment.rb</code>
-
-<pre><code>
-class Post < ActiveRecord::Base
-  has_many :comments
-end
-
-class Comment < ActiveRecord::Base
-  belongs_to :post
-end
-</code></pre>
-
-3. go to script/console and execute
-
-<pre><code>
-post1 = Post.create(:name => 'first')
-post2 = Post.create(:name => 'second')
-post1.comments.create(:name => 'first')
-post1.comments.create(:name => 'second')
-post2.comments.create(:name => 'third')
-post2.comments.create(:name => 'fourth')
-</code></pre>
-
-4. change the <code>app/views/posts/index.html.erb</code> to produce a N+1 query
-
-<pre><code>
-<% @posts.each do |post| %>
-  <tr>
-    <td><%=h post.name %></td>
-    <td><%= post.comments.collect(&:name) %></td>
-    <td><%= link_to 'Show', post %></td>
-    <td><%= link_to 'Edit', edit_post_path(post) %></td>
-    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
-  </tr>
-<% end %>
-</code></pre>
-
-5. add bullet plugin
-
-<pre><code>
-$ script/plugin install git://github.com/flyerhzm/bullet.git
-</code></pre>
-
-6. enable the bullet plugin in development, add a line to <code>config/environments/development.rb</code>
-
-<pre><code>
-config.after_initialize do
-  Bullet.enable = true
-  Bullet.alert = true
-  Bullet.bullet_logger = true
-  Bullet.console = true
-#  Bullet.growl = true
-  Bullet.rails_logger = true
-  Bullet.disable_browser_cache = true
-end
-</code></pre>
-
-7. start server
-
-<pre><code>
-$ script/server
-</code></pre>
-
-8. input http://localhost:3000/posts in browser, then you will see a popup alert box says
-
-<pre><code>
-The request has unused preload associations as follows:
-None
-The request has N+1 queries as follows:
-model: Post => associations: [comment]
-</code></pre>
-
-which means there is a N+1 query from post object to comments associations.
-
-In the meanwhile, there's a log appended into <code>log/bullet.log</code> file
-
-<pre><code>
-2009-08-20 09:12:19[INFO] N+1 Query: PATH_INFO: /posts;    model: Post => assocations: [comments]
-Add your finder: :include => [:comments]
-2009-08-20 09:12:19[INFO] N+1 Query: method call stack:
-/Users/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:11:in `_run_erb_app47views47posts47index46html46erb'
-/Users/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:8:in `each'
-/Users/flyerhzm/Downloads/test_bullet/app/views/posts/index.html.erb:8:in `_run_erb_app47views47posts47index46html46erb'
-/Users/flyerhzm/Downloads/test_bullet/app/controllers/posts_controller.rb:7:in `index'
-</code></pre>
-
-The generated SQLs are
-
-<pre><code>
-  Post Load (1.0ms)   SELECT * FROM "posts"
-  Comment Load (0.4ms)   SELECT * FROM "comments" WHERE ("comments".post_id = 1)
-  Comment Load (0.3ms)   SELECT * FROM "comments" WHERE ("comments".post_id = 2)
-</code></pre>
-
-
-9. fix the N+1 query, change <code>app/controllers/posts_controller.rb</code> file
-
-<pre><code>
-  def index
-    @posts = Post.find(:all, :include => :comments)
-
-    respond_to do |format|
-      format.html # index.html.erb
-      format.xml  { render :xml => @posts }
-    end
-  end
-</code></pre>
-
-10. refresh http://localhost:3000/posts page, no alert box and no log appended.
-
-The generated SQLs are
-
-<pre><code>
-  Post Load (0.5ms)   SELECT * FROM "posts"
-  Comment Load (0.5ms)   SELECT "comments".* FROM "comments" WHERE ("comments".post_id IN (1,2))
-</code></pre>
-
-a N+1 query fixed. Cool!
-
-11. now simulate unused eager loading. Change <code>app/controllers/posts_controller.rb</code> and <code>app/views/posts/index.html.erb</code>
-
-<pre><code>
-  def index
-    @posts = Post.find(:all, :include => :comments)
-
-    respond_to do |format|
-      format.html # index.html.erb
-      format.xml  { render :xml => @posts }
-    end
-  end
-</code></pre>
-
-<pre><code>
-<% @posts.each do |post| %>
-  <tr>
-    <td><%=h post.name %></td>
-    <td><%= link_to 'Show', post %></td>
-    <td><%= link_to 'Edit', edit_post_path(post) %></td>
-    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
-  </tr>
-<% end %>
-</code></pre>
-
-12. refresh http://localhost:3000/posts page, then you will see a popup alert box says
-
-<pre><code>
-The request has unused preload associations as follows:
-model: Post => associations: [comment]
-The request has N+1 queries as follows:
-None
-</code></pre>
-
-In the meanwhile, there's a log appended into <code>log/bullet.log</code> file
-
-<pre><code>
-2009-08-25 21:13:22[INFO] Unused preload associations: PATH_INFO: /posts;    model: Post => associations: [comments]·
-Remove from your finder: :include => [:comments]
-</code></pre>
-
-13. simulate counter_cache. Change <code>app/controllers/posts_controller.rb</code> and <code>app/views/posts/index.html.erb</code>
-
-<pre><code>
-  def index
-    @posts = Post.find(:all)
-
-    respond_to do |format|
-      format.html # index.html.erb
-      format.xml  { render :xml => @posts }
-    end
-  end
-</code></pre>
-
-<pre><code>
-<% @posts.each do |post| %>
-  <tr>
-    <td><%=h post.name %></td>
-    <td><%=h post.comments.size %></td>
-    <td><%= link_to 'Show', post %></td>
-    <td><%= link_to 'Edit', edit_post_path(post) %></td>
-    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
-  </tr>
-<% end %>
-</code></pre>
-
-14. refresh http://localhost:3000/posts page, then you will see a popup alert box says
-
-<pre><code>
-Need counter cache
-  Post => [:comments]
-</code></pre>
-
-In the meanwhile, there's a log appended into <code>log/bullet.log</code> file.
-
-<pre><code>
-2009-09-11 10:07:10[INFO] Need Counter Cache
-  Post => [:comments]
-</code></pre>
-
-****************************************************************************
-
-
-Copyright (c) 2009 - 2012 Richard Huang (flyerhzm@gmail.com), released under the MIT license

data/lib/bullet/action_controller2.rb

@@ -1,49 +0,0 @@
-module Bullet
-  class ActionController
-    def self.enable
-      require 'action_controller'
-      if Rails.version =~ /\A2.3/
-        ::ActionController::Dispatcher.middleware.use Bullet::Rack
-        ::ActionController::Dispatcher.class_eval do
-          class <<self
-            alias_method :origin_reload_application, :reload_application
-            def reload_application
-              origin_reload_application
-              Bullet.clear
-            end
-          end
-        end
-      elsif Rails.version =~ /\A2.[12]/
-        ::ActionController::Dispatcher.class_eval do
-          alias_method :origin_reload_application, :reload_application
-          def reload_application
-            origin_reload_application
-            Bullet.clear
-          end
-        end
-
-        ::ActionController::Base.class_eval do
-          alias_method :origin_process, :process
-          def process(request, response, method = :perform_action, *arguments)
-            Bullet.start_request
-            response = origin_process(request, response, method = :perform_action, *arguments)
-
-            if Bullet.notification?
-              if response.headers["type"] && response.headers["type"].include?('text/html') &&
-                  response.body.include?("<html>") && response.body.include?("</html>")
-                response.body <<= Bullet.gather_inline_notifications
-                response.headers["Content-Length"] = response.body.length.to_s
-              end
-
-              Bullet.perform_out_of_channel_notifications
-            end
-            Bullet.end_request
-            response
-          end
-        end
-      else
-        puts "Gem Bullet: Unsupported rails version"
-      end
-    end
-  end
-end

data/lib/bullet/active_record2.rb

@@ -1,121 +0,0 @@
-module Bullet
-  module ActiveRecord
-    def self.enable
-      require 'active_record'
-      ::ActiveRecord::Base.class_eval do
-        class << self
-          alias_method :origin_find_every, :find_every
-          # if select a collection of objects, then these objects have possible to cause N+1 query.
-          # if select only one object, then the only one object has impossible to cause N+1 query.
-          def find_every(options)
-            records = origin_find_every(options)
-
-            if records
-              if records.size > 1
-                Bullet::Detector::Association.add_possible_objects(records)
-                Bullet::Detector::Counter.add_possible_objects(records)
-              elsif records.size == 1
-                Bullet::Detector::Association.add_impossible_object(records.first)
-                Bullet::Detector::Counter.add_impossible_object(records.first)
-              end
-            end
-
-            records
-          end
-        end
-      end
-
-      ::ActiveRecord::AssociationPreload::ClassMethods.class_eval do
-        alias_method :origin_preload_associations, :preload_associations
-        # include query for one to many associations.
-        # keep this eager loadings.
-        def preload_associations(records, associations, preload_options={})
-          records = [records].flatten.compact.uniq
-          return if records.empty?
-          records.each do |record|
-            Bullet::Detector::Association.add_object_associations(record, associations)
-          end
-          Bullet::Detector::Association.add_eager_loadings(records, associations)
-          origin_preload_associations(records, associations, preload_options={})
-        end
-      end
-
-      ::ActiveRecord::Associations::ClassMethods.class_eval do
-        # add include in named_scope
-        alias_method :origin_find_with_associations, :find_with_associations
-        def find_with_associations(options)
-          records = origin_find_with_associations(options)
-          associations = merge_includes(scope(:find, :include), options[:include])
-          records.each do |record|
-            Bullet::Detector::Association.add_object_associations(record, associations)
-            Bullet::Detector::NPlusOneQuery.call_association(record, associations)
-          end
-          Bullet::Detector::Association.add_eager_loadings(records, associations)
-          records
-        end
-      end
-
-      ::ActiveRecord::Associations::ClassMethods::JoinDependency.class_eval do
-        # call join associations
-        alias_method :origin_construct_association, :construct_association
-        def construct_association(record, join, row)
-          associations = join.reflection.name
-          Bullet::Detector::Association.add_object_associations(record, associations)
-          Bullet::Detector::NPlusOneQuery.call_association(record, associations)
-          origin_construct_association(record, join, row)
-        end
-      end
-
-      ::ActiveRecord::Associations::AssociationCollection.class_eval do
-        # call one to many associations
-        alias_method :origin_load_target, :load_target
-        def load_target
-          Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name)
-          origin_load_target
-        end
-
-        alias_method :origin_first, :first
-        def first(*args)
-          Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name)
-          origin_first(*args)
-        end
-
-        alias_method :origin_last, :last
-        def last(*args)
-          Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name)
-          origin_last(*args)
-        end
-      end
-
-      ::ActiveRecord::Associations::AssociationProxy.class_eval do
-        # call has_one and belong_to association
-        alias_method :origin_load_target, :load_target
-        def load_target
-          # avoid stack level too deep
-          result = origin_load_target
-          Bullet::Detector::NPlusOneQuery.call_association(@owner, @reflection.name) unless caller.any? {|c| c.include?("load_target") }
-          Bullet::Detector::Association.add_possible_objects(result)
-          result
-        end
-      end
-
-      ::ActiveRecord::Associations::HasManyAssociation.class_eval do
-        alias_method :origin_has_cached_counter?, :has_cached_counter?
-        def has_cached_counter?
-          result = origin_has_cached_counter?
-          Bullet::Detector::Counter.add_counter_cache(@owner, @reflection.name) unless result
-          result
-        end
-      end
-
-      ::ActiveRecord::Associations::HasManyThroughAssociation.class_eval do
-        alias_method :origin_has_cached_counter?, :has_cached_counter?
-        def has_cached_counter?
-          result = origin_has_cached_counter?
-          Bullet::Detector::Counter.add_counter_cache(@owner, @reflection.name) unless result
-          result
-        end
-      end
-    end
-  end
-end

data/lib/bullet/detector/counter.rb

@@ -1,48 +0,0 @@
-module Bullet
-  module Detector
-    class Counter < Base
-      class <<self
-        def clear
-          @@possible_objects = nil
-          @@impossible_objects = nil
-        end
-
-        def add_counter_cache(object, associations)
-          if conditions_met?(object.bullet_ar_key, associations)
-            create_notification object.class.to_s, associations
-          end
-        end
-
-        def add_possible_objects(object_or_objects)
-          if object_or_objects.is_a? Array
-            object_or_objects.each { |object| possible_objects.add object.bullet_ar_key }
-          else
-            possible_objects.add object_or_objects.bullet_ar_key
-          end
-        end
-
-        def add_impossible_object(object)
-          impossible_objects.add object.bullet_ar_key
-        end
-
-        private
-          def create_notification(klazz, associations)
-             notice = Bullet::Notification::CounterCache.new klazz, associations
-             Bullet.notification_collector.add notice
-          end
-
-          def possible_objects
-            @@possible_objects ||= Bullet::Registry::Object.new
-          end
-
-          def impossible_objects
-            @@impossible_objects ||= Bullet::Registry::Object.new
-          end
-
-          def conditions_met?(bullet_ar_key, associations)
-            possible_objects.include?(bullet_ar_key) && !impossible_objects.include?(bullet_ar_key)
-          end
-      end
-    end
-  end
-end

data/lib/bullet/detector/unused_eager_association.rb

@@ -1,42 +0,0 @@
-module Bullet
-  module Detector
-    class UnusedEagerAssociation < Association
-      class <<self
-        # check if there are unused preload associations.
-        #   get related_objects from eager_loadings associated with object and associations
-        #   get call_object_association from associations of call_object_associations whose object is in related_objects
-        #   if association not in call_object_association, then the object => association - call_object_association is ununsed preload assocations
-        def check_unused_preload_associations
-          @@checked = true
-          object_associations.each do |bullet_ar_key, associations|
-            object_association_diff = diff_object_associations bullet_ar_key, associations
-            next if object_association_diff.empty?
-
-            create_notification bullet_ar_key.bullet_class_name, object_association_diff
-          end
-        end
-
-        private
-          def create_notification(klazz, associations)
-            notice = Bullet::Notification::UnusedEagerLoading.new(klazz, associations)
-            Bullet.notification_collector.add(notice)
-          end
-
-          def call_associations(bullet_ar_key, associations)
-            all = Set.new
-            eager_loadings.similarly_associated(bullet_ar_key, associations).each do |related_bullet_ar_key|
-              coa = call_object_associations[related_bullet_ar_key]
-              next if coa.nil?
-              all.merge coa
-            end
-            all.to_a
-          end
-
-          def diff_object_associations(bullet_ar_key, associations)
-            potential_associations = associations - call_associations(bullet_ar_key, associations)
-            potential_associations.reject { |a| a.is_a?(Hash) }
-          end
-      end
-    end
-  end
-end