cache_debugging 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 966d977f9f2e3f02a1659ef160c7386742b92a16
+  data.tar.gz: 069c388fe175aaaae2491748a4e81a387ef7ec5c
+SHA512:
+  metadata.gz: ea249f02ce4f52639732bc59d1b53a4017c1cbba3c1c1c4c2e9fd788727d0bf7e1a7bd2635617390b2648ebb9d73e6eeeae255eef10e320ff3a8ef09dc0d8816
+  data.tar.gz: 01ef735d0ae31649da1f70aef82ca5de7c8d60d31d8f1df6d05d892da35b6cbace54fb02ebc03087d61a33e9bac99789874cb0f51bc4426728294a40be2ffaa7

data/.gitignore

@@ -0,0 +1,23 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile ~/.gitignore_global
+
+# Ignore bundler config
+/.bundle
+
+# Ignore the default SQLite database.
+*.sqlite3
+
+# Ignore all logfiles and tempfiles.
+*.log
+/tmp
+
+*.swp
+*.mwb.bak
+*.mwb.beforefix
+
+*.DS_Store
+
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,3 @@
+env:
+  - "RAILS_VERSION=3.2.0"
+  - "RAILS_VERSION=4.0.0"

data/Gemfile

@@ -0,0 +1,29 @@
+source "https://rubygems.org"
+
+# Declare your gem's dependencies in cache_debugging.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+rails_version = ENV["RAILS_VERSION"] || "default"
+
+rails = case rails_version
+when "default"
+  ">= 3.2.0"
+else
+  "~> #{rails_version}"
+end
+
+gem "rails", rails
+
+if rails.match /3\.2\.*/
+  gem 'cache_digests', '~> 0.3.0'
+end
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use debugger
+# gem 'debugger'

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) {{year}} {{fullname}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# CacheDebugging [![Build Status](https://travis-ci.org/chingor13/cache_debugging.png)](https://travis-ci.org/chingor13/cache_debugging)
+
+`cache_debugging` aims to detangle `cache_digests`'s template dependencies.  It currently contains 2 different hooks to check for cache integrity.
+
+## StrictDependencies
+
+This module ensures that every `render` call within a cache block is called on a partial that is in the callers template dependencies.
+
+### Why?
+
+We may not have declared all of our explicit template dependencies.
+
+Consider:
+
+```
+cache @workers do
+  render @workers
+end
+```
+
+Seems reasonable, as it will assume `workers/worker` is the partial to be depended upon. 
+
+We could also declaring the template explicitly:
+
+```
+cache @workers do
+  render partial: 'workers/worker', collection: @workers
+end
+```
+
+What if, however, `@workers` is a collection of duck-typed objects that behave like workers?  We have to explicitly declare the dependencies:
+
+```
+<%# Template Dependency: plumbers/plumber %>
+<%# Template Dependency: gardeners/gardener %>
+…
+<%# Template Dependency: electricians/electrician %>
+cache @workers do
+  render @workers
+end
+```
+
+How do we ensure that all the possible worker types are declared?
+
+### Usage
+
+In application.rb (or environment config):
+
+```
+config.cache_debugging.strict_dependencies = true
+```
+
+We keep track of each cache block with it's dependencies and trigger an ActiveSupport notification (`cache_debugging.cache_dependency_missing`) if we're rendering a partial not included any parent's template dependencies.  You can handle this notification any way you want.
+
+## View Sampling
+
+This module ensures that you have declared all the variable dependencies for your cache block.
+
+### Why?
+
+We might be missing a cache variable and not know it.
+
+Consider an view of a bug report ticket that can be assigned:
+
+```
+# tickets/index.html.erb
+<% cache @tickets do %>
+  <%= render @tickets %>
+<% end %>
+
+# tickets/_ticket.html.erb
+<% cache ticket do %>
+  <tr>
+    <td><%= ticket.id %></td>
+    <td><%= ticket.title %></td>
+    <td><%= ticket.assigned_to.name %></td>
+  </tr>
+<% end %>
+```
+
+Let's say we decided to replace `assigned_to.name` with "me" if the ticket is assigned to me.  So we update the ticket partial:
+
+```
+# tickets/_ticket.html.erb
+<% cache(ticket, current_user) do %>
+  <tr>
+    <td><%= ticket.id %></td>
+    <td><%= ticket.title %></td>
+    <td><%= ticket.assigned_to == current_user ? "me" : ticket.assigned_to.name %></td>
+  </tr>
+<% end %>
+```
+
+We've updated the cache block for the singular ticket, but forgotten to update the collection cache block.  We won't be notified that we're rendering a different view than we expect.
+
+### Usage
+
+In application.rb (or environment config):
+
+```
+config.cache_debugging.view_sampling = 0.1
+```
+
+Every X% of cache hits (10% for the above example), we will re-render the cache block anyways and compare the results.  If they don't match, we trigger and ActiveSupport notification (`cache_debugging.cache_mismatch`). You can handle this notification any way you want.

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'CacheDebugging'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/cache_debugging.gemspec

@@ -0,0 +1,20 @@
+# Provide a simple gemspec so you can easily use your enginex
+# project in your rails apps through git.
+require File.expand_path('../lib/cache_debugging/version', __FILE__)
+Gem::Specification.new do |s|
+  s.name = "cache_debugging"
+  s.version = CacheDebugging::VERSION
+  s.description = 'Verify cache key dependencies'
+  s.summary = 'Verify cache key dependencies via random sampling'
+  s.add_dependency "rails", ">= 3.2.0"
+
+  s.author = "Jeff Ching"
+  s.email = "ching.jeff@gmail.com"
+  s.homepage = "http://github.com/chingor13/cache_debugging"
+  s.license = "MIT"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = Dir.glob('test/*_test.rb')
+
+  s.add_development_dependency "sqlite3"
+end

data/lib/cache_debugging.rb

@@ -0,0 +1,18 @@
+require 'rails'
+if Rails::VERSION::MAJOR != 4
+  begin
+    require 'cache_digests'
+  rescue LoadError
+    raise "You must use the 'cache_digests' gem if you are running Rails 3"
+  end
+end
+
+module CacheDebugging
+  autoload :CacheBlocks, 'cache_debugging/cache_blocks'
+  autoload :StrictDependencies, 'cache_debugging/strict_dependencies'
+  autoload :ViewSampling, 'cache_debugging/view_sampling'
+  autoload :Digestor, 'cache_debugging/digestor'
+  autoload :Utils, 'cache_debugging/utils'
+end
+
+require 'cache_debugging/railtie'

data/lib/cache_debugging/cache_blocks.rb

@@ -0,0 +1,44 @@
+module CacheDebugging
+  module CacheBlocks
+    extend ActiveSupport::Concern
+
+    included do
+      alias_method_chain :cache, :blocks
+    end
+
+    # every time we start a cache block, we want to store the template and the block's dependencies
+    def cache_with_blocks(name = {}, options = nil, &block)
+      if current_template
+        dependencies = Digestor.new(
+          current_template,
+          lookup_context.rendered_format || :html, ApplicationController.new.lookup_context
+        ).nested_dependencies
+
+        cache_blocks.push({
+          template: current_template,
+          dependencies: Utils.deep_flatten(dependencies)
+        })
+        ret = cache_without_blocks(name, options, &block)
+        cache_blocks.pop
+        ret
+      else
+        cache_without_blocks(name, options, &block)
+      end
+    end
+
+    private
+
+    def cache_blocks
+      @cache_blocks ||= []
+    end
+
+    def current_template
+      @virtual_path
+    end
+
+    def cache_depth
+      cache_blocks.length
+    end
+
+  end
+end

data/lib/cache_debugging/digestor.rb

@@ -0,0 +1,3 @@
+module CacheDebugging
+  Digestor = CacheDigests::TemplateDigestor rescue ActionView::Digestor
+end

data/lib/cache_debugging/railtie.rb

@@ -0,0 +1,19 @@
+module CacheDebugging
+  class Railtie < Rails::Railtie
+    config.cache_debugging = ActiveSupport::OrderedOptions.new(
+      # raise exceptions if templates aren't in the dependency tree
+      strict_dependencies: false,
+
+      # [0,1] - decimal (percent) of cache hits to check
+      view_sampling: 0
+    )
+
+    initializer "cache_debugging.setup", :before => 'cache_digests' do |app|
+      ActiveSupport.on_load(:action_view) do
+        include CacheDebugging::CacheBlocks
+        include CacheDebugging::StrictDependencies
+        include CacheDebugging::ViewSampling
+      end
+    end
+  end
+end

data/lib/cache_debugging/strict_dependencies.rb

@@ -0,0 +1,47 @@
+module CacheDebugging
+  module StrictDependencies
+    extend ActiveSupport::Concern
+
+    def self.strict_dependencies_enabled?
+      !!Rails.application.config.cache_debugging.strict_dependencies
+    end
+
+    included do
+      alias_method_chain :render, :template_dependencies
+    end
+
+    # every time we render, we want to check if the partial is in the dependency list
+    def render_with_template_dependencies(*args, &block)
+      if CacheDebugging::StrictDependencies.strict_dependencies_enabled? && cache_blocks.length > 0
+        options = args.first
+        if options.is_a?(Hash)
+          if partial = options[:partial]
+            validate_partial!(partial)
+          end
+        else
+          (options.respond_to?(:to_ary) ? options.to_ary : Array(options)).each do |object|
+            validate_partial!(Utils.object_partial_path(object))
+          end
+        end
+      end
+      render_without_template_dependencies(*args, &block)
+    end
+
+    private
+
+    def validate_partial!(partial)
+      unless valid_partial?(partial)
+        Utils.publish_notification("cache_debugging.cache_dependency_missing", {
+          partial: partial,
+          template: cache_blocks.last[:template],
+          dependencies: cache_blocks.last[:dependencies]
+        })
+      end
+    end
+
+    def valid_partial?(partial)
+      cache_blocks.last[:dependencies].include?(partial)
+    end
+
+  end
+end

data/lib/cache_debugging/utils.rb

@@ -0,0 +1,40 @@
+# Use this module to keep helper methods out of ActionView::Base scope
+module CacheDebugging
+  module Utils
+    # recursively flatten complex array/hash objects
+    def self.deep_flatten(array_or_hash)
+      case array_or_hash
+      when Array
+        array_or_hash.map do |value|
+          if value.is_a?(Hash) || value.is_a?(Array)
+            deep_flatten(value)
+          else
+            value
+          end
+        end.flatten
+      when Hash
+        deep_flatten(array_or_hash.keys + array_or_hash.values)
+      end
+    end
+
+    # wrapper for ActiveSupport::Notification publish
+    def self.publish_notification(name, extra = {})
+      ActiveSupport::Notifications.publish(
+        name, 
+        Time.now,             # not a block, so fake the start time
+        Time.now,             # not a block, so fake the finish time
+        SecureRandom.hex(10), # generate a unique id
+        extra
+      )
+    end
+
+    def self.object_partial_path(object)
+      partial = begin
+        object.to_partial_path
+      rescue 
+        object.class.model_name.partial_path
+      end
+      partial.split("/").tap{|parts| parts.last.gsub!(/^_?/, "_")}.join("/")
+    end
+  end
+end

data/lib/cache_debugging/version.rb

@@ -0,0 +1,3 @@
+module CacheDebugging
+  VERSION = "0.0.1"
+end

data/lib/cache_debugging/view_sampling.rb

@@ -0,0 +1,80 @@
+module CacheDebugging
+  module ViewSampling
+    extend ActiveSupport::Concern
+
+    mattr_accessor :force_sampling
+
+    def self.force_sampling?
+      !!self.force_sampling
+    end
+
+    def self.view_sampling_rate
+      Rails.application.config.cache_debugging.view_sampling
+    end
+
+    def self.view_sampling_enabled?
+      !!view_sampling_rate
+    end
+
+    # code taken from fragment_for
+    def self.render_block(view, &block)
+      # VIEW TODO: Make #capture usable outside of ERB
+      # This dance is needed because Builder can't use capture
+      output_buffer = view.output_buffer
+      pos = output_buffer.length
+      yield
+      output_safe = output_buffer.html_safe?
+      fragment = output_buffer.slice!(pos..-1)
+      if output_safe
+        view.output_buffer = output_buffer.class.new(output_buffer)
+      end
+      fragment
+    end
+
+    def self.should_sample?(options)
+      return false unless view_sampling_enabled?
+      return true if force_sampling?
+
+      sample = (options || {}).fetch(:sample) { view_sampling_rate }.to_f
+      rand <= sample
+    end
+
+    included do
+      alias_method_chain :cache, :view_sampling
+    end
+
+    # clear forcing of view sampling if it's been initiated
+    def cache_with_view_sampling(name = {}, options = nil, &block)
+      cache_without_view_sampling(name, options, &block)
+      CacheDebugging::ViewSampling.force_sampling = false if cache_depth == 0
+    end
+
+    private
+
+    # since there are no hooks on a cache hit, that also has access to the render block, we
+    #   must override fragement_for here
+    def fragment_for(name = {}, options = nil, &block)
+      if fragment = controller.read_fragment(name, options)
+        return fragment unless CacheDebugging::ViewSampling.should_sample?(options)
+        CacheDebugging::ViewSampling.force_sampling = true
+
+        CacheDebugging::ViewSampling.render_block(self, &block).tap do |uncached|
+          Utils.publish_notification("cache_debugging.cache_mismatch", {
+            cached: fragment,
+            uncached: uncached,
+            template: current_template,
+            cache_key: name
+          }) unless uncached == fragment
+        end
+      else
+        fragment = CacheDebugging::ViewSampling.render_block(self, &block)
+        controller.write_fragment(name, fragment, options)
+      end
+    end
+
+    def current_template
+      @virtual_path
+    end
+
+  end
+end