When your templates change, browser caches bust automatically.

New default: the template digest is automatically included in your ETags.
When you call `fresh_when @post`, the digest for `posts/show.html.erb`
is mixed in so future changes to the HTML will blow HTTP caches for you.
This makes it easy to HTTP-cache many more of your actions.

If you render a different template, you can now pass the `:template`
option to include its digest instead:

  fresh_when @post, template: 'widgets/show'

Pass `template: false` to skip the lookup. To turn this off entirely, set:

  config.action_controller.etag_with_template_digest = false

7 files changed, 136 insertions, 9 deletions

diff --git a/actionpack/CHANGELOG.md b/actionpack/CHANGELOG.md
index 7c460fbaef..90fb99ad3a 100644
--- a/actionpack/CHANGELOG.md
+++ b/actionpack/CHANGELOG.md
@@ -1,3 +1,21 @@
+*   When your templates change, browser caches bust automatically.
+
+    New default: the template digest is automatically included in your ETags.
+    When you call `fresh_when @post`, the digest for `posts/show.html.erb`
+    is mixed in so future changes to the HTML will blow HTTP caches for you.
+    This makes it easy to HTTP-cache many more of your actions.
+
+    If you render a different template, you can now pass the `:template`
+    option to include its digest instead:
+
+      fresh_when @post, template: 'widgets/show'
+
+    Pass `template: false` to skip the lookup. To turn this off entirely, set:
+
+      config.action_controller.etag_with_template_digest = false
+
+    *Jeremy Kemper*
+
 *   Remove deprecated `AbstractController::Helpers::ClassMethods::MissingHelperError`
     in favor of `AbstractController::Helpers::MissingHelperError`.
 
diff --git a/actionpack/lib/action_controller.rb b/actionpack/lib/action_controller.rb
index 50bc26a80f..7f1aeafe8b 100644
--- a/actionpack/lib/action_controller.rb
+++ b/actionpack/lib/action_controller.rb
@@ -17,6 +17,7 @@ module ActionController
     autoload :ConditionalGet
     autoload :Cookies
     autoload :DataStreaming
+    autoload :EtagWithTemplateDigest
     autoload :Flash
     autoload :ForceSSL
     autoload :Head
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index e6fe6b0b00..7bbf938987 100644
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -213,6 +213,7 @@ module ActionController
       Rendering,
       Renderers::All,
       ConditionalGet,
+      EtagWithTemplateDigest,
       RackDelegation,
       Caching,
       MimeResponds,
diff --git a/actionpack/lib/action_controller/metal/conditional_get.rb b/actionpack/lib/action_controller/metal/conditional_get.rb
index 6e0cd51d8b..a93727df90 100644
--- a/actionpack/lib/action_controller/metal/conditional_get.rb
+++ b/actionpack/lib/action_controller/metal/conditional_get.rb
@@ -41,6 +41,11 @@ module ActionController
     # * <tt>:last_modified</tt>.
     # * <tt>:public</tt> By default the Cache-Control header is private, set this to
     #   +true+ if you want your application to be cachable by other devices (proxy caches).
+    # * <tt>:template</tt> By default, the template digest for the current
+    #   controller/action is included in ETags. If the action renders a
+    #   different template, you can include its digest instead. If the action
+    #   doesn't render a template at all, you can pass <tt>template: false</tt>
+    #   to skip any attempt to check for a template digest.
     #
     # === Example:
     #
@@ -66,18 +71,24 @@ module ActionController
     #     @article = Article.find(params[:id])
     #     fresh_when(@article, public: true)
     #   end
+    #
+    # When rendering a different template than the default controller/action
+    # style, you can indicate which digest to include in the ETag:
+    #
+    #   before_action { fresh_when @article, template: 'widgets/show' }
+    #
     def fresh_when(record_or_options, additional_options = {})
       if record_or_options.is_a? Hash
         options = record_or_options
-        options.assert_valid_keys(:etag, :last_modified, :public)
+        options.assert_valid_keys(:etag, :last_modified, :public, :template)
       else
         record  = record_or_options
         options = { etag: record, last_modified: record.try(:updated_at) }.merge!(additional_options)
       end
 
-      response.etag          = combine_etags(options[:etag]) if options[:etag]
-      response.last_modified = options[:last_modified]       if options[:last_modified]
-      response.cache_control[:public] = true                 if options[:public]
+      response.etag          = combine_etags(options)   if options[:etag] || options[:template]
+      response.last_modified = options[:last_modified]  if options[:last_modified]
+      response.cache_control[:public] = true            if options[:public]
 
       head :not_modified if request.fresh?(response)
     end
@@ -93,6 +104,11 @@ module ActionController
     # * <tt>:last_modified</tt>.
     # * <tt>:public</tt> By default the Cache-Control header is private, set this to
     #   +true+ if you want your application to be cachable by other devices (proxy caches).
+    # * <tt>:template</tt> By default, the template digest for the current
+    #   controller/action is included in ETags. If the action renders a
+    #   different template, you can include its digest instead. If the action
+    #   doesn't render a template at all, you can pass <tt>template: false</tt>
+    #   to skip any attempt to check for a template digest.
     #
     # === Example:
     #
