josevalim / easy_http_cache

Easy HTTP Cache

Allows Rails applications to do conditional cache easily and in a DRY way (without messing up your actions):

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => :list

    protected
      def list
        @list ||= List.find(params[:id])
      end
  end

It uses :last_modified and :etag keys, that besides Time, String or resources accepts Proc, Method and Symbol that are evaluated within the current controller.

Read more about each option (more examples at the end of this page):

  :last_modified
    Used to manipulate Last-Modified header. You can pass any object that responds
    to :updated_at, :updated_on or :to_time. If you pass a Proc or Method or Symbol,
    they will be evaluated within the current controller first.

    Finally, if you pass an array, it will get the most recent time to be used.

  :etag
    Used to manipulate Etag header. The Etag is generated as memcached keys are
    generated, i.e. calling to_param in the object and then MD5 is applied.

    If you pass a Proc or Method or Symbols, they will be also evaluated within the
    current controller first.

  :if
    Only perform http cache if it returns true.

  :unless
    Only perform http cache if it returns false.

  :method
    If in :last_modified you want to pass a object that doesn't respond to updated_at,
    updated_on or to_time, you can specify the method that will be called in this object.

Install

Install Easy HTTP Cache is available on gemcutter, so just execute:

  sudo gem install easy_http_cache

And add it to your environment.

Environment Variables

As in memcached, you can set ENV[‘RAILS_CACHE_ID’] or ENV[‘RAILS_APP_VERSION’] variables to change the Etag that will be generated. This means you can control the cache by setting a timestamp or a version number in ENV[‘RAILS_APP_VERSION’] everytime you deploy.

Examples

The example below will cache your actions and it will never expire:

  class ListsController < ApplicationController
    http_cache :index, :show
  end

If you do not want to cache when you are showing a flash message (and you usually want that), you can simply do:

  class ListsController < ApplicationController
    http_cache :index, :show, :if => Proc.new { |c| c.send(:flash).empty? }
  end

And if you do not want to cache JSON requests:

  class ListsController < ApplicationController
    http_cache :index, :show, :unless => Proc.new { |c| c.request.format.json? }
  end

Or if you want to expire all http cache before 2008, just do:

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => Time.utc(2008)
  end

If you want to cache a list and automatically expire the cache when it changes, just do (it will check updated_at and updated_on on the @list object):

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => :list

    protected
      def list
        @list ||= List.find(params[:id])
      end
  end

You can also set :etag header (it will generate an etag calling to_param in the object and applying MD5):

  class ListsController < ApplicationController
    http_cache :index, :show, :etag => :list

    protected
      def list
        @list ||= List.find(params[:id])
      end
  end

If you are using a resource that doesn’t respond to updated_at or updated_on, you can pass a method as parameter that will be called in your resources:

  class ListsController < ApplicationController
    http_cache :index, :show, :last_modified => :list, :method => :cached_at

    protected
      def list
        @list ||= List.find(params[:id])
      end
  end

The sample below will call @list.cached_at to generate Last-Modified header. Finally, you can also pass an array at :last_modified as below:

  class ItemsController < ApplicationController
    http_cache :index, :show,
               :last_modified => [ :list, :item ]

    protected
      def list
        @list ||= List.find(params[:list_id])
      end

      def item
        @item ||= list.items.find(params[:id])
      end
  end

This will check which one is the most recent to compare with the "Last-Modified" field sent by the client.

What if?

At this point (or at some point), you will ask what happens if you use :etag and :last_modified at the same time.

Well, the specification says that if both are sent by the client, both have to be valid for the cache not be considered stale. This subject was already brought to Rails Core group and this is also how Rails’ current implementation behaves.

Bugs and Feedback

If you find any issues, please use Github issues tracker.

Copyright © 2009 José Valim blog.plataformatec.com.br/