josevalim-easy_http_cache 2.0 → 2.1

data/README

@@ -1,21 +1,11 @@
-Copyright (c) 2008 José Valim (jose.valim at gmail dot com)
-Site: http://www.pagestacker.com/
-Blog: http://josevalim.blogspot.com/
+Easy HTTP Cache
 License: MIT
-Version: 2.0
+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
 
-Warning
--------
-
-Since version 2.0, this plugin/gem has drastically changed to fit Rails 2.2
-http cache goodness. :expires_in, :expires_at and :control options were
-removed, so if you want to use previous versions, see "Previous versions"
-below.
-
 Description
 -----------
 
@@ -23,36 +13,42 @@ 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
+    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 Symbols that are evaluated within the current controller.
-Read more about each option below:
+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 :to_time. If you pass a Proc or Method or Symbols, they will be evaluated
-    within the current controller and :to_time will be called.
+    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.
 
-    You can also pass resources and :updated_at or :updated_on will be called on
-    it. If you want to call a different method on your resource, you can pass it as
-    a symbol using the :method option.
-
-    All times will be converted to UTC. Finally, if you pass an array, it will get
-    the most recent time to be used.
+    Finally, if you pass an array, it will get the most recent time to be used.
 
   :etag
-    Used to manipulate Etag header. If you pass a Proc or Method or Symbols, they
-    will be evaluated within the current controller.
-
-    You can also pass an array and each element will be also evaluated with needed.
+    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
@@ -62,9 +58,6 @@ 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
-
-Then install the gem:
-
   sudo gem install josevalim-easy_http_cache
 
 In RAILS_ROOT/config/environment.rb:
@@ -77,6 +70,7 @@ If you want it as plugin, just do:
     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
 -----------------
@@ -89,21 +83,21 @@ If you are running on Rails 2.1.x, you should use v1.2.3:
     git checkout v1.2.3
     rm -rf ./.git
 
-If you are using a previous version, please updagrade your app. =)
+If you are using earlier than 2.1, please upgrade your app. =)
 
 
 Variables
 ---------
 
-You can set ENV['RAILS_CACHE_ID'] or ENV['RAILS_APP_VERSION'] to change
-the ETag that will be generated, expiring all previous caches. Those variables
-are also used by other cache stores (memcached, file, ...).
+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
 --------
 
-Just as above:
+The example below will cache your actions and it will never expire:
 
   class ListsController < ApplicationController
     http_cache :index, :show
@@ -113,10 +107,10 @@ 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? }
+    http_cache :index, :show, :if => Proc.new { |c| c.send(:flash).empty? }
   end
 
-And if you do not want JSON requests:
+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? }
@@ -128,8 +122,8 @@ Or if you want to expire all http cache before 2008, just do:
     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:
+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
@@ -140,7 +134,8 @@ it changes, just do:
       end
   end
 
-You can also set :etag header:
+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
@@ -152,23 +147,54 @@ You can also set :etag header:
   end
 
 If you are using a resource that doesn't respond to updated_at or updated_on,
-you can pass a method as parameter and it will be called in your resources:
+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
+      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 ListsController < ApplicationController
+  class ItemsController < ApplicationController
     http_cache :index, :show,
-               :last_modified => [ :list, Time.utc(2007,12,27) ]
+               :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.
+"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/

data/Rakefile

@@ -2,11 +2,18 @@ require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'
 
-desc 'Generate documentation for Footnotes plugin.'
+desc 'Run tests for Easy HTTP Cache.'
+Rake::TestTask.new(:test) do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for Easy HTTP Cache.'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'Easy HTTP Cache'
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('MIT-LICENSE')
   rdoc.rdoc_files.include('lib/**/*.rb')
-end
+end

data/lib/easy_http_cache.rb

@@ -33,10 +33,6 @@ module ActionController #:nodoc:
         end
 
         def filter(controller)
-          # We don't go ahead if we are rendering a component
-          #
-          return if component_request?(controller)
-
           last_modified = get_last_modified(controller)
           controller.response.last_modified = last_modified if last_modified
 
@@ -44,7 +40,7 @@ module ActionController #:nodoc:
           controller.response.etag = processed_etags if processed_etags
 
           if controller.request.fresh?(controller.response)
-            controller.__send__(:head, :not_modified)
+            controller.send(:head, :not_modified)
             return false
           end
         end
@@ -53,11 +49,6 @@ module ActionController #:nodoc:
           # If :etag is an array, it processes all Methods, Procs and Symbols
           # and return them as array. If it's an object, we only evaluate it.
           #
-          # Finally, if :etag is not sent but RAILS_CACHE_ID or RAILS_APP_VERSION
-          # are set, we return an empty string allowing etag to be performed
-          # because those variables, when modified, are a valid way to expire
-          # all previous caches.
-          #
           def get_processed_etags(controller)
             if @options[:etag].is_a?(Array)
               @options[:etag].collect do |item|