@@ -133,6 +149,14 @@ module ActionController
     #       end
     #     end
     #   end
+    #
+    # When rendering a different template than the default controller/action
+    # style, you can indicate which digest to include in the ETag:
+    #
+    #   def show
+    #     super if stale? @article, template: 'widgets/show'
+    #   end
+    #
     def stale?(record_or_options, additional_options = {})
       fresh_when(record_or_options, additional_options)
       !request.fresh?(response)
@@ -168,8 +192,9 @@ module ActionController
     end
 
     private
-      def combine_etags(etag)
-        [ etag, *etaggers.map { |etagger| instance_exec(&etagger) }.compact ]
+      def combine_etags(options)
+        etags = etaggers.map { |etagger| instance_exec(options, &etagger) }.compact
+        etags.unshift options[:etag]
       end
   end
 end
diff --git a/actionpack/lib/action_controller/metal/etag_with_template_digest.rb b/actionpack/lib/action_controller/metal/etag_with_template_digest.rb
new file mode 100644
index 0000000000..3ca0c6837a
--- /dev/null
+++ b/actionpack/lib/action_controller/metal/etag_with_template_digest.rb
@@ -0,0 +1,50 @@
+module ActionController
+  # When our views change, they should bubble up into HTTP cache freshness
+  # and bust browser caches. So the template digest for the current action
+  # is automatically included in the ETag.
+  #
+  # Enabled by default for apps that use Action View. Disable by setting
+  #
+  #   config.action_controller.etag_with_template_digest = false
+  #
+  # Override the template to digest by passing `:template` to `fresh_when`
+  # and `stale?` calls. For example:
+  #
+  #   # We're going to render widgets/show, not posts/show
+  #   fresh_when @post, template: 'widgets/show'
+  #
+  #   # We're not going to render a template, so omit it from the ETag.
+  #   fresh_when @post, template: false
+  #
+  module EtagWithTemplateDigest
+    extend ActiveSupport::Concern
+
+    include ActionController::ConditionalGet
+
+    included do
+      class_attribute :etag_with_template_digest
+      self.etag_with_template_digest = true
+
+      ActiveSupport.on_load :action_view, yield: true do |action_view_base|
+        etag do |options|
+          determine_template_etag(options) if etag_with_template_digest
+        end
+      end
+    end
+
+    private
+    def determine_template_etag(options)
+      if template = pick_template_for_etag(options)
+        lookup_and_digest_template(template)
+      end
+    end
+
+    def pick_template_for_etag(options)
+      options.fetch(:template) { "#{controller_name}/#{action_name}" }
+    end
+
+    def lookup_and_digest_template(template)
+      ActionView::Digestor.digest name: template, finder: lookup_context
+    end
+  end
+end
diff --git a/actionpack/test/controller/live_stream_test.rb b/actionpack/test/controller/live_stream_test.rb
index 0500b7c789..7fd1276e98 100644
--- a/actionpack/test/controller/live_stream_test.rb
+++ b/actionpack/test/controller/live_stream_test.rb
@@ -162,7 +162,7 @@ module ActionController
       end
 
       def with_stale
-        render :text => 'stale' if stale?(:etag => "123")
+        render text: 'stale' if stale?(etag: "123", template: false)
       end
 
       def exception_in_view
diff --git a/actionpack/test/controller/render_test.rb b/actionpack/test/controller/render_test.rb
index 9926130c02..b036b6c08e 100644
--- a/actionpack/test/controller/render_test.rb
+++ b/actionpack/test/controller/render_test.rb
@@ -10,11 +10,17 @@ class TestControllerWithExtraEtags < ActionController::Base
   etag { nil  }
 
   def fresh
-    render text: "stale" if stale?(etag: '123')
+    render text: "stale" if stale?(etag: '123', template: false)
   end
 
   def array
-    render text: "stale" if stale?(etag: %w(1 2 3))
+    render text: "stale" if stale?(etag: %w(1 2 3), template: false)
+  end
+
+  def with_template
+    if stale? template: 'test/hello_world'
+      render text: 'stale'
+    end
   end
 end
 
@@ -409,6 +415,32 @@ class EtagRenderTest < ActionController::TestCase
     assert_response :success
   end
 
+  def test_etag_reflects_template_digest
+    get :with_template
+    assert_response :ok
+    assert_not_nil etag = @response.etag
+
+    request.if_none_match = etag
+    get :with_template
+    assert_response :not_modified
+
+    # Modify the template digest
+    path = File.expand_path('../../fixtures/test/hello_world.erb', __FILE__)
+    old = File.read(path)
+
+    begin
+      File.write path, 'foo'
+      ActionView::Digestor.cache.clear
+
+      request.if_none_match = etag
+      get :with_template
+      assert_response :ok
+      assert_not_equal etag, @response.etag
+    ensure
+      File.write path, old
+    end
+  end
+
   def etag(record)
     Digest::MD5.hexdigest(ActiveSupport::Cache.expand_cache_key(record)).inspect
   end