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

4 files changed, 83 insertions, 6 deletions

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