@@ -65,8 +56,6 @@ module ActionController #:nodoc:
               end
             elsif @options[:etag]
               evaluate_method(@options[:etag], controller)
-            elsif ENV['RAILS_CACHE_ID'] || ENV['RAILS_APP_VERSION']
-              ''
             else
               nil
             end
@@ -126,15 +115,10 @@ module ActionController #:nodoc:
             end
           end
 
-          # We should not do http cache when we are using components
-          #
-          def component_request?(controller)
-            controller.instance_variable_get('@parent_controller')
-          end
         end
 
     end
   end
 end
 
-ActionController::Base.__send__ :include, ActionController::Caching::HttpCache
+ActionController::Base.send :include, ActionController::Caching::HttpCache

data/test/easy_http_cache_test.rb

@@ -1,9 +1,16 @@
 # Those lines are plugin test settings
-ENV["RAILS_ENV"] = "test"
+require 'test/unit'
+require 'rubygems'
 require 'ostruct'
-require File.dirname(__FILE__) + '/../../../../config/environment'
+
+ENV["RAILS_ENV"] = "test"
+
+require 'active_support'
+require 'action_controller'
+require 'action_controller/test_case'
+require 'action_controller/test_process'
+
 require File.dirname(__FILE__) + '/../lib/easy_http_cache.rb'
-require 'test_help'
 
 ActionController::Base.perform_caching = true
 ActionController::Routing::Routes.draw do |map|
@@ -62,7 +69,7 @@ class HttpCacheTestController < ActionController::Base
     end
 end
 
-class HttpCacheTest < Test::Unit::TestCase
+class HttpCacheTest < ActionController::TestCase
   def setup
     reset!
   end
@@ -115,17 +122,7 @@ class HttpCacheTest < Test::Unit::TestCase
     @request.env['HTTP_ACCEPT'] = 'application/json'
     @request.env['HTTP_IF_MODIFIED_SINCE'] = 1.hour.ago.httpdate
     get :show
-    assert_equal '200 OK', @response.headers['Status']
-  end
-
-  def test_http_cache_without_input_with_env_variable
-    ENV['RAILS_APP_VERSION'] = '1.2.3'
-
-    get :index
-    assert_headers('200 OK', 'private, max-age=0, must-revalidate', 'Last-Modified', Time.utc(0).httpdate)
-    reset!
-
-    etag_http_cache(:index, '')
+    assert_equal '200 OK', @response.status
   end
 
   def test_etag_http_cache
@@ -141,22 +138,6 @@ class HttpCacheTest < Test::Unit::TestCase
     etag_http_cache(:etag, 'ETAG_CACHE')
   end
 
-  def test_should_not_cache_when_rendering_components
-    set_parent_controller! 
-    get :show
-    assert_headers('200 OK', 'no-cache')
-
-    set_parent_controller!
-    @request.env['HTTP_IF_MODIFIED_SINCE'] = 1.hour.ago.httpdate
-    get :show
-    assert_headers('200 OK', 'no-cache')
-
-    set_parent_controller!
-    @request.env['HTTP_IF_MODIFIED_SINCE'] = 3.hours.ago.httpdate
-    get :show
-    assert_headers('200 OK', 'no-cache')
-  end
-
   private
     def reset!
       @request = ActionController::TestRequest.new
@@ -164,20 +145,12 @@ class HttpCacheTest < Test::Unit::TestCase
       @controller = HttpCacheTestController.new
     end
 
-    def set_parent_controller!
-      get :index
-      old_controller = @controller.dup
-      reset!
-
-      @controller.instance_variable_set('@parent_controller', old_controller)
-    end
-
     def etag_for(etag)
       %("#{Digest::MD5.hexdigest(ActiveSupport::Cache.expand_cache_key(etag))}")
     end
 
     def assert_headers(status, control, cache_header=nil, value=nil)
-      assert_equal status, @response.headers['Status']
+      assert_equal status, @response.status
       assert_equal control, @response.headers['Cache-Control']
 
       if cache_header

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: josevalim-easy_http_cache
 version: !ruby/object:Gem::Version 
-  version: "2.0"
+  version: "2.1"
 platform: ruby
 authors: 
 - "Jos\xC3\xA9 Valim"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-11-29 00:00:00 -08:00
+date: 2009-02-04 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
@@ -25,7 +25,6 @@ files:
 - MIT-LICENSE
 - README
 - Rakefile
-- init.rb
 - lib/easy_http_cache.rb
 - test/easy_http_cache_test.rb
 has_rdoc: true

data/init.rb

@@ -1 +0,0 @@
-require 'easy_http_cache'