rtomayko-rack-cache 0.3.9 → 0.4

data/CHANGES

@@ -1,4 +1,4 @@
-## 0.4.0 / Unreleased
+## 0.4.0 / March 2009
 
   * Ruby 1.9.1 / Rack 1.0 compatible.
 
@@ -9,7 +9,8 @@
 
   * Implement "Cache-Control: max-age=N" request directive by forcing
     validation when the max-age provided exceeds the age of the cache
-    entry.
+    entry. This can be disabled by setting the "allow_revalidate" option to
+    false.
 
   * Properly implement "Cache-Control: no-cache" request directive by
     performing a full reload. RFC 2616 states that when "no-cache" is
@@ -19,7 +20,8 @@
     first validate its entry with the origin. Previously, we implemented
     "no-cache" on requests by passing so no new cache entry would be stored
     based on the response. Now we treat it as a forced miss and enter the
-    response into the cache if it's cacheable.
+    response into the cache if it's cacheable. This can be disabled by
+    setting the "allow_reload" option to false.
 
   * Assume identical semantics for the "Pragma: no-cache" request header
     as the "Cache-Control: no-cache" directive described above.

data/README

@@ -24,14 +24,6 @@ caching solution for small to medium sized deployments. More sophisticated /
 high-performance caching systems (e.g., Varnish, Squid, httpd/mod-cache) may be
 more appropriate for large deployments with significant throughput requirements.
 
-Status
-------
-
-Rack::Cache is a young and experimental project that is likely to change
-substantially and may not be wholly functional, consistent, fast, or correct.
-The current focus is on reaching basic compliance with RFC 2616 and providing
-good documentation.
-
 Installation
 ------------
 
@@ -65,6 +57,24 @@ Assuming you've designed your backend application to take advantage of HTTP's
 caching features, no further code or configuration is required for basic
 caching.
 
+Using with Rails
+----------------
+
+Add this to your `config/environment.rb`:
+
+   config.middleware.use Rack::Cache,
+       :verbose => true,
+       :metastore   => 'file:/var/cache/rack/meta',
+       :entitystore => 'file:/var/cache/rack/body'
+
+You should now see `Rack::Cache` listed in the middleware pipeline:
+
+    rake middleware
+
+See the following for more information:
+
+    http://snippets.aktagon.com/snippets/302
+
 Links
 -----
 

data/Rakefile

@@ -31,7 +31,7 @@ end
 
 # DOC =======================================================================
 desc 'Build all documentation'
-task :doc => %w[doc:api doc:graphs doc:markdown]
+task :doc => %w[doc:api doc:markdown]
 
 # requires the hanna gem:
 #   gem install mislav-hanna --source=http://gems.github.com
@@ -55,19 +55,6 @@ file 'doc/api/index.html' => FileList['lib/**/*.rb'] do |f|
 end
 CLEAN.include 'doc/api'
 
-desc 'Build graphviz graphs'
-task 'doc:graphs'
-%w[pdf png svg].each do |filetype|
-  FileList["doc/*.dot"].each do |source|
-    dest = source.sub(/dot$/, filetype)
-    file dest => source do |f|
-      sh "dot -T#{filetype} #{source} -o #{f.name}"
-    end
-    task 'doc:graphs' => dest
-    CLEAN.include dest
-  end
-end
-
 desc 'Build markdown documentation files'
 task 'doc:markdown'
 FileList['doc/*.markdown'].each do |source|

data/TODO

@@ -1,13 +1,8 @@
-## 0.4
+## Backlog
 
   - Move breakers.rb configuration file into rack-contrib as a middleware
     component.
-  - Add docs on using Rack::Cache with Rails 2.3 or link to one of the
-    existing tutorials on this.
   - Sample apps: Rack, Rails, Sinatra, Merb, etc.
-
-## Backlog
-
   - Use Bacon instead of test/spec
   - Work with both memcache and memcached gems (memcached hasn't built on MacOS
     for some time now).

data/doc/faq.markdown

