Easy HTTP Cache
License: MIT
Version: 2.1

You can also read this README in pretty html at the GitHub project Wiki page

  http://github.com/josevalim/easy_http_cache/wikis/home

Description
-----------

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 very easy. It is stored in GitHub, so if you
have never installed a gem via GitHub run the following:

  gem sources -a http://gems.github.com
  sudo gem install josevalim-easy_http_cache

In RAILS_ROOT/config/environment.rb:

  config.gem "josevalim-easy_http_cache",  :lib => "easy_http_cache", :source => "http://gems.github.com"

If you want it as plugin, just do:

    cd myapp
    git clone git://github.com/josevalim/easy_http_cache.git
    rm -rf vendor/plugins/easy_http_cache/.git

Current version supports Rails 2.2.x and Rails 2.3.x.

Previous versions
-----------------

If you are running on Rails 2.1.x, you should use v1.2.3:

    cd myapp
    git clone git://github.com/josevalim/easy_http_cache.git
    cd vendor/plugins/easy_http_cache
    git checkout v1.2.3
    rm -rf ./.git

If you are using earlier than 2.1, please upgrade your app. =)


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, Padawan, 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 discover any bugs, please send an e-mail to jose.valim@gmail.com
If you just want to give some positive feedback or drop a line, that's fine too! =)

Copyright (c) 2009 José Valim
http://www.pagestacker.com/
http://josevalim.blogspot.com/