vendor/rails/actionpack/lib/action_controller/caching/pages.rb

   1 require 'fileutils'
   2 require 'uri'
   3
   4 module ActionController #:nodoc:
   5   module Caching
   6     # Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server
   7     # can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically
   8     # through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages
   9     # where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are
  10     # a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less
  11     # likely candidates.
  12     #
  13     # Specifying which actions to cache is done through the <tt>caches_page</tt> class method:
  14     #
  15     #   class WeblogController < ActionController::Base
  16     #     caches_page :show, :new
  17     #   end
  18     #
  19     # This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>,
  20     # which match the URLs used to trigger the dynamic generation. This is how the web server is able
  21     # pick up a cache file when it exists and otherwise let the request pass on to Action Pack to generate it.
  22     #
  23     # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache
  24     # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
  25     #
  26     #   class WeblogController < ActionController::Base
  27     #     def update
  28     #       List.update(params[:list][:id], params[:list])
  29     #       expire_page :action => "show", :id => params[:list][:id]
  30     #       redirect_to :action => "show", :id => params[:list][:id]
  31     #     end
  32     #   end
  33     #
  34     # Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be
  35     # expired.
  36     #
  37     # == Setting the cache directory
  38     #
  39     # The cache directory should be the document root for the web server and is set using <tt>Base.page_cache_directory = "/document/root"</tt>.
  40     # For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>RAILS_ROOT + "/public"</tt>). Changing
  41     # this setting can be useful to avoid naming conflicts with files in <tt>public/</tt>, but doing so will likely require configuring your
  42     # web server to look in the new location for cached files.
  43     #
  44     # == Setting the cache extension
  45     #
  46     # Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>. In these cases, the page caching mechanism will add one in
  47     # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is <tt>.html</tt>.
  48     # If you want something else, like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension. In cases where a request already has an
  49     # extension, such as <tt>.xml</tt> or <tt>.rss</tt>, page caching will not add an extension. This allows it to work well with RESTful apps.
  50     module Pages
  51       def self.included(base) #:nodoc:
  52         base.extend(ClassMethods)
  53         base.class_eval do
  54           @@page_cache_directory = defined?(Rails.public_path) ? Rails.public_path : ""
  55           cattr_accessor :page_cache_directory
  56
  57           @@page_cache_extension = '.html'
  58           cattr_accessor :page_cache_extension
  59         end
  60       end
  61
  62       module ClassMethods
  63         # Expires the page that was cached with the +path+ as a key. Example:
  64         #   expire_page "/lists/show"
  65         def expire_page(path)
  66           return unless perform_caching
  67
  68           benchmark "Expired page: #{page_cache_file(path)}" do
  69             File.delete(page_cache_path(path)) if File.exist?(page_cache_path(path))
  70           end
  71         end
  72
  73         # Manually cache the +content+ in the key determined by +path+. Example:
  74         #   cache_page "I'm the cached content", "/lists/show"
  75         def cache_page(content, path)
  76           return unless perform_caching
  77
  78           benchmark "Cached page: #{page_cache_file(path)}" do
  79             FileUtils.makedirs(File.dirname(page_cache_path(path)))
  80             File.open(page_cache_path(path), "wb+") { |f| f.write(content) }
  81           end
  82         end
  83
  84         # Caches the +actions+ using the page-caching approach that'll store the cache in a path within the page_cache_directory that
  85         # matches the triggering url.
  86         #
  87         # Usage:
  88         #
  89         #   # cache the index action
  90         #   caches_page :index
  91         #
  92         #   # cache the index action except for JSON requests
  93         #   caches_page :index, :if => Proc.new { |c| !c.request.format.json? }
  94         def caches_page(*actions)
  95           return unless perform_caching
  96           options = actions.extract_options!
  97           after_filter({:only => actions}.merge(options)) { |c| c.cache_page }
  98         end
  99
 100         private
 101           def page_cache_file(path)
 102             name = (path.empty? || path == "/") ? "/index" : URI.unescape(path.chomp('/'))
 103             name << page_cache_extension unless (name.split('/').last || name).include? '.'
 104             return name
 105           end
 106
 107           def page_cache_path(path)
 108             page_cache_directory + page_cache_file(path)
 109           end
 110       end
 111
 112       # Expires the page that was cached with the +options+ as a key. Example:
 113       #   expire_page :controller => "lists", :action => "show"
 114       def expire_page(options = {})
 115         return unless perform_caching
 116
 117         if options.is_a?(Hash)
 118           if options[:action].is_a?(Array)
 119             options[:action].dup.each do |action|
 120               self.class.expire_page(url_for(options.merge(:only_path => true, :skip_relative_url_root => true, :action => action)))
 121             end
 122           else
 123             self.class.expire_page(url_for(options.merge(:only_path => true, :skip_relative_url_root => true)))
 124           end
 125         else
 126           self.class.expire_page(options)
 127         end
 128       end
 129
 130       # Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used
 131       # If no options are provided, the requested url is used. Example:
 132       #   cache_page "I'm the cached content", :controller => "lists", :action => "show"
 133       def cache_page(content = nil, options = nil)
 134         return unless perform_caching && caching_allowed
 135
 136         path = case options
 137           when Hash
 138             url_for(options.merge(:only_path => true, :skip_relative_url_root => true, :format => params[:format]))
 139           when String
 140             options
 141           else
 142             request.path
 143         end
 144
 145         self.class.cache_page(content || response.body, path)
 146       end
 147
 148       private
 149         def caching_allowed
 150           request.get? && response.headers['Status'].to_i == 200
 151         end
 152     end
 153   end
 154 end