@@ -10,6 +10,14 @@ General
 -------
 
 
+<a class='hash' id='rails' href='#rails'>#</a>
+
+### Q: Can I use Rack::Cache with Rails?
+
+Rack::Cache can be used with Rails 2.3 or above. Documentation and a
+sample application is forthcoming; in the mean time, see
+[this example of using Rack::Cache with Rails 2.3](http://snippets.aktagon.com/snippets/302-How-to-setup-and-use-Rack-Cache-with-Rails-2-3-0-RC-1).
+
 <a class='hash' id='why-not-squid' href='#why-not-squid'>#</a>
 
 ### Q: Why Rack::Cache? Why not Squid, Varnish, Perlbol, etc.?

data/doc/index.markdown

@@ -9,13 +9,13 @@ for [Rack][]-based applications that produce freshness (`Expires`,
   * Portable: 100% Ruby / works with any [Rack][]-enabled framework.
   * Disk, memcached, and heap memory [storage backends][storage].
 
-Status
-------
+News
+----
 
-__Rack::Cache__ is a young and experimental project that is likely to
-change substantially and may not be wholly functional, consistent,
-fast, or correct. The current focus is on reaching basic compliance
-with RFC 2616 and providing good documentation.
+  * [How to use Rack::Cache with Rails 2.3](http://snippets.aktagon.com/snippets/302-How-to-setup-and-use-Rack-Cache-with-Rails-2-3-0-RC-1) - it's really easy.
+  * [RailsLab's Advanced HTTP Caching Screencast](http://railslab.newrelic.com/2009/02/26/episode-11-advanced-http-caching)
+    is a really great review of HTTP caching concepts and shows how to
+    use Rack::Cache with Rails.
 
 Installation
 ------------
@@ -51,7 +51,7 @@ caching.
 More
 ----
 
-  * [Configuration and Options][config] - how to set cache options.
+  * [Configuration Options][config] - how to set cache options.
 
   * [Cache Storage Documentation][storage] - detailed information on the various
     storage implementations available in __Rack::Cache__ and how to choose the one

data/lib/rack/cache/context.rb

@@ -15,11 +15,12 @@ module Rack::Cache
     # The Rack application object immediately downstream.
     attr_reader :backend
 
-    def initialize(backend, options={}, &block)
+    def initialize(backend, options={})
       @backend = backend
       @trace = []
+
       initialize_options options
-      instance_eval(&block) if block_given?
+      yield self if block_given?
 
       @private_header_keys =
         private_headers.map { |name| "HTTP_#{name.upcase.tr('-', '_')}" }
@@ -109,7 +110,7 @@ module Rack::Cache
     # Whether the cache entry is "fresh enough" to satisfy the request.
     def fresh_enough?(entry)
       if entry.fresh?
-        if max_age = @request.cache_control.max_age
+        if allow_revalidate? && max_age = @request.cache_control.max_age
           max_age > 0 && max_age >= entry.age
         else
           true
@@ -143,7 +144,7 @@ module Rack::Cache
     # stale, attempt to #validate the entry with the backend using conditional
     # GET. When no matching cache entry is found, trigger #miss processing.
     def lookup
-      if @request.no_cache?
+      if @request.no_cache? && allow_reload?
         record :reload
         fetch
       elsif entry = metastore.lookup(@request, entitystore)

data/lib/rack/cache/options.rb

@@ -7,20 +7,22 @@ module Rack::Cache
   # uses the Rack Environment to store option values. All options documented
   # below are stored in the Rack Environment as "rack-cache.<option>", where
   # <option> is the option name.
-  #
-  # The #set method can be used to configure a option values. When #set is
-  # called outside of request scope, the value applies to all requests; when
-  # called from within a request context, applies only to the request being
-  # processed.
   module Options
-    class << self
-      private
-      def option_accessor(key)
-        define_method(key) { || read_option(key) }
-        define_method("#{key}=") { |value| write_option(key, value) }
-        define_method("#{key}?") { || !! read_option(key) }
+    def self.option_accessor(key)
+      name = option_name(key)
+      define_method(key) { || options[name] }
+      define_method("#{key}=") { |value| options[name] = value }
+      define_method("#{key}?") { || !! options[name] }
+    end
+
+    def option_name(key)
+      case key
+      when Symbol ; "rack-cache.#{key}"
+      when String ; key
+      else raise ArgumentError
       end
     end
+    module_function :option_name
 
     # Enable verbose trace logging. This option is currently enabled by
     # default but is likely to be disabled in a future release.
@@ -57,9 +59,9 @@ module Rack::Cache
     #   end
     option_accessor :cache_key
 
-    # A URI specifying the entity-store implement that should be used to store
-    # response bodies. See the metastore option for information on supported URI
-    # schemes.
+    # A URI specifying the entity-store implementation that should be used to
+    # store response bodies. See the metastore option for information on
+    # supported URI schemes.
     #
     # If no entity store is specified the 'heap:/' store is assumed. This
     # implementation has significant draw-backs so explicit configuration is
@@ -83,6 +85,16 @@ module Rack::Cache
     # Default: ['Authorization', 'Cookie']
     option_accessor :private_headers
 
+    # Specifies whether the client can force a cache reload by including a
+    # Cache-Control "no-cache" directive in the request. This is enabled by
+    # default for compliance with RFC 2616.
+    option_accessor :allow_reload
+
+    # Specifies whether the client can force a cache revalidate by including
+    # a Cache-Control "max-age=0" directive in the request. This is enabled by
+    # default for compliance with RFC 2616.
+    option_accessor :allow_revalidate
+
     # The underlying options Hash. During initialization (or outside of a
     # request), this is a default values Hash. During a request, this is the
     # Rack environment Hash. The default values Hash is merged in underneath
@@ -112,6 +124,21 @@ module Rack::Cache
     end
 
   private
+    def initialize_options(options={})
+      @default_options = {
+        'rack-cache.cache_key'        => Key,
+        'rack-cache.verbose'          => true,
+        'rack-cache.storage'          => Rack::Cache::Storage.instance,
+        'rack-cache.metastore'        => 'heap:/',
+        'rack-cache.entitystore'      => 'heap:/',
+        'rack-cache.default_ttl'      => 0,
+        'rack-cache.private_headers'  => ['Authorization', 'Cookie'],
+        'rack-cache.allow_reload'     => true,
+        'rack-cache.allow_revalidate' => true
+      }
+      self.options = options
+    end
+
     def read_option(key)
       options[option_name(key)]
     end
@@ -119,27 +146,5 @@ module Rack::Cache
     def write_option(key, value)
       options[option_name(key)] = value
     end
-
-    def option_name(key)
-      case key
-      when Symbol ; "rack-cache.#{key}"
-      when String ; key
-      else raise ArgumentError
-      end
-    end
-
-  private
-    def initialize_options(options={})
-      @default_options = {
-        'rack-cache.cache_key'       => Key,
-        'rack-cache.verbose'         => true,
-        'rack-cache.storage'         => Rack::Cache::Storage.instance,
-        'rack-cache.metastore'       => 'heap:/',
-        'rack-cache.entitystore'     => 'heap:/',
-        'rack-cache.default_ttl'     => 0,
-        'rack-cache.private_headers' => ['Authorization', 'Cookie']
-      }
-      self.options = options
-    end
   end
 end

data/rack-cache.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'rack-cache'
-  s.version = '0.3.9'
-  s.date = '2009-03-07'
+  s.version = '0.4'
+  s.date = '2009-03-16'
 
   s.description = "HTTP Caching for Rack"
   s.summary     = "HTTP Caching for Rack"
@@ -20,7 +20,6 @@ Gem::Specification.new do |s|
     Rakefile
     TODO
     doc/configuration.markdown
-    doc/events.dot
     doc/faq.markdown
     doc/index.markdown
     doc/layout.html.erb

data/test/cache_test.rb

@@ -25,14 +25,14 @@ describe 'Rack::Cache::new' do
   end
 
   it 'takes a block; executes it during initialization' do
-    state, block_scope = 'not invoked', nil
-    object =
-      Rack::Cache.new @app do
-        block_scope = self
+    state, object  = 'not invoked', nil
+    instance =
+      Rack::Cache.new @app do |cache|
+        object = cache
         state = 'invoked'
-        should.respond_to :set
+        cache.should.respond_to :set
       end
     state.should.equal 'invoked'
-    object.should.be block_scope
+    object.should.be instance
   end
 end

data/test/context_test.rb

@@ -148,6 +148,31 @@ describe 'Rack::Cache::Context' do
     cache.trace.should.include :store
   end
 
+  it 'does not reload responses when allow_reload is set false' do
+    count = 0
+    respond_with 200, 'Cache-Control' => 'max-age=10000' do |req,res|
+      count+= 1
+      res.body = (count == 1) ? ['Hello World'] : ['Goodbye World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    get '/',
+      'rack-cache.allow_reload' => false,
+      'HTTP_CACHE_CONTROL' => 'no-cache'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.not.include :reload
+  end
+
   it 'revalidates fresh cache entry when max-age request directive is exceeded' do
     count = 0
     respond_with do |req,res|
@@ -175,6 +200,34 @@ describe 'Rack::Cache::Context' do
     cache.trace.should.include :store
   end
 
+  it 'does not revalidate fresh cache entry when enable_revalidate option is set false' do
+    count = 0
+    respond_with do |req,res|
+      count+= 1
+      res['Cache-Control'] = 'max-age=10000'
+      res['ETag'] = count.to_s
+      res.body = (count == 1) ? ['Hello World'] : ['Goodbye World']
+    end
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :store
+
+    get '/'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.include :fresh
+
+    get '/',
+      'rack-cache.allow_revalidate' => false,
+      'HTTP_CACHE_CONTROL' => 'max-age=0'
+    response.should.be.ok
+    response.body.should.equal 'Hello World'
+    cache.trace.should.not.include :stale
+    cache.trace.should.not.include :invalid
+    cache.trace.should.include :fresh
+  end
   it 'fetches response from backend when cache misses' do
     respond_with 200, 'Expires' => (Time.now + 5).httpdate
     get '/'

data/test/spec_setup.rb

@@ -1,5 +1,6 @@
 require 'pp'
 require 'tmpdir'
+require 'stringio'
 
 [ STDOUT, STDERR ].each { |io| io.sync = true }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rtomayko-rack-cache
 version: !ruby/object:Gem::Version 
-  version: 0.3.9
+  version: "0.4"
 platform: ruby
 authors: 
 - Ryan Tomayko
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-07 00:00:00 -08:00
+date: 2009-03-16 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,7 +40,6 @@ files:
 - Rakefile
 - TODO
 - doc/configuration.markdown
-- doc/events.dot
 - doc/faq.markdown
 - doc/index.markdown
 - doc/layout.html.erb

data/doc/events.dot

@@ -1,27 +0,0 @@
-digraph cache_logic {
-  nodesep=1.25;
-  center=true;
-
-  node[fontname="Lucida Sans Unicode",labelloc=c,margin=0.10,0.03]
-  edge[fontname="Lucida Sans Unicode",fontcolor="#444444",labeldistance=20];
-
-  receive -> pass[label="uncacheable request",color=grey];
-  receive -> lookup[label="cacheable request"];
-
-  pass -> deliver[label="",color=grey];
-
-  lookup -> hit[label="fresh"];
-  lookup -> fetch[label="stale (needs validation)"];
-  lookup -> miss[label="uncached"];
-
-  hit -> deliver[label="sizzling"];
-  hit -> pass[label="bailing...",color=grey];
-
-  miss -> fetch[label=""];
-  miss -> pass[color=grey];
-
-  fetch -> store[label="cacheable"];
-  fetch -> deliver[label="not cacheable",color=grey];
-
-  store -> deliver[label="KTHX"];
-}